En esta guía, se proporcionan instrucciones para configurar OpenSSL a fin de usar una clave de Cloud HSM en Debian 11 (Bullseye). Por lo general, estas instrucciones son aplicables incluso si usas otro SO o entorno, pero ten en cuenta que puede haber pequeñas diferencias.
Requisitos
Descarga una versión de la biblioteca para comenzar. Para obtener detalles adicionales sobre la biblioteca de PKCS n.o 11, consulta la guía del usuario.
Antes de comenzar, instala el paquete libengine-pkcs11-openssl.
sudo apt-get update
sudo apt-get install libengine-pkcs11-openssl
Configuración
Configuración de la variable de entorno PKCS11_MODULE_PATH
Para que openssl use nuestra biblioteca PKCS #11, configura la variable de entorno PKCS11_MODULE_PATH:
export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"
Para configurar la variable de entorno de forma permanente, agrega export PKCS11_MODULE_PATH="/path/to/libkmsp11.so" a /etc/profile mediante la ejecución del siguiente comando:
echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee -a /etc/profile
Configuración de la biblioteca PKCS #11
La biblioteca PKCS #11 requiere un archivo de configuración YAML para ubicar los recursos de Cloud KMS. El YAML debe, como mínimo, configurar un único token PKCS #11.
Si usas OpenSSL con otro proceso que puede llegar a bifurcarse (por ejemplo, Apache o Nginx), también debes asegurarte de que el campo refresh_interval_secs permanezca sin configurarse o se configure en 0.
Archivo de configuración de muestra:
---
tokens:
- key_ring: "projects/my-project/locations/us-central1/keyRings/my-keyring"
Con esta configuración, todas las claves de firma y desencriptación asimétricas en my-keyring estarán disponibles en la biblioteca.
Debes establecer los permisos en el archivo de configuración para que solo el propietario del archivo pueda escribir en él. Apunta KMS_PKCS11_CONFIG al archivo de configuración:
export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"
De nuevo, puedes hacer que esta configuración sea permanente si la agregas a /etc/profile.
echo 'export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"' | sudo tee -a /etc/profile
Ejecuta comandos de OpenSSL
Una vez que el motor y la biblioteca estén configurados correctamente, podrás usar el motor en los comandos de OpenSSL.
Cuando crees firmas asimétricas, ten en cuenta que las claves de Cloud KMS están limitadas a usar un único resumen. Por ejemplo, una CryptoKeyVersion con el algoritmo EC_SIGN_P256_SHA256 siempre se debe usar junto con un resumen SHA-256. Esto corresponde a la marca -sha256 en OpenSSL. Las claves que requieren resúmenes de SHA-384 o SHA-512 deben usarse con las marcas -sha384 o -sha512.
Crea una nueva firma
Si suponemos que hay una clave llamada foo en tu llavero de claves configurado, usa el siguiente comando para crear una firma en bar.txt:
openssl dgst -sha256 -engine pkcs11 -keyform engine -sign pkcs11:object=foo bar.txt
El resultado de este comando es un objeto binario sin formato.
Ese comando supone que usas una clave que toma un resumen SHA-256, por lo que se usó el argumento -sha256. Las opciones -sha384 o -sha512 serían adecuadas para las claves de Cloud HSM que usan esos tipos de resumen.
Para una clave RSA-PSS, recuerda usar las opciones -sigopt que se analizaron antes.
Crea una solicitud de firma de certificado nueva
También puedes generar una solicitud de firma de certificado (CSR) para una clave de firma de Cloud HSM. Esto es útil si tu autoridad certificadora requiere una CSR a fin de generar un certificado nuevo para firmar el código o proteger las sesiones web de TLS.
openssl req -new -subj '/CN=test/' -sha256 -engine pkcs11 \
-keyform engine -key pkcs11:object=foo > my-request.csr
Genera un certificado autofirmado nuevo
Para el desarrollo y las pruebas locales, puedes usar un certificado autofirmado a fin de obtener una clave de firma de Cloud HSM. Los certificados autofirmados también son útiles para la firma de tokens de SAML.
openssl req -new -x509 -days 3650 -subj '/CN=test/' -sha256 -engine pkcs11 \
-keyform engine -key pkcs11:object=foo > my-request.crt
Solución de problemas con PKCS #11 Spy
PKCS #11 Spy es una herramienta de código abierto que registra el contenido de las interacciones a través de una interfaz PKCS #11. Para ello, se conecta entre la aplicación y la biblioteca PKCS #11, y registra todas las llamadas que se realizan. Esto puede ser útil para solucionar problemas.
Para usar PKCS #11 Spy, debes tener instalado el paquete opensc. El paquete opensc contiene PKCS #11 Spy. Para asegurarte de que opensc esté instalado, ejecuta el siguiente comando:
sudo apt-get install opensc
Luego, configura la variable de entorno PKCS11_MODULE_PATH para que apunte OpenSSL a la biblioteca espía PKCS #11 mediante la ejecución del siguiente comando:
export PKCS11_MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so
Por último, apunta el PKCS n.o 11 Spy a la biblioteca de PKCS #11 de Cloud HSM configurando las variables de entorno PKCS11SPY y PKCS11SPY_OUTPUT. Para configurar estas variables de entorno, ejecuta los siguientes comandos:
export PKCS11SPY="/path/to/libkmsp11.so"
# Optional, stderr will be used for logging if not set
export PKCS11SPY_OUTPUT="/path/to/pkcs11-spy.log"