Using Fortanix Data Security Manager with Microsoft CNG Provider and SignTool

1.0 Introduction

This article describes how to integrate Fortanix Data Security Manager (DSM) with Microsoft CNG Provider and SignTool.

It also contains the information that a user requires to:

• Prepare the Build Server and Code-Signing Workstation

• Configure Fortanix Data Security Manager for Microsoft CNG and Code-Signing integration

• Generate/Import Private Key and Certificate

• Verify signed-code

Fortanix-Data-Security-Manager (DSM) has a state-of-the-art code-signing solution that offers the following capabilities:

1. FIPS 140-2 level 3 assurance for private key protection.

2. Supports all types of asymmetric keys, signing, and hashing algorithms used for code signing. It also supports signing just the hash.

3. Code signing in large enterprises often requires verification of metadata associated with the data being signed as well as access control around the use of keys. These checks can easily be performed in a secure environment using plugins in Fortanix DSM.

4. Code signing keys are very sensitive, and their use should be tightly controlled. Fortanix DSM provides elaborate quorum-based policies to be configured for these keys which require approval from M of N administrators before the signing operation is performed. These approvals can be obtained in an asynchronous and distributed fashion.

5. Strict role-based access control, quorum-based approval workflows, automation, and audit logs for all code signing operations.

6. Support of 100% REST APIs, KMIP, PKCS11, JCE, Microsoft CAPI, and CNG for easy integration with your existing DevOps tooling.

7. Code signing is future-proof in Fortanix DSM. Post-quantum algorithms, such as LMS, are already supported and can be used for code signing.

2.0 Architecture Workflow

Microsoft’s SignTool is a prominent tool used in a Microsoft environment to sign and verify the authenticity of code developed for the Microsoft platforms. Fortanix KMS CNG Provider makes it easy to securely store sensitive objects/keys required during the sign and verify processes, a native feature provided by Fortanix DSM for enterprise-level code-signing capabilities.

3.0 Preparing the Build Server/Code-Signing Workstation

The Server/Workstation that will be running the SignTool must have the following installed:

• Fortanix KMS CNG Provider:

  • Link: Fortanix CNG EKM

    NOTE

    If you use the 32-bit CNG provider, you must use the 32-bit command prompt to execute all the commands mentioned in this article.

  • After installing, validate that the provider has been correctly registered. Since the CNG provider is not configured yet, you will see an error.

    certutil -csplist

    

• SignTool:

  • SignTool is now part of Windows SDK and is required.

  • Link: Windows 10 SDK

  For more information, refer to SignTool documentation.

4.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

4.1 Signing Up

To get started with the Fortanix Data Security Manager (DSM) cloud service, you must register an account at <Your_DSM_Service_URL>. For example, https://eu.smartkey.io.

For detailed steps on how to set up the Fortanix DSM, refer to the User's Guide: Sign Up for Fortanix Data Security Manager SaaS documentation.

4.2 Creating an Account

Access the <Your_DSM_Service_URL> on the web browser and enter your credentials to log in to the Fortanix DSM.

4.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

1. Click the Groups menu item in the DSM left navigation panel and click the + button on the Groups page to add a new group.

   

2. On the Adding new group page, enter the following details:

   • Title: Enter a title for your group.

   • Description (optional): Enter a short description for the group.

3. Click the SAVE button to create the new group.

The new group has been added to the Fortanix DSM successfully.

4.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

1. Click the Apps menu item in the DSM left navigation panel and click the + button on the Apps page to add a new app.

   

2. On the Adding new app page, enter the following details:

   • App name: Enter the name of your application.

   • Interface (optional): Select the REST API option as interface type from the drop down menu.

   • ADD DESCRIPTION (optional): Enter a short description for the application.

   • Authentication method: Select the default API Key as the method of authentication from the drop down menu. For more information on these authentication methods, refer to User's Guide: Authentication documentation.

   • Assigning the new app to groups: Select the group created in Section 4.3: Creating a Group from the list.

3. Click the SAVE button to add the new application.

The new application has been added to the Fortanix DSM successfully.

4.5 Copying the API Key

Perform the following steps to copy the API key from the Fortanix DSM:

1. Click the Apps menu item in the DSM left navigation panel and click the app created in Section 4.4: Creating an Application to go to the detailed view of the app.

2. On the INFO tab, click the VIEW API KEY DETAILS button.

3. From the API Key Details dialog box, copy the API Key of the app to be used later.

4. On the Build Server/Code-Signing Workstation, Fortanix KMS CNG Provider requires configuration variables. Fortanix DSM supports certificate-based authentication or API key-based authentication for a CNG client. For more information on the authentication steps, refer to the Developer's Guide: Client-Microsoft CNG Key Storage Provider

5. Confirm Fortanix KMS CNG Provider can communicate properly with Fortanix DSM:

   certutil -csp "Fortanix KMS CNG Provider" -key

5.0 Generate or Import the Private Key and Certificate

Securing the Private Keys and Certificates are the most critical tasks to ensure codes cannot be maliciously signed by offending parties. Fortanix supports two main methods in generating/importing and securing the appropriate Security Objects:

• Generate the Private Key using Fortanix DSM user interface (UI), create a Certificate Sign Request from SignTool, and then import the Certificate into Fortanix DSM after it is signed by a trusted Certificate Authority.

• Generate a Self-Signed Certificate by automatically creating the Private Key in Fortanix DSM through PowerShell. Then import the Certificate securely into Fortanix DSM.

5.1 Method 1 - Generate Private Key on Fortanix DSM/Generate CSR Using Certreq.exe

This method will generate the Private Key and Certificate sign request from Fortanix DSM and certreq.exe. Upon receiving a signed certificate from the trusted Certificate Authority, the certificate can then be imported into Fortanix DSM.

1. Create a new security object that will be the Private Key and assign it to the appropriate group (in this example, we will call the security object - wincryptoapp):  

   

2. Generate the Certificate Sign Request using the private key using the SignTool:

   1. Create a new file called inf in a temporary directory.

   2. Replace the following content into the file:

      1. Subject: X.509 distinguished name as used in the certificate.

      2. KeyContainer: Name of the security object created previously/Private Key.

      3. ProviderName: Based on the provider’s name when installing the Fortanix CNG Provider.

      4. MachineKeySet: Used to determine whether SignTool will check the current user or local machine for CNG configurations, as described in the Clients: Microsoft CNG Key Storage Provider. If this parameter is not set appropriately, the certificate sign request (CSR) will not be generated.

      5. UseExistingKeySet: Set to true to use the keys created already on Fortanix DSM.

         [NewRequest]
         Subject = "CN=wincryptoapp, OU=fyoo,O=Fortanix,C=AU"
         KeyContainer = "wincryptoapp"
         ;Uncomment the following line if using the machine key storage
         ;MachineKeySet = true
         ProviderName = "Fortanix KMS CNG Provider"
         UseExistingKeySet = true

   3. Type the following command to generate the Certificate Sign Request:

      certreq.exe -new request.inf request.csr

   4. This command will now generate a request.csr Certificate Sign Request file and should be sent to the trusted Certificate Authority to receive a signed Certificate.

3. After the signed Certificate is received, you can import the certificate into Fortanix DSM.

   

4. Keep a copy of the certificate on the server where the SignTool will be run from (the certificate can be exported from Fortanix DSM at any time).

5.2 Method 2 - Generate Self-Signed Certificate Locally Using PowerShell and Fortanix DSM

1. Launch PowerShell and create a new key as well as a self-signed certificate.

   $cert = New-SelfSignedCertificate -Subject "NewIIS2" -type codesigningcert -provider "Fortanix KMS CNG Provider" -certstorelocation Cert:\LocalMachine\My

   Cd Cert:\LocalMachine\My

   Get-ChildItem | Format-Table Subject, FriendlyName, Thumbprint –autosize

   certutil -store My

   

2. The Private Key should have been created within Fortanix DSM.

   

3. Export the certificate and key into a file.

   Export-Certificate -Cert (Get-Item Cert:\LocalMachine\My\<thumbprint-of-cert>) -FilePath C:\Test.cert

   certutil.exe -encode C:\Test.cert C:\Test.pem

   

4. (Optional) Import the certificate into Fortanix DSM:

   

6.0 Code-Signing Integration (Directly from Workstation)

1. Verify no other signatures are present on the file that will be signed:

   

2. Open a command prompt. Locate the file SignTool that is appropriate for your code (for example: x64, x86, and so on).

   

3. Verify that the key you wish to use to sign the code is available in the remote CNG provider:

   certutil -csp "Fortanix KMS CNG Provider" -key

   

4. The following command will sign the code specified in the SignTool and require the following parameters at a minimum to successfully run the SignTool:

   • /csp: The CNG provider you wish to use for the sign operation.

   • /kc: Key Container (also known as an alias) that will be used for the sign operation.

   • /f: Certificate generated from the Private Key stored in Fortanix DSM.

   • File to sign.

     For more details on the SignTool parameters, refer to Sign Command Options.

     signtool.exe sign /csp "Fortanix KMS CNG Provider" /kc "wincryptoapp" /f c:\temp\wincryptoapp.cer c:\temp\lala.ps1

     

     If you are using a certificate that is already stored in the certstore, you can skip the /csp and /kc parameters. Instead, use the /sha1 flag with the certificate's fingerprint.

     signtool.exe sign /sha1 <thumbprint-of-cert> C:\temp\lala.ps1 

     

     NOTE

     If the code signing certificate is cross-signed with an alternative trust path, create a .p7b certificate file instead of a .pem or .cer file using the following command and use it for signing:

     openssl crl2pkcs7 -nocrl -certfile certificatename.pem -certfile IntermediateCert.cer -out wincryptoapp.p7b -certfile CACert.cer
     
     signtool.exe sign /csp "Fortanix KMS CNG Provider" /kc "wincryptoapp" /f c:\temp\wincryptoapp.p7b c:\temp\lala.ps1

     Microsoft signtool has a known issue that causes the exit status to be non-zero even when the signing operation succeeds. To work around this issue, set the following environment variable before running signtool:

     set FORTANIX_SIGNTOOL_BUG_WORKAROUND=true

1. After the file has been signed, Fortanix DSM will log an event within the audit log to signify the private key was used to sign the code:

   

   

7.0 Verify Signed Code

The signed Code can also be verified using SignTool.

If a self-signed certificate is used, then it must be installed on the Server / Workstation you wish to verify from as it will not have a trusted root CA chain in the certificate. The use of a self-signed certificate should only be used in a test environment. The procedure to test is as follows:

1. If you do not have the certificate readily available, download the certificate from Fortanix DSM.

2. Right-click the downloaded/existing certificate file and install the Certificate. Ensure it is imported into the Trusted Root Certification Authority (in this example certificate fyoo was used):  

   

3. The following command will verify the code using SignTool and require the following parameters at a minimum to successfully run the SignTool:

   signtool verify /pa c:\temp\lala.ps1

   

8.0 Sign and Verify Microsoft Office Macro Files Using 32-Bit Sign Tool

For more details, refer to Using Fortanix Data Security Manager with 32-Bit SignTool for Signing and Verifying Microsoft Office Macro Files.

9.0 Frequently Asked Questions

1. How do I validate the supported algorithms and modes using Fortanix KMS CNG Provider?

• You can view all the supported methods, algorithms, and modes with Fortanix DSM using the CNG provider by running a csptest:

  certutil -csp "Fortanix KMS CNG Provider" -csptest