En esta guía se explica cómo configurar OpenSSL para usar una clave de Cloud HSM en Debian 11 (Bullseye). Estas instrucciones se pueden aplicar en general aunque uses otro SO u otro entorno, pero ten en cuenta que puede haber ligeras diferencias.
Requisitos
Descarga una versión de la biblioteca para empezar. Para obtener más información sobre la biblioteca PKCS #11, consulta la guía de usuario.
Antes de empezar, instala el paquete libengine-pkcs11-openssl.
sudo apt-get update
sudo apt-get install libengine-pkcs11-openssl
Configuración
Definir la variable de entorno PKCS11_MODULE_PATH.
Para que openssl use nuestra biblioteca PKCS #11, define la variable de entorno PKCS11_MODULE_PATH:
export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"
Para definir la variable de entorno de forma permanente, añade export PKCS11_MODULE_PATH="/path/to/libkmsp11.so" a /etc/profile
ejecutando el 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 localizar los recursos de Cloud KMS. El archivo YAML debe configurar al menos un token PKCS #11.
Si usas OpenSSL con otro proceso que pueda bifurcarse (por ejemplo, Apache o Nginx), también debes asegurarte de que el campo refresh_interval_secs no se defina o se defina en 0.
Archivo de configuración de ejemplo:
---
tokens:
- key_ring: "projects/my-project/locations/us-central1/keyRings/my-keyring"
Con esta configuración, todas las claves de firma y descifrado asimétricas de my-keyring estarán disponibles en la biblioteca.
Debes definir los permisos del archivo de configuración para que solo el propietario del archivo pueda escribir en él. Dirige KMS_PKCS11_CONFIG a tu archivo de configuración:
export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"
De nuevo, puedes hacer que este ajuste sea permanente añadiéndolo a /etc/profile.
echo 'export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"' | sudo tee -a /etc/profile
Ejecutar comandos de OpenSSL
Una vez que el motor y la biblioteca estén configurados correctamente, podrá usar el motor en los comandos de OpenSSL.
Cuando crees firmas asimétricas, ten en cuenta que las claves de Cloud KMS solo pueden usar un único resumen. Por ejemplo, un CryptoKeyVersion
con el algoritmo EC_SIGN_P256_SHA256 siempre debe usarse junto con
un resumen SHA-256. Esto corresponde a la marca -sha256 de OpenSSL. Las claves que requieren resúmenes SHA-384 o SHA-512 deben usarse con las marcas -sha384 o -sha512.
Crear una firma
Si hay una clave llamada foo en el conjunto 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
La salida de este comando es binaria sin formato.
Este comando da por hecho que estás usando una clave que toma un resumen SHA-256, por lo que se ha usado el argumento -sha256. Las opciones -sha384 o -sha512 serían adecuadas para las claves de Cloud HSM que usen esos tipos de digest.
En el caso de las claves RSA-PSS, recuerda usar las opciones -sigopt que hemos comentado anteriormente.
Crear una solicitud de firma de certificado
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 de certificación requiere una CSR para generar un nuevo certificado de firma de código o para proteger las sesiones web TLS.
openssl req -new -subj '/CN=test/' -sha256 -engine pkcs11 \
-keyform engine -key pkcs11:object=foo > my-request.csr
Generar un nuevo certificado autofirmado
Para el desarrollo y las pruebas locales, puedes usar un certificado autofirmado para una clave de firma de Cloud HSM. Los certificados autofirmados también son útiles para firmar tokens SAML.
openssl req -new -x509 -days 3650 -subj '/CN=test/' -sha256 -engine pkcs11 \
-keyform engine -key pkcs11:object=foo > my-request.crt
Solucionar 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 coloca 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
A continuación, define la variable de entorno PKCS11_MODULE_PATH para que OpenSSL apunte a la biblioteca PKCS #11 Spy ejecutando el siguiente comando:
export PKCS11_MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so
Por último, apunta PKCS #11 Spy a la biblioteca PKCS #11 de Cloud HSM configurando las variables de entorno PKCS11SPY y PKCS11SPY_OUTPUT. Para definir 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"