Sprievodca riešením problémov pre KeyLocker
KeyLocker je mocný nástroj pre podpisovanie kódu, ktorý umožňuje uloženie vášho Code Signing certifikátu v cloude a bezpečné vzdialené podpisovanie jeho hashu. Prvotné nastavenie však má určité úskalia, s ktorými pomôže tento článok.
Kontrola premenných
Zásadným krokom pre fungovanie KeyLockeru na vašom systéme je správne nastavenie premenných. Tie určujú nielen cestu k podpisovacím nástrojom, ale hlavne nesú autentizačné údaje. Tie môžete nastaviť na jednu session, alebo trvale.
Premenné môžete do systému nastaviť rôznymi spôsobmi. Okrem samostatného súboru a premenných ich môžete uložiť aj do Windows Credential Managera. Ak chcete podpisovať pomocou GUI, môžete ich nastaviť v utilite Click-to-sign, ktorú nájdete v KeyLocker účte (premenné však nebudú fungovať na úrovni systému).
Nastavenie premennej vykonáte vo Windows jednoducho pomocou príkazového riadku. Spustite cmd a napíšte setx PREMENNA=hodnota. Pozor - setx pracuje s užívateľskými premennými, nie systémovými.
Pre správnu funkciu KeyLockeru je potrebné nastaviť premenné pre autentizáciu klienta + umiestnenie podpisovacích nástrojov a knižníc od DigiCertu.
Nastavenie autentizácie
- SM_CLIENT_CERT_FILE - cesta k umiestneniu autentizačného certifikátu s koncovkou p12, ktorý ste si stiahli zo sprievodcu v DigiCert ONE
- SM_HOST - host adresa DigiCert ONE, tá je https://clientauth.one.digicert.com
Tieto dve premenné nie sú tajné, pretože certifikát je chránený heslom. Môžete ich pokojne nastaviť do systému. Nasledovné dve premenné už tajné sú a odporúčam ich nenastavovať do systému, ak k nemu má prístup viac užívateľov. Je lepšie ich uložiť do správcu hesiel Windows. Viac informácií o nastavení premenných pre Windows nájdete v článku Credential setup for Windows.
- SM_API_KEY - API kľúč, ktorý ste si vygenerovali v rozhraní DigiCert ONE
- SM_CLIENT_CERT_PASSWORD - heslo k autentizačnému certifikátu v P12, ktoré sa vám jednorazovo zobrazilo v sprievodcovi DC1
Nastavenie cesty k podpisovým nástrojom
Pridanie hodnoty k premennej PATH sa robí pomocou príkazu setx PATH "cesta;%PATH%". Tento príkaz pridá novú hodnotu k existujúcim užívateľským hodnotám premennej PATH a uloží ju natrvalo. Pre správnu funkčnosť KeyLockeru je potrebné nastaviť minimálne dve:
- Cestu k Windows SDK a signtool
- Cestu k DigiCert Keylocker Tools
Zistite platnú cestu k Windows SDK (cesta používa číslo verzie, ktorú máte nainštalovanú). Ďalej budete potrebovať DigiCert Keylocker Tools, ktoré ste stiahli a nainštalovali z DigiCert ONE; nájdete ich v C:\Program Files\DigiCert\DigiCert Keylocker Tools.
Pridáme obe premenné naraz cez CMD, inak sa bude prepísovať jedna druhou:
setx PATH "C:\Program Files\DigiCert\DigiCert Keylocker Tools\;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\;%PATH%"Premenné systému môžete nastaviť aj cez GUI Windows; cez CMD je to rýchlejšie, no hodnoty sa pri viacerých zadaniach prepíšu. Možné je použiť aj PowerShell.
Ako upraviť premennú PATH ručne vo Windows
Ak chcete mať istotu, že sa hodnoty zachovajú, môžete PATH upraviť ručne:
- Otvorte Ovládací panel → Systém → Pokročilé nastavenie systému.
- Kliknite na Premenné prostredia.
- Nájdite PATH (v Systémových premenných alebo Užívateľských premenných).
- Kliknite na Upraviť, pridajte jednotlivé cesty a uložte.
Ako pridať premennú PATH pomocou PowerShellu
Ak chcete trvale pridať cestu do premennej PATH pomocou PowerShellu, postupujte nasledovne:
- Otvorte PowerShell ako správca (kliknite pravým tlačidlom na Start → Windows PowerShell (Admin)).
- Najprv zistite aktuálnu hodnotu premennej "PATH":
[System.Environment]::GetEnvironmentVariable("Path", "User") - Potom pridajte novú cestu k existujúcim hodnotám:
$path = [System.Environment]::GetEnvironmentVariable("Path", "User") $newPath = $path + ";C:\Program Files\DigiCert\DigiCert Keylocker Tools\" [System.Environment]::SetEnvironmentVariable("Path", $newPath, "User") - Ak potrebujete pridať ďalšiu cestu, zopakujte proces:
$newPath = $newPath + ";C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\" [System.Environment]::SetEnvironmentVariable("Path", $newPath, "User") - Po vykonaní príkazov reštartujte príkazový riadok alebo počítač, aby sa zmeny prejavili.
Poznámka: Ak chcete zmeniť systémovú premennú "PATH" (platnú pre všetkých užívateľov), nahraďte "User" za "Machine" v príkaze.
Pozor: Po nastavení premenných cez CMD reštartujte príkazový riadok, inak sa zmeny neprejavia!
Kontrola hodnoty premennej v cmd: echo %PREMENNA% Napríklad "echo %PATH%". Potom vám cmd vypíše jej hodnotu.
Kontrola správneho nastavenia
KeyLocker tools obsahujú utilitu smctl, ktorou môžete podpisovať, ale slúži tiež k základnej diagnostike. Nasledujúci príkaz skontroluje, či je všetko na stanici dobre nastavené a smctl sa môže spojiť s cloudom DigiCertu:
smctl healthcheckVo výpise uvidíte potvrdenie, či ste sa spojili s KeyLockerom (funguje autentizácia) a či smctl deteguje prítomnosť podpisovacích nástrojov, napríklad signtool. Príklad:
smctl healthcheck
--------- Account Settings ---------
Teams: Disabled
Threat detection: Enabled
Static Binary Analysis: Enabled
Software Composition Analysis: Disabled
--------- User credentials ---------
Status: Connected
Username: XXXX-keylocker
Accounts: XXXX-1699076
Authentication: 2FA
Environment: Prod
Credentials:
Host: https://clientauth.one.digicert.com
API key: 010897bf735bbc57d48270cd3d_50dxxxxx...e4 (Pulled from environment variable)
Client certificate file path: C:\Users\xy\Documents\keylocker\Certificate_pkcs12.p12
Client certificate password: ytf_xxxxxx0F (Pulled from environment variable)
API keys:
Name: xy (expires on Mon, 31 Dec 2029 23:59:59 UTC)
Client certificates:
Name: xy (expires on Mon, 31 Dec 2029 23:59:59 UTC)
Privileges:
Can sign: Yes
Can approve offline release: No
Can revoke certificate: Yes
Can scan: No
--------- Signing tools ---------
Signtool 32 bit:
Mapped: No
Signtool:
Mapped: Yes
Path: C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\signtool.exe
Mage:
Mapped: No
Nuget:
Mapped: No
Jarsigner:
Mapped: No
Apksigner:
Mapped: NoAk je problém s autentizáciou, skontrolujte, či ste nastavili správne hodnoty, ktoré ste získali v sprievodcovi KeyLockeru v rozhraní DigiCert ONE. Ak máte pochybnosti, môžete sprievodcu resetovať a vytvoriť nové credentials.
Môžete tiež naraziť na to, že smctl nedetekuje signtool či ďalšie podpisové nástroje. To znamená, že je potrebné pridať ich umiestnenie do premennej PATH užívateľa či systému. Viz vyššie v oddiele o premenných.
MMC a kontrola prítomnosti certifikátu
Ak pracujete na Windows, pozrite sa do správcu certifikátov, ktorý spustíte príkazom certmgr.msc. Ak prebehne synchronizácia s KeyLockerom úspešne, uvidíte certifikát s príznakom privátneho kľúča v certificate store. To však neznamená, že tam skutočne s privátnym kľúčom je - certifikát s privátnym kľúčom je stále uložený v cloude.
Ak tam certifikát nie je, spustite synchronizáciu.
smctl windows certsyncPri úspešnej synchronizácii uvidíte potvrdenie:
Syncing certificate for alias: key_1236506290, ID: ac793b6d-cac4-4be4-b145-003d4d1d63db and SHA1 Fingerprint: 54d0c7a2d93ae4d5fccb41d97c51a8ab3581c72cProblémy s podpisovaním
Ak máte problémy s podpisovaním, skúste ísť od najobecnejšieho k zložitejšiemu. Najjednoduchšie je podpísať pomocou utility smctl od DigiCertu, ktorá môže slúžiť ako nadstavba pre podpisovacie nástroje ako signtool či jarsigner. To je najmenej konfliktný spôsob a nepotrebuje žiadne parametre. Pre riešenie problémov nepoužívajte timestamp, ani iné voľby.
Podpis pomocou smctl vykonáte jednoducho:
smctl sign --keypair-alias=key_1234567890 --input C:\Users\John.Doe\Desktop\file_to_sign.exeOdkazovať sa na certifikát môžete parametrom "keypair-alias" či "fingerprint", tieto informácie o certifikáte nájdete napríklad pomocou príkazu smctl windows certsync.
Po podpísaní môžete podpis skontrolovať:
smctl sign verify --input <path to signed file or folder>Nápovedu pre podpisovanie nájdete v článku Sign binaries with SMCTL.
Po úspešnom podpísaní pomocou smctl môžete podpísať iným nástrojom, napríklad signtool. Ten by mal tiež fungovať. Voľbu certifikátov nechajte automaticky a postupne pridávajte ďalšie parametre.
Až to bude úspešne fungovať podľa vašich predstáv, môžete skúsiť podpisovanie napríklad pomocou Visual Studio či v inom vývojovom prostredí.
Kde nájsť logy
Ak všetko vyššie uvedené zlyhá a podpisovanie nefunguje, odporúčam sa pozrieť do logov smctl a ďalších nástrojov od DigiCertu. Ak použijete logy pri riešení problému s našou podporou, určite tým urýchlite vyriešenie problému.
Log utility smctl nájdete v súbore smctl.log, ktorý bude umiestnený v priečinku /.signingmanager/logs v danom užívateľskom profile. Skúste napísať do cmd echo %USERPROFILE%/.signingmanager/logs a uvidíte kompletné umiestnenie priečinka.
Ďalšie zdroje a informácie
- Najčastejšie chyby - Troubleshoot Guide v dokumentácii KeyLockeru.
- Dokumentácia KeyLockeru na webe DigiCertu
Bol tento článok pre vás užitočný?
Ďakujeme vám za spätnú väzbu na tento článok.
Mrzí nás, že ste tu nenašli potrebné.
Pomôžete nám článok vylepšiť? Napíš nám, čo ste tu očakávali a nedozvedeli sa.