- Abstract
- Creating and editing artifact configurations
- Containers: defining file and directory structure
- Deep signing containers
- File elements
- <directory> element
- Signing methods
- Using wildcards
- File and directory sets
- File attribute restrictions
- User-defined parameters
- Examples
Abstract
The artifact configuration describes the structure of the artifacts you want to sign. For simple artifacts, you can use predefined configurations to get started quickly. For signing several artifacts together, and for more complex artifacts, specify the structure of your artifact and provide signing directives using XML.
Creating and editing artifact configurations
Upload an artifact sample
Before you start creating an artifact configuration from scratch, we recommend that you upload an artifact sample first. SignPath will then analyze your sample and look for nested artifacts that can be signed.
For non-trivial artifacts, you may want to edit the resulting artifact configuration:
- It may contain signing instructions for files that you do not want to sign, such as third-party components.
- It may contain fixed strings, such as version numbers, that you want to replace with wildcards.
- It may have very similar sections that you want to unify using
<directory>
elements and wildcards (example).
Create an artifact configuration
When you create a new project, a default artifact configuration will be added. To create additional artifact configurations, select the project and click Add in the Artifact Configurations section. In either case, you can
- select Upload an artifact sample and select an artifact file to have the artifact configuration generated
- select a Ready to use artifact configuration
- select one of the Templates for custom artifact configurations and edit the XML content
- select Custom and create an artifact configuration from scratch
Edit an artifact configuration
To modify an existing artifact configuration, select a project, then select the artifact configuration you want to change, and then either
- select Edit to select pre-defined artifact configurations or edit the XML content
- select Update from an artifact sample to generate your artifact configuration from a sample file
When you edit XML content in place, a graphical representation will be rendered immediately. If you prefer to use code completion, select Download XML schema and use a schema-aware XML editor, such as Microsoft Visual Studio.
Read more about projects and artifact configurations in Setting up Projects.
Containers: defining file and directory structure
Every XML description is wrapped in an <artifact-configuration>
root element which contains exactly one file element. This file element specifies the type of artifact and signing method. Optionally, you can restrict the name of the file using the path
attribute.
Container-format elements may contain other file elements for deep signing. Every container format can contain multiple other file or directory elements to be signed. Each of those will be extracted, signed, and then put back into the container during the signing process. All inner elements need a path
attribute.
Deep signing containers
Sometimes you need to sign both the container and its contents. For instance, an MSI installer package needs to be signed, but you also want the files it installs to be signed. SignPath can sign both the container and its contents in a single pass if you specify an appropriate artifact configuration. See here for an example.
Platform considerations
File and directory names in path
attributes are case-insensitive. You may use slash /
or backslash \
as directory separators.
File elements
File element types and signing directives
Element | Container format | Signing directive | Extensions | Description |
---|---|---|---|---|
<pe-file> |
No | <authenticode-sign> |
.exe, .dll, .acm, .ax, .cpl, .drv, .efi, .mui, .ocx, .scr, .sys, .tsp | Portable Executable (PE) files: EXE, DLL, and other executable files |
<powershell-file> |
No | <authenticode-sign> |
.ps1, .psm1, psd1, .psdc1, .ps1xml | PowerShell scripts and modules |
<windows-script-file> |
No | <authenticode-sign> |
.wsf, ,vbs, .js |
Windows scripts for Windows Scripting Host, typically VBScript and JScript1. (Not available for Starter subscriptions.) |
<msi-file> |
Yes | <authenticode-sign> |
.msi, .msm, .msp | Microsoft installer files |
<cab-file> |
Yes | <authenticode-sign> |
.cab | Windows cabinet files |
<catalog-file> |
Yes | <authenticode-sign> |
.cat | Windows catalog files |
<appx-file> |
Yes2 |
<authenticode-sign> |
.appx, .appxbundle |
App packages for Microsoft Store/Universal Windows Platform The Common Name of the code signing certificate must match the PublisherDisplayName in the AppxManifest.xml file. |
<msix-file> |
Yes2 |
<authenticode-sign> |
.msix, .msixbundle | MSIX installer app packages for Microsoft Windows |
<opc-file> |
Yes | <opc-sign> |
.vsix, .xps, hlkx, ... | Open Packaging Conventions (OPC) files including Visual Studio Extensions (VSIX) and Hardware Lab Kit driver signing packages. (Driver signing not available for Starter subscriptions.) |
<nupkg-file> |
Yes | <nuget-sign> |
.nupkg | NuGet packages |
<jar-file> |
Yes | <jar-sign> |
.jar, .war, .ear, .apk, .aab | Java archives and Android apps. (Not available for Starter subscriptions.) |
<zip-file> |
Yes | <jar-sign> |
.zip | Use ZIP archives to sign multiple files at once. (ZIP archives can also be signed and verified using the JAR format. |
<office-oxml-file> |
No | <office-macro-sign> |
.xlsm, .xltm, .docm, .dotm, .pptm, .potm, .vsdm, vstm, ... | Sign VBA macros in Microsoft Office Open XML files and templates: Excel, Word, PowerPoint and Visio (available for Enterprise subscriptions) |
<office-binary-file> |
No | <office-macro-sign> |
.xls, .xlt, .doc, .dot, .pot, .ppa, .pps, .ppt, .mpp, .mpt, .pub, .vsd, .vst, ... | Sign VBA macros in binary Microsoft Office files and templates: Project, Publisher, and legacy Excel, Word, PowerPoint and Visio (available for Enterprise subscriptions) |
<directory> |
Yes | <clickonce-sign> |
Directories within container files. This directive is primarily used to structure further elements within containers, e.g. ZIP, MSI, or other directories. It can also be used to sign ClickOnce files. |
File element examples
Signing an MSI package
<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
<msi-file>
<authenticode-sign/>
</msi-file>
</artifact-configuration>
See Examples for more complex artifact configurations.
Signing multiple artifacts
If you want to sign multiple independent artifacts in one step, you need to package them into a ZIP archive before processing.
You can combine signing multiple artifacts with deep signing.
<directory> element
All supported container formats have an internal directory structure. You can see this structure if you extract a container to a local disk.
You can either specify these directories in the path
attribute of each file element or nest these file elements within <directory>
elements.
<directory>
elements are also used for ClickOnce signing.
<directory> example
The following fragment | is equivalent to |
---|---|
|
|
Signing methods
Specify signing directives in file and directory elements. See file elements for available methods per element type.
For file and directory sets, specify the signing directive in the <for-each>
element.
<authenticode-sign>
Microsoft Authenticode is the primary signing method on the Windows platform. Authenticode is a versatile and extensible mechanism that works for many different file types:
- Portable Executable (PE) files: EXE, DLL, and some other executable file formats including device drivers
- Installation formats: AppX, MSI, and CAB
- PowerShell scripts and modules
Using <authenticode-sign>
is equivalent to using Microsoft’s SignTool.exe
.
<clickonce-sign>
ClickOnce signing, also called ‘manifest signing’, is a method used for ClickOnce applications and Microsoft Office Add-ins.
ClickOnce signing applies to directories, not to individual files. Therefore, you need to specify a <directory>
element for this method. If you want to sign files in the root directory of a container, specify path="."
.
<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
<zip-file>
<directory path=".">
<clickonce-sign/>
</directory>
</zip-file>
</artifact-configuration>
Using <clickonce-sign>
is equivalent to using Microsoft’s mage.exe
.
<nuget-sign>
NuGet package signing is currently being introduced to the NuGet Gallery.
Although the NuGet Package format is based on OPC (see next section), it uses its own specific signing format.
Using <nuget-sign>
is equivalent to using Microsoft’s nuget
sign
command.
<office-macro-sign>
Available for Enterprise subscriptions
Use this directive to sign Visual Basic for Applications (VBA) macros in Microsoft Office files.
Use <office-oxml-file>
for Microsoft Office Open XML files:
- Excel: .xlam, .xlsb, .xlsm, .xltm
- PowerPoint: .potm, .ppam, .ppsm, .pptm
- Visio: .vsdm, .vssm, .vstm
- Word: .docm, .dotm
Use <office-binary-file>
for binary Microsoft Office files:
- Excel: .xla, .xls, .xlt
- PowerPoint: .pot, .ppa, .pps, .ppt
- Project: .mpp, .mpt
- Publisher: .pub
- Visio: .vdw, .vdx, .vsd, .vss, .vst, .vsx, .vtx
- Word: .doc, .dot, .wiz
Macro signatures apply only to the macros within the document files and are not affected by any other changes in the signed document files.
<opc-sign>
The Open Packaging Conventions (OPC) specification has its own signature format. Since OPC is the foundation for several file formats, it is not strictly a code signing format. However, code signing is used for Visual Studio Extensions (VSIX).
Other OPC formats include:
- Open XML Paper Specification (OpenXPS)
- Office Open XML files (Microsoft Office)
Note that while OPC signing can be applied to all OPC formats, specific applications and formats do not necessarily use or verify signatures, or even require a different signing format (case in point: NuGet packages).
Using <opc-sign>
for Visual Studio Extensions is equivalent to using Microsoft’s VSIXSignTool.exe
.
<jar-sign>
Available for Basic and Enterprise subscriptions
This signing method can be used to sign the following file formats:
Format | Extensions | Remarks |
---|---|---|
Java archives | .jar, .ear, .war | |
Android apps und app-bundles | .apk, .aab | Only APK signing scheme v1 (v2 and v3 are not yet supported) |
ZIP files | .zip | Only UTF-8 encoded ZIP files are supported |
Verification
- Java always verifies signatures for client components. For server components, you will need to create a policy. Please consult the documentation of your application server or Oracle’s documentation.
- Android always verifies App signatures.
- If you sign ZIP files, the receiver needs to manually check the signature before unpacking the file.
For manual verification, use the following command (requires JDK):
jarsigner -verify -strict <file>.zip
Add the -verbose
option to see the certificate.
Using wildcards
Every path attribute can contain the following wildcard patterns:
Wildcard | Description | Example | Matches |
---|---|---|---|
* |
Matches any number of any character (including none, excluding the directory separator) | m*y |
my , mary , my first pony |
? |
Matches any single character | th?s : this , th$s , but not ths |
|
[abc] |
Matches one character given in the bracket | [fb]oo |
foo and boo |
[a-z] |
Matches one character from the range given in the bracket | [0-9] |
all digits |
[!abc] |
Matches one character that is not given in the bracket | [!f]oo |
boo and $oo , but not foo |
[!a-z] |
Matches one character that is not from the range given in the bracket | [!0-9] |
every character that is not a digit |
** |
Matches any number of path/directory segments. When used, they must be the only contents of the dedicated segment. | **/*.dll |
*.dll files in all subdirectories (recursive) |
Number of matches
If wildcards are used, optional max-matches
and min-matches
parameters can be specified to set the number of files that may match the wildcard expression.
- Both default to
1
, so wildcard expressions withoutmax-matches
ormin-matches
must match exactly one file - Use
min-matches="0"
for optional elements (even without wildcards) - Use
max-matches="unbounded"
for unlimited matches
File and directory sets
If multiple files or directories should be handled in the same way, you can enumerate them using one of the following file or directory set elements:
<directory-set>
<pe-file-set>
<powershell-file-set>
<windows-script-file-set>
<msi-file-set>
<cab-file-set>
<catalog-file-set>
<appx-file-set>
<msix-file-set>
<opc-file-set>
<nupkg-file-set>
<jar-file-set>
<zip-file-set>
<office-oxml-file-set>
<office-binary-file-set>
Each set element contains:
- an
<include>
element for each file (or pattern) to be processed - a
<for-each>
element that will be applied to all included elements of the set
A set’s <for-each>
element can include the same child elements as the corresponding simple file or directory element:
<pe-file>
supports<authenticode-signing/>
- therefore
<pe-file-set>
supports<authenticode-signing/>
within the<for-each>
element
Sets are especially useful if your artifacts contain repeating nested structures.
File set example
The following fragment | is equivalent to |
---|---|
|
|
File attribute restrictions
For Microsoft Portable Executable (PE) files, the existence of their Product Name / Product Version header attributes can be enforced by setting the productName
and productVersion
attributes on the <pe-file>
, <pe-file-set>
and including <include>
elements. The value of the <include>
overrides any value set on the <pe-file-set>
element.
File attribute restriction example
<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
<msi-file>
<!-- requires all pe-files to have the respective attributes set -->
<pe-file-set productName="YourProductName" productVersion="1.0.0.0">
<include path="main.exe" />
<!-- overrides the value of the parent pe-file-set -->
<include path="resources*.resource.dll" max-matches="unbounded" productVersion="1.0.1.0" />
<for-each>
<authenticode-sign />
</for-each>
</pe-file-set>
<authenticode-sign /> <!-- finally sign the MSI file -->
</msi-file>
</artifact-configuration>
User-defined parameters
Available for Enterprise subscriptions
You can define parameters for each signing request. Use this to create a more restrictive artifact configuration, track values, or include build-time values.
Parameter values can be set when submitting a signing request via the user interface or API (see documentation). Actual values are displayed on the signing request details page.
Parameters are defined in an optional parameters
block at the beginning of the artifact configuration and can be referenced using the ${parameterName}
syntax in any XML attribute.
<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
<parameters>
<parameter name="productVersion" default-value="1.0.0" required="true" />
</parameters>
<pe-file path="my-installer-${productVersion}.exe" productVersion="${productVersion}">
</artifact-configuration>
Examples
For the sake of clarity, all examples omit the XML prolog. A complete artifact configuration looks like this:
<?xml version="1.0" encoding="utf-8" ?>
<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
<!-- ... -->
</artifact-configuration>
Predefined configuration for single Portable Executable file
This configuration works for all PE files.
<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
<pe-file>
<authenticode-sign/>
</pe-file>
</artifact-configuration>
Signing multiple artifacts in a ZIP container
You can sign multiple unrelated artifacts by packing them into a single ZIP file.
<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
<zip-file>
<pe-file path="app.exe">
<authenticode-sign/>
</pe-file>
<powershell-file path="setup.ps1">
<authenticode-sign/>
</powershell-file>
</zip-file>
</artifact-configuration>
Deep-signing an MSI installer
This will sign the PE files libs/common.dll
and main.exe
, then re-package their MSI container and sign it too. It also restricts the name of the MSI container file.
<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
<msi-file path="MyProduct.v*.msi">
<pe-file path="libs/common.dll">
<authenticode-sign/>
</pe-file>
<pe-file path="main.exe">
<authenticode-sign/>
</pe-file>
<authenticode-sign/>
</msi-file>
</artifact-configuration>
Signing similar directories within an MSI file
This artifact configuration describes an MSI installer package containing several components. The components have a similar structure and are therefore defined as a <directory-set>
. Each component contains a main.exe
and zero or more resource DLLs.
|
|
Example of a directory structure that would match this configuration:
(All |
|