Podepisování pomocí KeyLocker cloud HSM
Tento článek vás naučí podepisovat pomocí cloudu a KeyLocker HSM. Návod je relevantní pro všechny platformy a různé podepisovací nástroje – od signtool až po jarsigner. Uvedené informace jsou i základem pro podepisování pomocí Software Trust Manageru z DigiCert ONE; princip podepisování tedy platí pro obě uvedené služby.
Kompatibilita KeyLockeru
Jistě si před vyzkoušením KeyLockeru položíte otázku, zdali bude možné ho použít ve vašem workflow a zdali vám bude fungovat. KeyLocker a související knihovny podporují (stejně jako Software Trust Managet v DC1) podpisové nástroje třetí strany. Na webu DigiCertu naleznete v článku Signing tool integration kompletní přehled formátů souborů, které můžete za použití KeyLockeru podepsat kompatibilními nástroji.
Zde zmíním pouze nejrozšířenější Signtool ve 32b a 64b verzi:
- 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
Průvodce v KeyLockeru
Po přihlášení do KeyLockeru uvidíte Průvodce nastavením, který vám pomůže stáhnout aplikaci DigiCert ONE Clients. Pomocí ní se přihlásíte na počítači ke KeyLocker účtu, nainstaluje vám potřebné knihovny včetně SMCTL a nastaví do systému proměnné pro autentizaci. Oproti dřívějšímu postupu se jedná o výrazné ulehčení.
V prvním kroku KeyLocker průvodce si stáhněte DigiCert ONE Clients app, nainstalujte a spusťte. Přihlášení je stejné, jako jste si nastavili do webového rozhraní KeyLockeru.
V dalším kroku v desktop aplikaci nainstalujte SMCTL, který je hlavním nástrojem pro samotné podepisování.
Po instalaci uvidíte výběr ze tří možných způsobů uložení proměnné KeyLockeru v systému. Doporučujeme ponechat výchozí možnost "Store my credentials". Údaje se uloží do systému a nebudete se muset před každým podepsáním znovu přihlašovat k účtu.
Když zvolíte možnost uložení do systému, tak v systému Windows budou credentials ve Správci přihlašovacích údajů (Credential Manager).
Po nastavení přihlašovacích údajů do systému, které provede automaticky DigiCert ONE Clients app, přejděte do třetího kroku průvodce. Ten po vás nyní bude ve vašem systému chtít spustit příkaz SMCTL healthcheck, který otestuje komunikaci lokálního prostředí s KeyLockerem a správnou autentizaci. Vše by mělo proběhnout hladce, takže potvrďte "I have run the healthcheck command in SMCTL" a klikněte na tlačítko Check Status.
Uvidíte zelené potvrzení You're ready to start signing with SMCTL, což znamená, že vše je nastaveno správně, komunikace funguje a můžete začít podepisovat.
Vyberte si ze čtyř možností správnou platformu, kterou využíváte pro podepisování, a následně uvidíte příklad (návod) pro podepsání pomocí KeyLockeru.
Podepisování souborů
Pro podepisování doporučujeme primárně používat utilitu SMCTL, která funguje v příkazovém řádku (CLI). Druhou variantou je utilita DigiCert® Click-to-sign (viz poslední odstavec).
Návody pro podepisování souborů pro hlavní platformy (Authenticode, Docker, Java...) najdete přímo ve webovém rozhraní KeyLockeru. Po dokončení průvodce (nadpis "Setup complete!") můžete kliknout na jednu z nabízených platforem a rozhraní vám ukáže připravený příkaz s využitím vybraného certifikátu. Stačí ho zkopírovat do CLI a určit podepisovaný soubor. Jednodušší to už být nemůže!
Podepisování souborů pomocí SMCTL (doporučujeme)
Utilita SMCTL pochází od DigiCertu a může sloužit i ke zjednodušenému podepisování souborů pomocí nástrojů třetí strany (stále potřebujete minimálně signtool). SMCTL spolupracuje s nejrozšířenějšími nátroji – Signtool, Apksigner, Jarsigner, Mage, Nuget. Nástroj najdete ve složce C:/Program Files/DigiCert/DigiCert Keylocker Tools/smctl.exe
V posledním kroku průvodce klikněte na Authenticode a v dalším dialogu si vyberte certifikát, který je v KeyLockeru k dispozici. Dostanete kompletní příkaz pro podepsání, kam doplníte cíl a pustíte lokálně ve svém CLI. Ihned dostanete potvrzení o úspěšném podepsání souboru.
Kompletní dokumentaci SMCTL najdete na webu DigiCertu.
Podepisování souborů pomocí Signtool
Následující návod se týká nástroje Signtool z balíku Windows SDK. Je to nejrozšířenější nástroj pro podepisování na platformě Windows.
Příkazu Signtool je potřeba specifikovat jaký soubor chci podepsat, jakým certifikátem a případně související parametry. Na podepisovací certifikát se můžete odkazovat více způsoby: Můžete nechat Signtool zvolit certifikát automaticky na základě úložiště, nebo můžete konkrétní volbu certifikátu provést manuálně odkazem na soubor s uloženým certifikátem (samozřejmě jen veřejná část bez privátního klíče), nebo můžete použít SHA-1 hash daného certifikátu.
Zde je příklad podepsání pomocí hash otisku certifikátu:
C:/>signtool.exe sign /sha1 ecb0f10ab1XXXXXXXXXX1681fb70a31e32288263 /tr http://timestamp.digicert.com /td SHA256 /fd SHA256 C:/Users/User/Documents/HelloSign.exe
A zde je příklad podepsání pomocí KeyLockeru a souboru s certifikátem:
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
Platnost podpisu si můžete ověřit příkazem: signtool verify /v file.exe Vlastnosti podpisu najdete také u podepsaného souboru přes Průzkumníka a Vlastnosti (pravé tlačítko myši).
Podepisování souborů pomocí Jarsigner
Jarsigner můžete využít spolu s KeyLockerem díky knihovně PKCS11; podepisovat můžete zjednodušeně pomocí SMCTL, nebo přímo pomocí Jarsigneru a knihovny PKCS11.
Příklad podpisu pomocí 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"
Správnost podpisu ověříte příkazem:
jarsigner -verify
Dokumentaci k Jarsigner najdete na webu DigiCertu.
Podepisování pomocí DigiCert® Click-to-sign
Tato utilita nabízí grafické rozhraní pro ulehčení podpisu souboru. Výsledek a princip podepisování se však neliší od nástrojů pro příkazový řádek; ty naopak umožňují detailnější nastavení parametrů podpisu. DigiCert® Click-to-sign nabízí pouze zjednodušené možnosti, které však mohou většině uživatelů stačit.
DigiCert® Click-to-sign má jednu obrovskou výhodu – pro jeho nastavení je potřeba projít průvodcem nastavení přístupových údajů (Secrets) ke KeyLockeru. Průvodce vám nejen jednoduše vyzkouší spojení s cloudem, ale zejména nastaví tyto proměnné do systému! Nebudete je tedy muset složitě nastavovat manuálně.
Samotné podepisování tímto nástrojem je maximálně jednoduché – kliknete pravým tlačítkem myši na soubor k podpisu a v menu vyberete Click to Sign. Pak můžete podepsat rovnou, nebo s potvrzením nastavení podpisu.
Dokumentaci ke Click-to-sign najdete na webu DigiCertu.
Poznámka: Pokud by vám Click-to-sign nefungoval, tak nastavte do proměnné PATH cesty k samotnému Click-to-sign a také k podepisovací aplikaci (Signtool) oddělené středníkem. Tedy například:
Path: C:/Program Files/DigiCert/DigiCert Keylocker Tools;C:/Program Files (x86)/Windows Kits/10/bin/10.0.22621.0x64;
Integrace do CI/CD
Hlavní výhodou KeyLockeru je možnost automatizace podpisů díky integraci do CI/CD workflow. DigiCert připravil řadu skriptů a pluginů pro nejrozšířenější vývojové nástroje a platformy. Pluginy jsou dostupné pro Azure DevOps, GitHub a Jenkins. Integračních skriptů pro knihovnu PKCS11 nabízí ještě více.
Kompletní informace najdete v článku CI/CD integrations.
Dokumentace a další zdroje:
- Dokumentace k SignTool, dostupná na https://learn.microsoft.com/cs-cz/dotnet/framework/tools/signtool-exe
- Dokumentace k KeyLocker, dostupná na https://docs.digicert.com/en/digicert-keylocker.html
