Exécution d'opérations de chiffrement à l'aide de l'API PKCS #11

IBM Cloud® Hyper Protect Crypto Services fournit l'API PKCS #11 standard pour accéder au module HSM en cloud d'Hyper Protect Crypto Services afin d'effectuer des opérations de chiffrement.

Prérequis

Avant de configurer et d'utiliser l'API de PKCS #11, suivez d'abord les pratiques recommandées pour la configuration des types d'utilisateur PKCS #11 pour créer différentes clés d'API d'ID de service pour les différents types d'utilisateur PKCS #11.

Etape 1 : Configuration de la bibliothèque PKCS #11

Vous devez configurer la bibliothèque PKCS #11 sur votre poste de travail afin de la rendre disponible pour vos applications et leur permettre d'appeler les fonctions PKCS #11 standard.

La bibliothèque PKCS #11 , pour les plateformes amd64 et s390x, est prise en charge uniquement sur Linux.

Si vous exécutez une application Java PKCS #11 à l'aide du fournisseur SunPKCS11 sur la plateforme IBM Z (s390x), veillez à utiliser la dernière machine virtuelle Java IBM Semeru et à spécifier l'option -Xjit:noResumableTrapHandler Java lors du démarrage de votre application. Vous pouvez télécharger la dernière version s390x de la JVM IBM Semeru en remplaçant la zone de filtre Architecture par s390x sur la page IBM Semeru Runtime Downloads.

Téléchargez la dernière bibliothèque PKCS #11. Les noms de fichier de bibliothèque utilisent la convention de dénomination suivante: pkcs11-grep11-<platform>.so.<version>. La valeur platform est amd64 ou s390x et la valeur version correspond à la syntaxe major.minor.build standard.
Déplacez la bibliothèque dans un dossier accessible par vos applications. Par exemple, si vous exécutez votre application sous Linux, vous pouvez déplacer la bibliothèque vers /usr/local/lib, /usr/local/lib64 ou /usr/lib.

Etape 2 : (Facultatif) Vérification de l'intégrité et de l'authenticité de la bibliothèque PKCS #11

Pour une sécurité maximale, vérifiez l'intégrité et l'authenticité de la bibliothèque PKCS #11 avant d'exécuter vos applications PKCS #11 pour utiliser cette bibliothèque.

Hyper Protect Crypto Services active la vérification du code signé pour s'assurer que la signature correspond au code d'origine. Si le fichier de bibliothèque PKCS #11 téléchargé est modifié ou endommagé, une autre signature est produite et la vérification échoue. Pour vous assurer que les fichiers ne sont pas altérés ou endommagés lors du processus de téléchargement, procédez comme suit à l'aide de l'outil de ligne de commandeOpenSSL.

Téléchargez la version la plus récente des fichiers suivants depuis le référentiel de bibliothèque dans le même répertoire que celui où vous stockez la bibliothèque PKCS #11 :
- pkcs11-grep11-<platform>.so.<version>.sig: le hachage cryptographique signé de la bibliothèque PKCS #11, où la plateforme est amd64 ou s390x et la version est Major.minor.build du fichier de signature. Les valeurs platform et version doivent correspondre aux valeurs platform et version respectives de la bibliothèque PKCS #11 que vous utilisez.
- signing_cert.pem : certificat signataire des fichiers client PKCS #11 d'Hyper Protect Crypto Services.
- digicert_cert.pem : certificat signataire de code intermédiaire permettant d'approuver le certificat signataire des fichiers client PKCS #11 d'Hyper Protect Crypto Services.
Extrayez la clé publique du certificat signataire signing_cert.pem dans le fichier sigkey.pub en exécutant la commande suivante :
```
openssl x509 -pubkey -noout -in signing_cert.pem -out sigkey.pub
```
Vérifiez l'intégrité du fichier de bibliothèque PKCS #11 à l'aide de la commande suivante :
```
openssl dgst -sha256 -verify sigkey.pub -signature pkcs11-grep11-<platform>.so.<version>.sig pkcs11-grep11-<platform>.so.<version>
```
Remplacez platform par amd64 ou s390x et remplacez version par la valeur major.minor.build de la bibliothèque.

Lorsque la vérification aboutit, le message Verified OK s'affiche.
Vérifiez l'authenticité et la validité du certificat signataire à l'aide de la commande suivante :
```
openssl ocsp -no_nonce -issuer digicert_cert.pem -cert signing_cert.pem -VAfile digicert_cert.pem -text -url http://ocsp.digicert.com -respout ocsptest
```
Lorsque la vérification aboutit, les messages Response verify OK et signing_cert.pem: good apparaissent dans la sortie.
Si la vérification échoue, annulez l'installation et contactez le support IBM.

Etape 3 : Configuration du fichier de configuration PKCS #11

Afin de connecter la bibliothèque PKCS #11 au module HSM en cloud d'Hyper Protect Crypto Services pour effectuer des fonctions de chiffrement, vous devez effectuer les étapes suivantes pour configurer le fichier de configuration :

Créez un fichier de configuration nommé grep11client.yaml basé sur l'exemple suivant. Le référentiel de bibliothèque fournit également un modèle que vous pouvez adapter. Vous pouvez consulter les commentaires inclus dans le code pour comprendre chaque zone.

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.

Si des magasins de clés authentifiés sont utilisés, l'option de configuration sessionauth doit être activée pour les deux magasins de clés et les mots de passe textuels de 6 à 8 caractères doivent être identiques pour les deux magasins de clés dans la zone tokenspaceIDPassword.

Remplacez les variables de l'exemple en fonction du tableau suivant :

Si vous créez vos instances après le 12 avril 2024 dans certaines régions, vous devrez peut-être utiliser les nouveaux noeuds finaux d'API avec le nouveau format <instance_ID>.ep11.<REGION>.hs-crypto.appdomain.cloud. La date de disponibilité varie selon la région. Pour plus d'informations sur les régions prises en charge, les dates de disponibilité et les nouvelles URL de noeud final, voir Nouveaux noeuds finaux.

Tableau 1. Décrit les variables nécessaires à la création du fichier de configuration PKCS #11
Variables	Description
`EP11_endpoint_URL`	Noeud final d'API Hyper Protect Crypto Services Enterprise PKCS #11 (EP11). Vous pouvez l'obtenir via Overview > Connect > EP11 endpoint URL dans l'interface utilisateur ou vous pouvez extraire dynamiquement l'URL de noeud final à l'aide de l'API. Selon que vous utilisez un réseau public ou privé, utilisez l'URL de noeud final EP11 public ou privé.
`EP11_endpoint_port_number`	Numéro de port du noeud final d'API EP11. Il se trouve après le signe deux-points dans l'URL de noeud final.
`enable_mtls`	Les valeurs valides sont `true` ou `false` pour indiquer si vous souhaitez activer le protocole TLS mutuel pour ajouter une deuxième couche d'authentification pour l'accès à l'API PKCS #11 pour le plan standard Hyper Protect Crypto Services. Par défaut, définissez la valeur `false` car EP11 requiert une authentification serveur uniquement. Pour plus d'informations sur les connexions TLS mutuelles, voir Activation de la deuxième couche d'authentification pour les connexions EP11.
`client_certificate`	Si vous activez les connexions TLS mutuelles, indiquez le chemin d'accès au certificat client qui est téléchargé sur votre instance par l'administrateur de certificats. Sinon, laissez cette zone vide.
`client_certificate_private_key`	Si vous activez les connexions TLS mutuelles, indiquez le chemin d'accès à la clé privée du certificat client qui est utilisée pour signer le certificat. Sinon, laissez cette zone vide.
`SO_user_name`	Nom du responsable de la sécurité. La norme PKCS #11 définit deux types d'utilisateur pour la connexion : le responsable de la sécurité et l'utilisateur standard. Pour plus d'informations sur les types d'utilisateurs PKCS #11, voir le Guide d'utilisation de l'interface de jeton cryptographique PKCS #11 Version 2.40 - Utilisateurs.
`normal_user_name`	Nom de l'utilisateur standard. La norme PKCS #11 définit deux types d'utilisateur pour la connexion : le responsable de la sécurité et l'utilisateur standard. Pour plus d'informations sur les types d'utilisateurs PKCS #11, voir le Guide d'utilisation de l'interface de jeton cryptographique PKCS #11 Version 2.40 - Utilisateurs.
`private_keystore_spaceid`	ID unique universel (UUID) 128 bits du fichier de clés privé. Vous pouvez générer l'UUID à l'aide d'un outil tiers, tel que le générateur d'UUID. Hyper Protect Crypto Services fournit deux magasins de clés EP11 sauvegardés dans une base de données pour une meilleure sécurité et une meilleure gestion des accès utilisateur: le magasin de clés privé auquel seul le type d'utilisateur normal peut accéder et le magasin de clés public auquel tous les types d'utilisateur peuvent accéder. L'UUID doit être différent de l'UUID spécifié pour le paramètre `public_keystore_spaceid`.
`private_keystore_password`	Les sessions autorisées peuvent être utilisées en activant l'option de configuration `sessionauth`. Si l'option `sessionauth` est activée, elle doit l'être pour les deux magasins de clés. En outre, un mot de passe texte de 6 à 8 caractères est requis pour la zone `tokenspaceIDPassword` et le mot de passe doit être identique pour les deux magasins de clés. Les sessions autorisées sont spécifiques au module de sécurité matérielle. Elles sont utilisées dans le flux #11 PKCS pour se connecter et se déconnecter et elles sont requises pour les opérations de clés authentifiées. Toutes les clés générées à l'aide de sessions autorisées sont stockées dans un magasin de clés authentifié et chiffré. La zone `tokenspaceIDPassword` permet de protéger les clés dans un magasin de clés authentifié et chiffré. Pour chaque instance de service, un maximum de cinq magasins de clés authentifiés est pris en charge.
`anonymous_user_name`	Nom de l'utilisateur anonyme. La norme PKCS #11 définit deux types d'utilisateur pour la connexion : le responsable de la sécurité et l'utilisateur standard. Si un utilisateur ne se connecte pas à l'aide de la fonction Cryptoki `C_Login`, l'utilisateur est connu en tant qu'utilisateur anonyme. Pour plus d'informations sur les types d'utilisateurs PKCS #11, voir le Guide d'utilisation de l'interface de jeton cryptographique PKCS #11 Version 2.40 - Utilisateurs.
`public_keystore_spaceid`	ID unique universel (UUID) 128 bits du fichier de clés public. Vous pouvez générer l'UUID à l'aide d'un outil tiers, tel que le générateur d'UUID. Hyper Protect Crypto Services fournit deux magasins de clés EP11 sauvegardés dans une base de données pour une meilleure sécurité et une meilleure gestion des accès utilisateur: le magasin de clés privé auquel seul le type d'utilisateur normal peut accéder et le magasin de clés public auquel tous les types d'utilisateur peuvent accéder. L'UUID doit être différent de l'UUID spécifié pour le paramètre `private_keystore_spaceid`. Important: La valeur de la chaîne UUID doit correspondre à la chaîne UUID utilisée pour configurer les règles d'accès de l'utilisateur anonyme. Voir Création d'une règle d'accès utilisateur anonyme.
`apikey_for_anonymous_user`	Clé d'API d'ID de service que vous créez pour le type d'utilisateur anonyme au cours de l'étape Prérequis précédente.
`logging_level`	Les niveaux de journalisation pris en charge, dans un ordre croissant de verbosité sont : `panic`, `fatal`, `error`, `warning`/`warn`, `info`, `debug` et `trace`. La valeur par défaut est `warning`.
`log_file_path`	Chemin d'accès complet à votre fichier de journalisation. Tous les journaux générés lorsque vos applications interagissent avec le module HSM en cloud d'Hyper Protect Crypto Services pour exécuter les fonctions PKCS #11 sont sauvegardés dans ce fichier.

