EJBCA admite dos formas de conectarse a HSM mediante la API PKCS#11, el proveedor Java PKCS#11 y P11-NG.

Existe un contenedor PKCS#11 en Java que se utiliza para implementar la compatibilidad con tokens con bibliotecas PKCS#11, comúnmente conocido como el Proveedor PKCS#11 de Java. Este proveedor se ha probado con los HSM descritos aquí, en diversas versiones de firmware y software (además de algunas no descritas). Para obtener información sobre la compatibilidad con versiones específicas, consulte el soporte técnico u otra documentación. Las actualizaciones de Java del proveedor PKCS#11 pueden interrumpir la compatibilidad sin nuestro control.

Además de las claves descritas en Módulos de seguridad de hardware (HSM) , el campo de propiedad Crypto Token (que coincide con los valores fáciles de usar del Crypto Token en la GUI de administración) debe contener las siguientes propiedades:

• sharedLibrary: Ruta a la biblioteca PKCS#11 del HSM (/etc/utimaco/libcs2_pkcs11.so, /usr/safenet/lunaclient/lib/libCryptoki2_64.so, etc.)

• slotLabelType: Tipo de referencia de ranura, ver más abajo

• slotLabelValue: Valor de la referencia de la ranura (1, myslot, etc.).

El tipo de etiqueta de ranura puede ser uno de los siguientes

• SLOT_NUMBER: Cualquier entero positivo, se puede utilizar para hacer referencia a ranuras en cualquier HSM con numeración de ranuras consecutiva.

• SLOT_INDEX: Cualquier entero positivo, precedido por una 'i'.

• SLOT_LABEL: El estándar PKCS#11 permite el uso de cadenas para etiquetar ranuras. Esta etiqueta también puede ser un entero o una "i" seguida de un entero (como un número o un índice).

• SUN_FILE: La ranura especificada por un archivo de configuración de SUN. La etiqueta de la ranura puede dejarse en blanco.

Opcionalmente se pueden utilizar algunos campos de propiedades adicionales:

• atributosFile: Un archivo que especifica atributos PKCS#11 (utilizados principalmente para la generación de claves).

• keyspec: Especificación de clave utilizada al generar nuevas claves HSM desde la interfaz gráfica de usuario (GUI). Keyspec se utiliza como primera opción al generar nuevas claves en la GUI con el formato "1024" para claves RSA, "DSA1024" para claves DSA y secp256r1 para claves EC. Si no se proporciona keyspec, EJBCA intenta generar una clave con la misma especificación que la clave de firma del certificado actual.

Un archivo de atributos tiene el formato especificado en la Guía de referencia de JavaTM PKCS#11 .

Si no se especifica un archivo de atributos, se utiliza una configuración predeterminada integrada (a partir de EJBCA 3.11). Generalmente, no se recomienda usar un archivo de atributos y, por lo tanto, solo en casos excepcionales, utilizando un HSM poco común que no funcione correctamente con los valores predeterminados.

A continuación se muestra un ejemplo de un 'attributesFile' (que no se debe utilizar) que otorgará a las claves generadas los mismos valores de atributo que los predeterminados:

La única ocasión conocida en la que el valor predeterminado no funciona es cuando se utiliza la ranura protegida del módulo de un HSM Thales/nCipher y el archivo debe existir y tener CKA_PRIVATE = falso (ver a continuación).

Los atributos predeterminados que se aplican a cada clave generada por EJBCA garantizarán que:

• Se podrían realizar todas las operaciones necesarias.

• La parte privada de la clave se almacena en el HSM, pero no la parte pública (que está en un certificado almacenado en el HSM).

• Será imposible leer la parte privada de la clave desde el HSM.

La configuración predeterminada también deshabilita ciertos mecanismos de firma. Estos mecanismos se utilizan para firmar cuando los datos a firmar se han hasheado mediante PKCS#11 antes de usar la clave privada en el HSM. Cuando estos mecanismos están deshabilitados, el proveedor de envoltorios PKCS#11 de Sun realizará el hasheado en lugar del HSM. Esto agiliza la firma en la mayoría de los casos, especialmente cuando el HSM está en otro host, y no afectará la seguridad, ya que no se utiliza ningún secreto del HSM para el hasheado.

Sin embargo, es posible no deshabilitar estos mecanismos de hash/firma; consulte la sección PKCS#11 de '$EJBCA_HOME/conf/cesecore.properties'. Puede intentar no deshabilitar estos mecanismos si recibe el error CKR_FUNCTION_NOT_SUPPORTED (0x54) de PKCS#11 al firmar.

La herramienta EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool se utiliza para administrar y generar claves. Úsela sin parámetros para obtener todas las opciones válidas. Las claves se generan utilizando una ranura predeterminada y una biblioteca PKCS#11, o bien mediante un archivo de configuración.

• Para generar claves utilizando el valor predeterminado incorporado con una ranura específica y una biblioteca PKCS#11, utilice:

• Para generar claves utilizando un archivo de configuración, utilice:

El contenido del archivo de configuración se especifica en la documentación del contenedor PKCS#11 de Oracle. Generalmente, basta con usar el valor predeterminado, pero con algunos HSM, puede ser necesario definir ciertos atributos PKCS#11 para la clave generada.

Tenga en cuenta que todas las claves que se utilizarán deben generarse antes de iniciar el servidor de aplicaciones.

Los atributos predeterminados intentan configurar automáticamente CKA_LABEL también al generar claves con clientToolBox. Puede configurar CKA_LABEL (caracteres hexadecimales) también con un archivo de atributos, ya sea configurando el valor CKA_LABEL:

o bien, estableciendo una cadena CKA_LABEL vacía con dos espacios antes y nada, ni siquiera un espacio después. Este marcador de posición se reemplazará dinámicamente con el valor del alias de la clave, codificado en hexadecimal: