Realización de operaciones criptográficas con la API de PKCS #11

IBM Cloud® Hyper Protect Crypto Services proporciona la API de PKCS #11 estándar para acceder al HSM de nube de Hyper Protect Crypto Services para operaciones criptográficas.

Requisitos previos

Para poder configurar y utilizar la API de PKCS #11, en primer lugar siga las Mejores prácticas para configurar los tipos de usuario de PKCS #11 para crear diferentes claves de API de ID de servicio para los diferentes tipos de usuario de PKCS #11.

Paso 1: Configurar la biblioteca de PKCS #11

Debe configurar la biblioteca de PKCS #11 en su estación de trabajo para hacerla disponible para que sus aplicaciones llamen a las funciones de PKCS #11 estándar.

La biblioteca PKCS #11 , para las plataformas amd64 y s390x, solo está soportada en Linux.

Si está ejecutando una aplicación Java PKCS #11 utilizando el proveedor SunPKCS11 en la plataforma IBM Z (s390x), asegúrese de que utiliza la JVM Semeru de IBM más reciente y especifique la opción -Xjit:noResumableTrapHandler Java al iniciar la aplicación. Puede descargar la última versión de s390x de la JVM de IBM Semeru cambiando el campo de filtro Arquitectura a s390x en la página de descargas de tiempo de ejecución deIBM Semeru.

Descargue la biblioteca PKCS #11 más reciente. Los nombres de archivo de biblioteca utilizan el convenio de denominación: pkcs11-grep11-<platform>.so.<version>. La plataforma es amd64 o s390x y la versión es la sintaxis major.minor.build estándar.
Mueva la biblioteca a una carpeta a la que puedan acceder las aplicaciones. Por ejemplo, si ejecuta la aplicación en Linux, puede mover la biblioteca a /usr/local/lib, /usr/local/lib64o /usr/lib.

Paso 2: (Opcional) Verifique la integridad y la autenticidad de la biblioteca de PKCS #11

Para obtener la máxima seguridad, verifique la integridad y la autenticidad de la biblioteca de PKCS #11 antes de ejecutar las aplicaciones PKCS #11 para que utilicen la biblioteca.

Hyper Protect Crypto Services habilita la verificación de código firmado para asegurarse de que la firma coincide con el código original. Si el archivo de biblioteca de PKCS #11 descargado se modifica o se daña, se genera una firma distinta y la verificación falla. Para asegurarse de que los archivos no están alterados o dañados durante el proceso de descarga, realice los pasos siguientes utilizando la herramienta de línea de mandatosOpenSSL.

Descargue la versión más reciente de los archivos siguientes del repositorio de bibliotecas en el mismo directorio donde almacena la biblioteca PKCS #11 :
- pkcs11-grep11-<platform>.so.<version>.sig: el hash criptográfico firmado de la biblioteca PKCS #11, donde plataforma es amd64 o s390x y la versión es el major.minor.build del archivo de firma. Tanto la plataforma como la versión deben coincidir con la respectiva plataforma y la versión de la biblioteca de PKCS #11 que se utiliza.
- signing_cert.pem: el certificado de firma de los archivos de cliente de Hyper Protect Crypto Services PKCS #11.
- digicert_cert.pem: un certificado de firma de código intermedio para probar el certificado de firma de los archivos de cliente de Hyper Protect Crypto Services PKCS #11.
Extraiga la clave pública del certificado de firma signing_cert.pem en el archivo sigkey.pub con el siguiente mandato:
```
openssl x509 -pubkey -noout -in signing_cert.pem -out sigkey.pub
```
Verifique la integridad del archivo de biblioteca de PKCS #11 con el siguiente mandato:
```
openssl dgst -sha256 -verify sigkey.pub -signature pkcs11-grep11-<platform>.so.<version>.sig pkcs11-grep11-<platform>.so.<version>
```
Sustituya platform por amd64 o s390x y sustituya version por major.minor.build de la biblioteca.

Donde la verificación es satisfactoria, se visualiza Verified OK.
Verifique la autenticidad y la validez del certificado de firma con el mandato siguiente:
```
openssl ocsp -no_nonce -issuer digicert_cert.pem -cert signing_cert.pem -VAfile digicert_cert.pem -text -url http://ocsp.digicert.com -respout ocsptest
```
Cuando la verificación se ha realizado correctamente, Response verify OK y signing_cert.pem: good se muestran en la salida.
Si la verificación falla, cancele la instalación y póngase en contacto con IBM para obtener soporte.

Paso 3: Configurar el archivo de configuración de PKCS #11

Para conectar la biblioteca de PKCS #11 al HSM de nube de Hyper Protect Crypto Services para realizar funciones criptográficas, debe realizar los pasos siguientes para configurar el archivo de configuración.

Cree un archivo de configuración con el nombre grep11client.yaml basado en el ejemplo siguiente. El repositorio de bibliotecas también proporciona una plantilla para que se adapte. Puede remitirse a los comentarios del código para comprender cada campo.

iamcredentialtemplate: &defaultiamcredential
  enabled: true
  endpoint: "https://iam.cloud.ibm.com"

sessionauthtemplate: &defaultsessionauth
  enabled: false
  tokenspaceIDPassword:  # Authenticated keystore password 6-8 characters in length

tokens:
  0:
    grep11connection:
      # The EP11 endpoint address starting from 'ep11'. For example: "<instance_ID>.ep11.us-south.hs-crypto.appdomain.cloud"
      address: "<EP11_endpoint_URL>"
      port: "<EP11_endpoint_port_number>" # The EP11 endpoint port number
      tls:
        enabled: true # EP11 requires TLS connection.
        # Set it 'true' if you want to enable mutual TLS connections.
        # By default, set it 'false' because EP11 requires server-only authentication.
        mutual: <enable_mtls>
        # 'cacert' is a full-path certificate file. In Linux with the 'ca-ca-certificates' package installed, this is normally not needed.
        cacert:
        # Specify the file path of the client certificate if you enable mutual TLS. Otherwise, keep it empty.
        certfile: <client_certificate>
        # Specify the file path of the client certificate private key if you enable mutual TLS. Otherwise, keep it empty.
        keyfile: <client_certificate_private_key>
    storage:
        # 'remotestore' needs to be enabled if you want to generate keys with the attribute CKA_TOKEN.
      remotestore:
        enabled: true
    users:
      0: # The index of the Security Officer (SO) user MUST be 0.
        # The name for the Security Officer (SO) user. For example: "Administrator".
        name: "<SO_user_name>"
        iamauth: *defaultiamcredential
      1: # The index of the normal user MUST be 1.
        # The name for the normal user. For example: "Normal user".
        name: "<normal_user_name>"
        # The 128-bit UUID of the private keystore. For example: "f00db2f1-4421-4032-a505-465bedfa845b".
        tokenspaceID: "<private_keystore_spaceid>"
        iamauth: *defaultiamcredential
        # Do not override the defaultsessionauth template
        # The same values must be used for both the private (normal user) and public (anonymous) keystores
        sessionauth: *defaultsessionauth
      2: # The index of the anonymous user MUST be 2.
        # The name for the anonymous user. For example: "Anonymous".
        name: "<anonymous_user_name>"
        # The 128-bit UUID of the public keystore. For example: "ca22be26-b798-4fdf-8c83-3e3a492dc215".
        tokenspaceID: "<public_keystore_spaceid>"
        iamauth:
          <<: *defaultiamcredential
          # The API key for the anonymous user. All other users can specify API key using the C_Login command.
          apikey: "<apikey_for_anonymous_user>"
        # Do not override the defaultsessionauth template
        # The same values must be used for both the private (normal user) and public (anonymous) keystores
        sessionauth: *defaultsessionauth

logging:
  # Set the logging level.
  # The supported levels, in an increasing order of verboseness: 'panic', 'fatal', 'error', 'warning'/'warn', 'info', 'debug', 'trace'. The Default value is 'warning'.
  loglevel: "<logging_level>"
  logpath: "<log_file_path>" # The full path of your logging file.

Si se utilizan almacenes de claves autenticados, la opción de configuración sessionauth debe estar habilitada para ambos almacenes de claves y las contraseñas de texto que tienen de 6 a 8 caracteres de longitud deben ser idénticas para ambos almacenes de claves en el campo tokenspaceIDPassword.

Sustituya las variables en el ejemplo según lo que se indica en la tabla siguiente:

