SignPath

Artifact Configuration  ❯  Reference

File and directory elements

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 Code Signing Starter.)

<msi-file>

Yes

<authenticode-sign>

.msi, .msm, .msp

Microsoft installer files

<cab-file>

Yes

<authenticode-sign>

.cab

Windows cabinet files

<catalog-file>

No

<authenticode-sign>

.cat

Windows catalog files

<appx-file>

Yes

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

Yes

<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 Code Signing Starter.) File size limit: 40 MB.

<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 Code Signing Starter.)

<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 Advanced Code Signing)

<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 Advanced Code Signing)

<xml-file>

No

<xml-sign>

.xml

Use this directive to sign XML files using XMLDSIG (available for Advanced Code Signing). File size limit: 2 MB.

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

No

<create-raw-signature>

Arbitrary files. This directive will create a detached raw signature file (available for Advanced Code Signing)

Container formats

Container elements such as directories, archives, installers and package formats allow nested file elements. See Syntax for more information.

Signing methods

Specify signing directives in file and directory elements.

For file and directory sets, specify the signing directive in the <for-each> element.

<authenticode-sign>

Supported elements:

Element Extensions Description

<pe-file>

.exe, .dll, .acm, .ax, .cpl, .drv, .efi, .mui, .ocx, .scr, .sys, .tsp

Portable Executable (PE) files: EXE, DLL, and other executable files

<powershell-file>

.ps1, .psm1, psd1, .psdc1, .ps1xml

PowerShell scripts and modules

<windows-script-file>

.wsf, ,vbs, .js

Windows scripts for Windows Scripting Host, typically VBScript and JScript1. (Not available for Code Signing Starter.)

<msi-file>

.msi, .msm, .msp

Microsoft installer files

<cab-file>

.cab

Windows cabinet files

<catalog-file>

.cat

Windows catalog files

<appx-file>

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

.msix, .msixbundle

MSIX installer app packages for Microsoft Windows

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. Using <authenticode-sign> is equivalent to using Microsoft’s SignTool.exe.

Optional attributes

Attribute Default Values Description

hash-algorithm

sha-256

sha1, sha256, sha384, sha512

Hash algorithm used to calculate the signature digest.

<appx-file> and <msix-file> don’t support sha1 and require the hash-algorithm to match the one specified in the AppxBlockMap.xml file.

description

text

Description of the signed content

description-url

Uniform Resource Locator (URL) for the expanded description of the signed content

append

false

boolean

When true, append the signature to any existing signatures. When false, replace any existing signatures. See below for supported formats.

Appending signatures

File formats that support appending signatures:

  • <pe-file> (.exe, .dll, …)
  • <cab-file> (.cab)
  • <catalog-file> (.cat)

Appending signatures is only needed for edge cases including

  • adding an signature to a file that’s already signed using another certificate
  • adding a signature using different parameters, such as digest algorithm

Example: append signature, preserving any existing signatures

<authenticode-sign append="true" />

Example: sign using SHA1 algoritm, then sign again using default SHA-256 algorithm (explicitly specified for clarity)

<authenticode-sign hash-algorithm="sha1" />
<authenticode-sign hash-algorithm="sha256" append="true" />

Example: provide description text and URL

<authenticode-sign description="ACME program" description-url="https://example.com/about-acme-program" />

See also:

<clickonce-sign>

Supported elements:

Element Extensions Description

<directory>

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.

ClickOnce signing, also called ‘manifest signing’, is a method used for ClickOnce applications and Microsoft Office Add-ins. Using <clickonce-sign> is equivalent to using Microsoft’s mage.exe.

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>

<nuget-sign>

Supported elements:

Element Extensions Description

<nupkg-file>

.nupkg

NuGet packages

NuGet packages are signed by NuGet Gallery. They can be signed by the publisher too. Using <nuget-sign> is equivalent to using Microsoft’s nuget sign command.

Publisher signing has the following additional security advantages:

  • NuGet Gallery can be configured to accept only uploads signed with a specific certificate
  • Users will be warned if package updates don’t match the previous signature
  • Users can configure which publishers to trust

Although the NuGet Package format is based on OPC (see next section), it uses its own specific signing format.

<office-macro-sign>

Available for Advanced Code Signing.

Use this directive to sign Visual Basic for Applications (VBA) macros in Microsoft Office documents and templates.

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>

Supported elements:

Element Extensions Description

<opc-file>

.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 Code Signing Starter.) File size limit: 40 MB.

Signs according to the Open Packaging Conventions (OPC) specification. Using <opc-sign> for Visual Studio Extensions is equivalent to using Microsoft’s VSIXSignTool.exe.

Note that not all OPC-based formats use OPC signatures:

  • Office Open XML files (Microsoft Office): OPC signatures are only partially recognized by Office applications
  • NuGet packages: ignored, use <nuget-sign> instead

<jar-sign>

Available for Code Signing Basic, Advanced Code Signing, Open Source Code Signing.

Supported elements:

Element Extensions Description

<jar-file>

.jar, .war, .ear, .apk, .aab

