Securosys Integratiehandleiding

Voorwaarden

Om de PKCS#11 Engine soepel te laten werken met uw Securosys Primus 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:

1. Securosys PKCS#11-provider

De Securosys PKCS#11 Provider (PrimusAPI PKCS#11) is vereist voor de interface met de Primus HSM. Deze bibliotheek maakt communicatie tussen uw applicaties en de HSM mogelijk via de PKCS#11-standaard.

Installatie Stappen:

  1. Downloadlink verkrijgen

    Ga naar de Securosys Support Portal om de PrimusAPI_PKCS11-DownloadLink-v#.txt bestand, dat de downloadreferenties en versiegegevens bevat. U hebt een account nodig op de Securosys Support Portal. Als u die niet hebt, neem dan contact op met de Securosys-ondersteuning om toegang te krijgen.

  2. Download de aanbieder

    • Gebruik de opdracht curl om het providerpakket te downloaden. Open een opdrachtprompt en voer de volgende opdrachten uit: 

      stel GEBRUIKER=support.reader.p11 in
      stel CRED= in

      Vervangen met de waarde uit het tekstbestand. 

      set VERSIE=v2.3.4
      curl -L -o "PrimusAPI_PKCS11-%VERSION%.zip" https://%USER%:%CRED%@securosys.jfrog.io/artifactory/p11/PrimusAPI_PKCS11-%VERSION%.zip

    • Als alternatief kunt u het ZIP-bestand rechtstreeks downloaden van de Securosys JFrog Artifactory met behulp van een browser hier

      • Gebruikersnaam: support.reader.p11
      • Wachtwoord: Haal de waarde uit het bestand PrimusAPI_PKCS11-DownloadLink-v#.txt.
  3. Installeer de provider
    • Pak het gedownloade ZIP-bestand uit en zoek het MSI-installatieprogramma (bijvoorbeeld PrimusAPI_PKCS11--win64.msi) in de uitgepakte map.
    • Dubbelklik op het MSI-bestand om het installatieprogramma uit te voeren en volg de installatie-instructies. Zorg ervoor dat u de installatie uitvoert op de standaardlocatie (C:\Program Files\Securosys\Primus P11), tenzij anders vereist.

      • Let op: Maak een back-up van alle bestaande primus.cfg- en .secrets.cfg-configuratiebestanden in de installatiemap, aangezien het installatieprogramma deze kan overschrijven.

  4. Omgevingsvariabele configureren

    Voeg de directorylocatie van de geïnstalleerde bestanden toe aan het systeem-PATH voor eenvoudigere toegang. 

    C:\Program Files\Securosys\Primus P11
  5. Verificatie

    Open een nieuwe opdrachtprompt en voer de volgende opdracht uit om de geïnstalleerde hulpprogramma's te testen: 

    ppin -v

2. OpenSSL 3.x

OpenSSL 3.x is vereist voor cryptografische bewerkingen en om de PKCS#11-provider te benutten met de Securosys HSM.

Installatie Stappen:

  1. OpenSSL downloaden

    Download het nieuwste 64-bits OpenSSL 3.x-installatieprogramma voor Windows met behulp van dit link.

  2. OpenSSL installeren
    • Voer het gedownloade installatieprogramma uit met beheerdersrechten.
    • Kies de standaardinstallatiemap (C:\Program Files\OpenSSL-Win64), tenzij u specifieke vereisten hebt.
  3. Omgevingsvariabele configureren

    Voeg de binaire map OpenSSL toe aan het systeem-PATH:

    C:\Program Files\OpenSSL-Win64\bin
  4. Verificatie

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

    openssl-versie

3. OpenSC PKCS11-tool

De OpenSC PKCS#11 Tool biedt hulpprogramma's zoals pkcs11-tool om sleutels te beheren en bewerkingen uit te voeren op de HSM via de PKCS#11-interface.

Installatie Stappen:

  1. OpenSC downloaden

    Download het nieuwste OpenSC Windows-installatieprogramma van de OpenSC GitHub-releasepagina hier.

  2. OpenSC installeren

    Voer het MSI-installatieprogramma uit als beheerder op de standaardlocatie (C:\Program Files\OpenSC Project\OpenSC).

  3. Omgevingsvariabele configureren

    Voeg de OpenSC tools-map toe aan het systeem-PATH:

    C:\Program Files\OpenSC Project\OpenSC\tools\
  4. Verificatie

    Open een nieuwe opdrachtprompt en voer de volgende opdracht uit om pkcs11-tool te testen 

    pkcs11-tool --versie

4. 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:

  1. Visual Studio Build Tools downloaden

    Download de Microsoft Build Tools voor Visual Studio 2022 met behulp van deze link.

  2. Bouwtools installeren

    Voer het installatieprogramma (vs_buildtools.exe) uit met beheerdersrechten.

  3. Installatie verifiëren

    Open de opdrachtprompt 'x64 Native Tools' vanuit het menu Start en voer het uit 

    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

5. 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:

  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.
  2. Stel de bibliotheek samen
    • Open de “x64 Native Tools Command Prompt”.
    • Navigeer naar de libp11-map
      • cd “C:\Gebruikers\\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.

  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.

  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 de Securosys PKCS#11 Provider, OpenSSL en de OpenSC PKCS#11 Wrapper Library configureren om communicatie met uw Securosys Primus HSM mogelijk te maken.

1. Configureer de Securosys PKCS#11-provider

