Documentation  ❯  Artifact Configuration

• Abstract
• Creating and editing artifact configurations
  • Upload an artifact sample
  • Create an artifact configuration
  • Edit an artifact configuration
• Containers: defining file and directory structure
• Deep signing containers
  • Platform considerations
• File elements
  • File element types and signing directives
  • File element examples
  • Signing multiple artifacts
• <directory> element
  • <directory> example
• Signing methods
  • <authenticode-sign>
  • <clickonce-sign>
  • <nuget-sign>
  • <office-macro-sign>
  • <opc-sign>
  • <jar-sign>
• Using wildcards
  • Number of matches
• File and directory sets
  • File set example
• File attribute restrictions
  • File attribute restriction example
• User-defined parameters
• Examples
  • Predefined configuration for single Portable Executable file
  • Signing multiple artifacts in a ZIP container
  • Deep-signing an MSI installer
  • Signing similar directories within an MSI file

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

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

<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:

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:

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

<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

<?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>

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