Java archives and Android apps. (Not available for Code Signing Starter.)

<zip-file>

.zip

Use ZIP archives to sign multiple files at once. (ZIP archives can also be signed and verified using the JAR format

Android apps and app-bundles: Note that JAR signatures only implement APK signing scheme v1 (v2 and v3 are not yet 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, but current Android versions require signing schemes v2 or v3.
  • 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.

<xml-sign>

Available for Advanced Code Signing.

Supported elements:

Element Extensions Description

<xml-file>

.xml

Use this directive to sign XML files using XMLDSIG (available for Advanced Code Signing). File size limit: 2 MB.

Sign XML files with XMLDSIG.

This will create an enveloped signature for the entire document.

The result is a Signature element added to the root element (after all existing children) with the following properties:

Property Value XPath
Canonicalization Exclusive XML Canonicalization: http://www.w3.org/2001/10/xml-exc-c14n# /*/Signature/SignedInfo/CanonicalizationMethod/@Algorithm
Signature Method RSA SHA-256: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 /*/Signature/SignedInfo/SignatureMethod/@Algorithm
ReferenceUri Whole document: "" /*/Signature/SignedInfo/Reference/@URI
Transformation Enveloped signature: http://www.w3.org/2000/09/xmldsig#enveloped-signature" /*/Signature/SignedInfo/Reference/Transforms/Transform/@Algorithm
Transformation Exclusive XML Canonicalization: http://www.w3.org/2001/10/xml-exc-c14n# /*/Signature/SignedInfo/Reference/Transforms/Transform/@Algorithm
Digest method SHA-256: http://www.w3.org/2001/04/xmlenc#sha256 /*/Signature/SignedInfo/Reference/DigestMethod/@Algorithm
X.509 Certificate See key-info-x509-data option /*/Signature/KeyInfo/X509Data

Supported options:

Option Optional Description
key-info-x509-data Yes none: Do not include any X.509 data in the signature
leaf (Default): Include only the leaf certificate in the signature
whole-chain: Include the whole certificate chain in the signature
exclude-root: Include the whole certificate chain in the signature, but exclude the root certificate
Note: whole-chain and exclude-root only work with public CA trusted certificates

See also:

Detached raw signatures using <create-raw-signature>

Available for Advanced Code Signing.

Supported elements:

Element Extensions Description

<file>

Arbitrary files. This directive will create a detached raw signature file (available for Advanced Code Signing)

Note: Since the detached signatures are placed in a separate file, this directive is only available within a <zip-file> element.

Detached raw signatures can be used to sign any binary or text file. They can also be used to sign Cosign metadata files.

The create-raw-signature directive supports the following parameters:

Parameter Required Values Description
file-name Yes   Name of the output file containing the signature. Use $(file.name) to reference the source file name.
hash-algorithm Yes sha256, sha384, sha512 Hash algorithm used to create the signature
rsa-padding For RSA keys pkcs1, pss Padding algorithm (RSA keys only)

Example

<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
  <zip-file>
    <file path="myfile.bin">
      <create-raw-signature file-name="${file.name}.sig" hash-algorithm="sha256" />
    </pe-file>
  </zip-file>
</artifact-configuration>

The resulting artifact will contain both the original file myfile.bin and the detached signature in myfile.bin.sig.

Detached signature verification

There are multiple tools and solutions that support handling of raw signature blocks. One popular option is openssl dgst. As the command does not support X.509 certificates, the public key has to be extracted before the signature can be verified using the following call:

openssl dgst -verify pubkey.pem -signature file.sig file

Verification methods

Verification directives are used to ensure that files in a singing request are already properly signed by their respective publisher.

Use this to

  • avoid installing unsigned files with your (signed) installers or packages
  • sign each file in it’s respective build pipeline rather than signing everything in the final (downstream) pipeline
  • re-sign third-party files to comply with your organization’s code signing policies

When used to verify a file before signing it, the verify directive must precede any sign directives.

<authenticode-verify>

Verifies that a file has a valid Authenticode signature.

This method verifies signatures according to Windows rules:

  • Supported hash digest algorithm and length, signing key type and length
  • Valid timestamp (or unexpired publisher certificate)
  • Certificate chain ends in Windows trusted root certificate

May be combined with <authenticode-sign>.

TODO: add

Use append="true" to add the new signature instead of replacing the existing one (supported formats only).

Example

<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
  <msi-file>
    <pe-file-set>
      <include path="Microsoft.*.dll" max-matches="unbounded" />
      <include path="System.*.dll" max-matches="unbounded" />
      <for-each>
        <authenticode-verify/>
      </for-each>
    </pe-file-set>
  </msi-file>
</artifact-configuration>

File metadata restrictions

Some element types support restricting certain metadata values.

The restrictions can be applied to file elements, file set elements, or <include> elements. Attributes on <include> elements override those on file set elements.

File element Supported restriction attributes Example
<pe-file> PE file headers: product-name, product-version PE file restrictions
<xml-file> Root element name and namespace: root-element-name, root-element-namespace SBOM restrictions

Footnotes:

  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

Sign up for news and special offers