Microsoft Authenticode
This guide outlines step-by-step instructions for seamlessly integrating Microsoft Authenticode with a Luna HSM device or Luna Cloud HSM service. Microsoft Authenticode is a robust code-signing technology that verifies both the identity of software publishers and the integrity of the code using cryptographic techniques and trusted certificate authorities (CAs). Users can confirm software origin by following a chain of certificates to a well-known root certificate. In essence, Microsoft Authenticode is a crucial tool in the realm of secure software distribution, ensuring that software remains unaltered and genuine from the moment it's signed and published.
The key benefits of this integration are:
-
Secure generation, storage, and protection of the identity signing private keys using either FIPS 140-2 or FIPS 140-3 Level 3 validated hardware.
-
Full life cycle management of the keys to ensure their integrity and reliability throughout their usage.
-
Maintenance of a comprehensive HSM audit trail for transparency and accountability in key operations. It's important to note that Luna Cloud HSM service does not have access to this secure audit trail.
-
Significant performance enhancements by offloading cryptographic operations from application servers.
Supported Platforms
This integration has been tested and verified on the following platforms:
| HSM Type | Platform Tested |
|---|---|
| Luna HSM | Windows 2019 Server Windows 2016 Server Windows Server 2012R2 |
| Luna Cloud HSM | Windows 2019 Server Windows 2016 Server Windows Server 2012R2 |
This integration been tested using Luna Client in both High Availability (HA) and FIPS-compliant modes.
Prerequisites
The prerequisites for this integration are:
Set up Luna HSM
As the first step to accomplish this integration, you need to set up either On-Premise Luna HSM or Luna Cloud HSM.
Set up On-Premise Luna HSM
Follow these steps to set up your on-premise Luna HSM:
Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.
Create a partition that will be later on used by Microsoft Authenticode.
Create and exchange certificate between the Luna Network HSM and client system. Register client and assign partition to create an NTLS connection.
Initialize Crypto Officer and Crypto User roles for the registered partition.
Run the following command to verify that the partition has been successfully registered and configured:
C:\Program Files\SafeNet\LunaClient>lunacm.exe
Upon successful execution, you should observe an output similar to the example provided below:
lunacm.exe (64-bit) v10.2.0-111. Copyright (c) 2020 SafeNet. All rights reserved. Available HSMs: Slot Id -> 0 Label -> HSM7 Serial Number -> 1213475834614 Model -> LunaSA 7.3.0 Firmware Version -> 7.3.0 Configuration -> Luna User Partition With SO (PW) Signing With Cloning Mode Slot Description -> Net Token Slot FW HW Status -> FM Ready
Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.
Set up Luna HSM in FIPS Mode
To configure Luna HSM in FIPS Mode, update the configuration file by adding or modifying the following setting within the [Misc] section:
RSAKeyGenMechRemap=1
This setting ensures that older calling mechanisms are redirected to the approved RSA key generation methods (186-3 with primes and 186-3 with aux primes) required for FIPS compliance. By making this configuration change, Luna HSM will be properly set up to operate in FIPS mode, adhering to the approved RSA key generation standards.
The configuration setting mentioned above, RSAKeyGenMechRemap=1, is not required for the Universal Client. It is applicable only for Luna Client 7.x.
Set up Luna Cloud HSM
The following steps are applicable for setting up the Luna Cloud HSM on a Windows environment:
Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means
Extract the .zip file into a directory on your client workstation.
Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.
cvclient-min.zip
Run the setenv script to generate a new configuration file with the necessary information for the Luna Cloud HSM service. Right-click setenv.cmd and select Run as Administrator.
To add the configuration to an already installed UC client, use the –addcloudhsm option when running the setenv script.
Run the LunaCM utility and verify that the Cloud HSM service is listed.
If your organization requires non-FIPS algorithms for your operations, ensure that the Allow non-FIPS approved algorithms check box is checked. For more information, refer to Supported Mechanisms.
Set up Microsoft Authenticode
Follow these steps to set up Microsoft Authenticode:
Acquire the Windows SDK: To initiate your Microsoft Authenticode setup, ensure you have the Windows SDK installed on your system. This SDK includes essential Authenticode programs like makecert and cert2spc.For comprehensive guidance on acquiring and installing the Windows SDK, please consult the official Microsoft Windows SDK installation documentation.
Optionally, incorporate the Office Smart Tags SDK: If you intend to showcase the capabilities of Authenticode, this integration guide may involve the utilization of the Microsoft Office Smart Tags SDK. For detailed instructions on obtaining and integrating the Microsoft Office Smart Tags SDK, please refer to the official installation documentation provided by Microsoft.
Integrate Luna HSM with Microsoft Authenticode
Integrating Luna HSM with Microsoft Authenticode involves the following steps:
Configure SafeNet Cryptographic Storage Provider
To configure the SafeNet Cryptographic Service Provider (CSP) for certificate generation in Authenticode, proceed with the following steps:
Ensure the Luna Cryptographic Service Provider (CSP) is configured on your Windows Server 2012 R2/2016/2019 system.
Run the command "register.exe" within the Luna CSP directory:
<Luna Client Installation Directory>\CSP>register.exe
Register the Luna Cryptographic Services for Microsoft Windows:
<Luna Client Installation Directory>\CSP>register.exe /l
Configure SafeNet Key Storage Provider
To allow access to the Luna HSM, you must configure the SafeNet Key Storage Provider (KSP). Here's how:
Navigate to the <Luna HSM Client Installation Directory>/KSP directory.
Run the KSP configuration wizard: KspConfig.exe.
Register or view the security library by browsing the cryptoki.dll library from the Luna HSM Client installation directory. On successful registration, you'll see a message confirming the registration.
Register the HSM slot for Domain\User.
Register the same slot for NT AUTHORITY\SYSTEM.
Generate a certificate using the makecert command in conjunction with the Luna CSP named Luna Cryptographic Services for Microsoft Windows. Use the following command format:
makecert -sk mykey -sp "Luna Cryptographic Services for Microsoft Windows" -n "CN=MS-AuthCode" -r -ss mystore Test.cer -a sha256 -len 2048
| Parameter | Description |
|---|---|
| -sk | The location of the subject’s key container holding the private key. |
| -sp | Subject CryptoAPI’s provider name. |
| -n | The name and details of the publisher’s certificate. |
| -ss | The name of the subject’s certificate store where the generated certificate is stored. |
| -a: | The signature's digest algorithm (choose from md5, sha1, sha256, sha384, sha512). Default is sha1. |
| -len | Generated key length (bits) (Default to 2048 for RSA and 512 for DSS). |
Create a Software Publishing Certificate (SPC) from the generated certificate using the cert2spc command:
cert2spc Test.cer Test.spc
Sign and timestamp your code
Sign and timestamp your code, using the signtool sign command with the Software Publishing Certificate (SPC). Follow this command format:
signtool sign /verbose /certificate "Publisher’s Certificate" /password "HSM Partition Password" /csp "Cryptographic Service Provider Name" /container "Key Container Name" /timestamp "Time Stamping URL" /file "File to be signed"
| Parameter | Description |
|---|---|
| /v | Enable verbose mode for detailed output. |
| /certificate | Specify the publisher's certificate. |
| /password | Provide the HSM partition password. |
| /csp | Define the Cryptographic Service Provider (CSP) name. |
| /container | Specify the name of the container containing the signing key. |
| /timestamp | Set the URL for the timestamp server. |
| /file | Indicate the file to be signed. |
Integrate Luna HSM with Microsoft Strong Name
Microsoft Strong Name provides a powerful way to give .NET Framework assemblies unique identities. Strong-naming an assembly involves signing it during the build process using a private key, which corresponds to the public key in the strong name. This signature can be verified using the public key. To integrate Luna HSM with Microsoft Strong Name, follow these steps:
Configure SafeNet Cryptographic Storage Provider
To enable Microsoft Strong Name to work with a Luna HSM, you must set up the SafeNet Cryptographic Service Provider (CSP) to generate keys and certificates required for Microsoft Authenticode. Here's how to proceed:
Open a command prompt.
Navigate to the Luna Client Installation Directory, and run the following command:
<Luna Client Installation Directory>\CSP>register.exe
Register the Luna Cryptographic Services for Microsoft Windows:
<Luna Client Installation Directory>\CSP>register.exe /l
Configure SafeNet Key Storage Provider
Configuring the SafeNet Key Storage Provider (KSP) allows both user accounts and the system to access the Luna HSM. To configure the SafeNet Key Storage Provider:
Install the KSP package during the Luna Client software installation, if you are using a Luna HSM. If you are using a Luna Cloud HSM, the KSP package is included in the HSMoD service client package, which you can find inside the /KSP directory.
Navigate to the <Luna HSM Client Installation Directory>/KSP directory.
Run the KspConfig.exe (KSP configuration wizard).
Double-click Register Or View Security Library.
Browse the cryptoki.dll library from the Luna HSM Client installation directory or the HSMoD service client package and click Register. After successful registration, you will see a message confirming the successful registration of the security library.
Double-click Register HSM Slots on the left side of the pane.
Enter the Slot (Partition) password.
Click Register Slot to register the slot for Domain\User. Upon successful registration, a message stating "The slot was successfully and securely registered" will be displayed.
Register the same slot for NT AUTHORITY\SYSTEM.
Generate a certificate using the makecert command and the Luna CSP "Luna Cryptographic Services for Microsoft Windows." Use the following command as a template:
makecert -sk <keyContainer> -sp "Luna Cryptographic Services for Microsoft Windows" -n "CN=Common Name" -ss <certStore> CertificateName.cer -a sha256 -len 2048
| Parameter | Description |
|---|---|
| -sk | Location of the subject's key container holding the private key. |
| -sp | Subject CryptoAPI's provider name. |
| -n | Name and details of the signer's certificate. |
| -ss | Name of the subject's certificate store in which the generated certificate will be stored. |
| -a |
Signature's digest algorithm (e.g., sha256). |
| -len |
Generated Key Length (e.g., 2048 for RSA). |
Make the Luna CSP the default CSP to use with Microsoft Strong Name using the following command:
sn.exe -c "Luna Cryptographic Services for Microsoft Windows"
Extract the public key from the key-pair that has been generated previously:
sn.exe -pc mykey mykey.snk
Replace mykey with the name of the key container and mykey.snk with the name of the public key file.
Sign a .NET Assembly
You can utilize MS Strong Name to sign a .NET Assembly. To sign a .NET assembly, follow these steps:
Write a C# program, then open the Visual Studio command prompt and compile the program. Delay sign the generated executable file using the following command:
csc /delaysign+ /keyfile:"C:\Program Files (x86)\Microsoft SDKs\Windows\v8.1A\bin\NETFX 4.5.1 Tools\x64\mykey.snk" C:\Users\Administrator\Desktop\myapp.cs
Here, /keyfile should reference the public key extracted from the key-pair generated in a previous command.
Sign the generated executable using Strong Name with the following command:
sn.exe -Rc C:\Users\Administrator\Desktop\myapp.exe mykey
In this command, mykey should correspond to the key container where you generated the key-pair.
Confirm that the assembly has been Strong Name signed using this command:
sn.exe -v C:\Users\Administrator\Desktop\myapp.exe
Integrate Luna HSM with Microsoft Mage/ClickOnce
Microsoft's Mage.exe is a command-line tool for generating and editing manifests in .NET Framework applications. This guide assumes you have a Windows application ready for deployment, referred to as AppToDeploy. Please note that Mage.exe is a 32-bit application, so you need to use the 32-bit Luna Client with the 32-bit CSP. Luna HSM is employed to protect and safeguard the signing keys used for digitally signing applications deployed through Microsoft Mage/ClickOnce. The primary purpose is to prevent any unauthorized or malicious individuals or entities from gaining access to these critical signing keys. This integration guide covers the following topics:
Configure SafeNet Cryptographic Storage Provider
To use Microsoft Mage/ClickOnce with a Luna HSM, you must configure the SafeNet Cryptographic Service Provider (CSP) for generating keys and certificates. Follow these steps:
Install Luna Cryptographic Service Provider (CSP) on Windows Server:
- Open the command prompt and run
register.exeto register the Luna CSP. The general command format is:
<Luna Client Installation Directory>\win32\csp>register.exe
- To register the Luna Cryptographic Services for Microsoft Windows, use this command format:
<Luna Client Installation Directory>\win32\csp>register.exe /l
Generate a certificate using the makecert command and the Luna CSP Luna Cryptographic Services for Microsoft Windows. Use the following command as a template:
makecert -sk <keyContainer> -sp "Luna Cryptographic Services for Microsoft Windows" -n "CN=Common Name" -ss <certStore> CertificateName.cer
| Parameter | Description |
|---|---|
| -sk | The location of the subject's key container that holds the private key. |
| -sp | Name of the subject's CSP. |
| -n | The name and details of the signer's certificate. |
| -ss | The name of the subject's certificate store in which the generated certificate will be stored. Use My, which is the default user certificate store where the application looks for certificates. |
After generating the certificate, use it in Visual Studio to sign the Application/Deployment manifest:
-
Open the Properties window of the project.
-
Click Signing and select Sign the ClickOnce manifests.
-
Click Select from Store..., choose the certificate generated in step 2, and then click OK to confirm your selection.
Deploy an application with the Mage.exe command-line tool
To deploy applications using the Mage.exe command-line tool, follow these steps:
Prepare Your Deployment Directory: Create a directory to store your ClickOnce deployment files. Inside this directory, create a version subdirectory. If it's the first deployment, name this version subdirectory 1.0.0.0.
Copy Application Files: Copy all application files, including executables, assemblies, resources, and data files, into the version subdirectory. If needed, create additional subdirectories to contain extra files.
Open the Command Prompt: Open the Windows SDK or Visual Studio command prompt and navigate to the version subdirectory you created in step 1.
Create the Application Manifest: Generate the application manifest with Mage.exe. Use the following command to create an application manifest for code compiled to run on the msil processor:
mage -New Application -Processor msil -ToFile AppToDeploy.exe.manifest -name "MyApp" -Version 1.0.0.0 -FromDirectory .
Sign the Application Manifest: Sign the application manifest with an Authenticode certificate.
mage -Sign AppToDeploy.exe.manifest -CertHash "Certificate Hash"
Verify the Certificate Hash: Use certutil.exe to retrieve the certificate hash value with the following command:
Certutil -verifystore -user My
My is the user certificate store where the certificate was generated using the makecert command.
Navigate to the Deployment Directory: Change to the root of the deployment directory.
Create the Deployment Manifest: Generate the deployment manifest with Mage.exe. By default, Mage.exe marks your ClickOnce deployment as an installed application, making it available both online and offline. To make it available only when the user is online, use the -Install option with a value of false.
mage -New Deployment -Processor msil -Install true -Publisher "My Company" -ProviderUrl "\\myServer\myShare\AppToDeploy.application" -AppManifest 1.0.0.0\AppToDeploy.exe.manifest -ToFile AppToDeploy.application
Sign the Deployment Manifest: Sign the deployment manifest with the Authenticode certificate.
mage -Sign AppToDeploy.application -CertHash "Certificate Hash"
Copy Deployment Files: Copy all the files in the deployment directory to the deployment destination, which may be a website, FTP site, file share, or CD-ROM.
Provide Access Information: Provide your users with the URL, UNC path, or physical media required to install your application. If providing a URL or UNC path, include the full path to the deployment manifest.
Integrate Luna HSM with Microsoft HCK
Microsoft's Hardware Certification Kit (HCK) comprises tools, documentation, and tests from Microsoft, designed to aid hardware manufacturers and developers in verifying that their hardware devices are compatible and dependable with the Windows operating system. The integration of Luna HSM with HCK enables hardware manufacturers to ensure the security, trustworthiness, and consistency of their products throughout the HCK certification process. The key steps involved in this integration are as follows:
Configure SafeNet Cryptographic Storage Provider
To utilize Microsoft Mage/ClickOnce with Luna HSM, configure the SafeNet Cryptographic Service Provider (CSP) to generate keys and certificates for Microsoft Mage/ClickOnce. Follow these steps:
Install Luna Cryptographic Service Provider (CSP) on Windows Server:
- Open the command prompt and register Luna CSP using the following command format:
<Luna Client Installation Directory>\win32\csp>register.exe
- To register Luna Cryptographic Services for Microsoft Windows, use this command format:
<Luna Client Installation Directory>\win32\csp>register.exe /l
Verify Registered Cryptographic Providers: Browse to "C:\Windows\SysWOW64" and execute certutil –csplist to verify the registered cryptographic providers.
Generate Signing Certificate: To integrate Luna HSM with Microsoft HCK, you must generate a certificate using Luna CSP Luna Cryptographic Services for Microsoft Windows. The certificate must be signed, and the signer certificate must be trusted in the Trusted Root Certificate Authority.
Sign the package
You can sign the package using one of the following methods:
Sign the package using a CA-signed certificate
To sign the package using a CA-signed certificate, follow these steps:
Create an INF File: Create an INF file with the following attributes:
[Version]
Signature="$Windows NT$"
[NewRequest]
Subject = "C=US,O=SafeNet,CN=HCK,OU=HCKIntegration"
KeySpec = 1
KeyLength = 2048
Exportable = FALSE
MachineKeySet = TRUE
KeyContainer = HCK
ProviderName = "Luna Cryptographic Services for Microsoft Windows"
ProviderType = 1
KeyUsage = 0x04
Generate a Certificate Request: Generate a certificate request using the INF file. Use the 32-bit certreq utility from the "C:\Windows\SysWOW64" directory. You should receive a success message after execution.
Obtain a Signed Certificate: Take the generated certificate request to a Certificate Authority (CA) and obtain a signed certificate.
Import the Signed Certificate: Import the obtained certificate into the user's personal certificate store. Use the 32-bit Microsoft Certificate Manager console:
C:\Windows\SysWOW64\certmgr.msc
Verify Certificate Import: Right-click Personal -> All Tasks -> Import and follow the instructions to import the signed certificate. Double-click the certificate and ensure that it has a private key associated with it.
Map the Private Key with Certificate: Open the certificate, go to the Details tab, and select the Serial Number field. Copy the serial number or thumbprint and execute the following command from the SysWOW64 directory to map the private key on the HSM with the certificate:
certutil -repairstore -user My "SerialNumber or ThumbPrint"
Verify Private Key Mapping: After the repairstore command successfully executes, refresh the Certificate Manager snap-in, open the certificate, and ensure the message at the bottom is displayed.
Sign the package using a self-signed certificate
Follow these steps to sign the package using a self-signed certificate:
Generate a Self-Signed Certificate: Use the makecert utility to create a self-signed certificate. Go to the C:\Program Files (x86)\Windows Kits\8.1\bin\x86 directory and run the following command:
makecert -sk <keyContainer> -sp "Luna Cryptographic Services for Microsoft Windows" -r -n "CN=Common Name" -ss <certStore> CertificateName.cer
| Parameter | Description |
|---|---|
| -sk | Location of the subject's key container holding the private key. |
| -sp | Subject CryptoAPI's provider name. |
| -n | Name and details of the signer's certificate. |
| -ss | Name of the subject's certificate store where the generated certificate will be stored. Use My, which is the default user certificate store that the application searches for. |
Export the Generated Certificate: Open certmgr.msc from the C:\Windows\SysWOW64 directory and export the generated certificate from the Personal folder.
Import the Certificate: Import the certificate into the Trusted Root Certificate Authority folder and verify that the import was successful.
Launch Windows Hardware Certification Kit: Open the Windows Hardware Certification Kit and import the project that requires signing.
Verify the Imported Project: Navigate through various tabs to ensure that the imported project is correct.
Sign the Package: In the Package tab, click Create Package to sign the package. This action prompts for Signing Options. Select Use Certificate Store and click OK.
Choose the Signing Certificate: From the pop-up, select the certificate imported earlier from the local machine's personal certificate store, and click OK.
Select a Save Location: Choose a location to save the signed package and click Save.
Start the Signing Process: Click Save to initiate the signing process. A Creating Package window will appear.
Verify Success: Once the signing is complete, a success message will appear. You can verify the signed package in the location where you saved it.
Troubleshooting
Problem:
When running the makecert command on an HSM in FIPS mode, you encounter the following error:
Error: CryptHashPublicKeyInfo failed => 0x80090005 (-2146893819) Failed.
Solution:
This error occurs because the certificate always has an MD5 hash. To resolve this issue, you need to configure the Luna CSP to perform MD5 hashing in software. Follow these steps:
Open the command prompt and navigate to the directory where Luna Client is installed:
<Luna Client Installation Directory>\CSP
Run the following command to register the MD5 algorithms in software:
Register.exe /algorithms
This command prompts you to register various algorithms, and you specifically need to register the MD5 algorithms in software. By configuring the Luna CSP to handle MD5 in software, you can address the error and successfully use the makecert command on your HSM in FIPS mode.