De Securosys PKCS#11 Provider heeft configuratiebestanden (primus.cfg en .secrets.cfg) nodig om de HSM-verbindingsgegevens op te geven, zoals het IP-adres, de poort, geheimen en logboekinstellingen.

Stappen:

  1. Zoek het configuratiebestand (primus.cfg)

    Navigeer naar de installatiemap van Securosys PKCS#11 Provider, meestal: 

    C:\Program Files\Securosys\Primus P11
  2. Bewerk de HSM-CONFIGURATIESECTIE met HSM-details
    • Open primus.cfg in een teksteditor met beheerdersrechten.
    • Voeg de volgende configuratie toe of werk deze bij in de sectie ‘HSM-CONFIGURATIE’, waarbij u tijdelijke aanduidingen vervangt door uw HSM-gegevens: 
      • hsm0 : { host = "HSM HOSTNAME (zoals a-api.cloudshsm.com)"; port = "HSM PORT (zoals 2310)"; slots: { slot0: { client_id = "Client_ID1 (zoals Client_0)"; user_name = "PARTITION_NAME1"; proxy_user = "SERVICE_USER"; /* of verwijder indien geen proxy nodig */ id = 1; }; /* end slot0 */ slot1: { client_id = "Client_ID2"; user_name = "PARTITION_NAME2"; proxy_user = "SERVICE_USER"; /* of verwijder indien geen proxy nodig */ id = 2; }; /* end slot1 */ }; /* end slots */ }; /* end hsm0 */
  3. Bewerk de LOGCONFIGURATIESECTIE met loggegevens

    Voeg de volgende configuratie toe of werk deze bij in de sectie 'LOGCONFIGURATIE', waarbij u tijdelijke aanduidingen vervangt door uw loggegevens: 

    log : { file = "C:\Program Files\Securosys\Primus P11\primus.log"; /* optioneel voor Windows */ trace_linenumber = false; trace_timestamp = true; trace_function = true; trace_inout = false; trace_pid = true; trace_filename = false; trace_mask = 0x01; trace_level = 6; /* 0-7 logniveaudetails */ }; /* einde log */
  4. Permanent Secret instellen in het .secrets.cfg-bestand
    • Open een opdrachtprompt en navigeer naar de map Primus P11 (indien deze niet is ingesteld in het pad van de omgevingsvariabele) met behulp van de onderstaande opdracht: 
      • cd C:\Program Files\Securosys\Primus P11
    • Vervang de tijdelijke aanduiding door de HSM-gebruikersnaamwaarde die u hebt ingesteld in het bestand primus.cfg en voer de volgende opdracht uit: 
      • ppin -a -e

      Stel de PKCS11_PIN in voor de genoemde HSM_USERNAME

      NOTITIE: Zorg ervoor dat u lees- en schrijfmachtigingen hebt om het bestand .secrets.cfg te wijzigen met een permanent geheim.

  5. Controleer de verbinding met HSM
    • Open een opdrachtprompt en navigeer naar de map Primus P11 (indien deze niet is ingesteld in het pad van de omgevingsvariabele) met behulp van de onderstaande opdracht: 
      • cd C:\Program Files\Securosys\Primus P11
    • Voer de ppin-tool uit om de HSM-verbinding te testen:
      • ppin -t

2. Configureer OpenSSL om de PKCS#11 Engine te gebruiken

OpenSSL moet worden geconfigureerd om de Securosys PKCS#11 Provider (primusP11.dll) en de OpenSC PKCS#11 Engine Plugin (pkcs11.dll) te laden om cryptografische bewerkingen met de HSM uit te voeren.

Stappen:

  1. Zoek het OpenSSL-configuratiebestand (openssl.cfg)

    Zoek het OpenSSL-configuratiebestand:

    C:\Program Files\Algemene bestanden\SSL
  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\\Securosys\\Primus P11\\primusP11.dll" PIN = "PKCS11_PIN" init = 0

      Dynamisch_pad: Pad naar de OpenSC PKCS#11 Engine Plugin (pkcs11.dll) gecompileerd in de vereisten.

      MODULE_PAD: Pad naar de Securosys PKCS#11 Provider DLL.

      PIN: PKCS11_PIN-waarde voor de vereiste HSM-gebruikersnaam/partitie die is ingesteld tijdens de permanente geheime stappen.

  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 ]

3. Test de PKCS#11-interface met pkcs11-tool

Gebruik de OpenSC pkcs11-tool om te controleren of de PKCS#11-interface kan communiceren met de HSM.

Stappen:

  1. Voer pkcs11-tool uit
    • Open een opdrachtprompt en navigeer naar de map OpenSC tools, indien dit niet is ingesteld in het pad van de omgevingsvariabele: 
      • cd “C:\Program Files\OpenSC Project\OpenSC\tools”
    • Voer de volgende opdracht uit om de beschikbare slots op de HSM weer te geven: 
      • pkcs11-tool --module "C:\Program Files\Securosys\Primus P11\primusP11.dll" --list-slots

4. CodeSign Secure configureren

CodeSign Secure vereist configuratie om verbinding te maken met de Securosys Primus HSM voor veilige codeondertekening. Het bestand app-config.properties specificeert de verschillende details voor een succesvolle verbinding met de Securosys Primus HSM.

Stappen:

  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 is dit: 

    C:\CodeSignSecure\src\CertificateManagement
  2. De HSM-detailvelden 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_SECUROSYS= 
HSM_PIN_SECUROSYS= 
HSM_TOKEN_SECUROSYS= 
HSM_SLOT_SECUROSYS=
    • Sla het bestand met de gewijzigde gegevens op.