1. Domů
  2. Nápověda
  3. Code Signing certifikáty
  4. Průvodce řešením problémů pro KeyLocker

Průvodce řešením problémů pro KeyLocker

KeyLocker je mocný nástroj pro podepisování kódu, který umožňuje uložení vašeho Code Signing certifikátu v cloudu a bezpečné vzdálené podepisování jeho hashe. Prvotní nastavení však má jistá úskalí, se kterými pomůže tento článek.

Obsah článku

Kontrola proměnných

Zásadním krokem pro fungování KeyLockeru na vašem systému je správné nastavení proměnných. Ty určují nejen cestu k podepisovacím nástrojům, ale hlavně nesou autentizační údaje. Ty můžete nastavit na jednu session, nebo trvale.

Proměnné můžete do systému nastavit různými způsoby. Kromě samostatného souboru a proměnných je můžete uložit i do Windows Credential Manageru. Pokud chcete podepisovat pomocí GUI, můžete je nastavit v utilitě Click-to-sign, kterou najdete v KeyLocker účtu (proměnné však nebudou fungovat na úrovni systému).

Nastavení proměnné provedete ve Windows snadno pomocí příkazové řádky. Spusťte cmd a napište setx PROMENNA=hodnota Pozor - setx pracuje s uživatelskými proměnnými, ne systémovými.

Pro správnou funkci KeyLockeru je potřeba nastavit proměnné pro autentizaci klienta + umístění podpisových nástrojů a knihoven od DigiCertu.

Nastavení autentizace

  • SM_CLIENT_CERT_FILE - cesta k umístění autentizačního certifikátu s koncovkou p12, který jste si stáhli z průvodce v DigiCert ONE
  • SM_HOST - host adresa DigiCert ONE, ta je https://clientauth.one.digicert.com

Tyto dvě proměnné nejsou tajné, protože certifikát je chráněn heslem. Můžete je klidně nastavit do systému. Následující dvě proměnné už tajné jsou a doporučuji je nenastavovat do systému, pokud k němu má přístup více uživatelů. Je lepší je uložit do správce hesel Windows. Více informací o nastavení proměnných pro Windows viz článek Credential setup for Windows.

  • SM_API_KEY - API klíč, který jste si vygenerovali v rozhraní DigiCert ONE
  • SM_CLIENT_CERT_PASSWORD - heslo k autentizačnímu certifikátu v P12, které se vám jednorázově zobrazilo v průvodci DC1

Nastavení cesty k podpisovým nástrojům

Přidání hodnoty k proměnné PATH se dělá příkazem setx PATH "cesta;%PATH%" Tento příkaz přidá novou hodnotu ke stávajícím uživatelským hodnotám proměnné PATH a uloží ji natrvalo. Pro správnou funkčnost KeyLockeru je potřeba nastavit minimálně dvě:

  • Cestu k Windows SDK a signtool
  • Cestu k DigiCert Keylocker Tools

Zjistěte platnou cestu k Windows SDK (cesta používá číslo verze, kterou máte nainstalovanou). Dále budete potřebovat DigiCert Keylocker Tools, které jste stáhli a nainstalovali z DigiCert ONE; najdete je v C:\Program Files\DigiCert\DigiCert Keylocker Tools.

Přidáme obě proměnné najednou přes CMD, jinak se bude přepisovat 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%"

Proměnné systému můžete nastavit i přes GUI Windows; přes CMD je to rychlejší, ale hodnoty se při vícenásobném zadání přepisují. Možné je použít i PowerShell.

Jak upravit proměnnou PATH ručně ve Windows

Pokud chcete mít jistotu, že se hodnoty zachovají, můžete PATH upravit ručně:

  1. Otevřete Ovládací panely → Systém → Upřesnit nastavení systému.
  2. Klikněte na Proměnné prostředí.
  3. Najděte PATH (ve Systémových proměnných nebo Uživatelských proměnných).
  4. Klikněte na Upravit, přidej jednotlivé cesty a ulož.
Přidání proměnných přes GUI Windows
Přidání proměnných přes GUI Windows

Jak přidat proměnnou PATH pomocí PowerShellu

