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.
- 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. - 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.
-
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.
-
-
Extrahieren Sie den öffentlichen Schlüssel aus dem Signierzertifikat
signing_cert.pem
in die Dateisigkey.pub
mit dem folgenden Befehl:openssl x509 -pubkey -noout -in signing_cert.pem -out sigkey.pub
-
Ü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. -
Ü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
undsigning_cert.pem: good
angezeigt. -
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.
-
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 FeldtokenspaceIDPassword
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
oderfalse
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 auffalse
, 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 Optionsessionauth
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 FeldtokenspaceIDPassword
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 FeldtokenspaceIDPassword
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
undtrace
. Der Standardwert istwarning
.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. -
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 UmgebungsvariableEP11CLIENT_CFG
auf den vollständigen Pfad und den Dateinamen der Konfigurationsdatei setzen. Dadurch sind Sie nicht auf dengrep11client
-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
- Schauen Sie sich das Lernprogramm an, das zeigt, wie die Hyper Protect Crypto Services-PKCS #11-Bibliothek zur Datenverschlüsselung mit Oracle Transparent Data Encryption verwendet wird, um sich mit der Verwendung der PKCS #11-Bibliothek besser vertraut zu machen.
- Prüfen Sie die PKCS #11-API-Referenz mit detaillierten Informationen zu Verschlüsselungsfunktionen.