Digital Code Signing
- Thomas Ventimiglia
Introduction
Software that is distributed as a desktop app (e.g. a Windows EXE file) may raise security concerns, especially if it is downloaded from websites such as Github or Google Drive or shared outside of Princeton. For example, a browser may block a file from being downloaded, or antivirus software may prevent it from executing. This problem can be addressed somewhat by digitially signing this software. Applying a code-signing certificate to a file verifies its creator, and security software often will allow such files to be downloaded and executed.
PUL has a code-signing certificate that is currently used with some software produced by the East Asian Library (e.g. the Excel Alma Lookup plugin). This certificate simply lists the software publisher as “The Trustees of Princeton University”, so in principle it could be used for any software produced by PUL. However, signing a file requires the use of a hardware token that is physically attached to the device doing the signing. Thomas Ventimiglia (tventimi@princeton.edu) from the EAL currently holds this hardware token. This documentation describes the entire process for acquiring the token and certificate, though in practice it may be possible to reuse what we already have. In such a case, you can skip to the section “Digitally signing the file”.
Please note that signing the file will not necessarily prevent the Windows SmartScreen (aka “Windows protected your PC”) alert from appearing, though such an alert is only a warning and may be bypassed. This alert appears based on Microsoft’s own database of trusted software. Digitially signing the file will help build trust with Microsoft, but this will only change over time as more users download and install the software. However, even in such alerts, the publisher name will appear as “The Trustees of Princeton University”, assuring end users that the software is from a reliable source.
Acquiring the token and certificate
Submit a SN@P ticket to OIT describing the reason a new certificate is needed. An OIT representative will follow up to coordinate with the certificate authority Sectigo. Most likely, you will need to generate a Certificate Signing Request (CSR), and Attestation Certficate, as described below.
Puchase a YubiKey 5 FIPS series hardware token. Various models are available for different port types (USB-A, USB-C, Lightning, etc.). The token is essentially a flash drive containing a private key, though the key itself cannot be exported from token.
Install https://www.yubico.com/products/services-software/download/yubikey-manager/ on the device that will be signing the software. Note that if this program is being run via a Remote Desktop session, the YubiKey must be connected to the local device, not the one being accessed remotely. (And Remote Desktop must be configured to detect USB devices on the local machine).
Using this documentation on the Sectigo website, follow steps 1 and 2 to generate the CSR and Attestation Certificate. Note the following revisions to the documentation:
Instead of running the command “type attestation.crt intermediateCA.crt > attestation.pem”, manually concatenate the files by opening them in Notepad, then copying and paste their contents into an empty text file.
Instead of running the commands “certutil -encode attestation.pem attestation.b64” and
”findstr /v CERTIFICATE attestation.b64 > attestation.b64”, use the website Base64 Encode and Decode - Online to perform the Base 64 encoding. Manually copy the contents of the PEM file created in the previous step into the converter, click “Encode”, and then copy the results into an empty text file called “attestation.b64”.
These files will be needed to complete a form sent to you by Sectigo after OIT contacts them. Section 3.6 of the Sectigo documentation provides more details about this form.
After Sectigo approves the certificate request, you will receive an email with links to download the certificate.
Digitally signing the file (Windows) [Start here if resuing an existing certificate]
In the email sent to you by Sectigo, download the version of the certificate labeled “Certificate (w/ chain), PEM encoded”.
(This is the same as step 3 in the previous section, so you can skip this if you have already done it.) Install https://www.yubico.com/products/services-software/download/yubikey-manager/ on the device that will be signing the software. Note that if this program is being run via a Remote Desktop session, the YubiKey must be connected to the local device, not the one being accessed remotely. (And Remote Desktop must be configured to detect USB devices on the local machine).
Download the latest version of the YubiKey Minidriver. Do not install it yet.
Open PowerShell, and run the following command to install the driver
msiexec /i [Minidriver MSI] INSTALL_LEGACY_NODE=1Connect the YubiKey to your device.
If you have not already done so, change the default PIN in YubiKey Manager by going to the section Applications > PIV > PIN Management > Change PIN.
Install the Sectigo certificate on the YubiKey as described in step 4 of the Sectigo Documentation.
In PowerShell, run the command “certutil.exe -scinfo”. Enter the YubiKey PIN when prompted to do so.
Run the command “certmgr.msc”. This will open the Certificate Manager control panel. Go to the section “Personal > Certificates”, and double-click on the entry called “The Trustees of Princeton University”. In the dialog that appears, go to the “Details” tab. Scroll to the bottom and click the “Thumbprint” entry. Copy the string that appears in the box below it. (This string will be used in the command for signing the target file).
Navigate to the directory containing Windows SignTool with the command :
cd "C:\Program Files (x86)\Microsoft SDKs\ClickOnce\SignTool"Sign the target file with the following command (you will be prompted again for the YubiKey PIN):
.\signtool.exe sign /debug /sha1 [thumbprint] /fd SHA256 /t http://timestamp.sectigo.com [path to target file]Verify that the file was signed properly with the command:
.\signtool.exe verify /pa /debug [path to target file]