Sign with CMS Signatures | Keyfactor Docs

The Cryptographic Message Syntax (CMS) format, based on PKCS#7, can sign arbitrary data similarly to the plain signature format. Many common signature formats use CMS internally, including Authenticode and JAR signing. The format is also useful standalone for signing firmware or release packages. Existing tools like OpenSSL can be used to verify CMS signatures in many cases.

A CMS signature includes the signer certificate and can optionally embed a timestamp token from a Time-Stamping Authority (TSA) in RFC 3161 format. The signature can either encapsulate the content from the original document within it, or be produced as a detached signature stored in a separate file. The detached signature is generally more practical for code signing.

SignServer includes several CMS signer variants:

CMS Signer: Provides basic functionality.
Extended CMS Signer: Adds timestamping support and other extended features. Recommended for most use cases.
JArchive CMS Signer: A variant of the Extended CMS Signer with defaults suited for JAR signing. Intended for client-side hashing.
APPX CMS Signer: A variant for signing Microsoft APPX packages and bundles.
MS Authenticode CMS Signer: A variant producing Authenticode-compatible signatures for .exe, .dll, MSI, and .cab files.

CMS Signer Configuration Properties

The following properties are most relevant when configuring the CMS Signer:

Worker Property	Description
`SIGNATUREALGORITHM`	The algorithm used to sign the data. Example: `SHA256withRSA`
`DETACHEDSIGNATURE`	Set to `true` to produce a detached signature where the content is not embedded in the signature file. Recommended for code signing.
`CLIENTSIDEHASHING`	Set to `true` if the input to the signer should be a hash of the content rather than the content itself. See Code Signing with Client-side Hashing.

For all available properties, refer to CMS Signer and Extended CMS Signer .

Set up the CMS Signer

Follow the steps to add and configure an Extended CMS Signer:

Step 1 - Add and Configure the Signer

Open the Admin Web and got to the Workers page.
Click Add, and select From Template.
Choose extended_cms_signer.properties, and click Next.
Click Apply.
Select the Worker named ExtendedCMSSigner in the list.
Click the Configuration tab and update the following properties:
- NAME: Set a descriptive name for the worker.
- CRYPTOTOKEN: set this to match your Crypto Token.
Click the Status Summary tab, and click Renew Key.
Select a Key Algorithm (for example, RSA) and Key Specification (for example, 2048), and click Generate.

Step 2 - Generate a CSR and Install the Certificate

If you set the NOCERTIFICATES property to true, the CMS Signer does not require a certificate. Skip this step and confirm the worker status is Active.

Choose a Signature Algorithm, for example, SHA256withRSA, and enter a Subject DN for the certificate, for example, CN=CMS Signer Test,O=My Company,C=SE.
Click Generate.
Click Download and save the CSR file.
Submit the CSR to your Certificate Authority. The CA returns the signed certificate and any CA certificates in the chain.

Before installing certificates in a production system, verify the Signer’s authorization settings. Once certificates are installed, the Signer is fully active and ready to accept signing requests.

Click Install certificates. Provide the Signer certificate first, then add the issuing CA certificates in order. Click Add for each certificate to append it to the chain.
When all certificates are in the correct order, click Install.
Confirm the worker status is Active. If not, check the Status Summary page for errors.

Sign a File

You can submit files for signing using the Client Web, the SignClient, or HTTP clients like cURL.

Using Client Web

Go to the SignServer Client Web Generic page.
Scroll down to the Generic Signing Or Validation by File Upload section and specify your Worker name, for example ExtendedCMSSigner, in the Worker Name field.
Click Choose File, select the file to create a detached signature for, such as release.zip.
Click Submit.
Save the resulting signature file, for example, release.zip.asc.

Using SignClient

Send a signing request using the SignServer SignClient:

bin/signclient signdocument -workername CMSSigner1 -infile firmware.bin -outfile firmware.sig

Where workername is the name of the Worker, infile is the path to the file to sign, and outfile is where the signature will be written to.

The SignClient can also run (as User) in batch mode, which processes all files in an input directory across parallel threads and writes results to an output directory:

bin/signclient signdocument -workername CMSSigner1 -indir ./input/ -removefromindir -outdir ./output/ -threads 10

Using cURL

Replace http://localhost:8080/ with the address of your server or appliance:

curl -F "workerName=CMSSigner1" -F "file=@firmware.bin" \
http://localhost:8080/signserver/process > firmware.sig

The following shows the HTTP traffic between the browser and the server, and the resulting signature file response:

Showing the HTTP traffic between the browser and the server — HTTP traffic between the browser and the server

Verify the Signature

For detached signatures, both the signature file and the original file are needed for verification. Use OpenSSL to verify a CMS detached signature:

openssl cms -verify -in firmware.sig -inform DER -content firmware.bin -CAfile ca.pem > /dev/null

-inform DER specifies that the signature file is in binary (DER) format.
The redirect to /dev/null suppresses the OpenSSL default behavior of printing the content of the signed file to stdout.

Replace firmware.sig and firmware.bin with your actual signature and content filenames, and ca.pem with your CA certificate file.

For example, if a file called software-release-1.0.zip is provided to the CMS Signer, the detached signature obtained is now stored in a file called software-release-1.0.zip.p7s.

openssl cms -verify -in software-release-1.0.zip.p7s -inform DER -content software-release-1.0.zip -CAfile ca.pem > /dev/null