File and directory elements
Element | Container format | Signing directive | Extensions | Description |
---|---|---|---|---|
|
No |
.exe, .dll, .acm, .ax, .cpl, .drv, .efi, .mui, .ocx, .scr, .sys, .tsp |
Portable Executable (PE) files: EXE, DLL, and other executable files | |
|
No |
.ps1, .psm1, psd1, .psdc1, .ps1xml |
PowerShell scripts and modules | |
|
No |
.wsf, ,vbs, .js |
Windows scripts for Windows Scripting Host, typically VBScript and JScript1. (Not available for Code Signing Starter.) | |
|
Yes |
.msi, .msm, .msp |
Microsoft installer files | |
|
Yes |
.cab |
Windows cabinet files | |
|
No |
.cat |
Windows catalog files | |
|
Yes |
.appx, .appxbundle |
App packages for Microsoft Store/Universal Windows Platform The Common Name of the code signing certificate must match the | |
|
Yes |
.msix, .msixbundle |
MSIX installer app packages for Microsoft Windows | |
|
Yes |
.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. | |
|
Yes |
.nupkg |
NuGet packages | |
|
Yes |
.jar, .war, .ear, .apk, .aab |
Java archives and Android apps. (Not available for Code Signing Starter.) | |
Yes |
.zip |
Use ZIP archives to sign multiple files at once. (ZIP archives can also be signed and verified using the JAR format | ||
|
No |
.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) | |
|
No |
.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) | |
|
No |
.xml |
Use this directive to sign XML files using XMLDSIG (available for Advanced Code Signing). File size limit: 2 MB. | |
Yes |
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. | |||
|
No |
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 |
---|---|---|
|
.exe, .dll, .acm, .ax, .cpl, .drv, .efi, .mui, .ocx, .scr, .sys, .tsp |
Portable Executable (PE) files: EXE, DLL, and other executable files |
|
.ps1, .psm1, psd1, .psdc1, .ps1xml |
PowerShell scripts and modules |
|
.wsf, ,vbs, .js |
Windows scripts for Windows Scripting Host, typically VBScript and JScript1. (Not available for Code Signing Starter.) |
|
.msi, .msm, .msp |
Microsoft installer files |
|
.cab |
Windows cabinet files |
|
.cat |
Windows catalog files |
|
.appx, .appxbundle |
App packages for Microsoft Store/Universal Windows Platform The Common Name of the code signing certificate must match the |
|
.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 used to calculate the signature digest.
|
|
text |
Description of the signed content | |
|
Uniform Resource Locator (URL) for the expanded description of the signed content | ||
|
|
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:
- Verify existing signatures using
authenticode-verify
. - Use metadata restrictions for
<pe-file>
to restrict product name and version.
<clickonce-sign>
Supported elements:
Element | Extensions | Description |
---|---|---|
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 |
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 |
---|---|---|
|
.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, .war, .ear, .apk, .aab |
Java archives and Android apps. (Not available for Code Signing Starter.) |
.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 |
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 signatureleaf (Default): Include only the leaf certificate in the signaturewhole-chain : Include the whole certificate chain in the signatureexclude-root : Include the whole certificate chain in the signature, but exclude the root certificateNote: whole-chain and exclude-root only work with public CA trusted certificates |
See also:
- Use metadata restrictions for
<xml-file>
to restrict root element and namespace.
Detached raw signatures using <create-raw-signature>
Available for Advanced Code Signing.
Supported elements:
Element | Extensions | Description |
---|---|---|
|
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: