Artifact Configuration  ❯   Reference

Elements and directives

File formats and supported code signing directives

Signature verification

Supported signature verification methods:

• authenticode-verify: Verify authenticode signatures

Attestations

See Attestations for how to create attestation using artifact configurations.

Composite formats

Composite element types such as <directory>, <zip-file>, installers, and package formats allow deep signing of nested file elements. See Syntax for more information.

Signing methods

Directives and categories

Signing directives are typically used in file elements or file sets, e.g.

• a <pe-file> containing an <authenticode-sign directive
• a <pe-file> set containing a <for-each> block with an <authenticode-sign directive

There are three major categories of signing methods:

Embedded signatures

Just specify the signing directive to sign the file.

Example

<pe-file path="myapp.exe">
  <authenticode-sign />
</pe-file>

Enveloped and detached signatures

• Since the signed file is added, the <file> element must be contained in a <zip-file> element.
• Use the variable ${file.name} to reference the original file’s name for output-file-name.

Example

<zip-file>
  <file path="myfile.bin">
    <create-gpg-signature output-file-name="${file.name}.asc" />
  </file>
</zip-file>

Signing directives

<authenticode-sign>: Authenticode (Windows)

Supported elements:

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

append attribute

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

Authenticode examples

Example: append signature, preserving any existing signatures

<authenticode-sign append="true" />

Example: sign using SHA1 algorithm, 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:

• Verify existing signatures using authenticode-verify.
• Use metadata restrictions for <pe-file> to restrict product name and version.

<nuget-sign>: NuGet packages

Supported elements:

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.

No support for private PKI

Only self-signed certificates or certificates issued by a publicly trusted Certificate Authority are supported by NuGet.

Certificate chain support

If certificate chains can be resolved at signing time, they will be embedded in the signature.

<office-macro-sign>: Microsoft Office VBA macros

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.

Certificate chain support

Only publisher certificates are embedded in Office macro signatures.

<opc-sign>: Open Packaging Convention

Supported elements:

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

No certificate chain support

Only publisher certificates are embedded in OPC signatures.

<jar-sign>: Java Archives

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

Supported elements:

Supported options:

Verification

• Java always verifies signatures for client components. For server components, you need to create a policy. Please consult the documentation of your application server or Oracle’s documentation.
• For signed ZIP files, the receiver needs to check the signature explicitly before unpacking the file.

For verification, use the following command (requires JDK):

jarsigner -verify -strict <file>.zip

Add the -verbose option to see the certificate.

** No longer supported for Android packages

Current Android versions require signing schemes v2 or v3. Use [<apk-sign>'](#apk-sign) instead of `.

<apk-sign>: Android app packages

Available for Advanced Code Signing, Open Source Code Signing.

Supported elements:

Android app package files support signatures in different schema versions depending on the app’s SDK.

Supported options:

Example

<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
  <apk-file>
    <apk-sign />
  </apk-file>
</artifact-configuration>

<rpm-sign>: RPM Package Manager

Available for Advanced Code Signing, Open Source Code Signing.

Supported elements:

RPM is the package manager format for many Linux distributions including Fedora, RedHat, and openSUSE. RPM is based on GPG signatures and requires signing policies with a GPG key certificate.

Example

<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
  <rpm-file>
    <rpm-sign />
  </rpm-file>
</artifact-configuration>

Verification

Package verification is typically performed automatically by package management tools like yum and DNF.

To manually verify .rpm files, use the following commands:

rpm --import my_key.asc # Import, i.e. trust, the GPG public key

rpm --verbose --checksig my_package.rpm

<debsigs-sign>: Debian packages

Available for Advanced Code Signing.

Supported elements:

Create embedded signatures for Debian packages (.deb files). Package signatures are based on GPG and require signing policies with a GPG key certificate. SignPath signs packages using the debsigs specification.

Supported options:

Example

<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
  <deb-file>
    <debsigs-sign signature-type="origin" />
  </deb-file>
</artifact-configuration>

Verification

Package signatures are verified implicitly during dpkg --install operations unless the --no-debsig parameter is specified.

Package signature verification is not the default

Many popular Linux distributions including Ubuntu and Debian set no-debsig by default in /etc/dpkg/dpkg.cfg. The reason is that rather than individual Debian package files, these distros verify the whole package repository via Release.gpg.

The dpkg command internally uses debsig-verify. You can also use this tool directly to verify a .deb file after importing the GPG key and setting up the policies (.pol) XML file (see man page for details).

<xml-sign>: XML Digital Signature

Available for Advanced Code Signing.

XMLDSIG can be used to sign CycloneDX XML SBOMs.

Supported elements:

Sign XML files with XMLDSIG.

This creates an XMLDSIG enveloped signature for the entire document: a <ds:Signature> element is added to the existing root element.

Terminology

XMLDSIG terminology names this method enveloped signature although it does not create an envelope. Since it preserves the existing XML document and structure, it can be treated as an embedded signature for most purpuses. However, the new element might break the root element’s schema if signing is not expected by the target schema.

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

Supported options:

See also:

• Use metadata restrictions for <xml-file> to restrict root element and namespace.

<jsf-sign>: JSON Signature Format

Available for Advanced Code Signing, Open Source Code Signing.

JSF can be used to sign CycloneDX v1.x JSON SBOMs.

Supported elements:

Sign JSON files with JSON Signature Format (JSF).

This creates signature of the whole document: a signature property is added at the root level. Note that a JSON object is expected, JSON arrays are not supported at the root level.

Supported options:

<notation-sign>: Notary (Notation) container signature

Sign container images using Notation (Notary).

Supported elements:

This places the signature at the right place within the OCI layout and add relevant references.

Supported options:

Example

<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
  <oci-image-layout-archive-file>
    <notation-sign tag="latest" />
  </oci-image-layout-archive-file>
</artifact-configuration>

Note: You can create both Notary and Cosign signatures for the same image.

<cosign-sign>: Sigstore Cosign container signature

Sign container images using Sigstore Cosign.

Supported elements:

This places the signature at the right place within the OCI layout and add relevant references.

Supported options:

Example

<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
  <oci-image-layout-archive-file>
    <cosign-sign tag="latest" />
  </oci-image-layout-archive-file>
</artifact-configuration>

Note: You can create both Notary and Cosign signatures for the same image.

<dsse-sign>: DSSE (Dead Simple Signing Envelope)

Available for Advanced Code Signing.

Supported elements:

Create a DSSE signature file that contains the signature and the enveloped original file in JSON format.

DSSE (Dead Simple Signing Envelope)

DSSE is a signing specification created by the Secure Systems Lab at NYU School of Engineering. It has not been formally standardized but is widely used in the context of code signing. Note that DSSE contains no metadata about the singing format, so all signing parameters must be agreed out-of-band.

DSSE is an enveloped signing method and must be used in <zip-file> elements.

The dsse-sign directive supports the following parameters:

DSSE example

This example signs SLSA Verification Summary Attestations using DSSE:

<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
  <zip-file>
    <file path="slsa-vsa.json">
      <dsse-sign payload-type="application/vnd.in-toto+json" 
                 hash-algorithm="sha256" rsa-padding="pkcs1"
                 output-file-name=" ${file.name}.dsse" />
    </file>
  </zip-file>
</artifact-configuration>

The resulting artifact contains both the original file slsa-vsa.json and the enveloped signatureslsa-vsa.dsse.

<smime-sign>: S/MIME signing

Available for Advanced Code Signing.

Supported elements:

S/MIME signing can be used to sign arbitrary “messages” with an X.509 certificate. Usually the input is in text form (e.g. the output of the shasum utility). The resulting file is a text file which contains both, the input (text), and a CMS signature and can be verified e.g. via openssl commands (see below).

S/MIME is an enveloped signing method and must be used in <zip-file> elements.

The smime-sign directive supports the following parameters:

S/MIME signing example

This example signs a hash sum text file as hashes.txt.msg:

<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
  <zip-file>
    <file path="hashes.txt">
      <smime-sign
        normalization="line-endings"
        hash-algorithm="sha256"
        rsa-padding="pkcs1"
        output-file-name="${file.name}.msg" />
    </file>
  </zip-file>
</artifact-configuration>

S/MIME verification

S/MIME signature files can be verified with both, the openssl cms or openssl smime commands:

openssl cms -verify -purpose codesign -in "hashes.txt.msg" -out "hashes.txt"

openssl smime -verify -purpose codesign -in "hashes.txt.msg" -out "hashes.txt"

OpenSSL CMS verification

• Prior to OpenSSL 3.2, the -purpose flag does not support codesign. Use any instead.
• When the certificate is not trusted on the target system, specify -CAfile with the path of the root certificate. Make sure that the root certificate is distributed in a secure way.

<create-cms-signature>: Cryptographic Message Syntax (CMS)

Available for Advanced Code Signing.

Supported elements:

Create CMS signatures to sign any file with an X.509 certificate. Tools like openssl cms can be used to verify these signatures.

Cryptographic Message Syntax (CMS)

CMS is an IETF standard for cryptographically protected messages, as defined in RFC 5652. It is often referred to as PKCS #7, although this is technically the name of the standard preceding CMS.

CMS is a detached signing method and must be used in <zip-file> elements.

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

CMS example

<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
  <zip-file>
    <file path="myfile.bin">
      <create-cms-signature output-encoding="pem" output-file-name="${file.name}.cms.pem"
         hash-algorithm="sha256" rsa-padding="pkcs1" />
    </file>
  </zip-file>
</artifact-configuration>

The resulting artifact contains both the original file myfile.bin and the detached signature in myfile.bin.cms.pem.

CMS signature verification

Multiple tools support verification of CMS signature. One popular option is openssl cms:

openssl cms -verify -purpose codesign -content myfile.bin -binary -inform PEM -in myfile.bin.cms.pem -out /dev/null

OpenSSL CMS verification

• Prior to OpenSSL 3.2, the -purpose flag does not support codesign. Use any instead.
• When the certificate is not trusted on the target system, specify -CAfile with the path of the root certificate. Make sure that the root certificate is distributed in a secure way.

<create-gpg-signature>: Detached GPG signing

Available for Advanced Code Signing.

Supported elements:

Create detached GPG signatures to sign any file with a GPG key.

Naming: GPG and OpenPGP, keys and certificates

Our documentation uses the term GPG for these key and signature types. While OpenPGP would be the technically correct term, is often referred to via its de-facto standard implementation, GNU Privacy Guard (GPG or GnuPG). The first implementation was Pretty Good Privacy (PGP), and the format was ultimately standardized as OpenPGP by the IETF.

The GPG community uses various terms for certificates, including GPG Key, Public Key, Transferable Public Key and Certificate. To avoid confusion with the public key of a asymmetric key pair, and for consistency within our documentation, we use the term GPG Key as a specific type of Certificate. See Managing Certificates for more information.

GPG is a detached signing method and must be used in <zip-file> elements. It is only available for signing policies with a GPG key certificate.

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

Example

<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
  <zip-file>
    <file path="myfile.bin">
      <create-gpg-signature output-encoding="ascii-armored" output-file-name="${file.name}.asc" />
    </file>
  </zip-file>
</artifact-configuration>

The resulting artifact contains both the original file myfile.bin and the detached signature in myfile.bin.asc.

GPG signature verification

Signature verification can be performed with any OpenPGP-compliant tool. Example using GnuPG:

# Import the GPG key (unless done before):
gpg --import my_key.asc

# Verify `myfile.bin` against the detached signature file `myfile.bin.asc`:
gpg --verify myfile.bin.asc myfile.bin

<create-raw-signature>: Detached raw signature files

Available for Advanced Code Signing.

Supported elements:

Create raw signatures for any binary or text file. A raw signature is the output of the key algorithm, or cipher (e.g. RSA, ECDSA), without any additional data.

Use cases for raw signatures include:

• Signing for lightweight verification, e.g. on embedded systems
• Creating signature blocks for subsequent use with other tools and formats
• Signing Cosign metadata files

Raw signing is a detached signing method and must be used in <zip-file> elements.

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

(All cryptographic parameters are mandatory because raw signatures contain no metadata for agnostic verification.)

Raw signature example

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

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

Raw signature verification

Extract the public key from the certificate, then use any tool that can process raw signature blocks to verify the detached signature.

Extract the public key:

openssl x509 -in certificate.cer -inform DER -pubkey -out pubkey.pem -noout

Verify the signature using the public key:

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

If you use this method directly to verify signatures, make sure that the public key is distributed in a secure way and independently from the file to be verified.

<clickonce-sign>: Microsoft ClickOnce and VSTO Office add-ins

Supported elements:

ClickOnce signing, also called manifest signing, is a method used for ClickOnce applications and Microsoft Office Add-ins created using Visual Studio Tools for Office (VSTO). 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 composite element, specify path=".".

<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
  <zip-file>
    <directory path=".">
      <clickonce-sign/>
    </directory>
  </zip-file>
</artifact-configuration>

Verification methods

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

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

Supported elements:

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> to replace the signature. For supported formats, you may add an additional signature using the append attribute.

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/>
        <authenticode-sign append="true"/>
      </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.