Si crea las instancias después del 12 de abril de 2024 en determinadas regiones, es posible que tenga que utilizar los nuevos puntos finales de API con el nuevo formato como <instance_ID>.ep11.<REGION>.hs-crypto.appdomain.cloud. La fecha de disponibilidad varía según la región. Para obtener más información sobre las regiones soportadas, las fechas de disponibilidad y los nuevos URL de punto final, consulte Nuevos puntos finales.

Tabla 1. Describe las variables necesarias para crear el archivo de configuración PKCS #11
Variable	Descripción
`EP11_endpoint_URL`	El punto final de la API de Hyper Protect Crypto Services Enterprise PKCS #11 (EP11). Puede obtenerlo a través de Visión general > Conectar > EP11 URL de punto final en la interfaz de usuario, o puede recuperar dinámicamente el URL de punto final con la API. En función de si está utilizando una red privada o pública, utilice el URL de punto final de EP11 público o privado.
`EP11_endpoint_port_number`	El número de puerto del punto final de API de EP11. Se encuentra después del signo de dos puntos en el URL de punto final.
`enable_mtls`	Los valores válidos son `true` o `false` para indicar si desea habilitar TLS mutuo para añadir una segunda capa de autenticación para el acceso de API PKCS #11 para el plan estándar Hyper Protect Crypto Services. De forma predeterminada, establézcalo en `false` ya que EP11 requiere autenticación solo de servidor. Para obtener más información sobre las conexiones TLS mutuas, consulte Habilitación de la segunda capa de autenticación para conexiones de EP11.
`client_certificate`	Si habilita las conexiones TLS mutuas, especifique la vía de acceso del certificado de cliente que el administrador del certificado ha cargado en la instancia. De lo contrario, mantenga este campo vacío.
`client_certificate_private_key`	Si habilita las conexiones TLS mutuas, especifique la vía de acceso de la clave privada del certificado de cliente que se utiliza para firmar el certificado. De lo contrario, mantenga este campo vacío.
`SO_user_name`	El nombre del tipo de usuario responsable de seguridad (SO). El estándar PKCS #11 define dos tipos de usuarios para el inicio de sesión: un responsable de seguridad (SO) y un usuario normal. Para obtener más información sobre los tipos de usuario PKCS #11, consulte la Guía de uso de PKCS #11 Cryptographic Token Interface Versión 2.40 - Usuarios.
`normal_user_name`	El nombre del tipo de usuario normal. El estándar PKCS #11 define dos tipos de usuarios para el inicio de sesión: un responsable de seguridad (SO) y un usuario normal. Para obtener más información sobre los tipos de usuario PKCS #11, consulte la Guía de uso de PKCS #11 Cryptographic Token Interface Versión 2.40 - Usuarios.
`private_keystore_spaceid`	El identificador único universal (UUID) de 128 bits del almacén de claves privadas. Puede generar el UUID con una herramienta de terceros, como por ejemplo Generador de UUID. Hyper Protect Crypto Services le proporciona dos almacenes de claves EP11 respaldados por base de datos para mejorar la seguridad y la gestión de accesos de usuario: el almacén de claves privado al que solo puede acceder el tipo de usuario normal y el almacén de claves público al que pueden acceder todos los tipos de usuario. El UUID debe ser diferente del UUID especificado para el parámetro `public_keystore_spaceid`.
`private_keystore_password`	Las sesiones autorizadas se pueden utilizar habilitando la opción de configuración de `sessionauth`. Si la opción `sessionauth` está habilitada, debe estar habilitada para ambos almacenes de claves. Además, se necesita una contraseña de texto de entre 6 y 8 caracteres de longitud para el campo `tokenspaceIDPassword` y la contraseña debe ser idéntica para ambos almacenes de claves. Las sesiones autorizadas son específicas del HSM y se utilizan en el flujo de PKCS #11 para iniciar sesión y cerrar sesión, y son necesarias para operaciones de claves autenticadas. Todas las claves generadas utilizando sesiones autorizadas se almacenan en un almacén de claves autenticado y cifrado. El campo `tokenspaceIDPassword` se utiliza para proteger las claves en un almacén de claves autenticado y cifrado. Para cada instancia de servicio, se da soporte a un máximo de cinco almacenes de claves autenticados.
`anonymous_user_name`	El nombre del usuario anónimo. El estándar PKCS #11 define dos tipos de usuarios para el inicio de sesión: un responsable de seguridad (SO) y un usuario normal. Si un usuario no inicia sesión utilizando la función Cryptoki de `C_Login`, el usuario se conoce como un usuario anónimo. Para obtener más información sobre los tipos de usuario PKCS #11, consulte la Guía de uso de PKCS #11 Cryptographic Token Interface Versión 2.40 - Usuarios.
`public_keystore_spaceid`	El identificador único universal (UUID) de 128 bits del almacén de claves públicas. Puede generar el UUID con una herramienta de terceros, como por ejemplo Generador de UUID. Hyper Protect Crypto Services le proporciona dos almacenes de claves EP11 respaldados por base de datos para mejorar la seguridad y la gestión de accesos de usuario: el almacén de claves privado al que solo puede acceder el tipo de usuario normal y el almacén de claves público al que pueden acceder todos los tipos de usuario. El UUID debe ser diferente del UUID especificado para el parámetro `private_keystore_spaceid`. Importante: El valor de serie de UUID debe coincidir con la serie de UUID utilizada para configurar las políticas de acceso para el usuario anónimo. Véase creación de política de acceso de usuario anónimo.
`apikey_for_anonymous_user`	La clave de API de ID de servicio que se crea para el tipo de usuario anónimo en el paso de requisitos previos anterior.
`logging_level`	Los niveles de registro soportados, en orden ascendente de verbosidad: `panic`, `fatal`, `error`, `warning`/`warn`, `info`, `debug`, y `trace`. El valor predeterminado es `warning`.
`log_file_path`	La vía de acceso completa del archivo de registro. Guarda todos los registros que se generan cuando las aplicaciones interactúan con el HSM de nube de Hyper Protect Crypto Services para ejecutar funciones de PKCS #11.

Para cifrar y autenticar el almacén de claves que utiliza PKCS #11, habilite el parámetro sessionauth y configure la contraseña para el almacén de claves. Para cada instancia de servicio, se da soporte a un máximo de cinco almacenes de claves autenticados. La contraseña puede tener entre 6 y 8 caracteres. Las contraseñas del almacén de claves no se almacenan en la instancia de servicio. Como administrador del almacén de claves, es responsable de mantener una copia local de las contraseñas. Si se pierde una contraseña, debe ponerse en contacto con el soporte de IBM para restablecer el almacén de claves, lo que significa que se borran todos los datos del almacén de claves.

Mueva el archivo de configuración al directorio /etc/ep11client. Cree el directorio /etc/ep11client si no existe. De forma alternativa, puede establecer la variable de entorno EP11CLIENT_CFG en la vía de acceso completa y el nombre de archivo del archivo de configuración. Al hacerlo, no está restringido al nombre grep11client del archivo yaml. Ejemplo: export EP11CLIENT_CFG=/home/user/pkcs11-config.yaml

Paso 4: Utilice la biblioteca de PKCS #11 para realizar llamadas de API de PKCS #11

Después de configurar la biblioteca y el archivo de configuración, los almacenes de claves deben inicializarse. Para inicializar los almacenes de claves, el usuario de seguridad (SO) necesita realizar una operación C_InitToken.

Después de inicializar los almacenes de claves, utilice la biblioteca PKCS #11 para invocar las funciones estándar de PKCS #11 para generar, almacenar y listar claves. Para obtener la lista detallada de las funciones de PKCS #11 soportadas, consulte Referencia de API de PKCS #11.

En función de las características y los requisitos de seguridad de su aplicación, pase diferentes claves de API de ID de servicio que ha creado en el paso de requisitos previos anterior para que sus aplicaciones puedan realizar las operaciones correspondientes. Por ejemplo, si su aplicación necesita suprimir un almacén de claves, proporcione la clave de API del usuario SO. Si la aplicación necesita acceder al almacén de claves privadas para almacenar nuevas claves, debe proporcionar la clave de API de usuario normal. Para obtener más información sobre la gestión de accesos de usuario para la API de PKCS #11, consulte Mejores prácticas para configurar los tipos de usuario de PKCS #11.

Qué hacer a continuación

Consulte la guía de aprendizaje que muestra cómo utilizar la biblioteca de PKCS #11 de Hyper Protect Crypto Services para Oracle Database Transparent Database Encryption para comprender mejor el uso de la biblioteca de PKCS #11.
Consulte la Referencia de API de PKCS #11 para obtener información detallada sobre las funciones criptográficas.