Documentation  ❯  Artifact Configuration   ❯   Reference

File and directory elements

Container formats

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

Signing methods

Signing methods are used in:

• file elements (e.g. <authenticode-sign in <pe-file>)
• directory elements (<clickonce-sign> in <directory)
• file and directory sets (in the <for-each> element)

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

<clickonce-sign>: Microsoft ClickOnce

Supported elements:

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

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

<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

<jar-sign>: Java Archives

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

Supported elements:

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>: XML Digital Signature

Available for Advanced Code Signing.

Supported elements:

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:

Supported options:

See also:

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

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

Available for Advanced Code Signing.

Supported elements:

Create Cryptographic Message Syntax (CMS) signatures to sign any file with a X.509 certificates. Tools like openssl cms can be used to verify these signatures.

This directive creates a detached signature file

This directive adds a file to the output and is therefore only available within a <zip-file> element.

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" />
    </pe-file>
  </zip-file>
</artifact-configuration>

The resulting artifact will contain 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 -inform PEM -in myfile.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.

Detached signature files and GPG key reference

• This directive adds a file to the output and is therefore only available within a <zip-file> element.
• 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 will contain 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

This directive creates a detached signature file

This directive adds a file to the output and is therefore only available within a <zip-file> element.

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

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.

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.

Footnotes: