Artifact Configuration  ❯  Reference

• File and directory elements
  • Container formats
• Signing methods
  • <authenticode-sign>
  • <clickonce-sign>
  • <nuget-sign>
  • <office-macro-sign>
  • <opc-sign>
  • <jar-sign>
  • <xml-sign>
  • Detached raw signatures using <create-raw-signature>
• File metadata restrictions

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

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:

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.

See also:

• Use metadata restrictions for <pe-file> to restrict product name and version.

<clickonce-sign>

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>

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>

Available for Enterprise subscriptions

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:

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 Basic and Enterprise subscriptions

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>

Available for Enterprise subscriptions

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.

Detached raw signatures using <create-raw-signature>

Available for Enterprise subscriptions

Supported elements:

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:

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.

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

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: