IBM Cloud Docs
Verschlüsselungsoperationen mit der PKCS #11-API durchführen

Verschlüsselungsoperationen mit der PKCS #11-API durchführen

Von IBM Cloud® Hyper Protect Crypto Services wird die PKCS #11-Standard-API für den Zugriff auf das Cloud-HSM von Hyper Protect Crypto Services für Verschlüsselungsoperationen bereitgestellt.

Voraussetzungen

Bevor Sie die PKCS #11-API einrichten und verwenden können, folgen Sie zunächst den Best Practices für das Einrichten von PKCS #11-Benutzertypen, um verschiedene Service-ID-API-Schlüssel für die verschiedenen PKCS #11-Benutzertypen zu erstellen.

Schritt 1: PKCS #11-Bibliothek einrichten

Die PKCS #11-Bibliothek muss auf Ihrer Workstation eingerichtet werden, um sie Ihren Anwendungen für den Aufruf der PKCS #11-Standardfunktionen zur Verfügung zu stellen.

Die PKCS #11-Bibliothek für beideamd64 Unds390x Plattformen, wird nur unterstützt aufLinux.

Wenn Sie eine Java PKCS #11 mit dem SunPKCS11-Provider auf der Plattform IBM Z (s390x) ausführen, stellen Sie sicher, dass Sie beim Starten Ihrer Anwendung die neueste IBM Semeru-JVM verwenden und die Option -Xjit:noResumableTrapHandler Java angeben. Sie können die neueste s390x-Version der IBM Semeru-Java Virtual Machine (JVM) herunterladen, indem Sie das Filterfeld Architektur auf der IBM Semeru Runtime-Downloadseitein s390x ändern.

  1. Laden Sie die neueste PKCS #11 -Bibliothek herunter. Für die Bibliotheksdateinamen gilt die folgende Namenskonvention:pkcs11-grep11-<platform>.so.<version>. Die Plattformangabe ist entweder amd64 oder s390x und die Versionsangabe entspricht der Standardsyntax übergeordnete_version.untergeordnete_version.build.
  2. Verschieben Sie die Bibliothek in einen Ordner, auf den Ihre Anwendungen zugreifen können. Wenn Sie Ihre Anwendung z. B. unter Linux ausführen, können Sie die Bibliothek in /usr/local/lib, /usr/local/lib64 oder /usr/lib verschieben.

Schritt 2: (Optional) Integrität und Authentizität der PKCS #11-Bibliothek überprüfen

Überprüfen Sie im Hinblick auf maximale Sicherheit die Integrität und Authentizität der PKCS #11-Bibliothek, bevor Sie Ihre PKCS #11-Anwendungen unter Verwendung der Bibliothek ausführen.

