1. Domov
  2. Nápoveda
  3. Code Signing certifikáty
  4. Sprievodca riešením problémov pre KeyLocker

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.

Obsah článku

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 premenné 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:

  1. Otvorte Ovládací panel → Systém → Pokročilé nastavenie systému.
  2. Kliknite na Premenné prostredia.
  3. Nájdite PATH (v Systémových premenných alebo Užívateľských premenných).
  4. Kliknite na Upraviť, pridajte jednotlivé cesty a uložte.
Pridanie premenných cez GUI Windows
Pridanie premenných cez GUI Windows

Ako pridať premennú PATH pomocou PowerShellu

Ak chcete trvale pridať cestu do premennej PATH pomocou PowerShellu, postupujte nasledovne:

  1. Otvorte PowerShell ako správca (kliknite pravým tlačidlom na Start → Windows PowerShell (Admin)).
  2. Najprv zistite aktuálnu hodnotu premennej "PATH":
    3. [System.Environment]::GetEnvironmentVariable("Path", "User")
  3. Potom pridajte novú cestu k existujúcim hodnotám:
    4. 
$path = [System.Environment]::GetEnvironmentVariable("Path", "User")
$newPath = $path + ";C:\Program Files\DigiCert\DigiCert Keylocker Tools\"
[System.Environment]::SetEnvironmentVariable("Path", $newPath, "User")
  4. Ak potrebujete pridať ďalšiu cestu, zopakujte proces:
    5. 
$newPath = $newPath + ";C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\"
[System.Environment]::SetEnvironmentVariable("Path", $newPath, "User")
  5. 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.

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 healthcheck

Vo 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_50dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxe4 (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

Permissions:
Account Manager:
        MANAGE_AM_PERMISSION
        MANAGE_AM_ROLE
        MANAGE_AM_ACCOUNT_USER
        VIEW_AM_ROLE
        VIEW_AM_ACCOUNT
        VIEW_AM_USER
        VIEW_AM_ORGANIZATION
        VIEW_AM_AUDIT_LOG

Keypairs:
        SIGN_SM_HASH
        VIEW_SM_KEYPAIR
        MANAGE_SM_KEYPAIR

Certificates:
Kontrola premenných

        VIEW_SM_CERTIFICATE
        REVOKE_SM_CERTIFICATE

Other permissions:
        VIEW_SM_LICENSE
        MANAGE_SM_CC_API_KEY

--------- 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: No

Ak 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 prebehnutie synchronizácie 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 certsync Pri úspešnej synchronizácii uvidíte potvrdenie: 

Syncing certificate for alias: key_1236506290, ID: ac793b6d-cac4-4be4-b145-003d4d1d63db and SHA1 Fingerprint: 54d0c7a2d93ae4d5fccb41d97c51a8ab3581c72c

Problé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 cmctl vykonáte jednoducho: smctl sign --keypair-alias=key_1234567890 --input C:\Users\John.Doe\Desktop\file_to_sign.exe

Odkazovať 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

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

Bol tento článok pre vás užitočný?