Guide för integration av Utimaco-anslutningar

Förutsättningar

För att PKCS#11-motorn ska fungera smidigt med din Utimaco HSM och Encryption Consultings CodeSign Secure behöver du några viktiga saker. Här är stegen för att installera de resurser som är viktiga för att konfigurera Windows-miljön:

Utimaco säkerhetsserver
Utimaco SecurityServer tillhandahåller kryptografiska bibliotek, verktyg och gränssnitt (t.ex. PKCS#11, CSP och JCE) för att hantera nycklar och utföra kryptografiska operationer säkert. Programvaran inkluderar CryptoServer SDK, administrativa verktyg och simulatorer, vilket underlättar sömlös HSM-integration för förbättrad säkerhet och regelefterlevnad.

Installationssteg:
Steg 1: Ladda ner leverantören
Ladda ner leverantören (t.ex. SecurityServerEvaluation-V6.1.1 för Windows) från Utimacos kundportal.
Steg 2: Installera leverantören
- Extrahera det nedladdade paketet, kör MSI-installationsprogrammet och följ anvisningarna för att konfigurera Utimaco Security Server på ditt system.
- Den installerar de nödvändiga verktygen på standardplatsen (C:\Program Files\Utimaco), om inget annat anges under installationen, och skapar även genvägar för följande verktyg på den aktuella användarens skrivbord för enklare åtkomst:
  - Kryptoserveradministration
  - PKCS#11 Kryptoserveradministration
  - Kryptoserversimulator
- Tillsammans med detta kommer den också att modifiera miljövariablerna med Utimaco SecurityServers valda platser och konfigurationsfiler.
OpenSSL 3.x
OpenSSL 3.x krävs för kryptografiska operationer och för att utnyttja PKCS#11-providern med Utimaco HSM.

Installationssteg:
Steg 1: Ladda ner OpenSSL
Ladda ner den senaste 64-bitars OpenSSL 3.x-installationsversionen för Windows med hjälp av den här länk.
Steg 2: Installera OpenSSL
- Kör det nedladdade installationsprogrammet med administratörsbehörighet.
- Välj standardinstallationskatalogen (C:\Program Files\OpenSSL-Win64) om du inte har specifika krav.
Steg 3: Konfigurera miljövariabel
Lägg till OpenSSL-binärkatalogen i systemets PATH:
- C:\Programfiler\OpenSSL-Win64\bin
Steg 4: Verifiering
Öppna en ny kommandotolk och kör följande kommando för att testa openssl-installationen.
```
openssl version
```

Java Runtime Environment

Utimaco SecurityServer kräver även en Java Runtime Environment (testad version Java 15). Se matrisen nedan för att kontrollera vilken Java-kompatibel version som är:

Java Runtime Environment	Version
oracle-java	8,11,15
OpenJDK	8,11,15

Installationssteg:

Steg 1: Ladda ner Java 15

Ladda ner den kompatibla Java-körbara filen från här. för ditt Windows-system.

Steg 2: Installera Java 15

Kör den nedladdade körbara filen och följ anvisningarna för att konfigurera Java 15.

Steg 3: Verifiering

Öppna en ny kommandotolk och kör följande kommando för att testa Java-installationen.

java -version

Microsoft Visual Studio-byggverktyg
Microsoft Visual Studio Build Tools krävs för att kompilera OpenSC PKCS#11 Wrapper Library (libp11) i Windows.

Installationssteg:
Steg 1: Ladda ner Visual Studio Build Tools
Ladda ner Microsoft Build Tools för Visual Studio 2022 med hjälp av detta länk.
Steg 2: Installera byggverktyg
Kör installationsprogrammet (vs_buildtools.exe) med administratörsbehörighet.
Steg 3: Verifiera installationen
Öppna x64 Native Tools-kommandotolken från Start-menyn och kör
```
nmake /?
```
Detta bör visa hjälpen för nmake-verktyget, vilket bekräftar att byggverktygen är installerade.
OBS: ”x64 Native Tools Command Prompt” borde finnas i C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2022\Visual Studio Tools\VC
OpenSC PKCS#11 Wrapper-bibliotek
OpenSC PKCS#11 Wrapper Library (libp11) tillhandahåller PKCS#11-motorpluginet (pkcs11.dll) för att OpenSSL ska kunna interagera med HSM.

Installationssteg:
Steg 1: Ladda ner källkoden
- Klona OpenSC/libp11-arkivet från GitHub eller ladda ner det som en ZIP-fil.
- Klona med Git (om installerat):
```
git-klon https://github.com/OpenSC/libp11.git C:\Användare\ \source\repos\libp11
```
- Eller ladda ner ZIP-filen från detta länk och extrahera den till C:\Användare\ \source\repos\libp11.
Steg 2: Kompilera biblioteket
- Öppna kommandotolken "x64 Native Tools".
- Navigera till libp11-katalogen, dvs. cd “C:\Users\ \source\repos\libp11”
- Kör nmake-kommandot för att bygga biblioteket
```
nmake /f Makefile.mak OPENSSL_DIR="C:\Programfiler\OpenSSL-Win64" BYGG_FÖR=WIN64
```
  OBS: Se till att OPENSSL_DIR pekar till din OpenSSL-installationskatalog.
Steg 3: Verifiera kompilering
Leta efter filen pkcs11.dll i mappen libp11\src. Detta är OpenSC PKCS#11 Engine Plugin.
Steg 4: Kopiera SRC-mappen
Kopiera src-mappen som du just skapade till din OpenSSL bin-katalog, dvs. C:\Program Files\OpenSSL-Win64\bin

konfiguration

Efter att du har installerat förutsättningarna måste du konfigurera Utimaco SecuritySever, OpenSSL och OpenSC PKCS#11 Wrapper Library för att möjliggöra kommunikation med din Utimaco HSM.

Konfigurera Utimaco SecurityServer
Konfigurering av Utimaco SecurityServer kräver att miljövariabler konfigureras och konfigurationsfiler uppdateras (t.ex. PKCS#11-inställningar) för att hantera HSM-åtkomst och -operationer på ett säkert sätt.

Steg:
Steg 1: Leta reda på konfigurationsfilen (cs_pkcs11_R3.cfg)
Navigera till installationskatalogen för Utimaco PKCS#11 Provider, vanligtvis: C:\ProgramData\Utimaco\PKCS11_R3
Steg 2: Uppdatera HSM:ens IP-adress
Under avsnittet [HSMCluster] uppdaterar du IP-adressen för din Utimaco HSM. Kom ihåg att avkommentera (ta bort hash-symbolen) raden (t.ex. [e-postskyddad]) där du har lagt till IP-adressen.

Här kommer vi att använda en lokal simulator som körs som standard på localhost (127.0.0.1) port 3001.
Skapa användarroller för en plats
För att generera nycklar och certifikat med Utimaco SecurityServer måste du skapa och definiera användarroller – administratör, säkerhetsansvarig (SO) och kryptografisk användare.

Steg:
Steg 1: Starta CryptoServer-simulatorn
- Starta CryptoServer Simulator, som finns på skrivbordet, för att initialisera de nödvändiga inställningarna.
  
  OBS: Om du använder en faktisk Utimaco HSM måste du starta CryptoServer Administrator-applikationen, som också finns på skrivbordet.
Steg 2: Leta reda på PKCS#11 CryptoServer-administrationsapplikationen
Öppna PKCS#11 CryptoServer-applikationen, som vanligtvis finns på användarens skrivbord

Steg 3: Välj önskad plats
Klicka på önskat platsnummer i tabellen till vänster. Här har vi valt platsnummer 1.

Steg 4: Logga in som ADMINISTRATÖR
- Gå till avsnittet Logga in/Logga ut i den översta fältet och välj alternativet "Generell inloggning".
- Ange "ADMIN" som användarnamn och välj "Keyfile" som lösenord.
- Bläddra i nyckelfilen och ange lösenordsfilen. När du kör simulatorn väljer du filen "ADMIN_SIM.key", annars använder du "ADMIN_EC.key". Dessa nyckelfiler finns vanligtvis i katalogen "C:\Program Files\Utimaco\SecurityServer\Administration".
- Klicka på Logga in för att logga in som ADMIN-användare. Det visar ett lås i inloggningsstatusen i den vänstra tabellen för den platsen.
Steg 5: Initiera token för den här platsen
- Öppna avsnittet Slot Management från den översta fältet och välj alternativet "Init Token".
- Ange det obligatoriska tokennamnet för den här platsen och ange en tillfällig PIN-kod för rollen som säkerhetsansvarig (denna PIN-kod kommer att ändras i senare steg)
- Klicka på knappen ”Init Token” för att slutföra token. Det kommer nu att inaktivera alternativet ”Init Token” för den här platsen och aktivera alternativet ”Ta bort SO”.
- Gå nu till avsnittet Logga in/Logga ut och klicka på alternativet "Logga ut alla" för att logga ut alla aktiva användarroller.
- Det kommer att visas en grön bockmarkering i den vänstra tabellen under Token Init för den här platsen.
Steg 6: Konfigurera rollen som säkerhetsansvarig
- Gå till avsnittet "Logga in/Logga ut" och välj alternativet "Logga in".
- Ange den tillfälliga SO-PIN-koden som du ställde in i det tidigare steget för rollen som säkerhetsansvarig och klicka på knappen "Logga in". En låssymbol visas i den vänstra tabellen under "Inloggningsstatus".
- Gå nu till avsnittet Slothantering från den översta fältet och ange en ny PIN-kod för rollen som säkerhetsansvarig genom att välja alternativet "Ange PIN".
- Ange en ny SO-PIN för säkerhetsansvarig för den här platsen.
- Den loggar ut dig från den aktuella sessionen som SO, vilket du kan se i avsnittet "Inloggning/Logga ut" eller i kolumnen "Inloggningsstatus" i tabellen till vänster.
- Logga in igen som SO med den nya SO-PIN-koden genom att välja ”Logga in SO” i avsnittet ”Logga in/Logga ut”.
- Det kommer att visas ett lås i tabellen till vänster vid lyckad inloggning.
Steg 7: Konfigurera rollen Kryptografisk användare
- Gå till avsnittet ”Slothantering” och välj alternativet ”Initiera PIN”.
- Ange en tillfällig PIN-kod för den kryptografiska användaren för den här platsen och klicka på knappen "Initiera PIN".
- Logga nu ut alla aktiva sessioner från avsnittet "Logga in/Logga ut".
- Logga nu in som kryptografisk användare med den tillfälliga PIN-koden genom att välja alternativet "Inloggning" i avsnittet "Inloggning/Logga ut".
- Gå till avsnittet ”Slot Management” och ställ in en ny PIN-kod för den kryptografiska användaren med hjälp av alternativet ”Ställ in PIN”.
- Uppdatera PIN-koden för den kryptografiska användaren i den här platsen
- Detta loggar ut dig från din nuvarande session. Logga in igen som användaren från avsnittet "Logga in/Logga ut".
- Du är redo med alla nödvändiga roller för den här platsen. Du måste vara inloggad som kryptografisk användare för att utföra objekthantering, till exempel nycklar eller certifikatgenerering.
Konfigurera OpenSSL för att använda PKCS#11-motorn
OpenSSL måste konfigureras för att ladda Utimaco PKCS#11 Provider (cs_pkcs11_R3.dll) och OpenSC PKCS#11 Engine Plugin (pkcs11.dll) för att utföra kryptografiska operationer med HSM.

Steg:
Steg 1: Leta reda på OpenSSL-konfigurationsfilen (openssl.cfg)
Hitta OpenSSL-konfigurationsfilen: C:\Program Files\Common Files\SSL
Steg 2: Redigera OpenSSL-konfigurationen
- Öppna openssl.cfg i en textredigerare med administratörsbehörighet.
- Lägg till följande högst upp i filen för att aktivera dynamisk motorbelastning:
```
openssl_conf = openssl_init
```
- Lägg till följande i slutet av filen för att konfigurera PKCS#11-motorn:
```
                                                    [openssl_init] engines = engine_section [engine_section] pkcs11 = pkcs11_section [pkcs11_section] engine_id = pkcs11 dynamic_path = C:\\Program Files\\OpenSSL-Win64\\src\\pkcs11.dll MODULE_PATH = C:\\Program Files\\Utimaco\\SecurityServer\\Lib\\cs_pkcs11_R3.dll init = 0

                                                
```
Steg 3: Verifiera OpenSSL-konfiguration och anslutning
- Öppna en kommandotolk och kör:
```
openssl-motor pkcs11 -t
```
- Förväntad utdata bekräftar att PKCS#11-motorn är tillgänglig:
  
  (pkcs11) PKCS#11-motor
  
  [ tillgänglig ]
Konfigurera CodeSign Secure
CodeSign Secure kräver konfiguration för att ansluta till Utimaco SecurityServer HSM för säkra kodsigneringsåtgärder. Filen app-config.properties anger de olika detaljer som behövs för att kunna ansluta till Utimaco HSM.

Steg:
Steg 1: Leta reda på filen app-config.properties
Navigera till mappen CertificateManagement i installationskatalogen för CodeSign Secure och leta reda på filen app-config.properties, vanligtvis: C:\CodeSignSecure\src\CertificateManagement
Steg 2: Uppdatera HSM-detaljfälten
- Öppna app-config.properties i en textredigerare med administratörsbehörighet.
- Uppdatera följande fält och ersätt platshållarna med dina HSM-anslutningsuppgifter:
  
  HSM_LIB_PATH_UTIMACO=
  
  HSM_PIN_UTIMACO=
  
  HSM_TOKEN_UTIMACO=
  
  HSM_SLOT_UTIMACO=
- Spara filen med de ändrade uppgifterna.