Firma con KeyLocker cloud HSM

Questo articolo ti insegnerà a firmare utilizzando il cloud e KeyLocker HSM. La guida è rilevante per tutte le piattaforme e diversi strumenti di firma - da signtool a jarsigner. Le informazioni fornite sono anche la base per firmare utilizzando il Software Trust Manager di DigiCert ONE; il principio della firma è valido per entrambi i servizi.

Compatibilità di KeyLocker

Sicuramente prima di provare KeyLocker ti chiederai se potrà essere utilizzato nel tuo workflow e se funzionerà per te. KeyLocker e le librerie correlate supportano (così come il Software Trust Manager in DC1) strumenti di firma di terze parti. Sul sito web di DigiCert troverai nell'articolo Integrazione con strumenti di firma una panoramica completa dei formati di file che puoi firmare con strumenti compatibili utilizzando KeyLocker.

Qui menziono solo il più diffuso Signtool nelle versioni a 32 e 64 bit:

  • SignTool (32-bit): .doc, .docm, .dot, .dotm, .msi, .cab, .exe, .dll, .mpp, .mpt, .pot, .potm, .ppa, .ppam, .pps, .ppsm, .ppt, .pptm, .pub, .vdw*, .vdx*, .vsd*, .vsdm, .vss*, .vssm, .vst*, .vstm, .vsx*, .vtx*, .wiz*, .xla, .xlam, .xls, .xlsb, .xlsm, .xlt, .xltm
  • SignTool (64-bit): .appx, .appxbundle, .arx, .cab, .cat, .cbx, .cpl, .crx, .dbx, .deploy, .dll, .drx, .efi, .exe, .js, .msi, .msix, .msixbundle, .msm, .msp, .ocx, .psi, .psm1, .stl, .sys, .vbs, .vsix, .wsf, .xsn

Guida in KeyLocker

Dopo l'accesso a KeyLocker, vedrai una guida alla configurazione che ti aiuterà a creare le credenziali di autenticazione necessarie.

Salva attentamente le credenziali di autenticazione, perché senza di esse non sarà possibile firmare. Salva il certificato di autenticazione sul computer dove firmerai. La password di questo certificato (PFX) dovrai salvarla in una variabile di sistema o inserirla nella guida.

Le credenziali di autenticazione vengono ottenute nella guida di KeyLocker

Configurare l'ambiente di firma

Prima di firmare, è necessario configurare nel sistema le variabili e l'autenticazione. Puoi farlo manualmente nelle impostazioni di sistema, oppure utilizzare la guida di DigiCert, inclusa nell'applicazione Click-to-sign (vedi l'ultimo paragrafo). Il programma di installazione dell'applicazione Click-to-sign si trova nella stessa cartella di smctl, tipicamente in C:/Program Files/DigiCert/DigiCert Keylocker Tools/

Le seguenti informazioni devono essere configurate nelle variabili di sistema (manualmente o tramite la guida):

  • Host - URL per la connessione, tipicamente https://clientauth.one.digicert.com
  • API key - il tuo token API di KeyLocker
  • Client authentication certificate - il tuo certificato di autenticazione e la sua password
  • Client authentication certificate password - la password del certificato sopra menzionato
  • Pkcs11 configuration file - opzionale per signtool; file di configurazione per la libreria PKCS11 utilizzata da smctl, jarsigner e altri. Come crearlo vedi qui

Configurazione delle variabili in DigiCert​​®​​ Click-to-sign

Se non sai come impostare manualmente le variabili del sistema Windows, guarda questo videotutorial.

L'accuratezza della configurazione sarà mostrata dalla guida (Credenziali salvate) oppure puoi verificarla utilizzando l'utilità SMCTL con il comando smctl healthcheck Questo comando verifica la connessione e l'autenticazione con KeyLocker, ma controlla anche se almeno uno strumento di firma è accessibile. Se sì, per lo strumento specificato sarà indicato Mapped: Yes e il percorso ad esso sul computer.

Se non vedi signtool nel risultato del test (Signtool: Mapped: No), significa che signtool non è installato oppure il percorso ad esso non è configurato nelle variabili di sistema (configurazione vedi Set PATH environment variable). L'assistenza per lo strumento healthcheck è disponibile nell'articolo Comandi di controllo dello stato nella documentazione di DigiCert.

Consigliamo di configurare le variabili nel sistema in modo permanente, nel caso di Windows in modo sicuro nel Windows Credential Manager (nelle variabili di sistema sono accessibili a chiunque abbia accesso al computer). Se configurerai le variabili solo nella riga di comando, dovrai configurarle ogni volta in ogni sessione. Vedi documentazione a Variabili di ambiente di sessione.

Sincronizzazione del certificato

Dopo aver configurato la connessione a KeyLocker (sezione precedente), è necessario sincronizzare i certificati nel tuo sistema.

C:/Program Files/DigiCert/DigiCert Keylocker Tools>smctl windows certsync --keypair-alias=key_558469087
Sincronizzazione del certificato per alias: key_558469087, ID: 2a47112c-4b5d-4ce0-8e70-d67437e58135 e Impronta digitale SHA1: ecb0f10ab1XXXXXXXXXX1681fb70a31e32288263

Puoi anche utilizzare l'utilità smksp_cert_sync:

C:/>smksp_cert_sync
Sincronizzazione del certificato per alias: key_558469087, ID: 2a47112c-4b5d-4ce0-8e70-d67437e58135

Ora la parte pubblica del certificato è memorizzata localmente nel Windows certificate store, ma la chiave privata rimane nello storage cloud.

Firma dei file

Sotto troverai la guida per firmare i file con vari strumenti, utile per iniziare a usare i certificati di firma del codice.

I programmi menzionati vengono utilizzati nella riga di comando (CLI), ad eccezione dell'utilità DigiCert​​®​​ Click-to-sign (vedi l'ultimo paragrafo).

Firma dei file con SMCTL (consigliato)

L'utilità SMCTL proviene da DigiCert e può essere utilizzata anche per la firma semplificata dei file con strumenti di terze parti (è comunque richiesto almeno signtool). SMCTL collabora con gli strumenti più diffusi - Signtool, Apksigner, Jarsigner, Mage, Nuget. Lo strumento si trova nella cartella C:/Program Files/DigiCert/DigiCert Keylocker Tools/smctl.exe

Per selezionare il certificato, puoi usare l'alias della chiave (consigliato - lo trovi in KeyLocker, tra l'altro) o l'impronta del certificato (hash SHA-1).

smctl sign --keypair-alias=key_558469087 -d=SHA256 --verbose --config-file "C:/Program Files/DigiCert/DigiCert Keylocker Tools/pkcs11properties.cfg" --input "C:/Users/User/HelloSign.exe" smctl sign --fingerprint --input

Puoi verificare la validità della firma con il comando smctl sign verify --input

La documentazione di SMCTL è disponibile su sito web di DigiCert

Firma dei file con Signtool

La seguente guida riguarda lo strumento Signtool del pacchetto Windows SDK. È lo strumento più diffuso per la firma sulla piattaforma Windows.

Nel comando signtool è necessario specificare quale file si desidera firmare, con quale certificato e eventualmente parametri correlati. Per il certificato di firma, puoi far riferimento in vari modi - puoi lasciare che Signtool scelga automaticamente il certificato in base allo store; la scelta specifica del certificato può essere fatta facendo riferimento a un file con il certificato memorizzato (ovviamente solo la parte pubblica senza la chiave privata) oppure puoi usare l'hash SHA-1 del certificato.

Ecco un esempio di firma utilizzando l'hash dell'impronta digitale del certificato:

C:/>signtool.exe sign /sha1 ecb0f10ab1XXXXXXXXXX1681fb70a31e32288263 /tr http://timestamp.digicert.com /td SHA256 /fd SHA256 C:/Users/User/Documents/HelloSign.exe

Ed ecco un esempio di firma utilizzando KeyLocker e un file con il certificato:

C:/Users/User>signtool.exe sign /csp "DigiCert Signing Manager KSP" /kc key_558469087 /f C:/Users/User/Documents/cert_558469087.crt /tr http://timestamp.digicert.com /td SHA256 /fd SHA256 C:/Users/User/Documents/HelloSign.exe
Done Adding Additional Store
Successfully signed: C:/Users/User/Documents/HelloSign.exe

Puoi verificare la validità della firma con il comando signtool verify /v file.exe Le proprietà della firma le trovi anche nel file firmato tramite Esplora risorse e Proprietà (pulsante destro del mouse).

Firma dei file con Jarsigner

Puoi utilizzare Jarsigner insieme a KeyLocker grazie alla libreria PKCS11; puoi firmare in modo semplificato utilizzando SMCTL oppure direttamente con Jarsigner e la libreria PKCS11.

Esempio di firma con Jarsigner: jarsigner -keystore NONE -storepass NONE -storetype PKCS11 -sigalg SHA256withRSA -providerClass sun.security.pkcs11.SunPKCS11 -providerArg pkcs11properties2.cfg -signedjar C:/Users/Name/Desktop/signed/signedjar.jar C:/Users/Name/Desktop/ToSign/jartosign.jar key3 -tsa "http://timestamp.digicert.com"

Verifica della validità della firma con il comando: jarsigner -verify -certs -verbose

La documentazione di Jarsigner è disponibile su sito web di DigiCert

Firma con DigiCert​​®​​ Click-to-sign

Questa utilità offre un'interfaccia grafica per facilitare la firma dei file. Il risultato e il principio della firma non differiscono dagli strumenti della riga di comando; questi permettono invece un'impostazione più dettagliata dei parametri di firma. DigiCert​​®​​ Click-to-sign ha solo opzioni semplificate, che però possono bastare alla maggior parte degli utenti.

DigiCert​​®​​ Click-to-sign ha un enorme vantaggio: per configurarlo è necessario seguire la guida alla configurazione delle credenziali di accesso (secrets) a KeyLocker. La guida testerà semplicemente la connessione al cloud, ma soprattutto configurerà queste variabili nel sistema! Non dovrai configurarle manualmente in modo complesso.

La firma effettiva con questo strumento è estremamente semplice: fai clic con il tasto destro del mouse sul file da firmare e nel menu seleziona Click to Sign. Poi puoi firmare direttamente o con la conferma delle impostazioni di firma.

Revisione prima della firma in DigiCert​​®​​ Click-to-sign

La documentazione di Click-to-sign è disponibile su sito web di DigiCert

Nota: Se Click-to-sign non funziona, imposta nel variabile PATH percorsi al Click-to-sign stesso e alla applicazione di firma (signtool) separati da punto e virgola. Ad esempio:
Path: C:/Program Files/DigiCert/DigiCert Keylocker Tools;C:/Program Files (x86)/Windows Kits/10/bin/10.0.22621.0x64;

Integrazione in CI/CD

Il principale vantaggio di KeyLocker è la possibilità di automatizzare le firme grazie all'integrazione nel workflow CI/CD. DigiCert ha preparato una serie di script e plugin per gli strumenti di sviluppo e le piattaforme più diffusi. I plugin sono disponibili per Azure DevOps, GitHub e Jenkins. Gli script di integrazione per la libreria PKCS11 sono ancora più numerosi.

Informazioni complete sono disponibili nell'articolo Integrazioni CI/CD.

Documentazione e altre risorse: