PKCS#11 con pkcs11-tool#

Esta guía describe el uso del controlador PKCS#11 para el NetHSM. La guía utiliza herramientas de OpenSC. Consulte su documentación para aprender a utilizarlas en su sistema operativo.

Importante

Este controlador es todavía una implementación de prueba de concepto temprana que sólo implementa las funciones necesarias para operar servidores TLS.

Instalación#

Instalar la biblioteca precompilada#

Descargue un archivo con la última versión desde la página de versiones ` <https://github.com/Nitrokey/nethsm-pkcs11/releases>` __ del repositorio. Utilice el archivo de la versión que contenga el nombre de su sistema operativo en el título.
Extraiga los ficheros del archivo descargado con un programa de archivado de su elección.
Copie la biblioteca extraída en la ruta correspondiente de su sistema operativo. La ruta depende de su instalación y configuración de OpenSC.

Compilar desde el código fuente#

Importante

Este controlador sólo se puede compilar con el compilador Go oficial. No utilice el compilador GNU Go (GCC-Go). Por favor, consulte su sitio web ` <https://go.dev/doc/install>` __ para aprender a instalarlo.

Descargue un archivo con la última versión desde la página releases del repositorio. Utilice el archivo de la versión que contenga Código fuente en el título.
Extraiga los ficheros del archivo descargado con un programa de archivado de su elección.
En el directorio con el código fuente extraído ejecute el siguiente comando para compilar la biblioteca.
./build.sh
./build.sh
Copie la biblioteca extraída en la ruta correspondiente de su sistema operativo. La ruta depende de su instalación y configuración de OpenSC.

Configuración#

El archivo de configuración p11nethsm.conf es necesario y se utiliza para configurar la conexión entre el controlador PKCS#11 y el NetHSM.

Un ejemplo de archivo de configuración tiene el siguiente aspecto.

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"

Modifique el archivo de configuración p11nethsm.conf según su entorno.

El archivo de configuración puede incluir múltiples ranuras, dentro de la matriz slots. Las ranuras representan múltiples despliegues de NetHSM. El campo label de una ranura debe contener un nombre único. Las claves url, user y password son obligatorias. Por razones de seguridad se recomienda pasar la contraseña en una variable de entorno. Para ello se pasa env:NETHSM_PASS en la clave password, donde NETHSM_PASS es el nombre de la variable de entorno que contiene la contraseña. La clave certSHA256 debe ser establecida si el certificado TLS no está firmado por una Autoridad de Certificación (CA) contenida en el almacén de certificados del sistema operativo.

El archivo de configuración debe guardarse en las siguientes rutas o en el directorio donde se ejecuta la aplicación.

$HOME/.nitrokey
/etc/nitrokey/

Gestión de claves#

Información#

Muestra información sobre la versión de cryptoki, y el controlador 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)

Lista de ranuras#

La información sobre las ranuras disponibles. Las ranuras listadas dependen de la configuración de la matriz de ranuras en el archivo de configuración p11nethsm.conf. Para saber más sobre la configuración de las ranuras, consulte el capítulo Configuración <pkcs11_with_pkcs11-tool.html#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

Nota

Si su configuración admite más de una ranura, tal vez tenga que añadir la opción –slot <arg> en los comandos de pkcs11-tool para utilizar la correcta.

Generar claves#

Genera un par de claves y lo almacena en el NetHSM.

Nota

El controlador PKCS#11 actualmente no soporta esta característica. Se puede generar un par de claves con nitropy o con una solicitud de la API REST. Para saber más sobre cómo generar una clave, consulte el capítulo Generar clave.

Lista de claves#

Muestra información sobre las claves y certificados en el Key Store en 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

Leer las llaves#

Leer claves y certificados del Key Store en un NetHSM. No es posible leer claves privadas desde el NetHSM.

La clave pública de un par de claves puede leerse como sigue.

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

El certificado de un par de claves puede leerse como sigue.

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

Los certificados o claves públicas devueltos están codificados en ASN.1. Los datos pueden descodificarse con la herramienta dumpasn1, ya que contienen datos en formato DER. El formato DER se puede convertir a formato PEM con OpenSSL.

Teclas de escritura#

Escriba claves y certificados en el Key Store en un NetHSM.

La clave privada de un par de claves puede escribirse como sigue.

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

La clave pública de un par de claves puede escribirse como sigue.

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

El certificado de un par de claves puede escribirse como sigue.

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

Operaciones clave#

Cifrar#

El NetHSM no puede cifrar datos con claves asimétricas, pero proporciona la clave pública que puede utilizarse para el cifrado. Consulte el capítulo Mostrar detalles de la clave, o recupere la clave como se describe en el capítulo Leer claves <pkcs11_con_pkcs11.html#read-keys>, para saber más sobre cómo recuperar la clave pública. El ejemplo asume la clave pública en el archivo public.pem.

Los datos pueden ser encriptados con OpenSSL de la siguiente manera.

$ 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

Descifrar#

El NetHSM puede descifrar los datos de una clave privada almacenada en el Key Store en el NetHSM. Este ejemplo utiliza el mensaje cifrado del capítulo anterior Cifrar.

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

NetHSM rulez!

Firma#

El NetHSM puede firmar datos para una clave privada almacenada en el almacenamiento de claves del NetHSM. Para las firmas con una clave RSA y ECDSA, se debe calcular primero un compendio.

Para calcular un compendio se necesitan primero los datos. Se crea un mensaje de la siguiente manera.

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

La firma creada puede ser verificada con OpenSSL de la siguiente manera.

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