Podpisovanie pomocou KeyLocker cloud HSM

Tento článok vás naučí podpisovať pomocou cloudu a KeyLocker HSM. Návod je relevantný pre všetky platformy a rôzne podpisovacie nástroje – od signtool až po jarsigner. Uvedené informácie sú aj základom pre podpisovanie pomocou Software Trust Managera z DigiCert ONE; princíp podpisovania platí pre obe služby.

Kompatibilita KeyLocker

Iste si pred vyskúšaním KeyLockeru položíte otázku, či bude možné ho použiť vo vašom workflow a či vám bude fungovať. KeyLocker a súvisiace knižnice podporujú (rovnako ako Software Trust Managet v DC1) podpisové nástroje tretej strany. Na webe DigiCert nájdete v článku Signing tool integration kompletný prehľad formátov súborov, ktoré môžete podpísať kompatibilnými nástrojmi za použitia KeyLockeru.

Tu spomeniem iba najrozšírenejší Signtool v 32b a 64b verzii:

  • 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

Sprievodca v KeyLocker

Po prihlásení do KeyLockeru uvidíte sprievodcu nastavením, ktorý vám pomôže vytvoriť si autentizačné prostriedky, ktoré budete potrebovať.

Autentizačné údaje si dôkladne uložte, pretože bez nich nemožno podpisovať. Certifikát pre autentizáciu si uložte na počítač, kde budete podpisovať. Heslo k tomuto certifikátu (PFX) budete ukladať do premennej systému, alebo ho zadáte do sprievodcu.

Údaje pre autentizáciu získate v KeyLocker sprievodcovi

Nastavenie podpisového prostredia

Pred samotným podpisovaním je potrebné nastaviť vo vašom systéme premenné a autentizáciu. Môžete tak urobiť ručne v nastavení systému, alebo použiť sprievodcu od DigiCertu, ktorý je súčasťou aplikácie Click-to-sign (viď posledný odsek). Inštalátor aplikácie Click-to-sign nájdete v rovnakom priečinku ako smctl, typicky v C:/Program Files/DigiCert/DigiCert Keylocker Tools/

Do systémových premenných je potrebné nastaviť tieto údaje (ručne, či pomocou sprievodcu):

  • Host - URL pre pripojenie, typicky https://clientauth.one.digicert.com
  • API key - váš API token z KeyLocker
  • Client authentication certificate - váš autentizačný certifikát a jeho heslo
  • Client authentication certificate password - heslo k vyššie uvedenému certifikátu
  • Pkcs11 configuration file - nepovinné pre signtool; konfiguračný súbor pre PKCS11 knižnicu, ktorú využíva smctl, jarsigner a ďalšie. Ako ho vytvoriť viď zde

Nastavenie premenných v DigiCert® Click-to-sign

Ak neviete, ako nastaviť premenné systému Windows ručne, pozrite sa na tento videonávod.

Správnosť nastavenia vám ukáže buď sprievodca (Credentials saved), alebo si ich overte pomocou utility SMCTL príkazom smctl healthcheck Tento príkaz skontroluje pripojenie a autentizáciu voči KeyLocker, ale tiež skontroluje, či je prístupný aspoň jeden nástroj na podpisovanie. Ak áno, tak pri danom nástroji bude uvedené Mapped: Yes a cesta k nemu v počítači.

Ak nevidíte signtool vo výsledku testu (Signtool: Mapped: No), tak to znamená, že signtool buď nie je nainštalovaný, alebo cesta k nemu nie je nastavená v premenných systéme (nastavenie viď Set PATH environment variable). Nápovedu k nástroju healthcheck nájdete v článku Healthcheck commands v dokumentácii DigiCertu.

Odporúčame nastaviť premenné do systému nastálo, v prípade Windows bezpečným spôsobom do Windows Credential Manager (v premenných systémoch sú prístupné komukoľvek, kto má prístup k danému počítaču). Pokiaľ budete premenné nastavovať iba v príkazovom riadku, tak ich budete musieť nastavovať pri každej session. Pozri dokumentáciu k Session-based environment variables.

Synchronizácia certifikátu

Po nastavení pripojenia ku KeyLocku (predchádzajúci odsek) je potrebné vykonať synchronizáciu certifikátov do vášho systému.

C:/Program Files/DigiCert/DigiCert Keylocker Tools>smctl windows certsync --keypair-alias=key_558469087
Syncing certificate for alias: key_558469087, ID: 2a47112c-4b5d-4ce0-8e70-d67437e58135 and SHA1 Fingerprint: ecb0f10ab1XXXXXXXXXX1681fb70a31e32288263

Môžete tiež využiť utilitu smksp_cert_sync:

C:/>smksp_cert_sync
Syncing certificate for alias: key_558469087, ID: 2a47112c-4b5d-4ce0-8e70-d67437e58135

Teraz je verejná časť certifikátu uložená lokálne vo Windows certificate store, ale privátny kľúč zostáva v cloudovom úložisku.

Podepisovanie súborov

Nižšie nájdete pomoc na podpisovanie súborov pomocou rôznych nástrojov, ktorá vám pomôže v začiatkoch používania Code Signing certifikátov.

Spomínané programy sa používajú v príkazovom riadku (CLI), výnimkou je utilita DigiCert® Click-to-sign (pozri posledný odsek).

Podepisovanie súborov pomocou SMCTL (odporúčame)

Utilita SMCTL pochádza od DigiCertu a môže slúžiť aj k zjednodušenému podpisovaniu súborov pomocou nástrojov tretej strany (stále potrebujete minimálne signtool). SMCTL spolupracuje s najrozšírenejšími nátrojmi - Signtool, Apksigner, Jarsigner, Mage, Nuget. Nástroj nájdete v priečinku C:/Program Files/DigiCert/DigiCert Keylocker Tools/smctl.exe

Pre zvolenie certifikátu môžete použiť buď key alias (odporúčam - nájdete ho v KeyLocker), alebo odtlačok certifikátu (SHA-1 hash).

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

Platnosť podpisu si môžete overiť príkazom smctl sign verify --input

Dokumentáciu SMCTL nájdete na webu DigiCertu

Podepisovanie súborov pomocou Signtool

Nasledujúci návod sa týka nástroja Signtool z balíka Windows SDK. Je to najrozšírenejší nástroj na podpisovanie na platforme Windows.

Príkazu signtool je potrebné špecifikovať aký súbor chcem podpísať, akým certifikátom a prípadne súvisiace parametre. Na podpisovací certifikát sa môžete odkazovať viacerými spôsobmi - môžete nechať Signtool automaticky zvoliť certifikát na základe úložiska; konkrétnu voľbu certifikátu môžete vykonať buď odkazom na súbor s uloženým certifikátom (samozrejme len verejná časť bez privátneho kľúča), alebo môžete použiť SHA-1 hash daného certifikátu.

Tu je príklad podpísania pomocou hash odtlačku certifikátu:

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

A tu je príklad podpísania pomocou KeyLockeru a súboru s certifikátom:

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

Platnosť podpisu si môžete overiť príkazom signtool verify /v file.exe Vlastnosti podpisu nájdete tiež u podpísaného súboru cez prieskumníka a Vlastnosti (pravé tlačidlo myši).

Podpisovanie súborov pomocou Jarsigner

Jarsigner môžete využiť spolu s KeyLockerom vďaka knižnici PKCS11; podpisovať môžete zjednodušene pomocou SMCTL, alebo priamo pomocou Jarsignera a knižnice PKCS11.

Príklad podpisu pomocou Jarsigner: jarsigner -keystore NONE -storepass NONE -storetype PKCS11 -sigalg SHA256withRSA -providerClass sun.security.pkcs11.SunPKCS11 -providerArg pkcs11properties2.cfg -signedjar /signedjar.jar C:/Users/Name/Desktop/ToSign/jartosign.jar key3 -tsa "http://timestamp.digicert.com"

Správnosť podpisu overíte príkazom: jarsigner -verify -certs -verbose

Dokumentáciu k Jarsigner nájdete na webu DigiCertu

Podepisovanie pomocou DigiCert ® Click-to-sign

Táto utilita ponúka grafické rozhranie pre uľahčenie podpisu súboru. Výsledok a princíp podpisovania sa však nelíšia od nástrojov pre príkazový riatok; tie naopak umožňujú detailnejšie nastavenie parametrov podpisu. DigiCert ® Click-to-sign má iba zjednodušené možnosti, ktoré však môžu väčšine užívateľov stačiť.

DigiCert® Click-to-sign má jednu obrovskú výhodu - pre jeho nastavenie je potrebné prejsť sprievodcom nastavenia prístupových údajov (secrets) ku KeyLockeru. Sprievodca vám jednoducho vyskúša spojenie s cloudom, ale najmä nastaví tieto premenné do systému! Nebudete ich musieť zložito nastavovať manuálne.

Samotné podpisovanie týmto nástrojom je maximálne jednoduché - kliknete pravým tlačidlom myši na súbor na podpis a menu vyberiete Click to Sign. Potom môžete podpísať rovno, alebo s potvrdením nastavenia podpisu.

Revízia pred podpisom v DigiCert® Click-to-sign

Dokumentáciu ku Click-to-sign nájdete na webu DigiCertu

Poznámka: Ak by vám Click-to-sign nefungoval, tak nastavte do premennej PATH cesty k samotnému Click-to-sign a tiež k podpisovacej aplikácii (signtool) oddelenej bodkočiarkou. Teda napríklad:
Path: C:/Program Files/DigiCert/DigiCert Keylocker Tools;C:/Program Files (x86)/Windows Kits/10/bin/10.0.22621.0x64;

Integrácia do CI/CD

Hlavnou výhodou KeyLockeru je možnosť automatizácie podpisov vďaka integrácii do CI/CD workflow. DigiCert pripravil množstvo skriptov a pluginov pre najrozšírenejšie vývojové nástroje a platformy. Pluginy sú dostupné pre Azure DevOps, GitHub a Jenkins. Integračných skriptov pre knižnicu PKCS11 ponúka ešte viac.

Kompletné informácie nájdete v článku CI/CD integrations.

Dokumentácia a ďalšie zdroje: