Important: This topic is for advanced users who want to use a custom (non-default) certificate - if you only want to enable code signing with the default settings, it should work out of the box. Please check the main topic: Enabling code signing
With the release of ISL Conference Proxy 4.4.2335.124 we have added support for using an external private key that is used to code sign programs on your ISL Conference Proxy, enhancing security and streamlining the signing process. The external private key can be located on cloud HSM, locally on HSM module or on a USB token. This article provides comprehensive instructions on configuring the setup on your end, ensuring a seamless integration with our new cloud HSM code signing feature.
In this guide, we have used Google Cloud HSM as the example for illustrating the setup process. However, the procedures outlined here are broadly applicable and should be similar for other HSM tools you may choose to use. By following the general steps provided, you can adapt the instructions to fit the specific requirements and interfaces of your preferred HSM service, ensuring successful implementation regardless of the platform.
The manual is separated into two topics:
- Google Cloud HSM Setup
- Configuration on ISL Conference Proxy
Google Cloud HSM Setup
Step 1 - Create Your Project
Begin by creating a new project in Google Cloud. This project will serve as the container for all your resources. Follow the instructions provided in this link to create your project.
Step 2 - Create a Key Ring
Once your project is set up, the next step is to create a key ring. A key ring is a logical grouping of keys in Google Cloud KMS. Detailed steps on how to create a key ring can be found here. Once you have done the setup of your key ring, navigate to the list of your Key Rings and click on the three dots under “Actions” and select “Copy resource name”. Save the copied value, create a new text file with the following content and replace the key_ring value with the copied resource name from your Key Ring:
---
tokens:
- key_ring: “projects/testproject/locations/europe-west10/keyRings/Test-KeyRing”
Save the created file as pkcs11-config.yaml and proceed to the next step.
Step 3 - Create a Key
After setting up your key ring and creating a configuration file, you need to create a key. This key will be used for signing your code. Instructions on how to create a key are available here. We have created a HSM key with “4096 bit RSA key PKCS#1 v1.5 padding - SHA512 Digest” Algorithm and set purpose as “Asymmetric sign”.
Step 4 - Create Service and Set Permissions
Finally, you will need to create a service account and set the appropriate permissions. This ensures that your service has the necessary permissions to access and use the keys for signing. Follow the Google Cloud documentation here to set up the service account. The roles that should be set for the service are “Cloud KMS CryptoKey Signer/Verifier” and “Cloud KMS Viewer”. Once you have set the correct permissions navigate to the created service → "Keys" → “Add Key” and select “Create new key”. Set Key type to “JSON” , click “Create” and save the downloaded file as we will need it in the ISL Conference Proxy configuration.
Configuration on ISL Conference Proxy
After completing the Google Cloud HSM setup, the next steps involve preparing and uploading the necessary files to the ISL Conference Proxy (ICP). Follow these instructions to ensure all files are correctly prepared and uploaded.
Step 1 - Prepare the Required Files
- Have the pkcs11-config.yaml file that you have saved in Step 2 of Google Cloud HSM Setup ready
- Have the .json file that you have saved in Step 4 of Google Cloud HSM Setup ready
- Ensure you have a “.crt” file that is digitally signed by a provider of your choice ready. This file will be used for signing your applications.
- If your ICP server is hosted on a Windows machine , download the “pkcs11.dll” file (or any other OpenSSL engine that allows accessing PKCS#11 modules) from its respective source. If your ICP server is hosted on a Linux machine download the “pkcs11.so” file from its respective source. We have used this repository
- If your ICP server is hosted on a Windows machine, download the “kmsp11.dll” from its respective source. If your ICP server is hosted on a Linux machine, download the “libkmps11.so” file from its respective source. We have used the file from here
- As we are using a Google Cloud HSM in this guide, we have to download Google roots.pem file . Download the file from its respective source. We have used the file from here
Step 2 - Upload the Required Files To The ISL Conference Proxy
Once all files are prepared, they need to be uploaded to the ISL Conference Proxy. Navigate to your ISL Conference Proxy configuration page ( ICPADDRESS/conf) and login. Once you're logged in go to “Configuration” → “Advanced” → “File storage” and click on “Private” tab. Upload all prepared files on this page.
Step 3 - Configure ISL Conference Proxy settings
After you upload all the files to the ISL Conference Proxy, you have to set certain settings on the server in order to enable Custom Code Signing Certificate. On the /conf page navigate to “Configuration” → “Security”.
On this page we'll have to configure certain settings:
Authenticode tool environment
Find the setting “Authenticode tool environment”, uncheck it and set the following value.
KMS_PKCS11_CONFIG=objects/pkcs11-config.yaml
GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=objects/roots.pem
GOOGLE_APPLICATION_CREDENTIALS=objects/test-53e67ae3ac8a.json
For the KMS_PKCS11_CONFIG value set .yaml file that we have saved in Step 2 of Google Cloud HSM Setup, for the GRPC_DEFAULT_SSL_ROOTS_FILE_PATH set the google roots.pem file, for the GOOGLE_APPLICATION_CREDENTIALS set the .JSON file that you have downloaded in Step 4 of Google Cloud HSM Setup. “objects/” must be set before the file name as it is the location where the files are saved on ISL Conference Proxy.
Authenticode tool arguments
Find the setting “Authenticode tool arguments”, uncheck it and set the following value:
-pkcs11engine
{platform=linux}objects/pkcs11.so
{platform=windows}objects/pkcs11.dll
-pkcs11module
{platform=linux}objects/libkmsp11.so
{platform=windows}objects/kmsp11.dll
-certs
objects/test.crt
-key
pkcs11:object=Test-Key
Note: The arguments defined in the setting are passed directly to the “osslsigncode” tool. In case the tool that you are using has different arguments, you can set them here.
For the "-pkcs11engine" and "-pkcs11module" value set either value for linux or windows, depending on the operating system of the machine where ISL Conference Proxy is hosted. If you have a GRID setup where your host machines are linux and windows, you can set both values and the correct one is used by ISL Conference Proxy.
For the “-certs” value set the name of the certificate with which you will sign the applications.
For the “-key” value set the value “pkcs11:object=Test-Key”, where you replace the “Test-Key” with the name of your HSM Key that you have created in Step 3 of Google Cloud HSM Setup.
Use authenticode from license
Uncheck the checkbox next to the setting “Use authenticode from license” and set the value to “No”
Authenticode enabled
Uncheck the checkbox next to the setting “Authenticode enabled” and set the value of the setting to “Yes”.
Authenticode hash function
Uncheck the checkbox next to the setting “Authenticode hash function” and set the value to the hash function that is used for hashing. In our case we have set the value to “SHA512”.
Use an external certificate and key for Authenticode
Uncheck the checkbox next to the setting “Use an external certificate and key for Authenticode” and set the value to “Yes”.
Now you have set all the necessary configuration on this page, scroll down to the bottom of the page and select “Save”.
If everything is set correctly, custom code signing is now available on your ISL Conference Proxy! Try and download the applications and assert that custom code signing is working correctly.
LEGACY APPROACH
Important: This approach is no longer available due to code signing changes. Read more about the topic here.
It is possible to enable custom code signing by uploading the appropriate certificate for your company (this certificate is also known as Microsoft Authenticode certificate) to the ISL Conference Proxy and enabling appropriate options. This means that executables downloaded from ISL Conference Proxy (e.g. ISL Light Desk, ISL Light Client etc.) will be digitally signed using your certificate with the appropriate issuer name (e.g. MyCompany Ltd.).
The general procedure is described below, please refer to your certificate provider's website for detailed instructions about verifying your identity, submitting your CSR and downloading the resulting certificate.
You will need two files:
- your private key (you use this private key to generate a CSR for your certificate provider)
- your code signing certificate (you get this file from your certificate provider as a reply to your CSR)
Useful OpenSSL conversion commands
Usually you receive a PKCS#7 file (usually called SPC) from your certificate provider - this is your code signing certificate, save it as codesign-cert.p7b. You have generated your private key when generating your CSR. Save your private key as codesign-key.pem and proceed to the next section.
In some cases you receive a PKCS#12 bundle (sometimes called PFX) from your certificate provider and this file contains both the private key and the certificate, so you will need to extract the private key and the code signing certificate from it before proceeding.
The easiest way to do this is through a series of OpenSSL commands (we refer to the bundle as codesign_bundle.pfx):
- Extract the private key from the bundle:
$ openssl pkcs12 -in codesign_bundle.pfx -out codesign-key.pem -nocerts
- Extract the code signing certificate from the bundle:
$ openssl pkcs12 -in codesign_bundle.pfx -out codesign-cert.pem -nokeys
- Convert the code signing certificate into PKCS#7 binary format (DER):
$ openssl crl2pkcs7 -certfile codesign-cert.pem -nocrl -outform DER -out codesign-cert.p7b
Now you have both required files and you can proceed with the steps below.
Private key
The private key file for ISL Conference Proxy (we will refer to it as codesign-key.pem in this example) needs to be in plain text (PEM format) - if you open it with any text editor, you should see the following:
-----BEGIN RSA PRIVATE KEY-----
(... your private key ...)
-----END RSA PRIVATE KEY-----
You can check your private key with the following command:
$ openssl rsa -in codesign-key.pem -check -noout
It should output RSA key ok.
If your private key is protected by a passphrase, you will need to enter it later on in the ISL Conference Proxy settings.
Code signing certificate
The code signing certificate needs to be in PKCS#7 binary format (DER).
You can check the file with the following command:
$ openssl pkcs7 -in codesign-cert.p7b -inform DER -print_certs
It should output the appropriate subject and issuer and below it, the certificate in PEM format:
subject=(... your code sign certificate subject ...) issuer=(... info about the issuer ...) -----BEGIN CERTIFICATE-----
(... your code sign certificate...)
-----END CERTIFICATE-----
Important: If there is more than one certificate in your p7b file, please check that the first certificate in the list is your certificate (check the CN part of the subject line), not the certificate vendor's root or intermediate certificate. If your certificate is not the first, you will need to reorder it - these are the steps:
Copy the output of the previous command into a new text file, then adjust the order of the certificates so that your certificate is placed first. Save this as codesign-cert-new.pem and then use the following openssl command to convert it into the binary format (DER):
$ openssl crl2pkcs7 -certfile codesign-cert-new.pem -nocrl -outform DER -out codesign-cert.p7b
Check the new (reordered and converted) codesign-cert.p7b file:
$ openssl pkcs7 -in codesign-cert.p7b -inform DER -print_certs
If the first certificate in the output is your certificate, then you can proceed.
Once you have both files in the required format, you can put them to the ISL Conference Proxy server.
Uploading certificate files to ISL Conference Proxy
The easiest way to put both files to ISL Conference Proxy is to upload them to the private file storage by following these steps:
- Login to your ISL Conference Proxy administration (http://localhost:7615/conf).
- Go to Configuration -> Advanced ->File storage -> Private.
- Click Choose..., select the private key file and click Upload.
- Repeat step 3 for the code signing certificate file.
- Both files will be shown in the list below - upload complete.
Now you are ready to enable the code signing.
Enabling code signing
- Login to your ISL Conference Proxy administration (http://localhost:7615/conf).
- Go to Configuration -> Security.
- Scroll to the bottom, uncheck the checkbox in front of Use authenticode from license and change the setting to No.
- Scroll to the bottom, uncheck the checkbox in front of Authenticode enabled and change the setting to Yes.
- Uncheck the checkbox in front of Authenticode publisher certificate file (PKCS#7) and paste the appropriate file location - in this case: objects/codesign-cert.p7b
- Uncheck the checkbox in front of Authenticode private key file (PEM) and paste the appropriate file location - in this case: objects/codesign-key.pem
- If your private key is protected by a passphrase, click change next to Authenticode private key passphrase and enter the appropriate passphrase.
- Click Save to apply these settings.
Now you can proceed to testing.
Testing
Now you can test if it works properly - simply download ISL Light Client (http://serveraddress:7615/start/ISLLightClient) and save it to your desktop. Right-click the executable and select Properties - you should see the Digital Signatures tab with details about the signature.
Important: If you get an internal server error when trying to download, then code signing failed. In that case please go back into settings and disable authenticode, then check both certificate files again and make sure they are in the correct format. If you are using an encrypted private key, please make sure the passphrase is set correctly.
If everything seems fine but it still does not work properly or if you get stuck at one of the steps, you can contact us via e-mail (support@islonline.com) or come to our live chat (at http://www.islonline.com/) and we will be glad to help.