Executando operações criptográficas com a API do PKCS n.º 11

Os IBM Cloud® Hyper Protect Crypto Services fornecem a API PKCS n.º 11 padrão para acessar o HSM em nuvem dos Hyper Protect Crypto Services para operações criptográficas.

Pré-requisitos

Antes de ser possível configurar e utilizar a API do PKCS n° 11 , primeiro siga as Melhores práticas para configurar os tipos de usuário do PKCS n° 11 para criar diferentes chaves de API de ID de serviço para os vários tipos de usuários do PKCS n° 11.

Etapa 1: configurar a biblioteca PKCS n.º 11

É necessário configurar a biblioteca PKCS n.º 11 em sua estação de trabalho para torná-la disponível aos seus aplicativos para chamar as funções do PKCS n.º 11 padrão.

A biblioteca PKCS #11, tanto para oamd64 es390x plataformas, é suportado apenas emLinux.

Se você estiver executando um aplicativo Java PKCS #11 usando o provedor SunPKCS11 na plataforma IBM Z (s390x), certise-se de usar a mais recente JVM IBM Semeru e especificar a opção -Xjit:noResumableTrapHandler Java ao iniciar sua aplicação. Você pode baixar a versão mais recente do s390x da JVM do IBM Semeru alterando o campo de filtro Architecture para s390x na página IBM Semeru Runtime Downloads.

  1. Baixe a biblioteca mais recente do PKCS #11. Os nomes dos arquivos da biblioteca usam a convenção de nomenclatura:pkcs11-grep11-<platform>.so.<version>. A plataforma é a amd64 ou a s390x e a versão é a sintaxe padrão major.minor.build.
  2. Mova a biblioteca em uma pasta que seja acessível por seus aplicativos. Por exemplo, se você estiver executando o seu aplicativo no Linux, é possível mover a biblioteca para /usr/local/lib, /usr/local/lib64 ou /usr/lib.

Etapa 2: (opcional) verifique a integridade e a autenticidade da biblioteca PKCS n.º 11

Para segurança máxima, verifique a integridade e a autenticidade da biblioteca PKCS n.º 11 antes de executar seus aplicativos PKCS n.º 11 para usar a biblioteca.

Hyper Protect Crypto Services habilita verificação de código assinado para garantir que a assinatura corresponda ao código original. Se o arquivo de biblioteca PKCS n.º 11 transferido por download for alterado ou corrompido, uma assinatura diferente será produzida e a verificação falhará. Para garantir que os arquivos não sejam adulterados ou corrompidos durante o processo de download, conclua as etapas a seguir usando o OpenSSL ferramenta de linha de comando.

  1. Baixe a versão mais recente dos seguintes arquivos do repositório de biblioteca para o mesmo diretório onde você armazena a biblioteca PKCS #11:

    • pkcs11-grep11-<platform>.so.<version>.sig: O hash criptográfico assinado da biblioteca PKCS #11, onde a plataforma é amd64 ou s390x e a versão é o major.minor.build do arquivo de assinatura. Tanto a plataforma quanto a versão devem combinar com a respectiva plataforma e a versão da biblioteca PKCS n.º 11 que você usa.

    • signing_cert.pem: o certificado de assinatura dos arquivos do cliente do PKCS n.º 11 dos Hyper Protect Crypto Services.

    • digicert_cert.pem: um certificado de assinatura de código intermediário para comprovar o certificado de assinatura dos arquivos do cliente do PKCS n.º 11 dos Hyper Protect Crypto Services.

  2. Extraia a chave pública do certificado de assinatura signing_cert.pem no arquivo sigkey.pub com o comando a seguir:

    openssl x509 -pubkey -noout -in signing_cert.pem -out sigkey.pub

  3. Verifique a integridade do arquivo de biblioteca PKCS n.º 11 com o comando a seguir:

    openssl dgst -sha256 -verify sigkey.pub -signature pkcs11-grep11-<platform>.so.<version>.sig pkcs11-grep11-<platform>.so.<version>

    Substitua a plataforma por amd64 ou s390x e substitua a versão pelo major.minor.build da biblioteca.

    Quando a verificação for bem-sucedida, Verified OK será exibido.

  4. Verifique a autenticidade e a validade do certificado de assinatura com o comando a seguir:

    openssl ocsp -no_nonce -issuer digicert_cert.pem -cert signing_cert.pem -VAfile digicert_cert.pem -text -url http://ocsp.digicert.com -respout ocsptest

    Quando a verificação for bem-sucedida, Response verify OK e signing_cert.pem: good serão exibidos na saída.

  5. Se a verificação falhar, cancele a instalação e entre em contato com a IBM para obter suporte.

Etapa 3: configurar o arquivo de configuração do PKCS n.º 11

Para conectar a biblioteca PKCS n.º 11 ao HSM em nuvem dos Hyper Protect Crypto Services para executar funções de criptografia, é necessário preencher as etapas a seguir para definir o arquivo de configuração.

  1. Crie um arquivo de configuração que seja denominado grep11client.yaml com base no exemplo a seguir. O repositório de biblioteca também fornece um modelo para você adaptar. É possível consultar os comentários no código para entender 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.

    Se os keystores autenticados forem usados, a opção de configuração sessionauth deverá ser ativada para os keystores e as senhas de texto que têm de 6 a 8 caracteres de comprimento deverão ser idênticas para ambos os keystores no campo tokenspaceIDPassword.

    Substitua as variáveis no exemplo de acordo com a tabela a seguir:

    Se você criar suas instâncias após 12 de abril de 2024 em determinadas regiões, talvez seja necessário usar os novos endpoints da API com o novo formato como <instance_ID>.ep11.<REGION>.hs-crypto.appdomain.cloud. A data de disponibilidade varia de acordo com a região. Para obter mais informações sobre as regiões suportadas, as datas de disponibilidade e os novos URLs de endpoint, consulte Novos pontos de extremidade.

    Tabela 1. Descreve as variáveis necessárias para criar o arquivo de configuração PKCS #11
    Variável Descrição
    EP11_endpoint_URL O terminal de API do Enterprise PKCS n.º 11 (EP11) dos Hyper Protect Crypto Services. Você pode passar por isso Visão geral >Conectar >EP11 URL do terminal na interface do usuário ou você pode dinamicamente recuperar o URL do terminal com a API. Dependendo se você estiver usando uma rede pública ou privada, use a URL do terminal EP11 público ou privado.
    EP11_endpoint_port_number O número da porta do terminal de API do EP11. Ele está localizado após os dois-pontos na URL de terminal.
    enable_mtls Os valores válidos são true ou false para indicar se você deseja ativar o TLS mútuo para adicionar uma segunda camada de autenticação para acesso à API PKCS #11 paraHyper Protect Crypto Services Plano Padrão. Por padrão, configure-o false uma vez que o EP11 requer autenticação somente do servidor. Para obter mais informações sobre as conexões TLS mútuas, consulte Ativando a segunda camada de autenticação para conexões EP11.
    client_certificate Se você ativar conexões TLS mútuas, especifique o caminho de arquivo do certificado de cliente que é transferido por upload para sua instância pelo administrador de certificados. Caso contrário, deixe esse campo vazio.
    client_certificate_private_key Se você ativar conexões TLS mútuas, especifique o caminho de arquivo da chave privada do certificado de cliente usado para assinar o certificado. Caso contrário, deixe esse campo vazio.
    SO_user_name O nome para o tipo de usuário do Responsável pela Segurança (SO). O padrão do PKCS n.º 11 define dois tipos de usuários para login: o responsável pela segurança (SO) e o usuário normal. Para obter mais informações sobre os tipos de usuário PKCS #11, consulte Guia de uso da interface de token criptográfico PKCS #11 Versão 2.40 - Usuários.
    normal_user_name O nome para o tipo de usuário normal. O padrão do PKCS n.º 11 define dois tipos de usuários para login: o responsável pela segurança (SO) e o usuário normal. Para obter mais informações sobre os tipos de usuário PKCS #11, consulte Guia de uso da interface de token criptográfico PKCS #11 Versão 2.40 - Usuários.
    private_keystore_spaceid O Universally Unique IDentifier (UUID) de 128 bits do keystore privado. É possível gerar o UUID com uma ferramenta de terceiros, como Gerador de UUID.

    Hyper Protect Crypto Services fornece dois keystores do EP11 suportados pelo banco de dados para segurança aprimorada e melhor gerenciamento de acesso de usuário: o keystore privado que somente o tipo de usuário normal pode acessar e o keystore público que todos os tipos de usuário podem acessar. O UUID deve ser diferente do UUID especificado para o parâmetro public_keystore_spaceid.
    private_keystore_password As sessões autorizadas podem ser usadas ao ativar a opção de configuração sessionauth. Se a opção sessionauth estiver ativada, ela deverá ser ativada para ambos os armazenamentos de chave Além disso, uma senha de texto com 6-8 caracteres de comprimento é necessária para o campo tokenspaceIDPassword e a senha deve ser idêntica para ambos os keystores. As sessões autorizadas são específicas para o HSM e são usadas no fluxo do PKCS n° 11 para fazer login e logout, assim como são necessárias para operações de chaves autenticadas. Todas as chaves geradas usando sessões autorizadas são armazenadas em um keystore autenticado e criptografado. O campo tokenspaceIDPassword é usado para proteger as chaves em um keystore autenticado e criptografado. Para cada instância de serviço, um máximo de cinco keystores autenticados são suportados.
    anonymous_user_name O nome para o usuário anônimo. O padrão do PKCS n.º 11 define dois tipos de usuários para login: o responsável pela segurança (SO) e o usuário normal. Se um usuário não fizer login usando a função Cryptoki C_Login, então o usuário é conhecido como um usuário anônimo. Para obter mais informações sobre os tipos de usuário PKCS #11, consulte Guia de uso da interface de token criptográfico PKCS #11 Versão 2.40 - Usuários.
    public_keystore_spaceid O Universally Unique IDentifier (UUID) de 128 bits do keystore público. É possível gerar o UUID com uma ferramenta de terceiros, como Gerador de UUID.

    Hyper Protect Crypto Services fornece dois keystores do EP11 suportados pelo banco de dados para segurança aprimorada e melhor gerenciamento de acesso de usuário: o keystore privado que somente o tipo de usuário normal pode acessar e o keystore público que todos os tipos de usuário podem acessar. O UUID deve ser diferente do UUID especificado para o parâmetro private_keystore_spaceid.

    . Importante: o valor da sequência UUID deve corresponder à sequência UUID usada para configurar políticas de acesso para o usuário anônimo. Consulte criação anônima de política de acesso de usuário
    apikey_for_anonymous_user A chave de API de ID de serviço que você cria para o tipo de usuário anônimo na etapa de pré-requisitos anterior.
    logging_level Os níveis de criação de log suportados, em ordem crescente de detalhamento: panic, fatal, error, warning/warn, info, debug e trace. O valor Padrão é warning.
    log_file_path O caminho completo do seu arquivo de criação de log. Ele salva todos os logs que são gerados quando seus aplicativos interagem com o HSM em nuvem do Hyper Protect Crypto Services para executar funções do PKCS n.º 11.

    Para criptografar e autenticar o keystore usado pelo PKCS n° 11, ative o parâmetro sessionauth e configure a senha para o keystore. Para cada instância de serviço, um máximo de cinco keystores autenticados são suportados. A senha pode ser de 6 até 8 caracteres. As senhas do keystore não são armazenadas na instância de serviço. Você, como administrador do keystore, é responsável por manter uma cópia local das senhas. Se uma senha for perdida, é necessário entrar em contato com o suporte IBM para redefinir o keystore, o que significa que todos os dados no keystore serão limpos.

  2. Mova o arquivo de configuração para o /etc/ep11client diretório. Crie o diretório /etc/ep11client se ele não existir. Como alternativa, é possível configurar a variável de ambiente EP11CLIENT_CFG para o caminho completo e o nome do arquivo de configuração. Fazendo isso, você não está restrito ao nome grep11client do arquivo yaml. Exemplo: export EP11CLIENT_CFG=/home/user/pkcs11-config.yaml

Etapa 4: usar a biblioteca PKCS n.º 11 para fazer chamadas de API PKCS n.º 11

Depois de configurar a biblioteca e o arquivo de configuração, os keystores devem ser inicializados. Para inicializar os keystores, o usuário responsável pela segurança (SO) precisa executar uma operação C_InitToken.

Após os keystores serem inicializados, use a biblioteca do PKCS n° 11 para chamar as funções padrão do PKCS n° 11 para gerar, armazenar e listar chaves. Para obter a lista detalhada de funções suportadas do PKCS n.º 11, consulte Referência de API PKCS n.º 11.

Dependendo dos recursos e dos requisitos de segurança de seu aplicativo, transmita as diferentes chaves de API do ID de serviço que você criou na etapa de pré-requisitos anterior de modo que seus aplicativos possam executar as operações correspondentes. Por exemplo, se o seu aplicativo precisa excluir um keystore, forneça a chave de API do usuário do SO. Se o seu aplicativo precisa acessar o keystore privado para armazenar novas chaves, é necessário fornecer a chave de API do usuário normal. Para obter mais informações sobre o gerenciamento de acesso de usuário para a API PKCS n.º 11, consulte Melhores práticas para configurar os tipos de usuário do PKCS n.º 11.

Se você estiver executando um aplicativo Java PKCS #11 usando o provedor SunPKCS11 na plataforma IBM Z (s390x), certise-se de usar a mais recente JVM IBM Semeru e especificar a opção -Xjit:noResumableTrapHandler Java ao iniciar sua aplicação. Você pode baixar a versão mais recente do s390x da JVM do IBM Semeru alterando o campo de filtro Architecture para s390x na página IBM Semeru Runtime Downloads.

O que vem a seguir