PKCS#11 avec pkcs11-tool#

Ce guide décrit l’utilisation du pilote PKCS#11 pour le NetHSM. Ce guide utilise des outils de OpenSC. Veuillez vous référer à leur documentation pour savoir comment les utiliser sur votre système d’exploitation.

Important

Ce pilote n’est encore qu’une première implémentation de validation de concept qui ne met en œuvre que les fonctions nécessaires au fonctionnement des serveurs TLS.

Installation#

Installer la bibliothèque précompilée#

  1. Téléchargez une archive contenant la dernière version à partir de la page releases du référentiel. Utilisez l’archive de la version qui contient le nom de votre système d’exploitation dans le titre.

  2. Extrayez les fichiers de l’archive téléchargée avec un programme d’archivage de votre choix.

  3. Copiez la bibliothèque extraite dans le chemin respectif de votre système d’exploitation. Le chemin dépend de votre installation et de la configuration d’OpenSC.

Compiler à partir du code source#

Important

Ce pilote ne peut être compilé qu’avec le compilateur officiel Go. N’utilisez pas le compilateur GNU Go (GCC-Go). Veuillez vous référer à leur site web ` <https://go.dev/doc/install>` __ pour apprendre comment l’installer.

  1. Téléchargez une archive avec la dernière version à partir de la page releases du référentiel. Utilisez l’archive de la version qui contient Source code dans le titre.

  2. Extrayez les fichiers de l’archive téléchargée avec un programme d’archivage de votre choix.

  3. Dans le répertoire contenant le code source extrait, exécutez la commande suivante pour compiler la bibliothèque.

    ./build.sh

  4. Copiez la bibliothèque extraite dans le chemin respectif de votre système d’exploitation. Le chemin dépend de votre installation et de la configuration d’OpenSC.

Configuration#

Le fichier de configuration p11nethsm.conf est requis et utilisé pour configurer la connexion entre le pilote PKCS#11 et le NetHSM.

Un exemple de fichier de configuration ressemble à ce qui suit.

YAML 1.1
---
p11nethsm:
  logfile: /tmp/p11nethsm.log
  maxsessioncount: 5
  debug: true
  slots:
  - label: NetHSM1
    description: NetHSM Zone A
    url: "https://nethsmdemo.nitrokey.com/api/v1"
    # certSHA256:
    #   - "0C:66:DC:EB:4D:12:C3:24:FC:82:F4:1D:4C:16:44:12:1D:00:79:FF:36:96:65:E2:21:C4:36:94:F7:8E:22:89"
    user: "operator"
    password: "env:NETHSM_PASS"

Modifiez le fichier de configuration p11nethsm.conf en fonction de votre environnement.

Le fichier de configuration peut inclure plusieurs slots, dans le tableau slots. Les slots représentent plusieurs déploiements de NetHSM. Le champ label d’un slot doit contenir un nom unique. Les clés url, user, et password sont obligatoires. Pour des raisons de sécurité, il est recommandé de passer le mot de passe dans une variable d’environnement. Pour cela, le env:NETHSM_PASS est passé dans la clé password, où NETHSM_PASS est le nom de la variable d’environnement contenant le mot de passe. La clé certSHA256 doit être définie si le certificat TLS n’est pas signé par une autorité de certification (CA) contenue dans le magasin de certificats du système d’exploitation.

Le fichier de configuration doit être enregistré soit dans les chemins suivants, soit dans le répertoire où l’application est exécutée.

  • $HOME/.nitrokey

  • /etc/nitrokey/

Gestion des clés#

Info#

Affiche des informations sur la version de cryptoki, et le pilote PKCS#11.

$ pkcs11-tool --module p11nethsm.so --show-info

Cryptoki version 2.40
Manufacturer     Nitrokey GmbH
Library          NetHSM PKCS#11 module (ver 0.1)
Using slot 0 with a present token (0x0)

Liste des machines à sous#

Les informations sur les créneaux disponibles. Les slots listés dépendent de la configuration du tableau des slots dans le fichier de configuration p11nethsm.conf. Pour en savoir plus sur la configuration des slots, veuillez vous référer au chapitre Configuration.

$ pkcs11-tool --module p11nethsm.so --list-slots

Available slots:
Slot 0 (0x0): NetHSM Zone A
  token label        : NetHSM1
  token manufacturer : Nitrokey GmbH
  token model        : NetHSM
  token flags        : rng, token initialized, PIN initialized, readonly
  hardware version   : 0.1
  firmware version   : 0.1
  serial num         : 0
  pin min/max        : 3/256

Note

Si votre configuration supporte plus d’un slot, vous devrez peut-être ajouter l’option –slot <arg> dans les commandes pkcs11-tool pour utiliser le bon slot.

Générer une clé#

Générer une paire de clés et la stocker sur le NetHSM.

Note

Le pilote PKCS#11 ne prend actuellement pas en charge cette fonctionnalité. Une paire de clés peut être générée avec nitropy ou une demande d’API REST. Pour en savoir plus sur la façon de générer une clé, veuillez vous reporter au chapitre Generate Key.

Clés de liste#

Afficher des informations sur les clés et les certificats dans le magasin de clés ** sur un NetHSM.

$ pkcs11-tool --module p11nethsm.so --list-objects

Using slot 0 with a present token (0x0)
Private Key Object; RSA
  label:      myFirstKey
  ID:         6d7946697273744b6579
  Usage:      decrypt, sign
  Access:     sensitive, always sensitive, never extractable
Public Key Object; RSA 0 bits
  label:      myFirstKey
  ID:         6d7946697273744b6579
  Usage:      none
  Access:     none

Clés de lecture#

Lire les clés et les certificats à partir du magasin de clés ** sur un NetHSM. Il n’est pas possible de lire des clés privées à partir du NetHSM.

La clé publique d’une paire de clés peut être lue comme suit.

$ pkcs11-tool --module p11nethsm.so --read-object --type pubkey --label myFirstKey -o public.key

Le certificat d’une paire de clés peut être lu comme suit.

$ pkcs11-tool --module p11nethsm.so --read-object --type cert --label myFirstKey -o public.key

Les certificats ou les clés publiques renvoyés sont codés en ASN.1. Les données peuvent être décodées avec l’outil dumpasn1, car elles contiennent des données au format DER. Le format DER peut être converti au format PEM avec OpenSSL.

Clés d’écriture#

Inscrivez les clés et les certificats sur le site Key Store sur un NetHSM.

La clé privée d’une paire de clés peut être écrite comme suit.

$ pkcs11-tool --module p11nethsm.so --write-object secret.key --type privkey --label myFirstKey

La clé publique d’une paire de clés peut être écrite comme suit.

$ pkcs11-tool --module p11nethsm.so --write-object public.key --type pubkey --label myFirstKey

Le certificat d’une paire de clés peut être écrit comme suit.

$ pkcs11-tool --module p11nethsm.so --write-object cert.pub --type cert --label myFirstKey

Opérations clés#

Crypter#

Le NetHSM ne peut pas chiffrer les données avec des clés asymétriques, mais il fournit la clé publique qui peut être utilisée pour le chiffrement. Veuillez vous référer au chapitre Show Key Details, ou récupérer la clé comme décrit dans le chapitre Read Keys <pkcs11_with_pkcs11.html#read-keys>, pour en savoir plus sur la façon de récupérer la clé publique. L’exemple suppose que la clé publique se trouve dans le fichier public.pem.

Les données peuvent être cryptées avec OpenSSL comme suit.

$ echo 'NetHSM rulez!' | openssl pkeyutl -encrypt -pubin \
   -inkey public.pem \
   -pkeyopt rsa_padding_mode:oaep \
   -pkeyopt rsa_oaep_md:sha512 \
   -pkeyopt rsa_mgf1_md:sha512 \
   -out encrypted.data

Décryptage#

Le NetHSM peut décrypter des données pour une clé privée stockée dans le magasin de clés ** sur le NetHSM. Cet exemple utilise le message crypté du chapitre précédent Encrypt.

$ pkcs11-tool --module p11nethsm.so --decrypt \
   --mechanism RSA-PKCS-OAEP \
   --input-file encrypted.data \
   --label myFirstKey \
   --hash-algorithm SHA512

NetHSM rulez!

Signe#

Le NetHSM peut signer des données pour une clé privée stockée dans le Key Store du NetHSM. Pour les signatures avec une clé RSA et ECDSA, un condensé doit d’abord être calculé.

Pour calculer un condensé, il faut d’abord disposer des données. Un message est créé comme suit.

$ echo 'NetHSM rulez!' | pkcs11-tool --module p11nethsm.so \
   --sign \
   --mechanism SHA512-RSA-PKCS-PSS \
   --output-file sig.data \
   --label myFirstKey

La signature créée peut être vérifiée avec OpenSSL comme suit.

$ echo 'NetHSM rulez!' | openssl dgst -keyform PEM \
   -verify public.pem \
   -sha512 \
   -sigopt rsa_padding_mode:pss \
   -sigopt rsa_pss_saltlen:-1 \
   -signature sig.data