Utimaco Connector Integratiehandleiding

Voorwaarden

Om de PKCS#11 Engine soepel te laten werken met uw Utimaco HSM en CodeSign Secure van Encryption Consulting, hebt u een paar belangrijke dingen nodig. Hier zijn de stappen voor het installeren van de resources die essentieel zijn voor het instellen van de Windows-omgeving:

Utimaco-beveiligingsserver
Utimaco SecurityServer biedt cryptografische bibliotheken, tools en interfaces (zoals PKCS#11, CSP en JCE) voor het veilig beheren van sleutels en uitvoeren van cryptografische bewerkingen. De software bevat de CryptoServer SDK, beheertools en simulatoren, die naadloze HSM-integratie mogelijk maken voor verbeterde beveiliging en naleving van regelgeving.

Installatie Stappen:
Stap 1: Download de Provider
Download de provider (bijv. SecurityServerEvaluation-V6.1.1 voor Windows) via het Utimaco-klantenportaal.
Stap 2: De provider installeren
- Pak het gedownloade pakket uit, voer het MSI-installatieprogramma uit en volg de aanwijzingen om Utimaco Security Server op uw systeem te installeren.
- De vereiste hulpprogramma's worden geïnstalleerd op de standaardlocatie (C:\Program Files\Utimaco), tenzij anders is opgegeven tijdens de installatie. Daarnaast worden er snelkoppelingen voor de volgende hulpprogramma's op het bureaublad van de huidige gebruiker gemaakt, zodat u er gemakkelijker toegang toe hebt:
  - CryptoServer-beheer
  - PKCS#11 CryptoServer-beheer
  - CryptoServer-simulator
- Daarnaast worden ook de omgevingsvariabelen aangepast met de geselecteerde locaties en configuratiebestanden van de Utimaco SecurityServer.
OpenSSL 3.x
OpenSSL 3.x is vereist voor cryptografische bewerkingen en om de PKCS#11-provider te benutten met de Utimaco HSM.

Installatie Stappen:
Stap 1: OpenSSL downloaden
Download het nieuwste 64-bits OpenSSL 3.x-installatieprogramma voor Windows met behulp van dit link.
Stap 2: OpenSSL installeren
- Voer het gedownloade installatieprogramma uit met beheerdersrechten.
- Kies de standaardinstallatiemap (C:\Program Files\OpenSSL-Win64), tenzij u specifieke vereisten hebt.
Stap 3: Omgevingsvariabele configureren
Voeg de binaire map OpenSSL toe aan het systeem-PATH:
- C:\Program Files\OpenSSL-Win64\bin
Stap 4: Verificatie
Open een nieuwe opdrachtprompt en voer de volgende opdracht uit om de openssl-installatie te testen.
```
openssl-versie
```

Java Runtime Environment

Utimaco SecurityServer vereist ook een Java Runtime Environment (geteste versie Java 15). Raadpleeg de onderstaande tabel om de Java-compatibele versie te controleren:

Java Runtime Environment	Versie
Oracle Java	8,11,15
OpenJDK	8,11,15

Installatie Stappen:

Stap 1: Java 15 downloaden

Download het compatibele Java-uitvoerbare bestand van hier voor uw Windows-systeem.

Stap 2: Java 15 installeren

Voer het gedownloade uitvoerbare bestand uit en volg de aanwijzingen om Java 15 te installeren.

Stap 3: Verificatie

Open een nieuwe opdrachtprompt en voer de volgende opdracht uit om de Java-installatie te testen.

java -version

Microsoft Visual Studio Build-tools
Microsoft Visual Studio Build Tools zijn vereist om de OpenSC PKCS#11 Wrapper Library (libp11) op Windows te compileren

Installatie Stappen:
Stap 1: Visual Studio Build Tools downloaden
Download de Microsoft Build Tools voor Visual Studio 2022 met behulp van deze link.
Stap 2: Build Tools installeren
Voer het installatieprogramma (vs_buildtools.exe) uit met beheerdersrechten.
Stap 3: Installatie verifiëren
Open de x64 Native Tools Opdrachtprompt vanuit het Startmenu en uitvoeren
```
nmake /?
```
Hiermee wordt de help voor het hulpprogramma nmake weergegeven, waarmee wordt bevestigd dat de buildtools zijn geïnstalleerd.
NOTITIE: "x64 Native Tools Command Prompt" zou aanwezig moeten zijn in C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2022\Visual Studio Tools\VC
OpenSC PKCS#11 Wrapper-bibliotheek
De OpenSC PKCS#11 Wrapper Library (libp11) biedt de PKCS#11 engine-plugin (pkcs11.dll) zodat OpenSSL kan communiceren met de HSM.

Installatie Stappen:
Stap 1: Download de broncode
- Kloon de OpenSC/libp11-repository van GitHub of download deze als een ZIP-bestand.
- Klonen met behulp van Git (indien geïnstalleerd):
```
git kloon https://github.com/OpenSC/libp11.git C:\Gebruikers\ \bron\repos\libp11
```
- Of download de ZIP hier link en pak het uit naar C:\Users\ \bron\repos\libp11.
Stap 2: De bibliotheek compileren
- Open de “x64 Native Tools Command Prompt”.
- Navigeer naar de map libp11, bijvoorbeeld cd “C:\Users\ \bron\repos\libp11”
- Voer de opdracht nmake uit om de bibliotheek te bouwen
```
nmake /f Makefile.mak OPENSSL_DIR="C:\Program Files\OpenSSL-Win64" BUILD_FOR=WIN64
```
  NOTITIE: Zorg ervoor dat OPENSSL_DIR verwijst naar uw OpenSSL-installatiemap.
Stap 3: Compilatie verifiëren
Controleer of het bestand pkcs11.dll zich in de map libp11\src bevindt. Dit is de OpenSC PKCS#11 Engine Plugin.
Stap 4: Kopieer de SRC-map
Kopieer de map src die u zojuist hebt gemaakt naar uw OpenSSL bin-directory, d.w.z. C:\Program Files\OpenSSL-Win64\bin

Configuratie

Nadat u de vereisten hebt geïnstalleerd, moet u Utimaco SecuritySever, OpenSSL en de OpenSC PKCS#11 Wrapper Library configureren om communicatie met uw Utimaco HSM mogelijk te maken.

Configureer de Utimaco SecurityServer
Voor het configureren van Utimaco SecurityServer moet u omgevingsvariabelen instellen en configuratiebestanden bijwerken (bijvoorbeeld PKCS#11-instellingen) om HSM-toegang en -bewerkingen veilig te beheren.

Stappen:
Stap 1: Zoek het configuratiebestand (cs_pkcs11_R3.cfg)
Navigeer naar de installatiemap van Utimaco PKCS#11 Provider, meestal: C:\ProgramData\Utimaco\PKCS11_R3
Stap 2: Werk het IP-adres van de HSM bij
Werk onder de sectie [HSMCluster] het IP-adres van uw Utimaco HSM bij. Vergeet niet de regel uit te schakelen (het hekje te verwijderen) (bijv. [e-mail beveiligd]) waar u het IP-adres hebt toegevoegd.

Hier gebruiken we een lokale simulator die standaard draait op localhost (127.0.0.1) poort 3001.
Gebruikersrollen voor een slot maken
Om sleutels en certificaten te genereren met Utimaco SecurityServer, moet u gebruikersrollen maken en definiëren: Beheerder, Beveiligingsfunctionaris (SO) en Cryptografische gebruiker.

Stappen:
Stap 1: Start de CryptoServer Simulator
- Start de CryptoServer Simulator op het bureaublad om de vereiste instellingen te initialiseren.
  
  NOTITIE: Als u een echte Utimaco HSM gebruikt, moet u de applicatie CryptoServer Administrator starten. Deze bevindt zich ook op het bureaublad.
Stap 2: Zoek de PKCS#11 CryptoServer-beheerapplicatie
Open de PKCS#11 CryptoServer-applicatie, die normaal gesproken op het bureaublad van de gebruiker staat

Stap 3: Selecteer de gewenste sleuf
Klik in de linker tabel op het gewenste slotnummer. Hier hebben we slotnummer 1 geselecteerd.

Stap 4: Meld u aan als ADMIN
- Ga naar het gedeelte Inloggen/Uitloggen in de bovenste balk en selecteer de optie 'Algemeen inloggen'.
- Voer “ADMIN” in als gebruikersnaam en selecteer de optie “Keyfile” voor het wachtwoord.
- Blader door het sleutelbestand en voer het wachtwoordbestand in. Selecteer tijdens het uitvoeren van de simulator het bestand "ADMIN_SIM.key"; anders gebruikt u "ADMIN_EC.key". Deze sleutelbestanden bevinden zich meestal in de directory "C:\Program Files\Utimaco\SecurityServer\Administration".
- Klik op Inloggen om in te loggen als ADMIN-gebruiker. Er wordt een slot weergegeven in de inlogstatus in de linkertabel voor dat slot.
Stap 5: Initialiseer het token voor deze sleuf
- Open het gedeelte Slotbeheer in de bovenste balk en selecteer de optie 'Token initiëren'.
- Voer de vereiste tokennaam voor deze sleuf in en geef een tijdelijke pincode op voor de rol van beveiligingsfunctionaris (deze pincode wordt in latere stappen gewijzigd)
- Klik op de knop "Init Token" om het token te finaliseren. Hiermee wordt de optie "Init Token" voor deze sleuf uitgeschakeld en de optie "Delete SO" ingeschakeld.
- Ga nu naar het gedeelte Inloggen/Uitloggen en klik op de optie 'Alles uitloggen' om alle actieve gebruikersrollen uit te loggen.
- Er verschijnt een groen vinkje in de linkertabel onder Token Init voor deze sleuf.
Stap 6: Stel de rol van beveiligingsfunctionaris in
- Ga naar het gedeelte ‘Inloggen/Uitloggen’ en selecteer de optie ‘Login SO’.
- Voer de tijdelijke SO-PIN in die u in de vorige stap voor de rol van Security Officer hebt ingesteld en klik op de knop 'Inloggen'. Er verschijnt een slotje in de linkertabel onder 'Inlogstatus'.
- Ga nu naar het gedeelte Slotbeheer in de bovenste balk en stel een nieuwe pincode in voor de rol van Security Officer door de optie 'Pincode instellen' te selecteren.
- Stel een nieuwe SO PIN in voor de beveiligingsfunctionaris van deze sleuf.
- U wordt dan afgemeld bij de huidige sessie als de SO. Dit kunt u zien in het gedeelte 'Inloggen/Uitloggen' of in de kolom 'Inlogstatus' in de tabel aan de linkerkant.
- Meld u opnieuw aan als SO met de nieuwe SO-PIN door 'Login SO' te selecteren in het gedeelte 'Login/Logout'.
- Als u succesvol bent ingelogd, ziet u in de linker tabel een slot.
Stap 7: De cryptografische gebruikersrol instellen
- Ga naar het gedeelte ‘Slotbeheer’ en selecteer de optie ‘PIN initialiseren’.
- Voer een tijdelijke pincode in voor de cryptografische gebruiker voor deze sleuf en klik op de knop “PIN initialiseren”.
- Meld u nu af bij alle actieve sessies via het gedeelte ‘Inloggen/Uitloggen’.
- Meld u nu aan als cryptografische gebruiker met behulp van de tijdelijke pincode door de optie 'Gebruiker aanmelden' te selecteren in het gedeelte 'Aanmelden/Afmelden'.
- Ga naar het gedeelte 'Slotbeheer' en stel een nieuwe pincode in voor de cryptografische gebruiker met behulp van de optie 'Pincode instellen'.
- Werk de pincode bij voor de cryptografische gebruiker in deze sleuf
- Hiermee wordt u afgemeld bij uw huidige sessie. Meld u opnieuw aan als gebruiker via het gedeelte 'Inloggen/Afmelden'.
- U beschikt nu over alle vereiste rollen voor deze sleuf. U moet ingelogd zijn als cryptografische gebruiker om objectbeheer uit te voeren, zoals het genereren van sleutels of certificaten.
OpenSSL configureren voor gebruik van de PKCS#11 Engine
OpenSSL moet worden geconfigureerd om de Utimaco PKCS#11 Provider (cs_pkcs11_R3.dll) en de OpenSC PKCS#11 Engine Plugin (pkcs11.dll) te laden om cryptografische bewerkingen met de HSM uit te voeren.

Stappen:
Stap 1: Zoek het OpenSSL-configuratiebestand (openssl.cfg)
Zoek het OpenSSL-configuratiebestand: C:\Program Files\Common Files\SSL
Stap 2: Bewerk de OpenSSL-configuratie
- Open openssl.cfg in een teksteditor met beheerdersrechten.
- Voeg het volgende bovenaan het bestand toe om dynamisch laden van de engine in te schakelen:
```
openssl_conf = openssl_init
```
- Voeg het volgende toe aan het einde van het bestand om de PKCS#11-engine te configureren:
```
                                                    [openssl_init] engines = engine_sectie [engine_sectie] pkcs11 = pkcs11_sectie [pkcs11_sectie] engine_id = pkcs11 dynamisch_pad = C:\\Program Files\\OpenSSL-Win64\\src\\pkcs11.dll MODULE_PATH = C:\\Program Files\\Utimaco\\SecurityServer\\Lib\\cs_pkcs11_R3.dll init = 0

                                                
```
Stap 3: Controleer de OpenSSL-configuratie en -verbinding
- Open een opdrachtprompt en voer het volgende uit:
```
openssl engine pkcs11 -t
```
- Verwachte output bevestigt dat de PKCS#11 engine beschikbaar is:
  
  (pkcs11) PKCS#11-motor
  
  [ beschikbaar ]
Configureer CodeSign Secure
CodeSign Secure vereist configuratie om verbinding te maken met de Utimaco SecurityServer HSM voor veilige codeondertekening. Het bestand app-config.properties specificeert de verschillende details die nodig zijn om verbinding te maken met de Utimaco HSM.

Stappen:
Stap 1: Zoek het app-config.properties-bestand
Navigeer naar de map CertificateManagement in de installatiemap van CodeSign Secure en zoek het bestand app-config.properties, meestal: C:\CodeSignSecure\src\CertificateManagement
Stap 2: De HSM-detailsvelden bijwerken
- Open app-config.properties in een teksteditor met beheerdersrechten.
- Werk de volgende velden bij en vervang tijdelijke aanduidingen door uw HSM-verbindingsgegevens:
  
  HSM_LIB_PATH_UTIMACO=
  
  HSM_PIN_UTIMACO=
  
  HSM_TOKEN_UTIMACO=
  
  HSM_SLOT_UTIMACO=
- Sla het bestand met de gewijzigde gegevens op.