Tutorial: Sign Windows Files with Certificate Authentication and SignTool

Time to complete: approximately 30 minutes

This tutorial walks through the complete setup for a Windows developer who needs to sign executables using Signum with certificate-based authentication, from importing a signing certificate into Signum, through creating a user backed by a client certificate, all the way to running signtool.exe sign from the command line.

Prerequisites

Before you begin the tutorial, you need the following:

• A Signum Administrator account with access to the Admin Web Console

• Signum Windows Agent installed

• Windows SDK installed on the signing machine (provides signtool.exe)

• A signing certificate (.cer public key file) already issued by your CA and ready to import

• A client authentication certificate ( .cer for the admin console and .p12 for the user's machine)

• Your Signum instance URL from the Signum SaaS Portal

Step 1 - Import the Signing Certificate

The signing certificate is the code signing certificate your users will sign with. It must be imported into Signum before it can be assigned to a policy.

If you are generating a new key pair, Signum generates the CSR with the private key stored on the HSM. The key is never exportable. Generate the CSR in Requests, and send the CSR to your CA, then return to this step to import the signed .cer file once issued.

To import the certificate:

1. In the Admin Web Console, navigate to Certificates in the top menu.

2. Open the Certificate tab.

3. Click Import and follow the prompts to import a certificate that has already been signed by your CA.

4. Once imported, confirm the certificate appears in the Certificate List with a status of Enabled.

For full details, see Certificates and Requests.

Step 2 - Upload the Client Authentication Certificate

The client authentication certificate is a separate certificate used to identify the user when they log in to the Signum Agent. It is not the signing certificate. The admin uploads the public key (.cer) here, and the user installs the private key (.p12) on their own machine later.

1. In the Admin Web Console, navigate to Certificates in the top menu.

2. Open the Client Auth Certificates tab.

3. Click Upload and select the .cer file for the user's client authentication certificate.

4. Confirm the certificate appears in the table with the correct Subject and validity dates.

For full details, see Client Auth Certificates.

Step 3 - Create a Certificate User Domain

Signum organizes users by Domain type. To use certificate-based authentication, you need a Certificate User Domain.

1. Navigate to Access in the top menu.

2. Under the Domains tab, click New.

3. Set Domain Type to Certificate users.

4. Give the domain a descriptive name (for example, cert-users-engineering) and click Submit.

The new domain appears in the Domains list. You will add users to it in the next step.

For full details, see Certificate User Domain.

Step 4 - Create a Certificate-authenticated User

1. In the Domains tab, click on the Certificate User Domain you just created to open the Edit Domain popup.

2. Navigate to the Users tab and click New.

3. Under Signum Configurations, fill in:

   • Username: for example, alice@example.com

   • Name: the user's display name

   • Email: the user's email address

4. Under Client Certificate Chains, click Select Certificates and choose the certificate you uploaded in Step 2.

5. Optionally, add Attribute Matching Rules to restrict authentication to a specific certificate. For example, adding a Thumbprint rule ensures only one specific certificate can authenticate as this user.

6. Click Submit to save the user.

For full details, see Certificate User Domain.

Step 5 - Create a Signing Policy

A policy connects a certificate (what to sign with), a user (who can sign), and optionally an application restriction (what tools are allowed) and a time schedule (when signing is permitted). Without a policy or direct ownership linking the certificate to the user, a user cannot sign, even if they are authenticated.

1. Navigate to Policies in the top menu and click New.

2. General: Give the policy a name (for example, eng-codesign-policy), set Action to Allow, and leave Status as Enabled.

3. Certificates: Start typing to search and select the signing certificate imported in Step 1.

4. Who: Search for and select the user created in Step 4.

5. Where: Optionally restrict to specific applications. For an unrestricted policy, leave this empty or add a permissive application group. If you want to restrict to SignTool specifically, create an Application Group that matches signtool.exe and add it here.

6. When: Leave as Any Time for now, or configure a schedule if your security policy requires it.

7. Click Submit to save the policy.

For full details, see Creating a Policy.

Step 6 - Install the Client Certificate on the Signing Machine

The user (or the build machine) needs the private key, the .p12 file, installed locally so the Agent can use it to authenticate.

1. Copy the .p12 file to a secure, accessible location on the machine. Keyfactor recommends placing it in a path accessible to the SignumService Windows service, such as C:\ProgramData\Keyfactor\certs\.

2. Double-click the .p12 file to open the Certificate Import Wizard.

3. Select Local Machine as the store location.

4. Enter the certificate password when prompted.

5. Place the certificate in the Personal store (My).

6. Complete the wizard and click Finish.

7. Verify the import succeeded by running the following:

Get-ChildItem -Path Cert:\LocalMachine\My | Select-Object Subject, Thumbprint

8. Note the Thumbprint, as you will need it in the next step.

Step 7 - Configure the Agent to Authenticate with the Certificate

With the certificate in the local store, use signum-util setup to configure certificate-based authentication:

1. Open a PowerShell window as administrator.

2. Add the Keyfactor directory to your PATH for this session:

   $env:PATH = "C:\Program Files\KeyFactor\;" + $env:PATH
   

3. Run the following command, replacing [CERTIFICATE THUMBPRINT] with the thumbprint noted in Step 6:

   signum-util setup -h [HOSTNAME] -t [CERTIFICATE THUMBPRINT] -w 8443
   

   Example:

   signum-util setup -h signum.mydeployment.us.s.az.keyfactorsaas.com -t F78AE7871FEF1D0CF3EFFB58E9CC85F261438D2B -w 8443
   

Expected output:

Instance [URL] successfuly reached .
User [example@keyfactor] successfuly logged in URL.
New configuration saved successfully, some changes to system settings might require restarting SignumService.

The Agent is now authenticated and has access to the signing certificates from Signum that the user has been granted through the policy created in Step 5,

For full details, see Authenticate with Certificate.

Step 8 - Add the Signing Certificate to the Windows Certificate Store

Place the signing certificates into the Windows certificate store so SignTool can use them:

signum-util cs -a -t LocalMachine

The -t LocalMachine matches the store SignTool will read via its own /sm flag.

For full details, see Add Certificates to System Cryptographic Store.

Before signing, verify the signing certificate has been fetched from Signum and placed in the Local Machine certificate store:

Get-ChildItem -Path Cert:\LocalMachine\My | Where-Object {
    $_.EnhancedKeyUsageList.Contains(
        [Microsoft.PowerShell.Commands.EnhancedKeyUsageRepresentation]::new('Code Signing','1.3.6.1.5.5.7.3.3')
    )
} | ForEach-Object {
    Write-Output "CN: $(($_.Subject -split ',')[0] -replace '^CN=', ''), Thumbprint: $($_.Thumbprint)"
}

You should see output similar to:

CN: My Code Signing Cert, Thumbprint: F78AE7871FEF1D0CF3EFFB58E9CC85F261438D2B

If no certificates appear, check that the policy in Step 5 is enabled and that the user configuration in Step 4 is correct.

Step 9 - Sign a File with SignTool

With the signing certificate available in the store, you can now sign any file that SignTool supports, such as .exe, .dll, .msi, .cab, .ps1, .appx, and others.

Sign using the certificate thumbprint

Using the thumbprint is the most explicit and reliable method:

signtool.exe sign /fd SHA256 /sm /sha1 <signing-cert-thumbprint> example.exe

The /sm flag tells SignTool to look in the Local Machine store.

Sign using the certificate CN

Using the Common Name (CN) has the advantage that scripts continue to work after a certificate renewal, as long as the CN stays the same:

signtool.exe sign /fd SHA256 /sm /n "My Code Signing Cert" example.exe

Sign with a timestamp

It is strongly recommended to always include a timestamp. This ensures the signature remains valid after the certificate expires:

signtool.exe sign /fd SHA256 /sm /sha1 <signing-cert-thumbprint> /tr <your-tsa-url> /td SHA256 example.exe

Replace <your-tsa-url> with your organization's Time Stamp Authority URL.

A successful result looks like:

Done Adding Additional Store
Successfully signed: example.exe

Step 10 - Verify the Signature

Confirm the file was signed correctly:

signtool.exe verify /pa /v example.exe

A successful output includes the full signing certificate chain and ends with:

Successfully verified: example.exe

Number of files successfully Verified: 1
Number of warnings: 0
Number of errors: 0

If you see File is not timestamped, consider re-signing with a /tr flag as described above.

Troubleshooting

SignTool reports "No certificates were found that met all the given criteria" The signing certificate may be in the wrong store. Use the PowerShell listing commands to confirm which store contains the certificate.

The same certificate is assigned to more than one user If the agent fails to authenticate with the message "The certificate matches more than one user profile", go to the Certificate User Domain and ensure the client auth certificate is only assigned to a single user.

Next steps

• To sign other file types, see Signing Guides. The same policy and authentication setup applies to JAR signing, XML signing, and Office macro signing.

• To set up alerts for certificate expiration, see Alerts.