Pokud chcete trvale přidat cestu do proměnné PATH pomocí PowerShellu, postupujte následovně:

  1. Otevřete PowerShell jako správce (klikněte pravým tlačítkem na Start → Windows PowerShell (Admin)).
  2. Nejprve zjistěte aktuální hodnotu proměnné "PATH":
    3. [System.Environment]::GetEnvironmentVariable("Path", "User")
  3. Poté přidejte novou cestu ke stávajícím 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. Pokud potřebujete přidat další 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 provedení příkazů restartujte příkazový řádek nebo počítač, aby se změny projevily.

Poznámka: Pokud chcete změnit systémovou proměnnou "PATH" (platnou pro všechny uživatele), nahraďte "User" za "Machine" v příkazu.

Kontrola hodnoty proměnné v cmd: echo %PROMENNA% Například "echo %PATH%". Pak vám cmd vypíše její hodnotu.

Kontrola správného nastavení

KeyLocker tools obsahují utilitu smctl, kterou můžete podepisovat, ale slouží taky k základní diagnostice. Následující příkaz zkontorluje, zdali je vše na stanici dobře nastaveno a smctl se může spojit s cloudem DigiCertu:

smctl healthcheck

Ve výpisu uvidíte potvrzení, zdali jste se spojili s KeyLockerem (funguje autentizace) a zdali smctl detekuje přítomnost podepisovacích nástrojů, například signtool. Pří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 proměnný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

Pokud je problém s autentizací, zkontrolujte, zdali jste nastavili správné hodnoty, které jste získali v průvodci KeyLockeru v rozhraní DigiCert ONE. Pokud máte pochyby, tak můžete průvodce resetovat a vytvořit nové credentials.

Můžete taky narazit na to, že smctl nedetekuje signtool či další podpisové nástroje. To znamená, že je potřeba přidat jejich umístění do proměnné PATH uživatele či systému. Viz výše v oddílu o proměnných.

MMC a kontrola přítomnosti certifikátu

Pokud pracujete na Windows, tak se podívejte do správce certifikátů, který spustíte příkazem certmgr.msc. Pokud proběhne synchronizace s KeyLockerem úspěšně, uvidíte certifikát s příznakem privátního klíče v certificate store. To však neznamená, že tam skutečně s privátním klíčem je - certifikát s privátním klíčem je stále uložen v cloudu.

Pokud tam certifikát není, spusťte synchronizaci. smctl windows certsync Při úspěšné synchronizaci uvidíte potvrzení: 

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

Problémy s podepisováním

Pokud máte problémy s podepisováním, zkuste jít od nejobecnějšího ke složitějšímu. Nejjednodušší je podepsat pomocí utility smctl od DigiCertu, která může sloužit jako nadstavba jak podepisovacími nástroji jako signtool či jarsigner. To je nejméně konfliktní způsob a nepotřebuje žádné parametry. Pro řešení problémů nepoužívejte timestamp, ani jiné volby.

Podpis pomocí cmctl provedete jednoduše: smctl sign --keypair-alias=key_1234567890 --input C:\Users\John.Doe\Desktop\file_to_sign.exe

Odkazovat se na certifikát můžete parametrem "keypair-alias" či "fingerprint", tyto informace o certifikátu najdete například pomocí příkazu smctl windows certsync.

Po podepsání můžete podpis zkontrolovat: smctl sign verify --input

Nápovědu pro podepisování najdete v článku Sign binaries with SMCTL.

Po úspěšném podepsání pomocí smctl můžete podepsat jiným nástrojem, například signtool. Ten by měl taky fungovat. Volbu certifikátů nechte automaticky a postupně přidávejte další parametry.

Až to bude úspěšně fungovat podle vašich představ, tak můžete zkusit podepisování například pomocí Visual Studio či v jiném vývojovém prostředí.

Kde najít logy

Pokud vše výše uvedené selže a podepisování nefunguje, doporučuji se podívat do logů smctl a dalších nástrojů od DigiCertu. Pokud použijete logy při řešení problému s naší podporou, určitě tím urychlíte vyřešení problému.

Log utility smctl najdete v souboru smctl.log, který bude umístěn ve složce /.signingmanager/logs v daném uživatelském profilu. Zkuste napsat do cmd echo %USERPROFILE%/.signingmanager/logs a uvidíte kompletní umístění složky.

Další zdroje a informace

Byl tento článek pro vás užitečný?