1. Domů
  2. Nápověda
  3. Code Signing certifikáty
  4. Podepisování pomocí KeyLocker cloud HSM

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í platí pro obě 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 podepsat kompatibilními nástroji za použití KeyLockeru.

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 vytvořit si autentizační prostředky, které budete potřebovat.

Autentizační údaje si důkladně uložte, protože bez nic nelze podepisovat. Certifikát pro autentizaci si uložte na počítač, kde budete podepisovat. Heslo k tomuto certifikátu (PFX) budete ukládat do proměnné systému, nebo jej zadáte do průvodce.

Údaje pro autentizaci získáte v KeyLocker průvodci

Nastavení podpisového prostředí

Před samotným podepisováním je potřeba nastavit ve vašem systému proměnné a autentizaci. Můžete tak učinit ručně v nastavení systému, nebo použít průvodce od DigiCertu, který je součástí aplikace Click-to-sign (viz poslední odstavec). Instalátor aplikace Click-to-sign najdete ve stejné složce jako smctl, typicky v C:/Program Files/DigiCert/DigiCert Keylocker Tools/

Do systémových proměnných je třeba nastavit tyto údaje (ručně, či pomocí průvodce):

  • Host - URL pro připojení, typicky https://clientauth.one.digicert.com
  • API key - váš API token z KeyLockeru
  • Client authentication certificate - váš autentizační certifikát a jeho heslo
  • Client authentication certificate password - heslo k výše uvedenému certifikátu
  • Pkcs11 configuration file - nepovinné pro signtool; konfigurační soubor pro PKCS11 knihovnu, kterou využívá smctl, jarsigner a další. Jak ho vytvořit viz zde

Nastavení proměnných v DigiCert​​®​​ Click-to-sign

Pokud nevíte, jak nastavit proměnné systému Windows ručně, podívejte se na tento videonávod.

Správnost nastavení vám ukáže buď průvodce (Credentials saved), nebo si je ověřte pomocí utility SMCTL příkazem smctl healthcheck Tento příkaz zkontroluje připojení a autentizaci vůči KeyLockeru, ale také zkontroluje, zdali je přístupný alespoň jeden nástroj na podepisování. Pokud ano, tak u daného nástroje bude uvedeno Mapped: Yes a cesta k němu v počítači.

Pokud nevidíte signtool ve výsledku testu (Signtool: Mapped: No), tak to znamená, že signtool buď není nainstalován, nebo cesta k němu není nastavena v proměnných systému (nastavení viz Set PATH environment variable). Nápovědu k nástroji healthcheck najdete v článku Healthcheck commands v dokumentaci DigiCertu.

Doporučujeme nastavit proměnné do systému nastálo, v případě Windows bezpečným způsobem do Windows Credential Manager (v proměnných systému jsou přístupné komukoliv, kdo má přístup k danému počítači). Pokud budete proměnné nastavovat pouze v příkazové řádce, tak je budete muset nastavovat při každé session. Viz dokumentace k Session-based environment variables.

Synchronizace certifikátu

Po nastavení připojení ke KeyLockeru (předchozí odstavec) je třeba provést synchronizaci certifikátů do vašeho 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 také využít utilitu smksp_cert_sync:

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

Nyní je veřejná část certifikátu uložena lokálně ve Windows certificate store, ale privátní klíč zůstává v cloudovém úložišti.

Podepisování souborů

Níže naleznete nápovědu k podepisování souborů pomocí různých nástrojů, která vám pomůže v začátcích používání Code Signing certifikátů.

Zmíněné programy se používají v příkazovém řádku (CLI), výjimkou je utilita DigiCert​​®​​ Click-to-sign (viz poslední odstavec).

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

Pro zvolení certifikátu můžete použít buď key alias (doporučuji - najdete ho v mj. KeyLockeru), nebo otisk 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 <certificate fingerprint> --input <path to unsigned file or folder>

Platnost podpisu si můžete ověřit příkazem smctl sign verify --input <path to signed file or folder>

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 automaticky zvolit certifikát na základě úložiště; konkrétní volbu certifikátu můžete provést buď 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 taky 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 <path to signed jar file> -certs -verbose

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 má 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 jednoduše vyzkouší spojení s cloudem, ale zejména nastaví tyto proměnné do systému! Nebudete je 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 menu vyberete Click to Sign. Pak můžete podepsat rovnou, nebo s potvrzením nastavení podpisu.

Revize před podpisem v DigiCert​​®​​ Click-to-sign

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: