SignPath

Documentation  ❯  Artifact Configuration

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.

Artifact configuration 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
<zip-file> 
  <pe-file path="bin/program.exe">
    <authenticode-sign/>
  </pe-file>
</zip-file>
<zip-file>
  <directory path="bin">
    <pe-file path="program.exe">
      <authenticode-sign/>
    </pe-file>
  </directory>
</zip-file>

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 without max-matches or min-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
<pe-file path="first.dll">
  <authenticode-sign/>
</pe-file>

<pe-file path="second.dll">
  <authenticode-sign/>
</pe-file>
<pe-file-set>
  <include path="first.dll" />
  <include path="second.dll" />
  <for-each>
    <authenticode-sign/>
  </for-each>
</pe-file-set>

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

Examples are shortened

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.

<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
  <msi-file>
    <directory-set>
      <include path="component1" />
      <include path="component2" />
      <include path="component3" />
      <for-each>
        <pe-file-set>
          <include path="main.exe" />
          <include path="resources/*.resource.dll" 
                   min-matches="0" max-matches="unbounded" />
          <for-each>
            <authenticode-sign/>
          </for-each>
        </pe-file-set>
      </for-each>
    </directory-set>
    <authenticode-sign/>
  </msi-file>
</artifact-configuration>

graphical artifact configuration

Example of a directory structure that would match this configuration:

• myapp.msi 
  • component1/
    • main.exe
    • resources/de.resource.dll
    • resources/en.resource.dll
    • resources/fr.resource.dll
  • component2/
    • main.exe
  • component3/
    • main.exe
    • resources/en.resource.dll

(All msi, exe and dll files are signed with Authenticode.)

graphical resolved artifacts

  1. Note that JScript is not the same as JavaScript. While it is possible to use this option to sign JavaScript files, JavaScript engines will not be able to use this signature. 

  2. Deep signing is not yet supported for AppX and MSIX.  2

Sign up for news and special offers