Pour chiffrer et authentifier le magasin de clés utilisé par PKCS #11, activez le paramètre sessionauth et configurez le mot de passe du magasin de clés. Pour chaque instance de service, un maximum de cinq magasins de clés authentifiés est pris en charge. Le mot de passe peut contenir entre 6 et 8 caractères. Les mots de passe du magasin de clés ne sont pas stockés dans l'instance de service. En tant qu'administrateur du magasin de clés, vous êtes responsable de la conservation d'une copie locale des mots de passe. Si un mot de passe est perdu, vous devez contacter le support IBM pour réinitialiser le magasin de clés, ce qui signifie que toutes les données du magasin de clés sont supprimées.

Déplacez le fichier de configuration dans le répertoire /etc/ep11client. Créez le répertoire /etc/ep11client s'il n'existe pas. Vous pouvez également définir la variable d'environnement EP11CLIENT_CFG sur le chemin d'accès complet et le nom du fichier de configuration. Ce faisant, vous n'êtes pas limité au nom grep11client du fichier yaml. Exemple : export EP11CLIENT_CFG=/home/user/pkcs11-config.yaml

Etape 4 : Utilisation de la bibliothèque PKCS #11 pour effectuer des appels API PKCS #11

Une fois que vous avez configuré la bibliothèque et le fichier de configuration, les magasins de clés doivent être initialisés. Pour initialiser les magasins de clés, le responsable de la sécurité doit effectuer une opération C_InitToken.

Une fois les magasins de clés initialisés, utilisez la bibliothèque PKCS #11 pour appeler les fonctions PKCS #11 standard pour générer, stocker et répertorier les clés. Pour obtenir la liste détaillée des fonctions PKCS #11 prises en charge, voir la documentation de référence de l'API PKCS #11.

En fonction des fonctions et des exigences de sécurité de votre application, transmettez les différentes clés d'API d'ID de service créées à l'étape précédente afin que vos applications puissent effectuer les opérations correspondantes. Par exemple, si votre application doit supprimer un magasin de clés, fournissez la clé d'API d'utilisateur SO. Si votre application doit accéder au magasin de clés privées pour stocker de nouvelles clés, vous devez fournir la clé d'API d'utilisateur normal. Pour plus d'informations sur la gestion des accès utilisateur pour l'API PKCS #11, voir Pratiques recommandées pour la configuration des types d'utilisateur PKCS #11.

Etapes suivantes

Suivez le tutoriel qui montre comment utiliser la bibliothèque PKCS #11 d'Hyper Protect Crypto Services pour Oracle Database Transparent Database Encryption afin de mieux appréhender l'utilisation de la bibliothèque PKCS #11.
Consultez la documentation de référence de l'API PKCS #11 pour obtenir des informations détaillées sur les fonctions de chiffrement.