Hyper Protect Crypto Services ermöglicht Überprüfung des signierten Codes um sicherzustellen, dass die Signatur mit dem Originalcode übereinstimmt. Wenn die heruntergeladene PKCS #11-Bibliotheksdatei verändert oder beschädigt wurde, wird eine andere Signatur erzeugt und die Verifizierung schlägt fehl. Um sicherzustellen, dass die Dateien während des Downloadvorgangs nicht manipuliert oder beschädigt werden, führen Sie die folgenden Schritte mithilfe des OpenSSL Kommandozeilentool.

  1. Laden Sie die neueste Version der folgenden Dateien herunter von der Bibliotheksrepository in dasselbe Verzeichnis, in dem Sie die PKCS#11-Bibliothek speichern:

    • pkcs11-grep11-<platform>.so.<version>.sig: Der signierte kryptografische Hashwert der PKCS #11-Bibliothek, wobei die Plattform entweder amd64 oder s390x und die Version der major.minor.build der Signaturdatei ist. Sowohl platform als auch version muss mit dem jeweiligen Wert für platform und version der PKCS #11-Bibliothek übereinstimmen, die Sie verwenden.

    • signing_cert.pem: Das Signierzertifikat der PKCS #11-Clientdateien von Hyper Protect Crypto Services.

    • digicert_cert.pem: Ein temporäres Codesignierzertifikat zum Überprüfen des Signierzertifikats der PKCS #11-Clientdateien von Hyper Protect Crypto Services.

  2. Extrahieren Sie den öffentlichen Schlüssel aus dem Signierzertifikat signing_cert.pem in die Datei sigkey.pub mit dem folgenden Befehl:

    openssl x509 -pubkey -noout -in signing_cert.pem -out sigkey.pub
    
  3. Überprüfen Sie die Integrität der PKCS #11-Bibliotheksdatei mit dem folgenden Befehl:

    openssl dgst -sha256 -verify sigkey.pub -signature pkcs11-grep11-<platform>.so.<version>.sig pkcs11-grep11-<platform>.so.<version>
    

    Ersetzen Sie platform entweder durch amd64 oder s390x und ersetzen Sie version durch die Werte für übergeordnete_version.untergeordnete_version.build der Bibliothek.

    Nachdem die Verifizierung erfolgreich abgeschlossen wurde, wird eine Nachricht angezeigt, in der Sie darüber informiert werden, dass die Verified OK war.

  4. Überprüfen Sie die Authentizität und Gültigkeit des Signierzertifikats mit dem folgenden Befehl:

    openssl ocsp -no_nonce -issuer digicert_cert.pem -cert signing_cert.pem -VAfile digicert_cert.pem -text -url http://ocsp.digicert.com -respout ocsptest
    

    Nachdem die Verifizierung erfolgreich abgeschlossen wurde, werden in der Ausgabe die Meldungen Response verify OK und signing_cert.pem: good angezeigt.

  5. Wenn die Überprüfung fehlschlägt, brechen Sie die Installation ab und wenden Sie sich an IBM, um Unterstützung anzufordern.

Schritt 3: PKCS #11-Konfigurationsdatei einrichten

