1. Home
  2. Aiuto
  3. Certificati Code Signing
  4. Guida alla risoluzione dei problemi per KeyLocker
{"copy":"Copia","expand":"Aprire","collapse":"Chiudere","copy_success":"Copiato!","copy_error":"Copia non riuscita!"}

Guida alla risoluzione dei problemi per KeyLocker

KeyLocker è uno strumento potente per la firma del codice, che consente di memorizzare il vostro certificato di firma del codice nel cloud e di firmare in modo sicuro l'hash a distanza. Tuttavia, la configurazione iniziale presenta alcune insidie, che questo articolo aiuterà a risolvere.

Indice dell'articolo

Controllo delle variabili

Un passo fondamentale per il funzionamento di KeyLocker sul vostro sistema è la corretta configurazione delle variabili. Queste determinano non solo il percorso agli strumenti di firma, ma soprattutto contengono le informazioni di autenticazione. È possibile configurarle per una singola sessione o in modo permanente.

Le variabili possono essere impostate nel sistema in vari modi. Oltre al file singolo e alle variabili stesse, potete conservarle nel Gestore delle credenziali di Windows. Se volete firmare tramite GUI, potete configurarle nel tool Click-to-sign, che trovate nell'account KeyLocker (le variabili, tuttavia, non funzioneranno a livello di sistema).

Per impostare una variabile su Windows, si può usare facilmente il prompt dei comandi. Avviate cmd e digitate setx VARIABILE=valore Attenzione - setx lavora con le variabili utente, non quelle di sistema.

Per il corretto funzionamento di KeyLocker, è necessario impostare le variabili per l'autenticazione del cliente e la posizione degli strumenti e delle librerie di firma di DigiCert.

Impostazione dell'autenticazione

  • SM_CLIENT_CERT_FILE - percorso al certificato di autenticazione con estensione p12, che avete scaricato dalla guida in DigiCert ONE
  • SM_HOST - indirizzo host di DigiCert ONE, è https://clientauth.one.digicert.com

Queste due variabili non sono segrete, poiché il certificato è protetto da password. Potete tranquillamente impostarle nel sistema. Le seguenti due variabili, invece, sono segrete e vi consiglio di non impostarle nel sistema, se esso è accessibile a più utenti. È meglio conservarle nel gestore delle password di Windows. Maggiori informazioni sulle impostazioni delle variabili per Windows si trovano nell’articolo Credential setup for Windows.

  • SM_API_KEY - chiave API, che avete generato nell'interfaccia DigiCert ONE
  • SM_CLIENT_CERT_PASSWORD - password del certificato di autenticazione in P12, che vi è stata visualizzata una sola volta nella guida DC1

Impostazione del percorso agli strumenti di firma

L'aggiunta di un valore alla variabile PATH si fa con il comando setx PATH "path;%PATH%". Questo comando aggiunge un nuovo valore ai valori utente esistenti della variabile PATH e lo salva in modo permanente. Per il corretto funzionamento di KeyLocker, è necessario impostarne almeno due:

  • Percorso a Windows SDK e signtool
  • Percorso a DigiCert Keylocker Tools

Determinare il percorso valido al Windows SDK (il percorso utilizza il numero di versione che avete installato). Avrete bisogno anche di DigiCert Keylocker Tools, che avete scaricato e installato da DigiCert ONE; li trovate in C:\Program Files\DigiCert\DigiCert Keylocker Tools.

Aggiungiamo entrambe le variabili in una volta tramite CMD, altrimenti si sovrascriverà uno con l'altro: setx PATH "C:\Program Files\DigiCert\DigiCert Keylocker Tools\;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\;%PATH%"

Le variabili di sistema possono essere impostate anche tramite l'interfaccia grafica di Windows; tramite CMD è più veloce, ma i valori vengono sovrascritti con input multipli. È possibile utilizzare anche PowerShell.

Come modificare manualmente la variabile PATH su Windows

Se volete assicurarvi che i valori siano conservati, potete modificare PATH manualmente:

  1. Aprire Pannello di controllo → Sistema → Impostazioni avanzate di sistema.
  2. Cliccare su Variabili di ambiente.
  3. Trovare PATH (nelle Variabili di sistema o nelle Variabili utente).
  4. Cliccare su Modifica, aggiungere i singoli percorsi e salvare.
Aggiunta delle variabili tramite interfaccia grafica di Windows
Aggiunta delle variabili tramite interfaccia grafica di Windows

Come aggiungere la variabile PATH usando PowerShell

Se volete aggiungere in modo permanente un percorso alla variabile PATH usando PowerShell, procedete come segue:

  1. Aprire PowerShell come amministratore (fare clic con il tasto destro su Start → Windows PowerShell (Admin)).
  2. Prima determinare il valore attuale della variabile "PATH":
    3. [System.Environment]::GetEnvironmentVariable("Path", "User")
  3. Quindi aggiungere un nuovo percorso ai valori esistenti:
    4. 
$path = [System.Environment]::GetEnvironmentVariable("Path", "User")
$newPath = $path + ";C:\Program Files\DigiCert\DigiCert Keylocker Tools\"
[System.Environment]::SetEnvironmentVariable("Path", $newPath, "User")
  4. Se avete bisogno di aggiungere un altro percorso, ripetere il processo:
    5. 
$newPath = $newPath + ";C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\"
[System.Environment]::SetEnvironmentVariable("Path", $newPath, "User")
  5. Dopo aver eseguito i comandi, riavviare il prompt dei comandi o il computer per applicare le modifiche.

Nota: Se desiderate modificare la variabile di sistema "PATH" (valida per tutti gli utenti), sostituite "User" con "Machine" nel comando.

Controllo del valore di una variabile in cmd: echo %VARIABILE% Ad esempio "echo %PATH%". Quindi cmd visualizzerà il suo valore.

Controllo della configurazione corretta

Gli strumenti KeyLocker includono l'utilità smctl, che permette di firmare, ma serve anche alla diagnosi di base. Il seguente comando verifica se tutto è configurato correttamente sul computer e se smctl può connettersi al cloud di DigiCert:

smctl healthcheck

Nell'output, vedrete una conferma se siete connessi a KeyLocker (autenticazione funzionante) e se smctl rileva la presenza degli strumenti di firma, come signtool. Esempio:

smctl healthcheck
--------- Impostazioni account ---------
Teams: Disabilitato
Rilevamento delle minacce: Abilitato
  Analisi binaria statica: Abilitata
  Analisi della composizione del software: Disabilitata

--------- Credenziali utente ---------
Stato: Connesso

Nome utente: XXXX-keylocker
Account: XXXX-1699076
Autenticazione: 2FA
Ambiente: Produzione
Credenziali:
  Host: https://clientauth.one.digicert.com
  Chiave API: 010897bf735bbc57d48270cd3d_50dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxe4 (Presa dalla variabile di ambiente)
  Percorso file certificato cliente: C:\Users\xy\Documents\keylocker\Certificate_pkcs12.p12
  Password certificato cliente: ytf_xxxxxx0F (Presa dalla variabile di ambiente)
Chiavi API:
  Nome: xy (scade il lun, 31 dic 2029 23:59:59 UTC)
       
Certificati cliente:
  Nome: xy (scade il lun, 31 dic 2029 23:59:59 UTC)
      
Privilegi:
  Può firmare: Sì
  Può approvare il rilascio offline: No
  Può revocare il certificato: Sì
  Può scansionare: No

Permessi:
Manager dell'account:
  GESTISCI_AUTORIZZAZIONE_AM
  GESTISCI_RUOLO_AM
  GESTISCI_UTENTE_ACCOUNT_AM
  VISUALIZZA_RUOLO_AM
  VISUALIZZA_ACCOUNT_AM
  VISUALIZZA_UTENTE_AM
  VISUALIZZA_ORGANIZZAZIONE_AM
  VISUALIZZA_LOG_CONTROLLO_AM

Coppie di chiavi:
  FIRMA_HASH_SM
  VISUALIZZA_COPPIA_CHIAVI_SM
  GESTISCI_COPPIE_CHIAVI_SM

Certificati:
  VISUALIZZA_CERTIFICATO_SM
  REVOCA_CERTIFICATO_SM

Altri permessi:
  VISUALIZZA_LICENZA_SM
  GESTISCI_CHIAVE_API_CC_SM

--------- Strumenti di firma ---------
Strumento di firma 32 bit:
  Mappato: No
Strumento di firma:
  Mappato: Sì
  Percorso: C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\signtool.exe
Mage:
  Mappato: No
Nuget:
  Mappato: No
Jarsigner:
  Mappato: No
Apksigner:
  Mappato: No

Se ci sono problemi con l'autenticazione, verificate se avete impostato i valori corretti, che avete ottenuto nella guida di KeyLocker nell'interfaccia DigiCert ONE. Se avete dubbi, potrete reimpostare la guida e creare nuove credenziali.

Potreste anche scoprire che smctl non rileva signtool o altri strumenti di firma. Ciò significa che è necessario aggiungere la loro posizione alla variabile PATH dell'utente o del sistema. Vedi sopra nel paragrafo sulle variabili.

MMC e controllo della presenza del certificato

Se lavorate su Windows, guardate nel gestore dei certificati, che avviate con il comando certmgr.msc. Se la sincronizzazione con KeyLocker avviene correttamente, vedrete il certificato con l'indicazione di una chiave privata nel magazzino certificati. Tuttavia, ciò non significa che sia effettivamente lì con la chiave privata - il certificato con chiave privata è ancora memorizzato nel cloud.

Se il certificato non è presente, avviate la sincronizzazione. smctl windows certsync Alla riuscita della sincronizzazione vedrete una conferma: 

Sincronizzazione del certificato per alias: key_1236506290, ID: ac793b6d-cac4-4be4-b145-003d4d1d63db e SHA1 Fingerprint: 54d0c7a2d93ae4d5fccb41d97c51a8ab3581c72c

Problemi di firma

Se avete problemi con la firma, provate ad affrontarli dal più generale al più complesso. Il modo più semplice è firmare con l'utility smctl di DigiCert, che può funzionare come un'interfaccia per strumenti di firma come signtool o jarsigner. Questo è il modo meno conflittuale e non richiede parametri. Per la risoluzione dei problemi, non usate timestamp o altre opzioni.

La firma con smctl si effettua semplicemente: smctl sign --keypair-alias=key_1234567890 --input C:\Users\John.Doe\Desktop\file_to_sign.exe

Ci si può riferire al certificato usando il parametro "keypair-alias" o "fingerprint", queste informazioni sul certificato si trovano ad esempio con il comando smctl windows certsync.

Dopo la firma, potete verificare la firma con: smctl sign verify --input

Un aiuto per la firma si trova nell'articolo Sign binaries with SMCTL.

Dopo una firma avvenuta con successo tramite smctl, potete provare a firmare con un altro strumento, per esempio signtool. Anche questo dovrebbe funzionare. Lasciate la selezione automatica dei certificati e aggiungete gradualmente altri parametri.

Una volta che tutto funziona con successo come previsto, potete provare a firmare per esempio tramite Visual Studio o in un altro ambiente di sviluppo.

Dove trovare i log

Se tutto quanto sopra fallisce e la firma non funziona, vi consiglio di controllare nei log di smctl e altri strumenti di DigiCert. Se usate i log nella risoluzione del problema con il nostro supporto, certamente accelererete la risoluzione del problema.

Il log dell'utility smctl si trova nel file smctl.log, che sarà posizionato nella cartella /.signingmanager/logs nel profilo utente attuale. Provate a digitare in cmd echo %USERPROFILE%/.signingmanager/logs e vedrete la posizione completa della cartella.

Altre risorse e informazioni

Ti è stato utile questo articolo?