Um die PKCS #11-Bibliothek mit dem Cloud-HSM von Hyper Protect Crypto Services zu verbinden, damit Sie Verschlüsselungsfunktionen ausführen können, müssen Sie die folgenden Schritte ausführen, um die Konfigurationsdatei einzurichten.

  1. Erstellen Sie eine Konfigurationsdatei mit dem Namen grep11client.yaml auf der Basis des folgenden Beispiels. Der Bibliotheksrepository stellt auch eine Vorlage zur Verfügung, die Sie anpassen können. Den Kommentaren im Code können Sie Informationen zu jedem Feld entnehmen.

    iamcredentialtemplate: &defaultiamcredential
      enabled: true
      endpoint: "https://iam.cloud.ibm.com"
    
    sessionauthtemplate: &defaultsessionauth
      enabled: false
      tokenspaceIDPassword:  # Authenticated keystore password 6-8 characters in length
    
    tokens:
      0:
        grep11connection:
          # The EP11 endpoint address starting from 'ep11'. For example: "<instance_ID>.ep11.us-south.hs-crypto.appdomain.cloud"
          address: "<EP11_endpoint_URL>"
          port: "<EP11_endpoint_port_number>" # The EP11 endpoint port number
          tls:
            enabled: true # EP11 requires TLS connection.
            # Set it 'true' if you want to enable mutual TLS connections.
            # By default, set it 'false' because EP11 requires server-only authentication.
            mutual: <enable_mtls>
            # 'cacert' is a full-path certificate file. In Linux with the 'ca-ca-certificates' package installed, this is normally not needed.
            cacert:
            # Specify the file path of the client certificate if you enable mutual TLS. Otherwise, keep it empty.
            certfile: <client_certificate>
            # Specify the file path of the client certificate private key if you enable mutual TLS. Otherwise, keep it empty.
            keyfile: <client_certificate_private_key>
        storage:
            # 'remotestore' needs to be enabled if you want to generate keys with the attribute CKA_TOKEN.
          remotestore:
            enabled: true
        users:
          0: # The index of the Security Officer (SO) user MUST be 0.
            # The name for the Security Officer (SO) user. For example: "Administrator".
            name: "<SO_user_name>"
            iamauth: *defaultiamcredential
          1: # The index of the normal user MUST be 1.
            # The name for the normal user. For example: "Normal user".
            name: "<normal_user_name>"
            # The 128-bit UUID of the private keystore. For example: "f00db2f1-4421-4032-a505-465bedfa845b".
            tokenspaceID: "<private_keystore_spaceid>"
            iamauth: *defaultiamcredential
            # Do not override the defaultsessionauth template
            # The same values must be used for both the private (normal user) and public (anonymous) keystores
            sessionauth: *defaultsessionauth
          2: # The index of the anonymous user MUST be 2.
            # The name for the anonymous user. For example: "Anonymous".
            name: "<anonymous_user_name>"
            # The 128-bit UUID of the public keystore. For example: "ca22be26-b798-4fdf-8c83-3e3a492dc215".
            tokenspaceID: "<public_keystore_spaceid>"
            iamauth:
              <<: *defaultiamcredential
              # The API key for the anonymous user. All other users can specify API key using the C_Login command.
              apikey: "<apikey_for_anonymous_user>"
            # Do not override the defaultsessionauth template
            # The same values must be used for both the private (normal user) and public (anonymous) keystores
            sessionauth: *defaultsessionauth
    
    logging:
      # Set the logging level.
      # The supported levels, in an increasing order of verboseness: 'panic', 'fatal', 'error', 'warning'/'warn', 'info', 'debug', 'trace'. The Default value is 'warning'.
      loglevel: "<logging_level>"
      logpath: "<log_file_path>" # The full path of your logging file.
    
    

    Wenn authentifizierte Keystores verwendet werden, muss die Konfigurationsoption sessionauth für beide Keystores aktiviert sein und die Textkennwörter mit einer Länge von 6 bis 8 Zeichen müssen für beide Keystores im Feld tokenspaceIDPassword identisch sein.

    Ersetzen Sie die Variablen in dem Beispiel wie in der folgenden Tabelle angegeben:

    Wenn Sie Ihre Instanzen nach dem 12. April 2024 in bestimmten Regionen erstellen, müssen Sie möglicherweise die neuen API-Endpunkte mit dem neuen Format verwenden als <instance_ID>.ep11.<REGION>.hs-crypto.appdomain.cloud. Das Verfügbarkeitsdatum variiert je nach Region. Weitere Informationen zu den unterstützten Regionen, den Verfügbarkeitsdaten und den neuen Endpunkt-URLs finden Sie unter Neue Endpunkte.

    Tabelle 1. Beschreibt die Variablen, die zum Erstellen der PKCS #11 -Konfigurationsdatei erforderlich sind.
    Variabel Beschreibung
    EP11_endpoint_URL Der Endpunkt der Hyper Protect Crypto Services Enterprise PKCS #11-API (EP11-API). Du kannst es durchÜberblick >Verbinden >EP11 Endpunkt-URL in der Benutzeroberfläche, oder Sie können dynamisch Abrufen der Endpunkt-URL mit der API. Abhängig davon, ob Sie ein öffentliches oder privates Netz verwenden, nutzen Sie die öffentliche oder private EP11-Endpunkt-URL.
    EP11_endpoint_port_number Die Portnummer des EP11-API-Endpunkts. Sie wird nach dem Doppelpunkt in der Endpunkt-URL angegeben.
    enable_mtls Gültige Werte sind true oder false um anzugeben, ob Sie gegenseitiges TLS aktivieren möchten, um eine zweite Authentifizierungsebene für den PKCS #11-API-Zugriff hinzuzufügen fürHyper Protect Crypto Services Standardplan. Setzen Sie den Wert standardmäßig auf false, da für EP11 nur die serverbasierte Authentifizierung erforderlich ist. Weitere Informationen zu gegenseitigen TLS-Verbindungen finden Sie unter Zweite Ebene der Authentifizierung für EP11-Verbindungen aktivieren.
    client_certificate Wenn Sie gegenseitige TLS-Verbindungen aktivieren, geben Sie den Dateipfad des Clientzertifikats an, das vom Zertifikatadministrator in Ihre Instanz hochgeladen wird. Andernfalls müssen Sie dieses Feld leer lassen.
    client_certificate_private_key Wenn Sie gegenseitige TLS-Verbindungen aktivieren, geben Sie den Dateipfad des privaten Schlüssels des Clientzertifikats an, der zum Signieren des Zertifikats verwendet wird. Andernfalls müssen Sie dieses Feld leer lassen.
    SO_user_name Der Name für den Benutzertyp des Sicherheitsbeauftragten (Security Officer - SO). Der PKCS #11-Standard definiert zwei Typen von Benutzern für die Anmeldung: den Sicherheitsbeauftragten (SO) und den Normalbenutzer. Weitere Informationen zu den PKCS #11 -Benutzertypen finden Sie im Anwendungshandbuch zur PKCS #11-Schnittstelle für Verschlüsselungstoken Version 2.40 – Benutzer.
    normal_user_name Der Name für den Normalbenutzertyp. Der PKCS #11-Standard definiert zwei Typen von Benutzern für die Anmeldung: den Sicherheitsbeauftragten (SO) und den Normalbenutzer. Weitere Informationen zu den PKCS #11 -Benutzertypen finden Sie im Anwendungshandbuch zur PKCS #11-Schnittstelle für Verschlüsselungstoken Version 2.40 – Benutzer.
    private_keystore_spaceid Die 128-Bit-UUID (Universally Unique IDentifier) des privaten Keystores. Sie können die UUID mit einem Tool eines anderen Anbieters generieren, z. B. UUID generator.

    Hyper Protect Crypto Services stellt Ihnen zwei datenbankgestützte EP11-Keystores für verbesserte Sicherheit und besseres Benutzerzugriffsmanagement bereit: den privaten Keystore, auf den nur der normale Benutzertyp zugreifen kann, und den öffentlichen Keystore, auf den alle Benutzertypen zugreifen können. Die UUID muss sich von der für den public_keystore_spaceid-Parameter angegebenen UUID unterscheiden.

    private_keystore_password Autorisierte Sitzungen können verwendet werden, indem die Konfigurationsoption sessionauth aktiviert wird. Wenn die Option sessionauth aktiviert ist, muss sie für beide Keystores aktiviert sein. Darüber hinaus ist ein Textkennwort mit einer Länge von 6-8 Zeichen für das Feld tokenspaceIDPassword erforderlich und das Kennwort muss für beide Keystores identisch sein. Autorisierte Sitzungen sind für das HSM spezifisch, sie werden im PKCS #11-Ablauf für das An- und Abmelden verwendet und sie sind für authentifizierte Schlüsseloperationen erforderlich. Alle Schlüssel, die mit autorisierten Sitzungen generiert werden, werden in einem authentifizierten und verschlüsselten Keystore gespeichert. Das Feld tokenspaceIDPassword wird verwendet, um die Schlüssel in einem authentifizierten und verschlüsselten Keystore zu schützen. Für jede Serviceinstanz werden maximal fünf authentifizierte Keystores unterstützt.
    anonymous_user_name Der Name für den anonymen Benutzer. Der PKCS #11-Standard definiert zwei Typen von Benutzern für die Anmeldung: den Sicherheitsbeauftragten (SO) und den Normalbenutzer. Wenn ein Benutzer sich nicht mit der Cryptoki-Funktion C_Login anmeldet, wird der Benutzer als anonymer Benutzer bezeichnet. Weitere Informationen zu den PKCS #11 -Benutzertypen finden Sie im Anwendungshandbuch zur PKCS #11-Schnittstelle für Verschlüsselungstoken Version 2.40 – Benutzer.
    public_keystore_spaceid Die 128-Bit-Version der UUID (Universally Unique IDentifier) des öffentlichen Keystores. Sie können die UUID mit einem Tool eines anderen Anbieters generieren, z. B. UUID generator.

    Hyper Protect Crypto Services stellt Ihnen zwei datenbankgestützte EP11-Keystores für verbesserte Sicherheit und besseres Benutzerzugriffsmanagement bereit: den privaten Keystore, auf den nur der normale Benutzertyp zugreifen kann, und den öffentlichen Keystore, auf den alle Benutzertypen zugreifen können. Die UUID muss sich von der für den Parameter private_keystore_spaceid angegebenen UUID unterscheiden.

    Wichtig: Die UUID-Zeichenfolge muss mit der UUID-Zeichenfolge übereinstimmen, die zum Einrichten von Zugriffsrichtlinien für den anonymen Benutzer verwendet wird. Siehe Erstellung von Richtlinien für anonymen Benutzerzugriff.

    apikey_for_anonymous_user Der Service-ID-API-Schlüssel, den Sie für den anonymen Benutzertyp in dem vorherigen Schritt unter Voraussetzungen erstellen.
    logging_level Die unterstützten Protokollierungsebenen in einer steigenden Reihenfolge der Ausführlichkeit: panic, fatal, error, warning/warn, info, debug und trace. Der Standardwert ist warning.
    log_file_path Der vollständige Pfad Ihrer Protokolldatei. In dieser Datei werden alle Protokolle gespeichert, die bei der Interaktion Ihrer Anwendungen mit dem Cloud-HSM von Hyper Protect Crypto Services zur Ausführung von PKCS #11-Funktionen generiert werden.

    Zum Verschlüsseln und Authentifizieren des Keystores, der von PKCS #11 verwendet wird, aktivieren Sie den Parameter sessionauth und konfigurieren das Kennwort für den Keystore. Für jede Serviceinstanz werden maximal fünf authentifizierte Keystores unterstützt. Das Kennwort kann 6 - 8 Zeichen lang sein. Die Keystore-Kennwörter werden nicht in der Serviceinstanz gespeichert. Als Keystore-Administrator sind Sie für die Verwaltung einer lokalen Kopie der Kennwörter verantwortlich. Wenn ein Kennwort verloren geht, müssen Sie sich an den IBM Support wenden, um den Keystore zurückzusetzen. Dies bedeutet, dass alle Daten im Keystore gelöscht werden.

  2. Verschieben Sie die Konfigurationsdatei in das /etc/ep11client Verzeichnis. Erstellen Sie das Verzeichnis /etc/ep11client, falls es nicht vorhanden ist. Alternativ können Sie die Umgebungsvariable EP11CLIENT_CFG auf den vollständigen Pfad und den Dateinamen der Konfigurationsdatei setzen. Dadurch sind Sie nicht auf den grep11client-Namen der YAML-Datei beschränkt. Beispiel: export EP11CLIENT_CFG=/home/user/pkcs11-config.yaml

Schritt 4: PKCS #11-Bibliothek zum Ausführen von PKCS #11-API-Aufrufen verwenden

Nach der Einrichtung der Bibliothek und der Konfigurationsdatei müssen die Keystores initialisiert werden. Zum Initialisieren der Keystores muss der Sicherheitsbeauftragte (SO) eine Operation C_InitToken ausführen.

Nachdem die Keystores initialisiert wurden, verwenden Sie die PKCS #11-Bibliothek, um die PKCS #11-Standardfunktionen zum Generieren, Speichern und Auflisten von Schlüsseln aufzurufen. Eine detaillierte Liste der unterstützten PKCS #11-Funktionen finden Sie in der PKCS #11-API-Referenz.

Abhängig von den Features und den Sicherheitsanforderungen Ihrer Anwendung müssen Sie verschiedene Service-ID-API-Schlüssel übergeben, die Sie im vorherigen Schritt für Voraussetzungen erstellt haben, damit Ihre Anwendungen die entsprechenden Operationen ausführen können. Wenn Ihre Anwendung beispielsweise einen Keystore löschen muss, geben Sie den API-Schlüssel des SO-Benutzers an. Wenn Ihre Anwendung auf den privaten Keystore zugreifen muss, um neue Schlüssel zu speichern, müssen Sie den API-Schlüssel des Normalbenutzers angeben. Weitere Informationen zum Benutzerzugriffsmanagement für die PKCS #11-API finden Sie unter Bewährte Verfahren zum Einrichten von PKCS #11-Benutzertypen.

Wenn Sie eine Java PKCS #11 mit dem SunPKCS11-Provider auf der Plattform IBM Z (s390x) ausführen, stellen Sie sicher, dass Sie beim Starten Ihrer Anwendung die neueste IBM Semeru-JVM verwenden und die Option -Xjit:noResumableTrapHandler Java angeben. Sie können die neueste s390x-Version der IBM Semeru-Java Virtual Machine (JVM) herunterladen, indem Sie das Filterfeld Architektur auf der IBM Semeru Runtime-Downloadseitein s390x ändern.

Nächste Schritte