As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Usando o Client SDK 5 para trabalhar com AWS CloudHSM
AWS CloudHSM inclui duas versões principais do SDK do cliente:
+ Client SDK 5: este é o nosso SDK de cliente padrão e mais recente. Para obter informações sobre os benefícios e vantagens que ela oferece, consulte [Benefícios do AWS CloudHSM Client SDK 5](client-sdk-5-benefits.md).
+ Client SDK 3: este é o nosso SDK do cliente mais antigo. Ele inclui um conjunto completo de componentes para ferramentas de gerenciamento e compatibilidade de aplicativos baseados em plataformas e linguagens.
Para obter instruções sobre como migrar do Client SDK 3 para o Client SDK 5, consulte [Migração do SDK do AWS CloudHSM cliente 3 para o SDK do cliente 5](client-sdk-migration.md).
Este tópico descreve o Client SDK 5. Para verificar qual versão do Client SDK você está usando, consulte
**Topics**
+ [Benefícios do AWS CloudHSM Client SDK 5](client-sdk-5-benefits.md)
+ [AWS CloudHSM Plataformas compatíveis com o Client SDK 5](client-supported-platforms.md)
+ [Biblioteca PKCS \$111 para AWS CloudHSM Client SDK 5](pkcs11-library.md)
+ [Mecanismo AWS CloudHSM dinâmico OpenSSL para cliente SDK 5](openssl-library.md)
+ [Provedor AWS CloudHSM de OpenSSL para cliente SDK 5](openssl-provider-library.md)
+ [Provedor de armazenamento de chaves (KSP) para o AWS CloudHSM Client SDK 5](ksp-library.md)
+ [Provedor de JCE para AWS CloudHSM Client SDK 5](java-library.md)
# Benefícios do AWS CloudHSM Client SDK 5
Comparado ao AWS CloudHSM Client SDK 3, o Client SDK 5 é mais fácil de gerenciar, oferece maior configurabilidade e maior confiabilidade. O Client SDK 5 também oferece algumas vantagens importantes além das proporcionadas pelo Client SDK 3.
**Projetado para arquitetura com tecnologia sem servidor**
O Client SDK 5 não exige um daemon de cliente, então você não precisa mais gerenciar um serviço em segundo plano. Isso ajuda os usuários de algumas maneiras importantes:
+ Simplifica o processo de startup do aplicativo. Tudo o que você precisa fazer para começar a usar o CloudHSM é configurar o SDK antes de executar seu aplicativo.
+ Você não precisa de um processo em execução constante, o que facilita a integração com componentes com tecnologia sem servidor, como Lambda e Elastic Container Service (ECS – serviço de contêiner elástico).
**Melhores integrações de terceiros e portabilidade simplificada**
O Client SDK 5 segue de perto a especificação JCE e fornece portabilidade mais fácil entre diferentes provedores de JCE e melhores integrações de terceiros
**Experiência de usuário e capacidade de configuração aprimoradas**
O Client SDK 5 melhora a legibilidade das mensagens de log e fornece exceções e mecanismos de tratamento de erros mais claros, o que torna a triagem de autoatendimento muito mais fácil para os usuários. O SDK 5 também oferece uma variedade de configurações, que estão listadas na [página Configurar ferramenta](https://docs.aws.amazon.com/cloudhsm/latest/userguide/configure-sdk-5.html).
**Suporte mais amplo à plataforma**
O Client SDK 5 oferece mais suporte para plataformas operacionais modernas. Isso inclui suporte para tecnologias ARM e maior compatibilidade com [JCE](https://docs.aws.amazon.com/cloudhsm/latest/userguide/java-library_5.html), [PKCS \$111](https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library.html) e [OpenSSL](https://docs.aws.amazon.com/cloudhsm/latest/userguide/openssl-library.html). Para obter mais informações, consulte [Plataformas compatíveis](client-supported-platforms.md).
**IPv6 suporte de conexão**
O Client SDK 5.14\$1 suporta conexões com o uso de pilha dupla. HSMs IPv6
**Atributos e mecanismos adicionais**
O Client SDK 5 inclui atributos e mecanismos adicionais que não estão disponíveis no Client SDK 3 e o Client SDK 5 continuará adicionando mais mecanismos no futuro.
# AWS CloudHSM Plataformas compatíveis com o Client SDK 5
O suporte básico é diferente para cada versão do SDK AWS CloudHSM do cliente. O suporte de plataforma para componentes em um SDK normalmente, mas nem sempre, corresponde ao suporte básico. Para determinar o suporte à plataforma para um componente específico, primeiro certifique-se de que a plataforma desejada apareça na seção base do SDK e, em seguida, verifique se há exclusões ou qualquer outra informação pertinente na seção de componentes.
AWS CloudHSM suporta somente sistemas operacionais de 64 bits.
O suporte da plataforma muda com o tempo. Versões anteriores do Client SDK do CloudHSM podem não ser compatíveis com todos os sistemas operacionais listados aqui. Use as notas de versão para determinar o suporte do sistema operacional para versões anteriores do Client SDK do CloudHSM. Para obter mais informações, consulte [Downloads para o SDK AWS CloudHSM do cliente](client-history.md).
Para ver as plataformas compatíveis com o Client SDK anterior, consulte [AWS CloudHSM Plataformas compatíveis com o Client SDK 3](sdk3-support.md)
O Client SDK 5 não exige um daemon de cliente.
**Topics**
+ [Suporte no Linux para o Client SDK 5 do](sdk8-linux.md)
+ [Suporte no Windows para o Client SDK 5 do](sdk8-windows.md)
+ [Suporte sem servidor para o Client SDK 5 do](sdk8-serverless.md)
+ [Compatibilidade com HSM para o Client SDK 5 do](sdk5-hsm-types.md)
# Suporte Linux para o AWS CloudHSM Client SDK 5
AWS CloudHSM O Client SDK 5 é compatível com os seguintes sistemas operacionais e plataformas Linux.
| Plataformas compatíveis | Arquitetura X86\$164 | Arquitetura ARM |
| --- | --- | --- |
| Amazon Linux 2 | Sim | Sim |
| Amazon Linux 2023 | Sim | Sim |
| Red Hat Enterprise Linux 8 (8.3\$1) | Sim | Sim |
| Red Hat Enterprise Linux 9 (9.2\$1) | Sim | Sim |
| Red Hat Enterprise Linux 10 (10.0\$1) | Sim | Sim |
| Ubuntu 22.04 LTS | Sim | Sim |
| Ubuntu 24.04 LTS | Sim | Sim |
+ O SDK 5.16 foi a última versão a fornecer suporte à plataforma Ubuntu 20.04 LTS. Para obter mais informações, consulte o [site do Ubuntu](https://ubuntu.com/blog/ubuntu-20-04-lts-end-of-life-standard-support-is-coming-to-an-end-heres-how-to-prepare).
+ O SDK 5.12 foi a última versão a fornecer suporte à plataforma CentOS 7 (7.8\$1). Para obter mais informações, consulte o [site do CentOS](https://blog.centos.org/2023/04/end-dates-are-coming-for-centos-stream-8-and-centos-linux-7/).
+ O SDK 5.12 foi a última versão a fornecer suporte à plataforma Red Hat Enterprise Linux 7 (7.8\$1). Para obter mais informações, acesse o [site do Red Hat](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux/rhel-7-end-of-maintenance).
+ O SDK 5.4.2 foi a última versão a fornecer suporte à plataforma CentOS 8. Para obter mais informações, consulte o [site do CentOS](https://www.centos.org/centos-linux-eol/).
# Suporte do Windows para o AWS CloudHSM Client SDK 5
AWS CloudHSM O Client SDK 5 oferece suporte às seguintes versões do Windows Server.
+ Microsoft Windows Server 2016
+ Microsoft Windows Server 2019
+ Microsoft Windows Server 2022
+ Microsoft Windows Server 2025
# Suporte sem servidor para o AWS CloudHSM Client SDK 5
AWS CloudHSM O Client SDK 5 oferece suporte aos seguintes AWS serviços sem servidor.
+ AWS Lambda
+ Docker/ECS
# Compatibilidade com HSM para o AWS CloudHSM Client SDK 5
A tabela a seguir descreve a compatibilidade AWS CloudHSM do Client SDK 5 para HSMs.
| hsm1.medium | hsm2m.medium |
| --- | --- |
| Compatível com o Client SDK versão 5.0.0 e posteriores. | Compatível com o SDK do cliente versão 5.9.0 e posterior. |
# Biblioteca PKCS \$111 para AWS CloudHSM Client SDK 5
O PKCS \$111 é um padrão para realizar operações criptográficas em módulos de segurança de hardware ()HSMs. AWS CloudHSM oferece implementações da biblioteca PKCS \$111 que são compatíveis com a versão 2.40 do PKCS \$111.
Para obter informações sobre bootstrapping, consulte [Conectar-se ao cluster](cluster-connect.md). Para solução de problemas, consulte [Problemas conhecidos da biblioteca PKCS \$111 para AWS CloudHSMProblemas conhecidos da biblioteca do PKCS\$111](ki-pkcs11-sdk.md).
Para obter mais informações sobre como usar Client SDK 3, consulte [Usando a versão anterior do SDK para trabalhar com AWS CloudHSM](choose-client-sdk.md).
**Topics**
+ [Instalar a biblioteca PKCS \$111](pkcs11-library-install.md)
+ [Autenticar na biblioteca PKCS \$111](pkcs11-pin.md)
+ [Tipos de chave](pkcs11-key-types.md)
+ [Mecanismos](pkcs11-mechanisms.md)
+ [Operações de API](pkcs11-apis.md)
+ [Atributos de chaves](pkcs11-attributes.md)
+ [Exemplos de código](pkcs11-samples.md)
+ [Configurações avançadas](pkcs11-library-configs.md)
+ [Armazenamento de certificados](pkcs11-certificate-storage.md)
# Instale a biblioteca PKCS \$111 para o AWS CloudHSM Client SDK 5
Este tópico fornece instruções para instalar a versão mais recente da biblioteca PKCS \$111 para a série de versões do Client SDK 5 do AWS CloudHSM . Para obter mais informações sobre a biblioteca Client SDK ou do PKCS \$111, consulte [Usando a biblioteca Client SDK](use-hsm.md) e [ PKCS \$111](pkcs11-library.md).
Com o Client SDK 5, você não precisa instalar ou executar um daemon de cliente.
Para executar um único cluster HSM com o Client SDK 5, você deve primeiro gerenciar as configurações de durabilidade da chave do cliente configurando `disable_key_availability_check` como `True`. Para obter mais informações, consulte [Sincronização de chave](manage-key-sync.md) e a [ferramenta de configuração do Client SDK 5](configure-sdk-5.md).
Para obter mais informações sobre a biblioteca PKCS \$111SDK do Client SDK 5, consulte [biblioteca PKCS \$111](pkcs11-library.md).
**nota**
Para executar um único cluster HSM com o Client SDK 5, você deve primeiro gerenciar as configurações de durabilidade da chave do cliente configurando `disable_key_availability_check` como `True`. Para obter mais informações, consulte [Sincronização de chave](manage-key-sync.md) e a [ferramenta de configuração do Client SDK 5](configure-sdk-5.md).
**Para instalar e configurar a biblioteca PKCS \$111**
1. Use os seguintes comandos para fazer download e instalar a biblioteca PKCS \$111.
------
#### [ Amazon Linux 2023 ]
Instale a biblioteca PKCS \$111 para o Amazon Linux 2023 na arquitetura X86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-pkcs11-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.amzn2023.x86_64.rpm
```
Instale a biblioteca PKCS \$111 para Amazon Linux 2023 na ARM64 arquitetura:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-pkcs11-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.amzn2023.aarch64.rpm
```
------
#### [ Amazon Linux 2 ]
Instale a biblioteca PKCS \$111 para Amazon Linux 2 na arquitetura X86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-pkcs11-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el7.x86_64.rpm
```
Instale a biblioteca PKCS \$111 para Amazon Linux 2 na ARM64 arquitetura:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-pkcs11-latest.el7.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el7.aarch64.rpm
```
------
#### [ RHEL 10 (10.0\$1) ]
Instale a biblioteca PKCS \$111 para RHEL 10 na arquitetura X86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-pkcs11-latest.el10.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el10.x86_64.rpm
```
Instale a biblioteca PKCS \$111 para RHEL 10 na ARM64 arquitetura:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-pkcs11-latest.el10.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el10.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
Instale a biblioteca PKCS \$111 para RHEL 9 na arquitetura X86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-pkcs11-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el9.x86_64.rpm
```
Instale a biblioteca PKCS \$111 para RHEL 9 na ARM64 arquitetura:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-pkcs11-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el9.aarch64.rpm
```
------
#### [ RHEL 8 (8.3\$1) ]
Instale a biblioteca PKCS \$111 para RHEL 8 na arquitetura X86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-pkcs11-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el8.x86_64.rpm
```
Instale a biblioteca PKCS \$111 para RHEL 8 na ARM64 arquitetura:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-pkcs11-latest.el8.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el8.aarch64.rpm
```
------
#### [ Ubuntu 24.04 LTS ]
Instale a biblioteca PKCS \$111 para Ubuntu 24.04 LTS na arquitetura X86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-pkcs11_latest_u24.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u24.04_amd64.deb
```
Instale a biblioteca PKCS \$111 para Ubuntu 24.04 LTS na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-pkcs11_latest_u24.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u24.04_arm64.deb
```
------
#### [ Ubuntu 22.04 LTS ]
Instale a biblioteca PKCS \$111 para Ubuntu 22.04 LTS na arquitetura X86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-pkcs11_latest_u22.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u22.04_amd64.deb
```
Instale a biblioteca PKCS \$111 para o Ubuntu 22.04 LTS na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-pkcs11_latest_u22.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u22.04_arm64.deb
```
------
#### [ Windows Server ]
Instale a biblioteca PKCS \$111 para Windows Server na arquitetura X86\$164:
1. Faça o download da [biblioteca PKCS \$111 para Client SDK 5](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMPKCS11-latest.msi).
1. Execute o instalador da biblioteca PKCS \$111 (**AWSCloudHSMPKCS11-latest.msi**) com privilégios administrativos do Windows.
------
1. Use a ferramenta de configuração para especificar um local para o certificado de emissão. Para instruções, consulte [Especifique o local do certificado de emissão.](cluster-connect.md#specify-cert-location).
1. Para se conectar e usar o cluster [Bootstrap o Client SDK](cluster-connect.md#connect-how-to).
1. Você pode encontrar os arquivos da biblioteca do PKCS \$111 nos seguintes locais:
+ Binários, scripts de configuração e arquivos de log do Linux:
```
/opt/cloudhsm
```
Binários do Windows:
```
C:\Program Files\Amazon\CloudHSM
```
Scripts de configuração e arquivos de log do Windows:
```
C:\ProgramData\Amazon\CloudHSM
```
# Autentique-se na biblioteca PKCS \$111 do AWS CloudHSM Client SDK 5
Quando você usa a biblioteca PKCS \$111, seu aplicativo é executado como um [usuário criptográfico (UC)](manage-hsm-users.md) específico em seu HSMs in. AWS CloudHSM O aplicativo pode visualizar e gerenciar apenas as chaves que o CU possui e compartilha. Você pode usar uma UC existente em seu aplicativo HSMs ou criar uma nova UC para seu aplicativo. Para obter informações sobre gerenciamento CUs, consulte [Gerenciando usuários do HSM com o CloudHSM CLI e [Gerenciando usuários do HSM com o CloudHSM](manage-hsm-users-cmu.md)](manage-hsm-users-chsm-cli.md) Management Utility (CMU)
Para especificar o CU para a biblioteca PKCS \$111, use o parâmetro do PIN da [função C\$1Login](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html#_Toc385057915) do PKCS \$111. Para AWS CloudHSM, o parâmetro pin tem o seguinte formato:
```
:
```
Por exemplo, o seguinte comando define o PIN de PKCS \$111 como o CU com nome de usuário `CryptoUser` e senha `CUPassword123!`.
```
CryptoUser:CUPassword123!
```
# Tipos de chave compatíveis com a biblioteca PKCS \$111 para o AWS CloudHSM Client SDK 5
A biblioteca PKCS \$111 para AWS CloudHSM Client SDK 5 é compatível com os seguintes tipos de chave.
****
| Tipo de chave | Description |
| --- | --- |
| AES | Gere chaves AES de 128, 192 e 256 bits. |
| DES triplo (3DES, DESede) | Gere chaves DES triplas de 192 bits. Consulte a nota [1](#key-types-1) abaixo para ver uma mudança futura. |
| EC | Gera chaves com as curvas secp224r1 (P-224), secp256r1 (P-256), secp256k1 (Blockchain), secp384r1 (P-384) e secp521r1 (P-521). |
| GENERIC\$1SECRET | Gerar chaves genéricas de 1 a 800 bytes. |
| RSA | Gera chaves RSA de 2.048 a 4.096 bits, em incrementos de 256 bits. |
[1] De acordo com a orientação do NIST, isso não é permitido em clusters no modo FIPS após 2023. Para clusters no modo não FIPS, isso ainda é permitido após 2023. Para mais detalhes, consulte [Conformidade com o FIPS 140: suspensão do mecanismo de 2024](compliance-dep-notif.md#compliance-dep-notif-1).
# Mecanismos compatíveis com a biblioteca PKCS \$111 para o AWS CloudHSM Client SDK 5
A biblioteca PKCS \$111 é compatível com a versão 2.40 da especificação PKCS \$111. Para invocar um recurso de criptografia usando o PKCS\$111, chame uma função com um determinado mecanismo. As seções a seguir resumem as combinações de funções e mecanismos compatíveis com o AWS CloudHSM Client SDK 5.
A biblioteca de software do para PKCS \$111 oferece suporte aos seguintes algoritmos:
+ **Criptografia e descriptografia** — AES-CBC, AES-CTR, AES-ECB, AES-GCM, -CBC, -ECB, RSA-OAEP e RSA-PKCS DES3 DES3
+ **Assinar e verificar**: RSA, HMAC e ECDSA; com e sem hash
+ **Hash/digest** — SHA1,, SHA224, e SHA256 SHA384 SHA512
+ **Encapsulamento de chave**: AES Key Wrap[1](#mech1), AES-GCM, RSA-AES e RSA-OAEP
+ **Derivação de chave** — SP800 -108 Counter KDF e ECDH com KDF (os algoritmos KDF suportados são X9.63 com,,,) SHA1 SHA224 SHA256 SHA384 SHA512
**Topics**
+ [Gere funções de chave e par de chaves](#pkcs11-mech-function-genkey)
+ [Funções de assinatura e verificação](#pkcs11-mech-function-signverify)
+ [Assine, recupere e verifique as funções de recuperação](#pkcs11-mech-function-sr-vr)
+ [Funções de resumo](#pkcs11-mech-function-digest)
+ [Funções de criptografia e descriptografia](#pkcs11-mech-function-enc-dec)
+ [Derivar funções de chave](#pkcs11-mech-function-derive-key)
+ [Funções de agrupamento e desagrupamento](#pkcs11-mech-function-wrap-unwrap)
+ [Tamanho máximo de dados para cada mecanismo](#pkcs11-mech-max)
+ [Anotações do mecanismo](#pkcs11-mech-annotations)
## Gere funções de chave e par de chaves
A biblioteca AWS CloudHSM de software da biblioteca PKCS \$111 permite que você use os seguintes mecanismos para as funções Generate Key e Key Pair.
+ `CKM_RSA_PKCS_KEY_PAIR_GEN`
+ `CKM_RSA_X9_31_KEY_PAIR_GEN`: esse mecanismo é funcionalmente idêntico ao mecanismo `CKM_RSA_PKCS_KEY_PAIR_GEN`, mas oferece maiores garantias para geração de `p` e de `q`.
+ `CKM_EC_KEY_PAIR_GEN`
+ `CKM_GENERIC_SECRET_KEY_GEN`
+ `CKM_AES_KEY_GEN`
+ `CKM_DES3_KEY_GEN`: próxima mudança listada na nota de rodapé [5](#mech5).
## Funções de assinatura e verificação
A biblioteca AWS CloudHSM de software da biblioteca PKCS \$111 permite que você use os seguintes mecanismos para as funções de assinatura e verificação. Com o Client SDK 5, os dados são codificados localmente no software. Isso significa que não há limite no tamanho dos dados que podem ser criptografados pelo SDK.
Com o Client SDK 5, o hashing RSA e ECDSA é feito localmente; portanto, não há limite de dados. Com o HMAC, há um limite de dados. Consulte a nota de rodapé [2](#mech2) para obter mais informações.
**RSA**
+ `CKM_RSA_X_509`
+ `CKM_RSA_PKCS`: somente operações de uma única parte.
+ `CKM_RSA_PKCS_PSS`: somente operações de uma única parte.
+ `CKM_SHA1_RSA_PKCS`
+ `CKM_SHA224_RSA_PKCS`
+ `CKM_SHA256_RSA_PKCS`
+ `CKM_SHA384_RSA_PKCS`
+ `CKM_SHA512_RSA_PKCS`
+ `CKM_SHA512_RSA_PKCS`
+ `CKM_SHA1_RSA_PKCS_PSS`
+ `CKM_SHA224_RSA_PKCS_PSS`
+ `CKM_SHA256_RSA_PKCS_PSS`
+ `CKM_SHA384_RSA_PKCS_PSS`
+ `CKM_SHA512_RSA_PKCS_PSS`
**ECDSA**
+ `CKM_ECDSA`: somente operações de uma única parte.
+ `CKM_ECDSA_SHA1`
+ `CKM_ECDSA_SHA224`
+ `CKM_ECDSA_SHA256`
+ `CKM_ECDSA_SHA384`
+ `CKM_ECDSA_SHA512`
**HMAC**
+ `CKM_SHA_1_HMAC`[2](#mech2)
+ `CKM_SHA224_HMAC`[2](#mech2)
+ `CKM_SHA256_HMAC`[2](#mech2)
+ `CKM_SHA384_HMAC`[2](#mech2)
+ `CKM_SHA512_HMAC`[2](#mech2)
**CMAC**
+ `CKM_AES_CMAC`
## Assine, recupere e verifique as funções de recuperação
O Client SDK 5 não oferece suporte às funções Sign Recover (recuperação de assinatura) e Verify Recover (verificar recuperação).
## Funções de resumo
A biblioteca AWS CloudHSM de software da biblioteca PKCS \$111 permite que você use os seguintes mecanismos para funções Digest. Com o Client SDK 5, os dados são codificados localmente no software. Isso significa que não há limite no tamanho dos dados que podem ser criptografados pelo SDK.
+ `CKM_SHA_1`
+ `CKM_SHA224`
+ `CKM_SHA256`
+ `CKM_SHA384`
+ `CKM_SHA512`
## Funções de criptografia e descriptografia
A biblioteca AWS CloudHSM de software da biblioteca PKCS \$111 permite que você use os seguintes mecanismos para as funções Encrypt e Decrypt.
+ `CKM_RSA_X_509`
+ `CKM_RSA_PKCS`: somente operações de uma única parte. Próxima mudança listada na nota de rodapé [5](#mech5).
+ `CKM_RSA_PKCS_OAEP`: somente operações de uma única parte.
+ `CKM_AES_ECB`
+ `CKM_AES_CTR`
+ `CKM_AES_CBC`
+ `CKM_AES_CBC_PAD`
+ `CKM_DES3_CBC`: próxima mudança listada na nota de rodapé [5](#mech5).
+ `CKM_DES3_ECB`: próxima mudança listada na nota de rodapé [5](#mech5).
+ `CKM_DES3_CBC_PAD`: próxima mudança listada na nota de rodapé [5](#mech5).
+ `CKM_AES_GCM` [1](#mech1), [2](#mech2)
+ `CKM_CLOUDHSM_AES_GCM`[3](#mech3)
## Derivar funções de chave
A biblioteca AWS CloudHSM de software para a biblioteca PKCS \$111 suporta os seguintes mecanismos de derivação de chaves:
+ `CKM_SP800_108_COUNTER_KDF`
+ `CKM_ECDH1_DERIVE`: é compatível com derivação de chave ECDH com os seguintes tipos de KDF definidos pelo fornecedor: [6](#kdf6)
+ `CKD_CLOUDHSM_X963_SHA1_KDF`- X9.63 KDF com SHA1 [7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA224_KDF`- X9.63 KDF com SHA224 [7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA256_KDF`- X9.63 KDF com SHA256 [7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA384_KDF`- X9.63 KDF com SHA384 [7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA512_KDF`- X9.63 KDF com SHA512 [7](#kdf7)
## Funções de agrupamento e desagrupamento
A biblioteca AWS CloudHSM de software da biblioteca PKCS \$111 permite que você use os seguintes mecanismos para as funções Wrap e Unwrap.
Para obter opções adicionais de empacotamento de chaves AES, consulte [Empacotamento de chaves AES](manage-aes-key-wrapping.md).
+ `CKM_RSA_PKCS`: somente operações de uma única parte. Uma nova mudança futura listada na nota de rodapé [5](#mech5).
+ `CKM_RSA_PKCS_OAEP`[4](#mech4)
+ `CKM_AES_GCM`[1](#mech1), [3](#mech3)
+ `CKM_CLOUDHSM_AES_GCM`[3](#mech3)
+ `CKM_RSA_AES_KEY_WRAP`
+ `CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD`[3](#mech3)
+ `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD`[3](#mech3)
+ `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD`[3](#mech3)
## Tamanho máximo de dados para cada mecanismo
A tabela a seguir lista o tamanho máximo de dados definido para cada mecanismo:
**Tamanho máximo do conjunto de dados**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/pkcs11-mechanisms.html)
## Anotações do mecanismo
+ [1] Ao executar a criptografia AES-GCM, o HSM não aceitará dados do vetor de inicialização (IV) do aplicativo. Você deve usar um IV gerado por ele. O IV de 12 bytes fornecido pelo HSM é gravado na referência da memória apontada pelo elemento pIV da estrutura de parâmetros `CK_GCM_PARAMS` que você fornece. Para que não haja confusão para o usuário, o SDK do PKCS \$111 na versão 1.1.1 e posterior, garante que o pIV aponte para um buffer zerado quando a criptografia AES-GCM é inicializada.
+ [2] Ao trabalhar com dados usando qualquer um dos mecanismos a seguir, se o buffer de dados exceder o tamanho máximo de dados, a operação resultará em um erro. Para esses mecanismos, todo o processamento de dados deve ocorrer dentro do HSM. Para obter informações sobre conjuntos de tamanho máximo de dados para cada mecanismo, consulte [Tamanho máximo de dados para cada mecanismo](#pkcs11-mech-max).
+ [3] Mecanismo definido pelo fornecedor. Para usar os mecanismos definidos pelo fornecedor do CloudHSM, os aplicativos PKCS \$111 devem incluir `/opt/cloudhsm/include/pkcs11/pkcs11t.h` durante a compilação.
`CKM_CLOUDHSM_AES_GCM`: Este mecanismo proprietário é uma alternativa programaticamente mais segura para o padrão `CKM_AES_GCM`. Ele antecede o IV gerado pelo HSM para o texto cifrado em vez de escrevê-lo de volta na estrutura `CK_GCM_PARAMS` fornecida durante a inicialização da cifra. Você pode usar esse mecanismo com as funções `C_Encrypt`, `C_WrapKey`, `C_Decrypt`, e `C_UnwrapKey`. Ao usar esse mecanismo, a variável pIV no struct `CK_GCM_PARAMS` deve ser definida como `NULL`. Ao usar este mecanismo com `C_Decrypt` e `C_UnwrapKey`, espera-se que o IV seja precedido pelo texto cifrado que está sendo desencapsulado.
`CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD`: Agrupamento de chaves AES com preenchimento PKCS \$15.
`CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD`: Agrupamento de chaves AES com preenchimento de zeros.
+ [4] Os seguintes `CK_MECHANISM_TYPE` e `CK_RSA_PKCS_MGF_TYPE` são compatíveis como `CK_RSA_PKCS_OAEP_PARAMS` para `CKM_RSA_PKCS_OAEP`:
+ `CKM_SHA_1` usando `CKG_MGF1_SHA1`
+ `CKM_SHA224` usando `CKG_MGF1_SHA224`
+ `CKM_SHA256` usando `CKG_MGF1_SHA256`
+ `CKM_SHA384` usando `CKM_MGF1_SHA384`
+ `CKM_SHA512` usando `CKM_MGF1_SHA512`
+ [5] De acordo com a orientação do NIST, isso não é permitido em clusters no modo FIPS após 2023. Para clusters no modo não FIPS, isso ainda é permitido após 2023. Para mais detalhes, consulte [Conformidade com o FIPS 140: suspensão do mecanismo de 2024](compliance-dep-notif.md#compliance-dep-notif-1).
+ [6] Tipos definidos pelo fornecedor. Para usar os tipos definidos pelo fornecedor do CloudHSM, as aplicação PKCS \$111 devem incluir `cloudhsm_pkcs11_vendor_defs.h` durante a compilação. Isso pode ser localizado em `/opt/cloudhsm/include/pkcs11/cloudhsm_pkcs11_vendor_defs.h` para plataformas baseadas em Linux e em `C:\Program Files\Amazon\CloudHSM\include\pkcs11\cloudhsm_pkcs11_vendor_defs.h` para plataformas baseadas no Windows
+ [7] As principais funções de derivação (KDFs) estão especificadas na [Publicação Especial 800-56A do NIST](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf), Revisão 3.
# Operações de API suportadas para a biblioteca PKCS \$111 para AWS CloudHSM Client SDK 5
A biblioteca PKCS \$111 oferece suporte às seguintes operações de API PKCS \$111 para o AWS CloudHSM Client SDK 5.
+ `C_CloseAllSessions`
+ `C_CloseSession`
+ `C_CreateObject`
+ `C_Decrypt`
+ `C_DecryptFinal`
+ `C_DecryptInit`
+ `C_DecryptUpdate`
+ `C_DeriveKey`
+ `C_DestroyObject`
+ `C_Digest`
+ `C_DigestFinal`
+ `C_DigestInit`
+ `C_DigestUpdate`
+ `C_Encrypt`
+ `C_EncryptFinal`
+ `C_EncryptInit`
+ `C_EncryptUpdate`
+ `C_Finalize`
+ `C_FindObjects`
+ `C_FindObjectsFinal`
+ `C_FindObjectsInit`
+ `C_GenerateKey`
+ `C_GenerateKeyPair`
+ `C_GenerateRandom`
+ `C_GetAttributeValue`
+ `C_GetFunctionList`
+ `C_GetInfo`
+ `C_GetMechanismInfo`
+ `C_GetMechanismList`
+ `C_GetSessionInfo`
+ `C_GetSlotInfo`
+ `C_GetSlotList`
+ `C_GetTokenInfo`
+ `C_Initialize`
+ `C_Login`
+ `C_Logout`
+ `C_OpenSession`
+ `C_Sign`
+ `C_SignFinal`
+ `C_SignInit`
+ `C_SignUpdate`
+ `C_UnWrapKey`
+ `C_Verify`
+ `C_VerifyFinal`
+ `C_VerifyInit`
+ `C_VerifyUpdate`
+ `C_WrapKey`
# Atributos principais na biblioteca PKCS \$111 para o AWS CloudHSM Client SDK 5
Um objeto AWS CloudHSM chave pode ser uma chave pública, privada ou secreta. As ações permitidas em um objeto de chave são especificadas por meio de atributos. Os atributos são definidos quando o objeto de chave é criado. Quando você usa a biblioteca PKCS \$111 para AWS CloudHSM, atribuímos valores padrão conforme especificado pelo padrão PKCS \$111.
AWS CloudHSM não suporta todos os atributos listados na especificação PKCS \$111. Estamos em conformidade com a especificação de todos os atributos aos quais oferecemos suporte. Esses atributos estão listados nas respectivas tabelas.
Funções criptográficas como `C_CreateObject`, `C_GenerateKey`, `C_GenerateKeyPair`, `C_UnwrapKey`, e `C_DeriveKey` que criam, modificam ou copiam objetos usam um modelo de atributo como um de seus parâmetros. Para obter mais informações sobre como passar um modelo de atributo durante a criação do objeto, consulte o exemplo para [Gerar chaves por meio da biblioteca PKCS \$111](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/generate).
Os tópicos a seguir fornecem mais informações sobre os AWS CloudHSM principais atributos.
**Topics**
+ [Tabelas de atributos](pkcs11-attributes-interpreting.md)
+ [Modificar atributos](modify-attr.md)
+ [Interpretar códigos de erro](attr-errors.md)
# Tabelas de atributos da biblioteca PKCS \$111 para o AWS CloudHSM Client SDK 5
As tabelas da biblioteca PKCS \$111 AWS CloudHSM contêm uma lista de atributos que diferem por tipo de chave. Ele indica se um determinado atributo é compatível com um determinado tipo de chave ao usar uma função criptográfica específica com AWS CloudHSM.
**Legenda:**
+ ✔ indica que o CloudHSM oferece suporte ao atributo para o tipo de chave específico.
+ ✖ indica que o CloudHSM não oferece suporte ao atributo para o tipo de chave específico.
+ R indica que o valor do atributo é definido como somente leitura para o tipo de chave específico.
+ S indica que o atributo não pode ser lido pelo `GetAttributeValue` pois ele é confidencial.
+ Uma célula vazia na coluna Valor padrão indica que não há nenhum valor padrão específico atribuído ao atributo.
## GenerateKeyPair
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## GenerateKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## CreateObject
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## UnwrapKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## DeriveKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## GetAttributeValue
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
**Anotações de atributos**
+ [1] Este atributo tem suporte parcial do firmware e deve ser explicitamente definido apenas como o valor padrão.
+ [2] Atributo obrigatório.
# Modificando atributos da biblioteca PKCS \$111 para o AWS CloudHSM Client SDK 5
Alguns atributos da biblioteca PKCS \$111 de um AWS CloudHSM objeto podem ser modificados após a criação do objeto, enquanto outros não. Para modificar atributos, use o comando [key set-attribute](cloudhsm_cli-key-set-attribute.md) da CloudHSM CLI. Você também pode derivar uma lista de atributos usando o comando [key list](cloudhsm_cli-key-list.md) da CloudHSM CLI.
A lista a seguir exibe os atributos cuja modificação é permitida após a criação do objeto:
+ `CKA_LABEL`
+ `CKA_TOKEN`
**nota**
A modificação é permitida somente para alterar uma chave de sessão para uma chave de token. Use o comando [key set-attribute](cloudhsm_cli-key-set-attribute.md) da CloudHSM CLI para alterar o valor do atributo.
+ `CKA_ENCRYPT`
+ `CKA_DECRYPT`
+ `CKA_SIGN`
+ `CKA_VERIFY`
+ `CKA_WRAP`
+ `CKA_UNWRAP`
+ `CKA_LABEL`
+ `CKA_SENSITIVE`
+ `CKA_DERIVE`
**nota**
Esse atributo oferece suporte à derivação de chaves. Ele deve ser `False` para todas as chaves públicas e não pode ser definido como `True`. Para chaves privadas EC e secretas, ele pode ser definido como `True` ou `False`.
+ `CKA_TRUSTED`
**nota**
Esse atributo pode ser definido como `True` ou `False` somente pelo Responsável pela criptografia (CO)
+ `CKA_WRAP_WITH_TRUSTED`
**nota**
Aplique esse atributo a uma chave de dados exportável para especificar que você só pode agrupar essa chave com chaves marcadas como `CKA_TRUSTED`. Depois que `CKA_WRAP_WITH_TRUSTED` for definido como verdadeiro, o atributo se torna somente para leitura e não é possível alterar ou remover o atributo.
# Interpretação dos códigos de erro da biblioteca PKCS \$111 para o AWS CloudHSM Client SDK 5
Especificar no modelo um atributo da biblioteca PKCS \$111 que não tenha suporte de uma chave específica resultará em um erro. A tabela a seguir contém códigos de erro que são gerados quando as especificações são violadas:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/attr-errors.html)
# Exemplos de código para a biblioteca PKCS \$111 para o AWS CloudHSM Client SDK 5
Os exemplos de código mostrados GitHub mostram como realizar tarefas básicas usando a biblioteca PKCS \$111 para o AWS CloudHSM Client SDK 5.
## Pré-requisitos
Antes de executar os exemplos, realize as seguintes etapas para configurar o ambiente:
+ Instale e configure a [biblioteca PKCS \$111](pkcs11-library-install.md) para o Client SDK 5.
+ Configure um [usuário de criptografia (CU)](manage-hsm-users.md). Seu aplicativo usa essa conta do HSM para executar as amostras de código no HSM.
## Exemplos de código
Exemplos de código para a biblioteca AWS CloudHSM de software para PKCS \$111 estão disponíveis em [GitHub](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples). Este repositório inclui exemplos de como fazer operações comuns usando PKCS \$111, incluindo criptografia, descriptografia, assinatura e verificação.
+ [Gerar chaves (AES, RSA, EC)](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/generate)
+ [Listar atributos de chave](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/attributes/)
+ [Criptografar e descriptografar dados com AES-GCM](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/encrypt/aes_gcm.c)
+ [Encrypt and decrypt data with AES\$1CTR](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/encrypt/aes_ctr.c)
+ [Encrypt and decrypt data with 3DES](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/encrypt/des_ecb.c)
+ [Assinar e verificar dados com RSA](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/sign/rsa_sign.c)
+ [Derive keys using HMAC KDF](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/derivation/hmac_kdf.c)
+ [Wrap and unwrap keys with AES using PKCS \$15 padding](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/aes_wrapping.c)
+ [Wrap and unwrap keys with AES using no padding](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/aes_no_padding_wrapping.c)
+ [Wrap and unwrap keys with AES using zero padding](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/aes_zero_padding_wrapping.c)
+ [Wrap and unwrap keys with AES-GCM](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/wrapping/aes_gcm_wrapping.c)
+ [Encapsular e desencapsular chaves com RSA](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/rsa_wrapping.c)
# Configurações avançadas para a biblioteca PKCS \$111 para AWS CloudHSM
O provedor AWS CloudHSM PKCS \$111 inclui a seguinte configuração avançada, que não faz parte das configurações gerais que a maioria dos clientes utiliza. Essas configurações fornecem recursos adicionais.
+ [Conectar-se a vários slots com o PKCS \$111](pkcs11-library-configs-multi-slot.md)
+ [Repita a configuração do PKCS \$111](pkcs11-library-configs-retry.md)
# Configuração de vários slots com a biblioteca PKCS \$111 para AWS CloudHSM
Um único slot na biblioteca PKCS \$111 do Client SDK 5 representa uma única conexão com um cluster no AWS CloudHSM. Com o Client SDK 5, você pode configurar sua PKCS11 biblioteca para permitir que vários slots conectem usuários a vários clusters do CloudHSM a partir de um único aplicativo PKCS \$111.
Use as instruções neste tópico para fazer com que seu aplicativo use a funcionalidade de vários slots para se conectar a vários clusters.
**Topics**
+ [Pré-requisitos de vários slots para a biblioteca PKCS \$111 para AWS CloudHSM](#pkcs11-multi-slot-prereqs)
+ [Configure a biblioteca PKCS \$111 para a funcionalidade de vários slots para AWS CloudHSM](pkcs11-multi-slot-config-run.md)
+ [Adicione um cluster com funcionalidade de vários slots para AWS CloudHSM](pkcs11-multi-slot-add-cluster.md)
+ [Remova um cluster com funcionalidade de vários slots para AWS CloudHSM](pkcs11-multi-slot-remove-cluster.md)
## Pré-requisitos de vários slots para a biblioteca PKCS \$111 para AWS CloudHSM
Antes de configurar vários slots para a biblioteca PKCS \$111 for AWS CloudHSM, preencha os seguintes pré-requisitos.
+ Dois ou mais AWS CloudHSM clusters aos quais você gostaria de se conectar, junto com seus certificados de cluster.
+ Uma instância do EC2 com grupos de segurança configurados corretamente para se conectar a todos os clusters acima. Para obter mais informações sobre como configurar um cluster e a instância cliente, consulte [Introdução ao AWS CloudHSM](getting-started.md).
+ Para configurar a funcionalidade de vários slots, você já deve ter baixado e instalado a biblioteca PKCS \$111. Se ainda não tiver feito isso, consulte as instruções em [Instale a biblioteca PKCS \$111 para o AWS CloudHSM Client SDK 5](pkcs11-library-install.md).
# Configure a biblioteca PKCS \$111 para a funcionalidade de vários slots para AWS CloudHSM
Para configurar sua biblioteca PKCS \$111 para a funcionalidade de vários slots AWS CloudHSM, siga estas etapas:
1. Identifique os clusters aos quais você deseja se conectar usando a funcionalidade de vários slots.
1. Adicione esses clusters à sua configuração PKCS \$111 seguindo as instruções em [Adicione um cluster com funcionalidade de vários slots para AWS CloudHSM](pkcs11-multi-slot-add-cluster.md)
1. Na próxima vez que seu aplicativo PKCS \$111 for executado, ele terá a funcionalidade de vários slots.
# Adicione um cluster com funcionalidade de vários slots para AWS CloudHSM
Ao [se conectar a vários slots com o PKCS \$111](pkcs11-library-configs-multi-slot.md) for AWS CloudHSM, use o **configure-pkcs11 add-cluster** comando para adicionar um cluster à sua configuração.
## Sintaxe
```
configure-pkcs11 add-cluster [OPTIONS]
--cluster-id
[--region ]
[--endpoint ]
[--hsm-ca-cert ]
[--client-cert-hsm-tls-file ]
[--client-key-hsm-tls-file ]
[-h, --help]
```
## Exemplos
### Adicione um cluster usando o parâmetro `cluster-id`
**Example**
Use o parâmetro **configure-pkcs11 add-cluster** junto com `cluster-id` para adicionar um cluster (com o ID de`cluster-1234567`) para a sua configuração.
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 add-cluster --cluster-id
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" add-cluster --cluster-id
```
**dica**
Se o uso de **configure-pkcs11 add-cluster** com o parâmetro `cluster-id` não resultar na adição do cluster, consulte o exemplo a seguir para obter uma versão mais longa deste comando que também requer os parâmetros `--region` e `--endpoint` para identificar o cluster que está sendo adicionado. Se, por exemplo, a região do cluster for diferente daquela configurada como padrão da AWS CLI, você deverá usar o parâmetro `--region` para usar a região correta. Além disso, você pode especificar o endpoint da AWS CloudHSM API a ser usado na chamada, o que pode ser necessário para várias configurações de rede, como usar endpoints de interface VPC que não usam o nome de host DNS padrão para. AWS CloudHSM
### Adicione um cluster usando os parâmetros `cluster-id`, `endpoint` e `region`
**Example**
Use **configure-pkcs11 add-cluster** junto com os parâmetros `cluster-id`, `endpoint` e `region` para adicionar um cluster (com o ID de `cluster-1234567`) à sua configuração.
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 add-cluster --cluster-id --region --endpoint
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" add-cluster --cluster-id --region --endpoint
```
Para obter mais informações sobre os parâmetros `--endpoint`, `--cluster-id` e `--region`, consulte [AWS CloudHSM Parâmetros de configuração do SDK do cliente 5](configure-tool-params5.md).
## Parâmetros
**--ID do cluster ****
Faz uma chamada `DescribeClusters` para encontrar todos os endereços IP da interface de rede elástica (ENI) do HSM no cluster associado ao ID do cluster. O sistema adiciona os endereços IP ENI aos arquivos de AWS CloudHSM configuração.
Se você usar o `--cluster-id` parâmetro de uma instância do EC2 em uma VPC que não tem acesso à Internet pública, deverá criar uma interface VPC endpoint à qual se conectar. AWS CloudHSM Para obter mais informações sobre os endpoints da VPC, consulte [AWS CloudHSM e VPC endpoints](cloudhsm-vpc-endpoint.md).
Obrigatório: Sim
**--ponto final ****
Especifique o endpoint AWS CloudHSM da API usado para fazer a `DescribeClusters` chamada. Você deve definir essa opção em combinação com `--cluster-id`.
Obrigatório: não
**--hsm-ca-cert ****
Especifica o caminho de arquivo do certificado de CA do HSM.
Obrigatório: não
**--região ****
Especifique a região do seu cluster. Você deve definir essa opção em combinação com `--cluster-id`.
Se você não fornecer o parâmetro `--region`, o sistema escolherá a região tentando ler as variáveis de ambiente `AWS_DEFAULT_REGION` ou `AWS_REGION`. Se essas variáveis não estiverem definidas, o sistema verificará a região associada ao seu perfil no seu arquivo de AWS Config (normalmente `~/.aws/config`), a menos que você tenha especificado um arquivo diferente na variável de ambiente `AWS_CONFIG_FILE`. Se nenhuma das opções acima for definida, o sistema usará a região `us-east-1` como padrão.
Obrigatório: não
**-- client-cert-hsm-tls -arquivo ****
Caminho para o certificado de cliente usado para autenticação mútua entre cliente TLS e HSM.
Use essa opção somente se você tiver registrado pelo menos uma âncora de confiança no HSM com a CLI do CloudHSM. Você deve definir essa opção em combinação com `--client-key-hsm-tls-file`.
Obrigatório: não
**-- client-key-hsm-tls -arquivo ****
Caminho para a chave do cliente usado para autenticação mútua entre cliente TLS e HSM.
Use essa opção somente se você tiver registrado pelo menos uma âncora de confiança no HSM com a CLI do CloudHSM. Você deve definir essa opção em combinação com `--client-cert-hsm-tls-file`.
Obrigatório: não
# Remova um cluster com funcionalidade de vários slots para AWS CloudHSM
Ao [se conectar a vários slots com o PKCS \$111](pkcs11-library-configs-multi-slot.md), use o comando **configure-pkcs11 remove-cluster** para remover um cluster dos slots PKCS \$111 disponíveis.
## Sintaxe
```
configure-pkcs11 remove-cluster [OPTIONS]
--cluster-id
[-h, --help]
```
## Exemplos
### Remover um cluster usando o parâmetro `cluster-id`
**Example**
Use o parâmetro **configure-pkcs11 remove-cluster** junto com `cluster-id` para remover um cluster (com o ID de `cluster-1234567`) da sua configuração.
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 remove-cluster --cluster-id
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" remove-cluster --cluster-id
```
Para obter mais informações sobre o parâmetro `--cluster-id`, consulte [AWS CloudHSM Parâmetros de configuração do SDK do cliente 5](configure-tool-params5.md).
## Parâmetro
**--ID do cluster ****
O ID do cluster a ser removido da configuração
Obrigatório: Sim
# Tente novamente os comandos da biblioteca PKCS \$111 para AWS CloudHSM
AWS CloudHSM O SDK do cliente 5.8.0 e versões posteriores têm uma estratégia de repetição automática integrada que repetirá as operações controladas pelo HSM do lado do cliente. Quando um HSM acelera as operações porque está muito ocupado executando operações anteriores e não pode receber mais solicitações, o cliente SDKs tentará repetir as operações limitadas até 3 vezes enquanto recua exponencialmente. Essa estratégia de repetição automática pode ser configurada para um dos dois modos: **desativado** e **padrão**.
+ **desativado**: o Client SDK não executará nenhuma estratégia de repetição para nenhuma operação com controle de utilização pelo HSM.
+ **padrão**: esse é o modo padrão para o Client SDK 5.8.0 e versões posteriores. Nesse modo, o cliente SDKs repetirá automaticamente as operações limitadas recuando exponencialmente.
Para obter mais informações, consulte [Controle de utilização do HSM](troubleshoot-hsm-throttling.md).
## Definir os comandos de repetição para o modo desativado
------
#### [ Linux ]
**Para definir comandos de repetição **off** para o Client SDK 5 no Linux**
+ Use os comandos a seguir para gerenciar as configurações do modo **off**:
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 --default-retry-mode off
```
------
#### [ Windows ]
**Para definir comandos de repetição **off** para o Client SDK 5 no Windows**
+ Use os comandos a seguir para gerenciar as configurações do modo **off**:
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --default-retry-mode off
```
------
# Armazenamento de certificados com a biblioteca PKCS \$111
A biblioteca AWS CloudHSM PKCS \$111 é compatível com o armazenamento de certificados de chave pública como “objetos públicos” (conforme definido no PKCS \$111 2.40) em clusters hsm2m.medium. Esse atributo permite que sessões públicas e privadas do PKCS \$111 criem, recuperem, modifiquem e excluam certificados de chave pública.
Para usar o armazenamento de certificados com a biblioteca PKCS \$111, você precisa habilitá-lo na configuração do seu cliente. Depois de habilitado, você pode gerenciar objetos de certificado de suas aplicações PKCS \$111. As operações que se aplicam tanto ao certificado quanto aos objetos de chave, como [C\$1 FindObjects](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html#_Toc323205461), retornarão resultados do armazenamento da chave e do certificado.
**Topics**
+ [Ativar o armazenamento de certificados](pkcs11-certificate-storage-configuration.md)
+ [API de armazenamento de certificados](pkcs11-certificate-storage-api.md)
+ [Atributos de certificado](pkcs11-certificate-storage-attributes.md)
+ [Logs de auditoria de armazenamento de certificados](pkcs11-certificate-storage-audit-logs.md)
# Ativar o armazenamento de certificados
Você pode ativar o armazenamento de certificados em clusters hsm2m.medium usando a ferramenta de configuração da biblioteca PKCS \$111. Esse atributo só está disponível no SDK versões 5.13 e posteriores. Para obter uma lista de operações que oferecem suporte ao tipo de objeto de certificado, consulte [Operações da API de armazenamento de certificados](pkcs11-certificate-storage-api.md).
Para ativar o armazenamento de certificados, siga estas etapas para seu sistema operacional:
------
#### [ Linux ]
+
****Ativar o armazenamento de certificados****
Execute este comando: .
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 --enable-certificate-storage
```
------
#### [ Windows ]
+
****Ativar o armazenamento de certificados****
Abra um prompt de comando e execute o seguinte comando:
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --enable-certificate-storage
```
------
# Operações da API de armazenamento de certificados
As seguintes operações do PKCS \$111 oferecem suporte ao tipo de objeto certificado (`CKO_CERTIFICATE`):
## Operações gerais de certificado
**`C_CreateObject`**
Cria um objeto de certificado.
**`C_DestroyObject`**
Exclui um objeto de certificado existente.
**`C_GetAttributeValue`**
Obtém o valor de um ou mais atributos de um objeto de certificado.
**`C_SetAttributeValue`**
Atualiza o valor de um ou mais atributos de um objeto de certificado.
## Operações de pesquisa de objetos de certificado
**`C_FindObjectsInit`**
Inicia uma pesquisa por objetos de certificado.
**`C_FindObjects`**
Continua uma pesquisa por objetos de certificado.
**`C_FindObjectsFinal`**
Encerra uma pesquisa por objetos de certificado.
# Atributos de armazenamento de certificados
A tabela a seguir lista os atributos do objeto de certificado compatíveis e seus valores:
| Atributo | Valor padrão | Description |
| --- | --- | --- |
| `CKA_CLASS` | Obrigatório | Deve ser `CKO_CERTIFICATE`. |
| `CKA_TOKEN` | Verdadeiro | Deve ser `True`. |
| `CKA_MODIFIABLE` | Verdadeiro | Deve ser `True`. |
| `CKA_PRIVATE` | Falso | Deve ser `False`. |
| `CKA_LABEL` | Vazio | Limite de 127 caracteres. |
| `CKA_COPYABLE` | Falso | Deve ser `False`. |
| `CKA_DESTROYABLE` | Verdadeiro | Deve ser `True`. |
| `CKA_CERTIFICATE_TYPE` | Obrigatório | Deve ser `CKC_X_509`. |
| `CKA_TRUSTED` | Falso | Deve ser `False`. |
| `CKA_CERTIFICATE_CATEGORY` | `CK_CERTIFICATE_CATEGORY_UNSPECIFIED` | Deve ser `CK_CERTIFICATE_CATEGORY_UNSPECIFIED`. |
| `CKA_CHECK_VALUE` | Derivado de `CKA_VALUE` | Definido automaticamente com base em `CKA_VALUE`. |
| `CKA_START_DATE` | Vazio | A data “não antes de” do certificado. |
| `CKA_END_DATE` | Vazio | A data “não depois de” do certificado. |
| `CKA_PUBLIC_KEY_INFO` | Vazio | O tamanho máximo é de 16 kilobytes. |
| `CKA_SUBJECT` | Obrigatório | O assunto do certificado. |
| `CKA_ID` | Vazio | O tamanho máximo é 128 bytes. A exclusividade não é imposta. |
| `CKA_ISSUER` | Vazio | O emissor do certificado. |
| `CKA_SERIAL_NUMBER` | Vazio | O número de série do certificado. |
| `CKA_VALUE` | Obrigatório | O tamanho máximo é de 32 kilobytes. |
# Logs de auditoria de armazenamento de certificados
O AWS CloudHSM grava registros de auditoria para operações de armazenamento de certificados que modificam dados em um stream de log separado do CloudWatch Amazon Events dentro do grupo de registros do seu cluster CloudWatch . Esse fluxo de logs é nomeado para o cluster, não para um HSM específico dentro do cluster.
Para obter informações sobre como acessar os registros de auditoria CloudWatch, consulte[Trabalhando com Amazon CloudWatch Logs e AWS CloudHSM Audit Logs](get-hsm-audit-logs-using-cloudwatch.md).
## Campos de entrada de log
`object_handle`
O identificador exclusivo do objeto do certificado.
`op_code`
A operação executada ou tentada. Possíveis valores:
+ `CreateObject`
+ `DestroyObject`
+ `SetAttributeValues`
`response`
`OK` se a operação foi bem-sucedida ou um dos seguintes tipos de erro:
+ `DuplicateAttribute`
+ `InvalidAttributeValue`
+ `ObjectNotFound`
+ `MaxObjectsReached`
+ `InternalFailure`
`attributes`
Os atributos modificados, se houver.
`timestamp`
O tempo em que a operação ocorreu, em milissegundos, desde a época do Unix.
## Exemplos de log de auditoria
### CreateObject exemplo
```
{
"object_handle": 463180677312929947,
"op_code": "CreateObject",
"response": "OK",
"attributes": null,
"timestamp": 1725482483671
}
```
### DestroyObject exemplo
```
{
"object_handle": 463180677312929947,
"op_code": "DestroyObject",
"response": "OK",
"attributes": null,
"timestamp": 1725482484559
}
```
### SetAttributeValues exemplo
```
{
"object_handle": 463180678453346687,
"op_code": "SetAttributeValues",
"response": "OK",
"attributes": [
"Label"
],
"timestamp": 1725482488004
}
```
### Exemplo malsucedido CreateObject
```
{
"object_handle": null,
"op_code": "CreateObject",
"response": "MaxObjectsReached",
"attributes": null,
"timestamp": 1726084937125
}
```
# Mecanismo AWS CloudHSM dinâmico OpenSSL para cliente SDK 5
O AWS CloudHSM OpenSSL Dynamic Engine permite que você descarregue operações criptográficas em seu cluster CloudHSM por meio da API OpenSSL.
AWS CloudHSM fornece um mecanismo dinâmico OpenSSL, sobre o qual você pode ler em ou. [AWS CloudHSM Descarregamento de SSL/TLS no Linux usando Tomcat com JSSE](third-offload-linux-jsse.md) [AWS CloudHSM Descarregamento de SSL/TLS no Linux usando NGINX ou Apache com OpenSSL](third-offload-linux-openssl.md) Para ver um exemplo de uso AWS CloudHSM com o OpenSSL, consulte [este blog de segurança da AWS](https://aws.amazon.com/blogs/security/automate-the-deployment-of-an-nginx-web-service-using-amazon-ecs-with-tls-offload-in-cloudhsm/). Para obter informações sobre o suporte da plataforma para SDKs, consulte[AWS CloudHSM Plataformas compatíveis com o Client SDK 5](client-supported-platforms.md). Para solução de problemas, consulte [Problemas conhecidos do OpenSSL Dynamic Engine para AWS CloudHSM](ki-openssl-sdk.md).
Use as seções a seguir para instalar e configurar o mecanismo AWS CloudHSM dinâmico para OpenSSL usando o Client SDK 5.
Para obter mais informações sobre como usar Client SDK 3, consulte [Usando a versão anterior do SDK para trabalhar com AWS CloudHSM](choose-client-sdk.md).
**Topics**
+ [Instale o OpenSSL Dynamic Engine AWS CloudHSM for Client SDK 5](openssl5-install.md)
+ [Tipos de chave compatíveis com o OpenSSL Dynamic Engine AWS CloudHSM for Client SDK 5](openssl-key-types.md)
+ [Mecanismos compatíveis com o OpenSSL Dynamic Engine AWS CloudHSM for Client SDK 5](openssl-mechanisms.md)
+ [Configurações avançadas para OpenSSL para AWS CloudHSM](openssl-library-configs.md)
# Instale o OpenSSL Dynamic Engine AWS CloudHSM for Client SDK 5
Use as seções a seguir para instalar o OpenSSL Dynamic Engine AWS CloudHSM for Client SDK 5.
**nota**
Para executar um único cluster HSM com o Client SDK 5, você deve primeiro gerenciar as configurações de durabilidade da chave do cliente configurando `disable_key_availability_check` como `True`. Para obter mais informações, consulte [Sincronização de chave](manage-key-sync.md) e a [ferramenta de configuração do Client SDK 5](configure-sdk-5.md).
**Instalar e configurar o mecanismo dinâmico do OpenSSL**
1. Use os seguintes comandos para fazer download e instalar o mecanismo OpenSSL.
------
#### [ Amazon Linux 2023 ]
Instale o OpenSSL Dynamic Engine para Amazon Linux 2023 na arquitetura X86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-dyn-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.amzn2023.x86_64.rpm
```
Instale o OpenSSL Dynamic Engine para Amazon Linux 2023 na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-dyn-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.amzn2023.aarch64.rpm
```
------
#### [ Amazon Linux 2 ]
Instale o OpenSSL Dynamic Engine para Amazon Linux 2 na arquitetura X86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-dyn-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el7.x86_64.rpm
```
Instale o OpenSSL Dynamic Engine para Amazon Linux 2 na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-dyn-latest.el7.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el7.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
Instale o OpenSSL Dynamic Engine para RHEL 9 na arquitetura X86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-dyn-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el9.x86_64.rpm
```
Instale o OpenSSL Dynamic Engine para RHEL 9 na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-dyn-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el9.aarch64.rpm
```
------
#### [ RHEL 8 (8.3\$1) ]
Instale o OpenSSL Dynamic Engine para RHEL 8 na arquitetura X86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-dyn-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el8.x86_64.rpm
```
Instale o OpenSSL Dynamic Engine para RHEL 8 na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-dyn-latest.el8.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el8.aarch64.rpm
```
------
#### [ Ubuntu 24.04 LTS ]
Instale o OpenSSL Dynamic Engine para Ubuntu 24.04 LTS na arquitetura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-dyn_latest_u24.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u24.04_amd64.deb
```
Instale o OpenSSL Dynamic Engine para Ubuntu 24.04 LTS na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-dyn_latest_u24.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u24.04_arm64.deb
```
------
#### [ Ubuntu 22.04 LTS ]
Instale o OpenSSL Dynamic Engine para Ubuntu 22.04 LTS na arquitetura X86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-dyn_latest_u22.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u22.04_amd64.deb
```
Instale o OpenSSL Dynamic Engine para Ubuntu 22.04 LTS na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-dyn_latest_u22.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u22.04_arm64.deb
```
------
Você instalou a biblioteca compartilhada para o mecanismo dinâmico em `/opt/cloudhsm/lib/libcloudhsm_openssl_engine.so`.
1. Bootstrap do Client SDK 5. Para obter mais informações sobre ações de bootstrap, consulte [Bootstrap o Client SDK](cluster-connect.md#connect-how-to).
1. Defina uma variável de ambiente com as credenciais de um usuário de criptografia (CU). Para obter informações sobre a criação CUs, consulte[Crie um AWS CloudHSM usuário com o CloudHSM CLI](cloudhsm_cli-user-create.md).
```
$ export CLOUDHSM_PIN=:
```
**nota**
O Client SDK 5 introduz a variável de `CLOUDHSM_PIN` ambiente para armazenar as credenciais do CU. No Client SDK 3, você armazena as credenciais do CU na variável de `n3fips_password` ambiente. O Client SDK 5 é compatível com as duas variáveis de ambiente, mas recomendamos o uso de `CLOUDHSM_PIN`.
Ao definir variáveis de `CLOUDHSM_PIN` ambiente, você deve escapar de quaisquer caracteres especiais que possam ser interpretados pelo seu shell.
1. Conecte sua instalação do mecanismo dinâmico do OpenSSL ao cluster. Para obter mais informações, consulte [Conexão com um cluster](cluster-connect.md).
1. Bootstrap o Client SDK 5. Para obter mais informações, consulte [Bootstrap o Client SDK](cluster-connect.md#connect-how-to).
## Verifique o mecanismo dinâmico do OpenSSL para Client SDK 5
Use o comando a seguir para verificar sua instalação do mecanismo dinâmico do OpenSSL.
```
$ openssl engine -t cloudhsm
```
A saída a seguir verifica sua configuração:
```
(cloudhsm) CloudHSM OpenSSL Engine
[ available ]
```
# Tipos de chave compatíveis com o OpenSSL Dynamic Engine AWS CloudHSM for Client SDK 5
O AWS CloudHSM OpenSSL Dynamic Engine oferece suporte aos seguintes tipos de chave com o Client SDK 5.
****
| Tipo de chave | Description |
| --- | --- |
| EC | ECDSA sign/verify para tipos de chaves P-256, P-384 e secp256k1. Para gerar chaves EC que sejam interoperáveis com o mecanismo OpenSSL, consulte [Exportar uma chave assimétrica com a CloudHSM CLI](cloudhsm_cli-key-generate-file.md). |
| RSA | Geração de chave de RSA para chaves de 2048, 3072 e 4096 bits.Assinar/verificar RSA. A verificação é descarregada para o software OpenSSL. |
# Mecanismos compatíveis com o OpenSSL Dynamic Engine AWS CloudHSM for Client SDK 5
O AWS CloudHSM OpenSSL Dynamic Engine suporta os seguintes mecanismos para as funções de assinatura e verificação com o Client SDK 5.
## Funções de assinatura e verificação
Com o Client SDK 5, os dados são codificados localmente no software. Isso significa que não há limite em relação ao tamanho dos dados que podem ser codificados.
Tipos de assinatura RSA
+ SHA1withRSA
+ SHA224withRSA
+ SHA256withRSA
+ SHA384withRSA
+ SHA512withRSA
Tipos de assinatura ECDSA
+ SHA1withECDSA
+ SHA224withECDSA
+ SHA256withECDSA
+ SHA384withECDSA
+ SHA512withECDSA
# Configurações avançadas para OpenSSL para AWS CloudHSM
O provedor AWS CloudHSM OpenSSL inclui a seguinte configuração avançada, que não faz parte das configurações gerais que a maioria dos clientes utiliza. Essas configurações fornecem recursos adicionais.
+ [Repetir comandos para OpenSSL](openssl-library-configs-retry.md)
# Tente novamente os comandos do OpenSSL para AWS CloudHSM
AWS CloudHSM O SDK do cliente 5.8.0 e versões posteriores têm uma estratégia de repetição automática integrada que repetirá as operações controladas pelo HSM do lado do cliente. Quando um HSM acelera as operações porque está muito ocupado executando operações anteriores e não pode receber mais solicitações, o cliente SDKs tentará repetir as operações limitadas até 3 vezes enquanto recua exponencialmente. Essa estratégia de repetição automática pode ser configurada para um dos dois modos: **desativado** e **padrão**.
+ **desativado**: o Client SDK não executará nenhuma estratégia de repetição para nenhuma operação com controle de utilização pelo HSM.
+ **padrão**: esse é o modo padrão para o Client SDK 5.8.0 e versões posteriores. Nesse modo, o cliente SDKs repetirá automaticamente as operações limitadas recuando exponencialmente.
Para obter mais informações, consulte [Controle de utilização do HSM](troubleshoot-hsm-throttling.md).
## Definir os comandos de repetição para o modo desativado
Você pode usar os comandos a seguir para definir os comandos de repetição para o modo **off**:
```
$ sudo /opt/cloudhsm/bin/configure-dyn --default-retry-mode off
```
# Provedor AWS CloudHSM de OpenSSL para cliente SDK 5
O AWS CloudHSM OpenSSL Provider permite que você descarregue operações criptográficas TLS em seu cluster CloudHSM por meio da API do OpenSSL Provider. A interface do provedor é a abordagem recomendada para novas implantações usando o OpenSSL 3.2 e versões posteriores.
Use as seções a seguir para instalar e configurar o AWS CloudHSM OpenSSL Provider usando o Client SDK 5.
**Atenção**
Atualmente, a integração com o OpenSSL CLI não é suportada pelo OpenSSL Provider. AWS CloudHSM Consulte [AWS CloudHSM Descarregamento de SSL/TLS no Linux usando NGINX ou com o OpenSSL Provider HAProxy](third-offload-linux-openssl-provider.md) as integrações compatíveis.
## Plataformas compatíveis
O OpenSSL Provider requer o OpenSSL 3.2 ou posterior, disponível em \$1, Ubuntu 24.04\$1 e Amazon Linux EL9 2023\$1.
Verifique a compatibilidade: `openssl version`
**Topics**
+ [Plataformas compatíveis](#openssl-provider-supported-platforms)
+ [Instale o OpenSSL Provider AWS CloudHSM for Client SDK 5](openssl-provider-install.md)
+ [Tipos de chave compatíveis com o OpenSSL Provider AWS CloudHSM for Client SDK 5](openssl-provider-key-types.md)
+ [Mecanismos suportados pelo OpenSSL Provider](openssl-provider-mechanisms.md)
+ [Configuração avançada do OpenSSL Provider](openssl-provider-advanced-config.md)
# Instale o OpenSSL Provider AWS CloudHSM for Client SDK 5
Use as seções a seguir para instalar o provedor OpenSSL para o SDK 5 do cliente AWS CloudHSM.
**nota**
Para executar um único cluster HSM com o Client SDK 5, você deve primeiro gerenciar as configurações de durabilidade da chave do cliente configurando `disable_key_availability_check` como `True`. Para obter mais informações, consulte [Sincronização de chave](working-client-sync.md#client-sync-sdk8) e a [ferramenta de configuração do Client SDK 5](configure-sdk-5.md).
## Requisitos
O provedor OpenSSL **exige** os tipos de cluster hsm2m.medium e o SDK mínimo do CloudHSM Client versão 5.17.0 ou posterior.
## Instale o provedor OpenSSL
**Para instalar o OpenSSL Provider**
1. Use os comandos a seguir para baixar e instalar o OpenSSL Provider.
------
#### [ Amazon Linux 2023 ]
Instale o provedor OpenSSL para Amazon Linux 2023 na arquitetura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-openssl-provider-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.amzn2023.x86_64.rpm
```
Instale o provedor OpenSSL para Amazon Linux 2023 na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-openssl-provider-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.amzn2023.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
Instale o provedor OpenSSL para RHEL 9 na arquitetura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-openssl-provider-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el9.x86_64.rpm
```
Instale o provedor OpenSSL para RHEL 9 na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-openssl-provider-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el9.aarch64.rpm
```
------
#### [ RHEL 10 (10.0\$1) ]
Instale o provedor OpenSSL para RHEL 10 na arquitetura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-openssl-provider-latest.el10.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el10.x86_64.rpm
```
Instale o provedor OpenSSL para RHEL 10 na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-openssl-provider-latest.el10.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el10.aarch64.rpm
```
------
#### [ Ubuntu 24.04 ]
Instale o provedor OpenSSL para Ubuntu 24.04 na arquitetura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-openssl-provider_latest_u24.04_amd64.deb
```
```
$ sudo dpkg -i ./cloudhsm-openssl-provider_latest_u24.04_amd64.deb
```
Instale o provedor OpenSSL para Ubuntu 24.04 na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-openssl-provider_latest_u24.04_arm64.deb
```
```
$ sudo dpkg -i ./cloudhsm-openssl-provider_latest_u24.04_arm64.deb
```
------
Você instalou a biblioteca compartilhada para o OpenSSL Provider em. `/opt/cloudhsm/lib/licloudhsm_openssl_provider.so`
1. Bootstrap do Client SDK 5. Para obter mais informações sobre ações de bootstrap, consulte [Bootstrap o Client SDK](cluster-connect.md#connect-how-to).
1. Defina a variável de `CLOUDHSM_PIN` ambiente com suas credenciais de usuário criptográfico (CU):
```
$ export CLOUDHSM_PIN=:
```
1. Conecte sua instalação do OpenSSL Provider ao cluster. Para obter mais informações, consulte [Conexão com um cluster](cluster-connect.md).
## Verificar a instalação
Verifique se o OpenSSL Provider está instalado corretamente:
```
$ CLOUDHSM_PIN=: openssl list -providers -provider cloudhsm
```
Você deve ver uma saída semelhante a:
```
Providers:
cloudhsm
name: AWS CloudHSM OpenSSL Provider
version: 5.17.0
status: active
default
name: OpenSSL Default Provider
version: 3.2.2
status: active
```
# Tipos de chave compatíveis com o OpenSSL Provider AWS CloudHSM for Client SDK 5
O AWS CloudHSM OpenSSL Provider oferece suporte aos seguintes tipos de chave com o Client SDK 5.
****
| Tipo de chave | Description |
| --- | --- |
| RSA | Operações de criptografia RSA sign/verify e assimétrica. A verificação é descarregada para o software OpenSSL. Para gerar chaves RSA que sejam interoperáveis com o provedor OpenSSL, consulte. [Exportar uma chave assimétrica com a CloudHSM CLI](cloudhsm_cli-key-generate-file.md) |
| EC | ECDSA sign/verify para curvas P-256, P-384 e P-521. A verificação é descarregada para o software OpenSSL. Para gerar chaves EC que sejam interoperáveis com o provedor OpenSSL, consulte. [Exportar uma chave assimétrica com a CloudHSM CLI](cloudhsm_cli-key-generate-file.md) |
# Mecanismos suportados pelo OpenSSL Provider
O AWS CloudHSM OpenSSL Provider SDK oferece suporte a um conjunto abrangente de mecanismos criptográficos para várias operações, incluindo assinaturas digitais, criptografia assimétrica, criptografia simétrica, troca de chaves e muito mais.
## Tipos de assinatura RSA
O OpenSSL Provider oferece suporte a assinaturas digitais RSA com vários algoritmos de hash e esquemas de preenchimento:
SHA1withRSA
Assinaturas RSA com algoritmo de hash SHA-1
+ Preenchimento PKCS \$11 v1.5
+ Preenchimento PSS (Esquema de Assinatura Probabilística)
SHA224withRSA
Assinaturas RSA com algoritmo de hash SHA-224
+ Preenchimento PKCS \$11 v1.5
+ Estofamento PSS
SHA256withRSA
Assinaturas RSA com algoritmo de hash SHA-256
+ Preenchimento PKCS \$11 v1.5
+ Estofamento PSS
SHA384withRSA
Assinaturas RSA com algoritmo de hash SHA-384
+ Preenchimento PKCS \$11 v1.5
+ Estofamento PSS
SHA512withRSA
Assinaturas RSA com algoritmo de hash SHA-512
+ Preenchimento PKCS \$11 v1.5
+ Estofamento PSS
## Tipos de assinatura ECDSA
O OpenSSL Provider oferece suporte a assinaturas digitais ECDSA com vários algoritmos de hash:
SHA1withECDSA
Assinaturas ECDSA com algoritmo de hash SHA-1
SHA224withECDSA
Assinaturas ECDSA com algoritmo de hash SHA-224
SHA256withECDSA
Assinaturas ECDSA com algoritmo de hash SHA-256
SHA384withECDSA
Assinaturas ECDSA com algoritmo de hash SHA-384
SHA512withECDSA
Assinaturas ECDSA com algoritmo de hash SHA-512
# Configuração avançada do OpenSSL Provider
O SDK do provedor de OpenSSL do AWS CloudHSM fornece opções avançadas de configuração para personalizar seu comportamento para diferentes casos de uso e ambientes. Use a ferramenta de configuração para definir essas opções.
+ [Tente novamente a configuração do OpenSSL Provider](openssl-provider-configs-retry.md)
# Tente novamente os comandos do OpenSSL Provider para AWS CloudHSM
AWS CloudHSM O SDK do cliente 5.8.0 e versões posteriores têm uma estratégia de repetição automática integrada que repetirá as operações controladas pelo HSM do lado do cliente. Quando um HSM acelera as operações porque está muito ocupado executando operações anteriores e não pode receber mais solicitações, o cliente SDKs tentará repetir as operações limitadas até 3 vezes enquanto recua exponencialmente. Essa estratégia de repetição automática pode ser configurada para um dos dois modos: **desativado** e **padrão**.
+ **desativado**: o Client SDK não executará nenhuma estratégia de repetição para nenhuma operação com controle de utilização pelo HSM.
+ **padrão**: esse é o modo padrão para o Client SDK 5.8.0 e versões posteriores. Nesse modo, o cliente SDKs repetirá automaticamente as operações limitadas recuando exponencialmente.
Para obter mais informações, consulte [Controle de utilização do HSM](troubleshoot-hsm-throttling.md).
## Definir os comandos de repetição para o modo desativado
------
#### [ Linux ]
**Para definir comandos de repetição **off** para o Client SDK 5 no Linux**
+ Use os comandos a seguir para gerenciar as configurações do modo **off**:
```
$ sudo /opt/cloudhsm/bin/configure-openssl-provider --default-retry-mode off
```
------
# Provedor de armazenamento de chaves (KSP) para o AWS CloudHSM Client SDK 5
O Provedor de armazenamento de chaves (KSP) é uma API de criptografia específica para o sistema operacional Microsoft Windows. O Provedor de armazenamento de chaves (KSP) permite que os desenvolvedores usem técnicas de criptografia para proteger aplicações baseadas em Windows.
Para obter informações sobre bootstrapping, consulte [Conectar-se ao cluster](cluster-connect.md).
Para obter mais informações sobre como usar Client SDK 3, consulte [Usando a versão anterior do SDK para trabalhar com AWS CloudHSM](choose-client-sdk.md).
**Topics**
+ [Instale o provedor de armazenamento de chaves (KSP) para o AWS CloudHSM Client SDK 5](ksp-library-install.md)
+ [Autentique-se no provedor de armazenamento de chaves (KSP) do AWS CloudHSM Client SDK 5](ksp-library-authentication.md)
+ [Tipos de chaves compatíveis com o Key Storage Provider (KSP) para AWS CloudHSM Client SDK 5](ksp-library--key-types.md)
+ [Operações de API suportadas Provedor de armazenamento de chaves (KSP) para o AWS CloudHSM Client SDK 5](ksp-library-apis.md)
+ [Configurações avançadas do KSP para AWS CloudHSM](ksp-library-configs.md)
# Instale o provedor de armazenamento de chaves (KSP) para o AWS CloudHSM Client SDK 5
Use as seções a seguir para instalar o provedor de armazenamento de chaves (KSP) para o AWS CloudHSM Client SDK 5.
**nota**
Para executar um único cluster HSM com o Client SDK 5, você deve primeiro gerenciar as configurações de durabilidade da chave do cliente configurando `disable_key_availability_check` como `True`. Para obter mais informações, consulte [Sincronização de chave](manage-key-sync.md) e a [ferramenta de configuração do Client SDK 5](configure-sdk-5.md).
**Para instalar e configurar o Provedor de armazenamento de chaves (KSP)**
1. Instale o Key Storage Provider (KSP) para Windows Server na arquitetura x86\$164, abra PowerShell como administrador e execute o seguinte comando:
```
PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMKSP-latest.msi -Outfile C:\AWSCloudHSMKSP-latest.msi
```
```
PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMKSP-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
```
1. Use a ferramenta de configuração para especificar um local para o certificado de emissão. Para instruções, consulte [Especifique o local do certificado de emissão.](cluster-connect.md#specify-cert-location).
1. Para se conectar e usar o cluster [Bootstrap o Client SDK](cluster-connect.md#connect-how-to).
1. Você pode encontrar os arquivos do Provedor de armazenamento de chaves (KSP) nos seguintes locais:
+ Binários do Windows:
```
C:\Program Files\Amazon\CloudHSM
```
Scripts de configuração e arquivos de log do Windows:
```
C:\ProgramData\Amazon\CloudHSM
```
# Autentique-se no provedor de armazenamento de chaves (KSP) do AWS CloudHSM Client SDK 5
Antes de usar o provedor de armazenamento de chaves (KSP) para o AWS CloudHSM Client SDK 5, você deve definir as credenciais de login para o HSM em seu sistema. Você tem duas opções:
+ Gerenciador de credenciais do Windows (recomendado para maior segurança)
+ Variáveis de ambiente do sistema (configuração mais simples)
## Gerenciador de credenciais do Windows
Você pode configurar as credenciais usando o utilitário `set_cloudhsm_credentials` ou a interface do Gerenciador de credenciais do Windows.
+ **Usar o utilitário `set_cloudhsm_credentials`**:
O Windows Installer inclui o utilitário `set_cloudhsm_credentials`. É possível usar esse utilitário para passar convenientemente as credenciais de login do HSM para o Gerenciador de credenciais do Windows. Se desejar compilar esse utilitário da origem, use o código Python incluído no instalador.
1. Acesse `C:\Program Files\Amazon\CloudHSM\tools\`.
1. Execute este comando: .
```
set_cloudhsm_credentials.exe --username --password
```
+ **Usar a interface do Gerenciador de credenciais**:
1. Abra o Gerenciador de credenciais:
+ Insira `credential manager` na caixa de pesquisa da barra de tarefas
+ Selecione **Gerenciador de credenciais**
1. Selecione **Windows Credentials (Credenciais do Windows)** para gerenciar as credenciais do Windows.
1. Selecione **Adicionar uma credencial genérica**
1. Insira os detalhes a seguir:
+ **Endereço de internet ou de rede**: `CLOUDHSM_PIN`.
+ **Nome de usuário**:**.
+ **Senha**:**.
1. Escolha **OK**
## Variáveis de ambiente do sistema
Você pode definir as variáveis de ambiente do sistema que identificam um HSM e um [usuário de criptografia](understanding-users.md#crypto-user-chsm-cli) (CU).
**Atenção**
A configuração de credenciais por meio de variáveis de ambiente do sistema armazena sua senha em texto simples no sistema. Para maior segurança, use o Gerenciador de credenciais do Windows em vez disso.
Você pode definir as variáveis de ambiente usando:
+ O [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx).
+ O painel de controle **Propriedades do Sistema** (guia **Avançado**) do Windows.
+ definir métodos [Programáticos](https://msdn.microsoft.com/en-us/library/system.environment.setenvironmentvariable(v=vs.110).aspx) de variáveis de ambiente do sistema permanentes.
Para definir a variável de ambiente do sistema:
**`CLOUDHSM_PIN=:`**
Identifica um [crypto user (usuário de criptografia)](understanding-users.md#crypto-user-chsm-cli) (CU) no HSM e fornece todas as informações de login necessárias. O aplicativo é autenticado e executado como esse CU. O aplicativo tem as permissões desse CU e pode visualizar e gerenciar apenas as chaves que o CU possui e compartilha. Para criar um usuário de criptografia, use o comando [user create](cloudhsm_cli-user-create.md) na CloudHSM CLI. Para encontrar os existentes CUs, use o comando [user list](cloudhsm_cli-user-list.md) na CLI do CloudHSM.
Por exemplo:
```
setx /m CLOUDHSM_PIN test_user:password123
```
**nota**
Ao definir as variáveis de ambiente CLOUDHSM\$1PIN, você deve escapar de quaisquer caracteres especiais que possam ser interpretados pelo seu shell.
# Tipos de chaves compatíveis com o Key Storage Provider (KSP) para AWS CloudHSM Client SDK 5
O AWS CloudHSM Key Storage Provider (KSP) oferece suporte aos seguintes tipos de chaves com o Client SDK 5.
****
| Tipo de chave | Description |
| --- | --- |
| EC | Gere chaves com as curvas secp256r1 (P-256), secp384r1 (P-384) e secp521r1 (P-521). |
| RSA | Gere chaves RSA de 2048, 3072 e 4096 bits. |
# Operações de API suportadas Provedor de armazenamento de chaves (KSP) para o AWS CloudHSM Client SDK 5
Os parâmetros no KSP são definidos pelo Microsoft KSP. Consulte a [documentação da Microsoft](https://learn.microsoft.com/en-us/windows/win32/api/ncrypt/) para obter mais informações.
O Key Storage Provider (KSP) oferece suporte às seguintes operações da API KSP para o AWS CloudHSM Client SDK 5.
+ [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)
+ [NCryptOpenKey](ksp-library-apis-open-key.md)
+ [NCryptCreatePersistedKey](ksp-library-apis-create-persisted-key.md)
+ [NCryptGetProperty](ksp-library-apis-get-property.md)
+ [NCryptSetProperty](ksp-library-apis-set-property.md)
+ [NCryptFinalizeKey](ksp-library-apis-finalize-key.md)
+ [NCryptDeleteKey](ksp-library-apis-delete-key.md)
+ [NCryptFreeObject](ksp-library-apis-free-object.md)
+ [NCryptFreeBuffer](ksp-library-apis-free-buffer.md)
+ [NCryptIsAlgSupported](ksp-library-apis-is-alg-supported.md)
+ [NCryptEnumAlgorithms](ksp-library-apis-enum-algorithms.md)
+ [NCryptEnumKeys](ksp-library-apis-enum-keys.md)
+ [NCryptExportKey](ksp-library-apis-export-key.md)
+ [NCryptSignHash](ksp-library-apis-sign-hash.md)
+ [NCryptVerifySignature](ksp-library-apis-verify-signature.md)
# NCryptOpenStorageProvider função com Key Storage Provider (KSP)
A função `NCryptOpenStorageProvider` carrega e inicializa o Provedor de armazenamento de chaves (KSP).
## Parâmetros
`phProvider` [out]
Um ponteiro para uma variável `NCRYPT_PROV_HANDLE` que armazena o identificador do provedor.
`pszProviderName` [in]
Um ponteiro para uma string Unicode terminada em nulo identificando o provedor de armazenamento de chaves. O Provedor de armazenamento de chaves (KSP) do AWS CloudHSM oferece suporte aos seguintes valores:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-open-provider.html)
Os valores são literais de string largos, conforme indicado pelo L antes do literal.
`dwFlags` [in]
Sinalizadores que modificam o comportamento da função. Nenhum sinalizador está definido para essa função.
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A operação foi concluída com êxito. |
| NTE\$1INVALID\$1PARAMETER | Um ou mais parâmetros não são válidos. |
| NTE\$1FAIL | A operação não foi concluída. |
# NCryptOpenKey com o provedor de armazenamento de chaves (KSP)
A função `NCryptOpenKey` abre uma chave que existe no Provedor de Armazenamento de Chaves (KSP).
## Parâmetros
`hProvider` [in]
O identificador do KSP que contém a chave. Use [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) para obter o identificador.
`phKey` [out]
Um ponteiro para uma variável `NCRYPT_KEY_HANDLE` que armazena o identificador da chave.
`pszKeyName` [in]
Um ponteiro para uma string Unicode terminada em nulo contendo o nome da chave.
`dwLegacyKeySpec` [in, unused]
AWS CloudHSM O Key Storage Provider (KSP) não usa esse parâmetro.
`dwFlags` [in]
Sinalizadores que modificam o comportamento da função. Nenhum sinalizador está definido para essa função.
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A operação foi concluída com êxito. |
| NTE\$1INVALID\$1PARAMETER | Um ou mais parâmetros não são válidos. |
| NTE\$1FAIL | A operação não foi concluída. |
| NTE\$1INVALID\$1HANDLE | O identificador em `hProvider` não é válido. |
| NTE\$1BAD\$1KEYSET | O nome da chave fornecido não retornou um resultado exclusivo. |
# NCryptCreatePersistedKey com o provedor de armazenamento de chaves (KSP)
A função `NCryptCreatePersistedKey` cria uma nova chave e a armazena no Provedor de armazenamento de chaves (KSP). Você pode usar a função [`NCryptSetProperty`](ksp-library-apis-set-property.md) para definir suas propriedades após a criação. Você deve chamar [`NCryptFinalizeKey`](ksp-library-apis-finalize-key.md) antes de poder usar a chave.
## Parâmetros
`hProvider` [in]
O identificador do provedor de armazenamento de chaves em que você criará a chave. Use [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) para obter esse identificador.
`phKey` [out]
O endereço de uma variável `NCRYPT_KEY_HANDLE` que armazena o identificador da chave.
`pszAlgId` [in]
Um ponteiro para uma string Unicode terminada em nulo que especifica o identificador do algoritmo criptográfico para criar a chave.
AWS CloudHSM O Key Storage Provider (KSP) suporta os seguintes algoritmos:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-create-persisted-key.html)
`pszKeyName` [in, optional]
Um ponteiro para uma string Unicode terminada em nulo que contém o nome da chave. Se esse parâmetro for NULL, essa função criará uma chave efêmera que não será persistida.
`dwLegacyKeySpec` [in, unused]
AWS CloudHSM O Key Storage Provider (KSP) não usa esse parâmetro.
`dwFlags` [in]
Sinalizadores para modificar o comportamento da função. Use nenhum ou mais dos seguintes valores:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-create-persisted-key.html)
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A função foi concluída com êxito. |
| NTE\$1INVALID\$1PARAMETER | Um ou mais parâmetros não são válidos. |
| NTE\$1FAIL | A operação não foi concluída. |
| NTE\$1BAD\$1FLAGS | O parâmetro `dwFlags` contém um valor inválido. |
| NTE\$1NOT\$1SUPPORTED | O parâmetro `pszAlgId` contém um valor não suportado. |
| NTE\$1EXISTS | Já existe uma chave com o nome especificado e a operação não usou ` NCRYPT_OVERWRITE_KEY_FLAG`. |
# NCryptGetProperty com o provedor de armazenamento de chaves (KSP)
A função `NCryptGetProperty` recupera os valores das propriedades de um objeto de armazenamento de chaves.
## Parâmetros
`hObject` [in]
O identificador do objeto cuja propriedade você deseja recuperar. Você pode usar:
+ Um identificador de provedor (`NCRYPT_PROV_HANDLE`)
+ Um identificador de chave (`NCRYPT_KEY_HANDLE`)
`pszProperty ` [in]
Um ponteiro para uma string Unicode terminada em nulo contendo o nome da propriedade a ser recuperada.
Ao usar`NCRYPT_PROV_HANDLE`, o AWS CloudHSM Key Storage Provider (KSP) oferece suporte aos seguintes identificadores KSP:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
Ao usar`NCRYPT_KEY_HANDLE`, o AWS CloudHSM Key Storage Provider (KSP) oferece suporte aos seguintes identificadores KSP:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
Os valores são literais de string largos, conforme indicado pelo L antes do literal.
`pbOutput` [out]
O endereço de um buffer para armazenar o valor da propriedade. Especifique o tamanho do buffer usando `cbOutput`.
Para determinar o tamanho do buffer necessário, defina esse parâmetro como NULL. A função armazena o tamanho necessário (em bytes) no local apontado por `pcbResult`.
`cbOutput` [in]
O tamanho em bytes do buffer `pbOutput`.
`pcbResult` [out]
Um ponteiro para uma variável DWORD que armazena o número de bytes copiados para o buffer `pbOutput`.
Se `pbOutput` for NULL, isso armazenará o tamanho necessário (em bytes).
`dwFlags` [in]
Sinalizadores para modificar o comportamento da função. Você pode usar zero ou:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
Quando pszProperty for `NCRYPT_SECURITY_DESCR_PROPERTY`, use um ou uma combinação de:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A operação foi concluída com êxito. |
| NTE\$1INVALID\$1PARAMETER | Um ou mais parâmetros não são válidos. |
| NTE\$1FAIL | A operação não foi concluída. |
| NTE\$1BAD\$1FLAGS | O parâmetro `dwFlags` contém um valor inválido. |
| NTE\$1NOT\$1SUPPORTED | O parâmetro `pszAlgId` contém um valor que não é suportado. |
| NTE\$1INVALID\$1HANDLE | O identificador em `hObject` não é válido. |
| NTE\$1BUFFER\$1TOO\$1SMALL | O parâmetro `cbOutput` é muito pequeno para valores de retorno. |
# NCryptSetProperty com o provedor de armazenamento de chaves (KSP)
A função `NCryptSetProperty` define os valores das propriedades para um objeto de armazenamento de chaves.
## Parâmetros
`hObject` [in]
O identificador do objeto cuja propriedade você deseja definir. Você pode usar:
+ Um identificador de provedor (`NCRYPT_PROV_HANDLE`)
+ Um identificador de chave (`NCRYPT_KEY_HANDLE`)
`pszProperty ` [in]
Um ponteiro para uma string Unicode terminada em nulo contendo o nome da propriedade a ser recuperada.
Ao usar`NCRYPT_PROV_HANDLE`, o AWS CloudHSM Key Storage Provider (KSP) oferece suporte aos seguintes identificadores KSP:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-set-property.html)
Ao usar`NCRYPT_KEY_HANDLE`, o AWS CloudHSM Key Storage Provider (KSP) oferece suporte aos seguintes identificadores KSP:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-set-property.html)
Os valores são literais de string largos, conforme indicado pelo L antes do literal.
`pbInput` [in]
O endereço de um buffer que contém o novo valor da propriedade. `cbInput` contém o tamanho do buffer.
`cbInput` [in]
O tamanho em bytes do buffer `pbInput`.
`dwFlags` [in]
Sinalizadores que modificam o comportamento da função. Nenhum sinalizador está definido para essa função.
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A operação foi concluída com êxito. |
| NTE\$1INVALID\$1PARAMETER | Um ou mais parâmetros não são válidos. |
| NTE\$1FAIL | A operação não foi concluída. |
| NTE\$1BAD\$1FLAGS | O parâmetro `dwFlags` contém um valor inválido. |
| NTE\$1NOT\$1SUPPORTED | O parâmetro `pszProperty` contém um valor que não é suportado. |
| NTE\$1INVALID\$1HANDLE | O identificador em `hObject` não é válido. |
| NTE\$1BAD\$1DATA | Os dados apontados por `pbInput` e `cbInput` não são válidos. |
# NCryptFinalizeKey com o provedor de armazenamento de chaves (KSP)
A função `NCryptFinalizeKey` completa uma chave do KSP. Você deve chamar essa função antes de poder usar a chave.
## Parâmetros
`hKey` [in]
O identificador da chave para completar. Obtenha esse identificador chamando a [NCryptCreatePersistedKey](ksp-library-apis-create-persisted-key.md)função.
`dwFlags` [in]
Sinalizadores para modificar o comportamento da função. Você pode usar nenhum ou um destes valores:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-finalize-key.html)
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A operação foi concluída com êxito. |
| NTE\$1FAIL | A operação não foi concluída. |
| NTE\$1INVALID\$1HANDLE | O identificador em `hKey` não é válido. |
| NTE\$1NOT\$1SUPPORTED | O parâmetro `dwFlags` contém um valor que não é suportado. |
| NTE\$1BAD\$1FLAGS | O parâmetro `dwFlags` contém um valor inválido. |
# NCryptDeleteKey com o provedor de armazenamento de chaves (KSP)
A função `NCryptDeleteKey` exclui uma chave KSP do Provedor de armazenamento de chaves (KSP).
## Parâmetros
`hKey` [in]
O identificador da chave a ser excluída.
`dwFlags` [in]
Sinalizadores para modificar o comportamento da função. É possível usar zero ou mais dos seguintes valores:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-delete-key.html)
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A função foi bem-sucedida. |
| NTE\$1INVALID\$1PARAMETER | Um ou mais parâmetros não são válidos. |
| NTE\$1BAD\$1FLAGS | O parâmetro `dwFlags` contém um valor inválido. |
| NTE\$1FAIL | A operação não foi concluída. |
| NTE\$1INVALID\$1HANDLE | O identificador em `hKey` não é válido. |
| NTE\$1INTERNAL\$1ERROR | Ocorreu um erro interno ao excluir a chave. |
# NCryptFreeObject com o provedor de armazenamento de chaves (KSP)
A função `NCryptFreeObject` libera o provedor ou o identificador de chave do Provedor de Armazenamento de Chaves (KSP).
## Parâmetros
`hObject` [in]
O identificador do objeto a ser liberado. Você pode usar:
+ Um identificador de provedor (`NCRYPT_PROV_HANDLE`)
+ Um identificador de chave (`NCRYPT_KEY_HANDLE`)
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A operação foi concluída com êxito. |
| NTE\$1INVALID\$1HANDLE | O identificador em `hObject` não é válido. |
# NCryptFreeBuffer com o provedor de armazenamento de chaves (KSP)
A função `NCryptFreeBuffer` libera um bloco de memória alocado pelo Provedor de armazenamento de chaves (KSP).
## Parâmetros
`pvInput` [in]
O endereço da memória a ser liberada.
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A operação foi concluída com êxito. |
| NTE\$1FAIL | A operação não foi concluída. |
# NCryptIsAlgSupported com o provedor de armazenamento de chaves (KSP)
NCryptIsAlgSupported função determina se o Key Storage Provider (KSP) suporta um algoritmo criptográfico específico.
## Parâmetros
`hProvider` [in]
O identificador do provedor de armazenamento de chaves. Use [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) para obter o identificador.
`pszAlgId` [in]
Um ponteiro para uma string Unicode terminada em nulo que contém o identificador do algoritmo criptográfico para criar a chave. O Provedor de armazenamento de chaves (KSP) do AWS CloudHSM oferece suporte aos seguintes algoritmos:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-is-alg-supported.html)
`dwFlags` [in]
Sinalizadores que modificam o comportamento da função. Esse valor pode ser zero ou os seguintes:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-is-alg-supported.html)
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A operação foi concluída com êxito. |
| NTE\$1INVALID\$1PARAMETER | Um ou mais parâmetros não são válidos. |
| NTE\$1BAD\$1FLAGS | O parâmetro `dwFlags` contém um valor inválido. |
| NTE\$1NOT\$1SUPPORTED | O parâmetro `pszAlgId` contém um valor não suportado. |
| NTE\$1INVALID\$1HANDLE | O identificador em `hProvider` não é válido. |
# NCryptEnumAlgorithms com o provedor de armazenamento de chaves (KSP)
A função `NCryptEnumAlgorithms` recupera os nomes dos algoritmos que o Provedor de armazenamento de chaves (KSP) suporta.
## Parâmetros
`hProvider` [in]
O identificador do provedor de armazenamento de chaves para o qual enumerar os algoritmos. Use a função [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) para obter esse identificador.
`dwAlgOperations` [in]
Um conjunto de valores que especificam quais classes de algoritmo devem ser enumeradas. Use zero para enumerar todos os algoritmos ou combinar um ou mais destes valores:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-enum-algorithms.html)
`pdwAlgCount` [out]
O endereço de um DWORD que armazena o número de elementos na matriz `ppAlgList`.
`ppAlgList` [out]
O endereço de um ponteiro de estrutura `NCryptAlgorithmName` que armazena uma matriz de nomes de algoritmos registrados. O parâmetro `pdwAlgCount` indica o número de elementos nessa matriz.
`dwFlags` [in]
Sinalizadores para modificar o comportamento da função. Use zero ou o seguinte valor:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-enum-algorithms.html)
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A operação foi concluída com êxito. |
| NTE\$1INVALID\$1PARAMETER | Um ou mais parâmetros não são válidos. |
| NTE\$1FAIL | A operação não foi concluída. |
| NTE\$1BAD\$1FLAGS | O parâmetro `dwFlags` contém um valor inválido. |
| NTE\$1NOT\$1SUPPORTED | O parâmetro `dwAlgOperations` contém um valor não suportado. |
# NCryptEnumKeys com o provedor de armazenamento de chaves (KSP)
NCryptEnumKeys função lista as chaves armazenadas no Provedor de Armazenamento de Chaves (KSP).
## Parâmetros
`hProvider` [in]
O identificador do provedor de armazenamento de chaves. Use [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) para obter esse identificador.
`pszScope` [in, unused]
Defina este parâmetro como NULL.
`ppKeyName` [out]
Um endereço de ponteiro para uma estrutura `NCryptKeyName` que armazena o nome da chave. Para liberar essa memória após o uso, chame `NCryptFreeBuffer`.
`ppEnumState` [in, out]
Um endereço de ponteiro VOID que rastreia o progresso da enumeração. O provedor de armazenamento de chaves usa essas informações internamente para gerenciar a sequência de enumeração. Para iniciar uma nova enumeração desde o início, defina esse ponteiro como NULL.
Para liberar essa memória após concluir a enumeração, passe esse ponteiro para `NCryptFreeBuffer`.
`dwFlags` [in]
Sinalizadores para modificar o comportamento da função. A função não tem sinalizadores.
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A operação foi concluída com êxito. |
| NTE\$1INVALID\$1PARAMETER | Um ou mais parâmetros não são válidos. |
| NTE\$1FAIL | A operação não foi concluída. |
| NTE\$1INVALID\$1HANDLE | O identificador em `hProvider` não é válido. |
| NTE\$1NO\$1MORE\$1ITEMS | A enumeração listou todas as chaves disponíveis. |
# NCryptExportKey com o provedor de armazenamento de chaves (KSP)
A função `NCryptExportKey` exporta uma chave do KSP para um BLOB de memória. Essa função é compatível somente com a exportação de chaves públicas.
## Parâmetros
`hKey` [in]
O identificador da chave a ser exportada.
`hExportKey` [in, unused]
AWS CloudHSM O Key Storage Provider (KSP) não usa esse parâmetro.
`pszBlobType` [in]
Uma string Unicode terminada em nulo que especifica o tipo a ser exportado. BLOB AWS CloudHSM O Key Storage Provider (KSP) suporta os seguintes valores:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-export-key.html)
`pParameterList` [in, unused]
AWS CloudHSM O Key Storage Provider (KSP) não usa esse parâmetro.
`pbOutput` [out, optional]
Um endereço de buffer para armazenar o BLOB de chaves. Especifique o tamanho do buffer usando `cbOutput`. Se definida como NULL, a função armazena o tamanho necessário (em bytes) no DWORD apontado por `pcbResult`.
`cbOutput` [in]
O tamanho em bytes do buffer `pbOutput`.
`pcbResult` [out]
Um endereço de variável DWORD que armazena o número de bytes copiados para o buffer `pbOutput`. Se `pbOutput` for NULL, a função armazenará o tamanho de buffer necessário em bytes.
`dwFlags` [in]
Sinalizadores que modificam o funcionamento da função. É possível usar nenhum ou o seguinte:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-export-key.html)
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A operação foi concluída com êxito. |
| NTE\$1INVALID\$1PARAMETER | Um ou mais parâmetros não são válidos. |
| NTE\$1FAIL | A operação não foi concluída. |
| NTE\$1INVALID\$1HANDLE | O identificador em `hProvider` não é válido. |
| NTE\$1BAD\$1FLAGS | O parâmetro `dwFlags` contém um valor inválido. |
| NTE\$1BAD\$1KEY\$1STATE | O estado da chave não é válido. |
| NTE\$1NOT\$1SUPPORTED | O parâmetro `pszBlobType` ou `dwFlags` contém um valor não suportado. |
| STATUS\$1INTERNAL\$1ERROR | Ocorreu um erro interno durante a operação. |
# NCryptSignHash com o provedor de armazenamento de chaves (KSP)
A função `NCryptSignHash` cria uma assinatura de um valor de hash.
## Parâmetros
`hKey` [in]
O identificador da chave a ser usada para assinar o hash.
`pPaddingInfo` [in, optional]
Um ponteiro para uma estrutura contendo informações de preenchimento. O tipo de estrutura depende do valor de `dwFlags`. Use esse parâmetro somente com chaves assimétricas; defina como NULL para outros tipos de chave.
`pbHashValue` [in]
Um ponteiro para um buffer contendo o valor de hash a ser assinado. Especifique o tamanho do buffer usando `cbHashValue`.
`cbHashValue` [in]
O tamanho em bytes do buffer atual de `pbHashValue`.
`pbSignature` [out]
O endereço de um buffer para armazenar a assinatura. Especifique o tamanho do buffer usando `cbSignature`.
Para determinar o tamanho do buffer necessário, defina esse parâmetro como NULL. A função armazena o tamanho necessário (em bytes) no local apontado por `pcbResult`.
`cbSignature` [in]
O tamanho em bytes do buffer `pbSignature`. A função ignora esse parâmetro se `pbSignature` for NULL.
`pcbResult` [out]
Um ponteiro para uma variável DWORD que armazena o número de bytes copiados para o buffer `pbSignature`.
Se `pbSignature` for NULL, isso armazenará o tamanho necessário, em bytes.
`dwFlags` [in]
Sinalizadores para modificar o comportamento da função. Os sinalizadores permitidos dependem do seu tipo de chave. Use um destes valores:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-sign-hash.html)
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A operação foi concluída com êxito. |
| NTE\$1INVALID\$1PARAMETER | Um ou mais parâmetros não são válidos. |
| NTE\$1FAIL | A operação não foi concluída. |
| NTE\$1INVALID\$1HANDLE | O identificador em `hKey` não é válido. |
| NTE\$1BAD\$1FLAGS | O parâmetro `dwFlags` contém um valor inválido. |
| NTE\$1BUFFER\$1TOO\$1SMALL | O parâmetro `pcbOutput` é muito pequeno para valores de retorno. |
| NTE\$1BAD\$1KEY\$1STATE | O estado da chave não é válido. |
| NTE\$1INTERNAL\$1ERROR | Ocorreu um erro interno ao assinar o hash. |
# NCryptVerifySignature com o provedor de armazenamento de chaves (KSP)
A função `NCryptVerifySignature` confirma se uma assinatura corresponde a um hash especificado.
## Parâmetros
`hKey` [in]
O identificador da chave a ser usada para descriptografar a assinatura. Você deve usar a parte da chave pública do par de chaves que foi usada para assinar os dados com [`NCryptSignHash`](ksp-library-apis-sign-hash.md).
`pPaddingInfo` [in, optional]
Um ponteiro para uma estrutura contendo informações de preenchimento. O tipo de estrutura depende do valor de `dwFlags`. Use esse parâmetro somente com chaves assimétricas; defina como NULL para outros tipos de chave.
`pbHashValue` [in]
Um ponteiro para um buffer contendo o valor de hash a ser assinado. Especifique o tamanho do buffer usando `cbHashValue`.
`cbHashValue` [in]
O tamanho em bytes do buffer `pbHashValue`.
`pbSignature` [out]
O endereço de um buffer contendo o hash assinado dos dados. Use [`NCryptSignHash`](ksp-library-apis-sign-hash.md) para criar essa assinatura. Especifique o tamanho do buffer usando `cbSignature`.
`cbSignature` [in]
O tamanho em bytes do buffer `pbSignature`. Use [`NCryptSignHash`](ksp-library-apis-sign-hash.md) para criar a assinatura.
`dwFlags` [in]
Sinalizadores para modificar o comportamento da função. Os sinalizadores permitidos dependem do seu tipo de chave. Use um destes valores:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/ksp-library-apis-verify-signature.html)
## Valor de retorno
A função retorna um código de status para indicar êxito ou falha.
Os códigos de retorno comuns incluem:
****
| Código de retorno | Description |
| --- | --- |
| ERROR\$1SUCCESS | A operação foi concluída com êxito. |
| NTE\$1INVALID\$1PARAMETER | Um ou mais parâmetros não são válidos. |
| NTE\$1FAIL | A operação não foi concluída. |
| NTE\$1INVALID\$1HANDLE | O identificador em `hKey` não é válido. |
| NTE\$1BAD\$1FLAGS | O parâmetro `dwFlags` contém um valor inválido. |
| NTE\$1BAD\$1SIGNATURE | A assinatura não foi verificada. |
| NTE\$1BAD\$1KEY\$1STATE | O estado da chave não é válido. |
| NTE\$1INTERNAL\$1ERROR | Ocorreu um erro interno ao verificar a assinatura. |
# Configurações avançadas do KSP para AWS CloudHSM
O AWS CloudHSM Key Storage Provider (KSP) inclui a seguinte configuração avançada, que não faz parte das configurações gerais que a maioria dos clientes utiliza. Essas configurações fornecem recursos adicionais.
+ [SDK3 modo de compatibilidade para KSP](ksp-library-configs-sdk3-compatibility-mode.md)
# SDK3 modo de compatibilidade do Key Storage Provider (KSP) para AWS CloudHSM
O Provedor de armazenamento de chaves (KSP) implementa diferentes abordagens para a interação de chaves do HSM:
+ Client SDK 5: oferece comunicação direta com as chaves armazenadas no HSM, eliminando a necessidade de arquivos de referência locais
+ Client SDK 3: mantém arquivos locais no servidor Windows que atuam como referências às chaves armazenadas no HSM, usando esses arquivos para facilitar as operações de chaves
Para clientes migrando do Client SDK 3 para o Client SDK 5, ativar a opção do modo de SDK3 compatibilidade suporta operações usando arquivos de referência de chave existentes, preservando a arquitetura subjacente de armazenamento de chaves do HSM.
## Ativar o modo de SDK3 compatibilidade
------
#### [ Windows ]
**Para ativar o modo de SDK3 compatibilidade do Key Storage Provider (KSP) para Client SDK 5 no Windows**
+ Você pode usar o comando a seguir para ativar o modo de SDK3 compatibilidade:
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --enable-sdk3-compatibility-mode
```
------
## Desativar o modo de SDK3 compatibilidade
------
#### [ Windows ]
**Para desativar o modo de SDK3 compatibilidade do Key Storage Provider (KSP) para Client SDK 5 no Windows**
+ Você pode usar o comando a seguir para desativar o modo de SDK3 compatibilidade:
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --disable-sdk3-compatibility-mode
```
------
# Provedor de JCE para AWS CloudHSM Client SDK 5
O provedor AWS CloudHSM JCE é uma implementação de provedor criada a partir da estrutura do provedor Java Cryptographic Extension (JCE). O JCE permite que você execute operações criptográficas usando o Java Development Kit (JDK). Neste guia, o provedor AWS CloudHSM JCE às vezes é chamado de provedor JCE. Use o provedor JCE e o JDK para transferir operações criptográficas para o HSM. Para solução de problemas, consulte [Problemas conhecidos do JCE SDK para AWS CloudHSM](ki-jce-sdk.md).
Para obter mais informações sobre como usar Client SDK 3, consulte [Usando a versão anterior do SDK para trabalhar com AWS CloudHSM](choose-client-sdk.md).
**Topics**
+ [Instale o provedor JCE para o AWS CloudHSM Client SDK 5](java-library-install_5.md)
+ [Tipos de chaves compatíveis com o provedor JCE para o AWS CloudHSM Client SDK 5](java-lib-keys_5.md)
+ [Fundamentos do gerenciamento de chaves no provedor de JCE para o AWS CloudHSM Client SDK 5](java-library-key-basics_5.md)
+ [Mecanismos compatíveis com o provedor JCE para o AWS CloudHSM Client SDK 5](java-lib-supported_5.md)
+ [Atributos de chave Java compatíveis com o AWS CloudHSM Client SDK 5](java-lib-attributes_5.md)
+ [Exemplos de código para a biblioteca AWS CloudHSM de software para Java for Client SDK 5](java-samples.md)
+ [AWS CloudHSM Javadocs, provedor de JCE](java-javadocs_5.md)
+ [AWS CloudHSM KeyStore Classe Java para Client SDK 5](alternative-keystore_5.md)
+ [Configurações avançadas para AWS CloudHSM JCE for Client SDK 5](java-lib-configs.md)
# Instale o provedor JCE para o AWS CloudHSM Client SDK 5
O provedor JCE para o AWS CloudHSM Client SDK 5 é compatível com OpenJDK 8, OpenJDK 11, OpenJDK 17, OpenJDK 21 e OpenJDK 25. Você pode baixar os dois no site do [OpenJDK.](https://openjdk.java.net/)
Use as seções a seguir para instalar e fornecer credenciais ao provedor.
**nota**
Para executar um único cluster HSM com o Client SDK 5, você deve primeiro gerenciar as configurações de durabilidade da chave do cliente configurando `disable_key_availability_check` como `True`. Para obter mais informações, consulte [Sincronização de chave](manage-key-sync.md) e a [ferramenta de configuração do Client SDK 5](configure-sdk-5.md).
**Topics**
+ [Etapa 1: instalar o provedor JCE](#install-java-library_5)
+ [Etapa 2: fornecer credenciais ao provedor JCE](#java-library-credentials_5)
## Etapa 1: instalar o provedor JCE
1. Use so seguintes comandos para fazer download e instalar o provedor JCE.
------
#### [ Amazon Linux 2023 ]
Instale o provedor JCE para Amazon Linux 2023 na arquitetura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-jce-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.amzn2023.x86_64.rpm
```
Instale o provedor JCE para Amazon Linux 2023 na ARM64 arquitetura:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-jce-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.amzn2023.aarch64.rpm
```
------
#### [ Amazon Linux 2 ]
Instale o provedor JCE para Amazon Linux 2 na arquitetura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el7.x86_64.rpm
```
Instale o provedor JCE para Amazon Linux 2 na ARM64 arquitetura:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el7.aarch64.rpm
```
------
#### [ RHEL 10 (10.0\$1) ]
Instale o provedor JCE para RHEL 10 na arquitetura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-jce-latest.el10.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el10.x86_64.rpm
```
Instale o provedor JCE para RHEL 10 na ARM64 arquitetura:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-jce-latest.el10.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el10.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
Instale o provedor JCE para RHEL 9 (9.2\$1) na arquitetura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-jce-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el9.x86_64.rpm
```
Instale o provedor JCE para RHEL 9 (9.2\$1) na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-jce-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el9.aarch64.rpm
```
------
#### [ RHEL 8 (8.3\$1) ]
Instale o provedor JCE para RHEL 8 na arquitetura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-jce-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el8.x86_64.rpm
```
Instale o provedor JCE para RHEL 8 na ARM64 arquitetura:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-jce-latest.el8.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el8.aarch64.rpm
```
------
#### [ Ubuntu 24.04 LTS ]
Instale o provedor JCE para Ubuntu 24.04 LTS na arquitetura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-jce_latest_u24.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u24.04_amd64.deb
```
Instale o provedor JCE para Ubuntu 24.04 LTS na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-jce_latest_u24.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u24.04_arm64.deb
```
------
#### [ Ubuntu 22.04 LTS ]
Instale o provedor JCE para Ubuntu 22.04 LTS na arquitetura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-jce_latest_u22.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u22.04_amd64.deb
```
Instale o provedor JCE para o Ubuntu 22.04 LTS na arquitetura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-jce_latest_u22.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u22.04_arm64.deb
```
------
#### [ Windows Server ]
Instale o provedor JCE para Windows Server na arquitetura x86\$164, abra PowerShell como administrador e execute o seguinte comando:
```
PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMJCE-latest.msi -Outfile C:\AWSCloudHSMJCE-latest.msi
```
```
PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMJCE-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
```
------
1. Bootstrap do Client SDK 5. Para obter mais informações sobre ações de bootstrap, consulte [Bootstrap o Client SDK](cluster-connect.md#connect-how-to).
1. Localize os seguintes arquivos do provedor JCE:
------
#### [ Linux ]
+ `/opt/cloudhsm/java/cloudhsm-.jar`
+ `/opt/cloudhsm/bin/configure-jce`
+ `/opt/cloudhsm/bin/jce-info`
------
#### [ Windows ]
+ `C:\Program Files\Amazon\CloudHSM\java\cloudhsm-.jar>`
+ `C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe`
+ `C:\Program Files\Amazon\CloudHSM\bin\jce_info.exe`
------
## Etapa 2: fornecer credenciais ao provedor JCE
Antes que seu aplicativo Java possa usar um HSM, o HSM precisa primeiro autenticar o aplicativo. HSMs autentique usando um método de login explícito ou implícito.
**Login explícito** AWS CloudHSM esse método permite que você forneça credenciais do diretamente no aplicativo. Ele usa o método [https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html](https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html), em que você passa no mome do usuário, a senha e o ID da partição do HSM do usuário CU. Para obter mais informações, consulte [Exemplo de login em um código HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java).
**Login implícito** AWS CloudHSM esse método permite que você defina as credenciais do em um novo arquivo de propriedades, as propriedades do sistema, ou como variáveis de ambiente.
+ **Propriedades do sistema**: defina as credenciais por meio das propriedades do sistema ao executar seu aplicativo. Os exemplos a seguir mostram duas formas diferentes de fazer isso:
------
#### [ Linux ]
```
$ java -DHSM_USER= -DHSM_PASSWORD=
```
```
System.setProperty("HSM_USER","");
System.setProperty("HSM_PASSWORD","");
```
------
#### [ Windows ]
```
PS C:\> java -DHSM_USER= -DHSM_PASSWORD=
```
```
System.setProperty("HSM_USER","");
System.setProperty("HSM_PASSWORD","");
```
------
+ **Variáveis de ambiente**: defina as credenciais como variáveis de ambiente.
**nota**
Ao definir variáveis de ambiente, você deve escapar de quaisquer caracteres especiais que possam ser interpretados pelo seu shell.
------
#### [ Linux ]
```
$ export HSM_USER=
$ export HSM_PASSWORD=
```
------
#### [ Windows ]
```
PS C:\> $Env:HSM_USER=""
PS C:\> $Env:HSM_PASSWORD=""
```
------
As credenciais talvez não estejam disponíveis se o aplicativo não fornecê-las ou se você tentar uma operação antes que o HSM autentique a sessão. Nesses casos, a biblioteca de software do CloudHSM para Java procura as credenciais na seguinte ordem:
1. Propriedades do sistema
1. Variáveis de ambiente
# Tipos de chaves compatíveis com o provedor JCE para o AWS CloudHSM Client SDK 5
A biblioteca AWS CloudHSM de software para Java permite que você gere os seguintes tipos de chaves.
****
| Tipo de chave | Description |
| --- | --- |
| AES | Gere chaves AES de 128, 192 e 256 bits. |
| DES triplo (3DES, DESede) | Gere uma chave DES tripla de 192 bits. [*](#java-lib-keys_5-note-1) |
| EC | Gere pares de chaves EC com as curvas NIST secp224r1 (P-224), secp256r1 (P-256), secp256k1 (Blockchain), secp384r1 (P-384) e secp521r1 (P-521). |
| GENERIC\$1SECRET | Gerar chaves genéricas de 1 a 800 bytes. |
| HMAC | Suporte de hash para SHA1, SHA224,, SHA256 SHA384, SHA512. |
| RSA | Gera chaves RSA de 2.048 a 4.096 bits, em incrementos de 256 bits. |
\$1 De acordo com a orientação do NIST, isso não é permitido em clusters no modo FIPS após 2023. Para clusters no modo não FIPS, isso ainda é permitido após 2023. Para mais detalhes, consulte [Conformidade com o FIPS 140: suspensão do mecanismo de 2024](compliance-dep-notif.md#compliance-dep-notif-1).
# Fundamentos do gerenciamento de chaves no provedor de JCE para o AWS CloudHSM Client SDK 5
Os conceitos básicos do gerenciamento de chaves no provedor JCE envolvem a importação e a exportação, o carregamento por identificador ou a exclusão de chaves. Para obter mais informações sobre como gerenciar chaves, consulte [Gerenciar chaves](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java) no exemplo de código.
Você também pode encontrar mais amostras de código de provedor JCE em [Exemplos de código](java-samples.md).
# Mecanismos compatíveis com o provedor JCE para o AWS CloudHSM Client SDK 5
Este tópico fornece informações sobre os mecanismos suportados pelo provedor JCE com o AWS CloudHSM Client SDK 5. Para obter informações sobre as interfaces e classes de mecanismo da Java Cryptography Architecture (JCA) suportadas pelo AWS CloudHSM, consulte os tópicos a seguir.
**Topics**
+ [Gere funções de chave e par de chaves](#java-gen-key-pairs-5)
+ [Funções de cifra](#java-ciphers_5)
+ [Funções de assinatura e verificação](#java-sign-verify_5)
+ [Funções de resumo](#java-digests_5)
+ [Funções de código de autenticação de mensagens por hash (HMAC)](#java-mac_5)
+ [Funções de código de autenticação de mensagens baseadas em cifras (CMAC)](#java-cmac_5)
+ [Funções-chave do contrato](#java-key-derivation_5)
+ [Converta chaves em especificações de chave usando fábricas de chaves](#java-key-factories)
+ [Anotações do mecanismo](#w2aac25c21c25c15c23)
## Gere funções de chave e par de chaves
A biblioteca AWS CloudHSM de software para Java permite que você use as seguintes operações para gerar funções de chave e par de chaves.
+ `RSA`
+ `EC`
+ `AES`
+ `DESede (Triple DES)`consulte a observação [1](#java-gen-key-pairs-5-note-1)
+ `GenericSecret`
## Funções de cifra
A biblioteca AWS CloudHSM de software para Java suporta as seguintes combinações de algoritmo, modo e preenchimento.
| Algoritmo | Modo | Padding | Observações |
| --- | --- | --- | --- |
| AES | CBC | `AES/CBC/NoPadding` `AES/CBC/PKCS5Padding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. Implementa `Cipher.UNWRAP_MODE for AES/CBC NoPadding` |
| AES | ECB | `AES/ECB/PKCS5Padding` `AES/ECB/NoPadding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. |
| AES | CTR | `AES/CTR/NoPadding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. |
| AES | GCM | `AES/GCM/NoPadding` | Implementa `Cipher.WRAP_MODE`, `Cipher.UNWRAP_MODE`, `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`.Ao executar a criptografia AES-GCM, o HSM ignora o vetor de inicialização (IV) na solicitação e usa um IV que ele mesmo gera. Quando a operação for concluída, você deverá chamar `Cipher.getIV()` para obter o IV. |
| AESWrap | ECB | `AESWrap/ECB/NoPadding` `AESWrap/ECB/PKCS5Padding` `AESWrap/ECB/ZeroPadding` | Implementa `Cipher.WRAP_MODE` e `Cipher.UNWRAP_MODE`. |
| DESede (DES triplo) | CBC | `DESede/CBC/PKCS5Padding` `DESede/CBC/NoPadding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. Consulte a nota [1](#java-gen-key-pairs-5-note-1) abaixo para ver uma mudança futura. |
| DESede (DES triplo) | ECB | `DESede/ECB/NoPadding` `DESede/ECB/PKCS5Padding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. Consulte a nota [1](#java-gen-key-pairs-5-note-1) abaixo para ver uma mudança futura. |
| RSA | ECB | `RSA/ECB/PKCS1Padding` **consulte a observação [1](#java-gen-key-pairs-5-note-1)** `RSA/ECB/OAEPPadding` `RSA/ECB/OAEPWithSHA-1ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-224ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-256ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-384ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-512ANDMGF1Padding` | Implementa `Cipher.WRAP_MODE`, `Cipher.UNWRAP_MODE`, `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. |
| RSA | ECB | `RSA/ECB/NoPadding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. |
| RSAAESWrap | ECB | `RSAAESWrap/ECB/OAEPPadding` `RSAAESWrap/ECB/OAEPWithSHA-1ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-224ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-256ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-384ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-512ANDMGF1Padding` | Implementa `Cipher.WRAP_MODE` e `Cipher.UNWRAP_MODE`. |
## Funções de assinatura e verificação
A biblioteca AWS CloudHSM de software para Java suporta os seguintes tipos de assinatura e verificação. Com o Client SDK 5 e algoritmos de assinatura com hashing, os dados são codificados localmente no software antes de serem enviados ao HSM para assinatura/verificação. Isso significa que não há limite no tamanho dos dados que podem ser criptografados pelo SDK.
**Tipos de assinatura RSA**
+ `NONEwithRSA`
+ `RSASSA-PSS`
+ `SHA1withRSA`
+ `SHA1withRSA/PSS`
+ `SHA1withRSAandMGF1`
+ `SHA224withRSA`
+ `SHA224withRSAandMGF1`
+ `SHA224withRSA/PSS`
+ `SHA256withRSA`
+ `SHA256withRSAandMGF1`
+ `SHA256withRSA/PSS`
+ `SHA384withRSA`
+ `SHA384withRSAandMGF1`
+ `SHA384withRSA/PSS`
+ `SHA512withRSA`
+ `SHA512withRSAandMGF1`
+ `SHA512withRSA/PSS`
**Tipos de assinatura ECDSA**
+ `NONEwithECDSA`
+ `SHA1withECDSA`
+ `SHA224withECDSA`
+ `SHA256withECDSA`
+ `SHA384withECDSA`
+ `SHA512withECDSA`
## Funções de resumo
A biblioteca AWS CloudHSM de software para Java suporta os seguintes resumos de mensagens. Com o Client SDK 5, os dados são codificados localmente no software. Isso significa que não há limite no tamanho dos dados que podem ser criptografados pelo SDK.
+ `SHA-1`
+ `SHA-224`
+ `SHA-256`
+ `SHA-384`
+ `SHA-512`
## Funções de código de autenticação de mensagens por hash (HMAC)
A biblioteca AWS CloudHSM de software para Java suporta os seguintes algoritmos HMAC.
+ `HmacSHA1` (Tamanho máximo de dados em bytes: 16288)
+ `HmacSHA224` (Tamanho máximo de dados em bytes: 16256)
+ `HmacSHA256` (Tamanho máximo de dados em bytes: 16288)
+ `HmacSHA384` (Tamanho máximo de dados em bytes: 16224)
+ `HmacSHA512` (Tamanho máximo de dados em bytes: 16224)
## Funções de código de autenticação de mensagens baseadas em cifras (CMAC)
CMACs (códigos de autenticação de mensagens baseados em cifras) crie códigos de autenticação de mensagens (MACs) usando uma cifra de bloco e uma chave secreta. Eles diferem HMACs porque usam um método de chave simétrica de bloco para o, MACs em vez de um método de hash.
A biblioteca AWS CloudHSM de software para Java suporta os seguintes algoritmos CMAC.
+ `AESCMAC`
## Funções-chave do contrato
A biblioteca AWS CloudHSM de software para Java suporta ECDH com Key Derivation Functions (KDF). Há suporte para os seguintes tipos de KDF:
+ `ECDHwithX963SHA1KDF`Suporta o algoritmo X9.63 KDF SHA1 [2](#kdf2)
+ `ECDHwithX963SHA224KDF`Suporta o algoritmo X9.63 KDF SHA224 [2](#kdf2)
+ `ECDHwithX963SHA256KDF`Suporta o algoritmo X9.63 KDF SHA256 [2](#kdf2)
+ `ECDHwithX963SHA384KDF`Suporta o algoritmo X9.63 KDF SHA384 [2](#kdf2)
+ `ECDHwithX963SHA512KDF`Suporta o algoritmo X9.63 KDF SHA512 [2](#kdf2)
## Converta chaves em especificações de chave usando fábricas de chaves
Você pode usar fábricas de chaves para converter chaves em especificações principais. AWS CloudHSM tem dois tipos de fábricas principais para a JCE:
**SecretKeyFactory:** usado para importar ou derivar chaves simétricas. Usando SecretKeyFactory, você pode passar uma chave compatível ou uma compatível KeySpec para importar ou derivar chaves simétricas. AWS CloudHSM A seguir estão as especificações suportadas para KeyFactory:
+ As seguintes [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html)classes SecretKeyFactory do `generateSecret` método For são suportadas:
+ **KeyAttributesMap**pode ser usado para importar bytes de chave com atributos adicionais como uma chave do CloudHSM. Um exemplo pode ser encontrado [aqui](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)
+ **[SecretKeySpec](https://docs.oracle.com/javase/8/docs/api/javax/crypto/spec/SecretKeySpec.html)**pode ser usado para importar uma especificação de chave simétrica como uma chave do CloudHSM.
+ **AesCmacKdfParameterSpec**pode ser usado para derivar chaves simétricas usando outra chave AES do CloudHSM.
**nota**
SecretKeyFactoryO `translateKey` método de usa qualquer chave que implemente a interface da [chave](https://docs.oracle.com/javase/8/docs/api/java/security/Key.html).
**KeyFactory:** usado para importar chaves assimétricas. Usando KeyFactory, você pode passar uma chave compatível ou compatível KeySpec para importar uma chave assimétrica. AWS CloudHSM Para obter mais informações, consulte os seguintes recursos:
+ Para KeyFactory o `generatePublic` método de For, [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html)as seguintes classes são suportadas:
+ KeyAttributesMap CloudHSM para RSA e EC, incluindo: KeyTypes
+ KeyAttributesMap CloudHSM para o público da RSA e da EC. KeyTypes Um exemplo pode ser encontrado [aqui](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)
+ [X509 EncodedKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/X509EncodedKeySpec.html) para chave pública RSA e EC
+ [RSAPublicKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/RSAPublicKeySpec.html)para chave pública RSA
+ [ECPublicKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/ECPublicKeySpec.html)para EC Public Key
+ Para KeyFactory o `generatePrivate` método de For, [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html)as seguintes classes são suportadas:
+ KeyAttributesMap CloudHSM para RSA e EC, incluindo: KeyTypes
+ KeyAttributesMap CloudHSM para o público da RSA e da EC. KeyTypes Um exemplo pode ser encontrado [aqui](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)
+ [PKCS8EncodedKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/PKCS8EncodedKeySpec.html)para chaves privadas EC e RSA
+ [RSAPrivateCrtKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/RSAPrivateCrtKeySpec.html)para chave privada RSA
+ [ECPrivateKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/ECPrivateKeySpec.html)para chave privada EC
KeyFactoryO `translateKey` método de For usa qualquer chave que implemente a [interface chave](https://docs.oracle.com/javase/8/docs/api/java/security/Key.html).
## Anotações do mecanismo
[1] De acordo com a orientação do NIST, isso não é permitido em clusters no modo FIPS após 2023. Para clusters no modo não FIPS, isso ainda é permitido após 2023. Para mais detalhes, consulte [Conformidade com o FIPS 140: suspensão do mecanismo de 2024](compliance-dep-notif.md#compliance-dep-notif-1).
[2] As funções de derivação de chaves (KDFs) estão especificadas na [Publicação Especial 800-56A do NIST](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf), Revisão 3.
# Atributos de chave Java compatíveis com o AWS CloudHSM Client SDK 5
Este tópico fornece informações sobre os atributos de chave Java compatíveis com o AWS CloudHSM Client SDK 5. Este tópico descreve como usar uma extensão proprietária para o provedor JCE para definir atributos de chave. Use essa extensão para definir atributos de chave compatíveis e seus valores durante estas operações:
+ Geração de chaves
+ Importação de chaves
Para obter exemplos de como usar os principais atributos, consulte [Exemplos de código para a biblioteca AWS CloudHSM de software para Java for Client SDK 5](java-samples.md).
**Topics**
+ [Noções básicas sobre atributos](#java-understanding-attributes_5)
+ [Atributos do compatíveis](#java-attributes_5)
+ [Definir atributos para uma chave](#java-setting-attributes_5)
## Noções básicas sobre atributos
Use atributos de chave para especificar quais ações são permitidas em objetos de chave, incluindo chaves púbicas, privadas ou secretas. Defina os atributos e valores de chave durante as operações de criação de objetos de chave.
A Java Cryptography Extension (JCE) não especifica como você deve definir valores em atributos de chave, portanto, a maioria das ações foi permitida por padrão. Em contrapartida, o padrão PKCS \$111 define um conjunto de atributos abrangente com padrões mais restritivos. Começando com o provedor JCE 3.1, AWS CloudHSM fornece uma extensão proprietária que permite definir valores mais restritivos para atributos comumente usados.
## Atributos do compatíveis
É possível definir valores para atributos listados na tabela abaixo. Como melhor prática, defina valores somente para os atributos que deseja tornar restritivos. Se você não especificar um valor, AWS CloudHSM usa o valor padrão especificado na tabela abaixo. Uma célula vazia nas colunas Valor padrão indica que não há nenhum valor padrão específico atribuído ao atributo.
****
| Atributo | Valor padrão | Observações | | Chave simétrica | Chave pública no par de chaves | Chave privada no par de chaves | |
| --- | --- | --- | --- | --- | --- | --- | --- |
| DECRYPT | TRUE | | TRUE | True indica que você pode usar a chave para descriptografar qualquer buffer. Geralmente, você define isso como FALSE para uma chave cujo WRAP esteja definido como true. |
| DERIVE | | | | Permite que uma chave seja usada para obter outras chaves. |
| ENCRYPT | TRUE | TRUE | | True indica que você pode usar a chave para criptografar qualquer buffer. |
| EXTRACTABLE | TRUE | | TRUE | True indica que você pode exportar essa chave para fora do HSM. |
| ID | | | | Um valor definido pelo usuário usado para identificar a chave. |
| KEY\$1TYPE | | | | Usado para identificar o tipo de chave (AES DESede, segredo genérico, EC ou RSA). |
| LABEL | | | | Uma string definida pelo usuário que permite que você identifique convenientemente as chaves no seu HSM. Para seguir as melhores práticas, use um rótulo exclusivo para cada chave para que seja mais fácil encontrá-la posteriormente. |
| LOCAL | | | | Indica uma chave gerada pelo HSM. |
| OBJECT\$1CLASS | | | | Usado para identificar a classe de objeto de uma chave (SecretKey PublicKey ou PrivateKey). |
| PRIVATE | TRUE | TRUE | TRUE | True indica que um usuário pode não acessar a chave até que o usuário seja autenticado. Para maior clareza, os usuários não podem acessar nenhuma chave AWS CloudHSM até serem autenticados, mesmo que esse atributo esteja definido como FALSE. |
| SIGN | TRUE | | TRUE | True indica que você pode usar a chave para assinar um resumo de mensagens. Geralmente, é definido como FALSE para chaves públicas e para chaves privadas arquivadas. |
| SIZE | | | | Um atributo que define o tamanho de uma chave. Para obter mais detalhes sobre os tamanhos de chave compatíveis, consulte [Supported mechanisms for Client SDK 5](https://docs.aws.amazon.com/cloudhsm/latest/userguide/java-lib-supported_5.html#java-keys_5). |
| TOKEN | FALSE | FALSE | FALSE | Uma chave permanente que é replicada HSMs em todo o cluster e incluída nos backups. TOKEN = FALSE implica uma chave efêmera que é apagada automaticamente quando a conexão com o HSM é interrompida ou é feito logout. |
| UNWRAP | TRUE | | TRUE | True indica que você pode usar a chave para desencapsular (importar) outra chave. |
| VERIFY | TRUE | TRUE | | True indica que você pode usar a chave para verificar uma assinatura. Isso geralmente é definido como FALSE para chaves privadas. |
| WRAP | TRUE | TRUE | | True indica que você pode usar a chave para encapsular outra chave. Geralmente, isso é definido como FALSE para chaves privadas. |
| WRAP\$1WITH\$1TRUSTED | FALSE | | FALSE | Verdadeiro indica que uma chave só pode ser encapsulada e desencapsulada com chaves que tenham o atributo TRUSTED definido como verdadeiro. Depois que uma chave tem o WRAP\$1WITH\$1TRUSTED definido como verdadeiro, esse atributo é somente para leitura e não pode ser definido como falso. Para ler sobre o agrupamento confiável, consulte [Using trusted keys to control key unwraps](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_using_trusted_keys_control_key_wrap.html). |
**nota**
Você obterá maior suporte para atributos na biblioteca PKCS \$111. Para obter mais informações, consulte [Atributos PKCS \$111 compatíveis](pkcs11-attributes.md).
## Definir atributos para uma chave
O `KeyAttributesMap` é um objeto semelhante ao Mapa Java, que pode ser usado para definir valores de atributos para objetos de chave. Os métodos para a função `KeyAttributesMap` funcionam de forma semelhante aos métodos usados na manipulação de mapa Java.
Para definir valores personalizados, existem duas opções:
+ Usar os métodos listados na tabela a seguir
+ Usar padrões do construtor demonstrados posteriormente nesse documento.
Os objetos de mapa de atributos oferecem suporte para os seguintes métodos para definir atributos:
****
| Operation | Valor de retorno | Método `KeyAttributesMap` |
| --- | --- | --- |
| Obter o valor de um atributo de chave para uma chave existente | Objeto (contendo o valor) ou nulo | **get**(keyAttribute) |
| Preencher o valor de um atributo de chave | O valor anterior associado a um atributo de chave, ou nulo se não houver mapeamento para um atributo de chave | **put**(keyAttribute, valor) |
| Preencher valores para múltiplos atributos de chave | N/D | **putAll** () keyAttributesMap |
| Remover um par de valor-chave do mapa de atributos | O valor anterior associado a um atributo de chave, ou *nulo* se não houver mapeamento para um atributo de chave | **remove**(keyAttribute) |
**nota**
Todos os atributos que você não especificar explicitamente serão definidos como os padrões listados na tabela anterior em [Atributos do compatíveis](#java-attributes_5).
### Definir atributos para um par de chaves
Use a classe Java `KeyPairAttributesMap` para manipular atributos de chave para um par de chaves. O `KeyPairAttributesMap` encapsula dois objetos `KeyAttributesMap`; um para uma chave pública e outro para uma chave privada.
Para definir atributos individuais para a chave pública e privada separadamente, é possível usar o método `put()` no objeto de mapa `KeyAttributes` correspondente para essa chave. Use o método `getPublic()` para recuperar o mapa de atributos para a chave pública e use `getPrivate()` para recuperar o mapa de atributos para a chave privada. Preencha o valor de múltiplos atributos de chave para os pares de chaves públicas e privadas usando `putAll()` com um mapa de atributos de um par de chaves como argumento.
# Exemplos de código para a biblioteca AWS CloudHSM de software para Java for Client SDK 5
Este tópico fornece recursos e informações sobre exemplos de código Java para o Client SDK 5 do AWS CloudHSM .
## Pré-requisitos
Antes de executar as amostras, você deve configurar seu ambiente:
+ Instale e configure o provedor [Java Cryptographic Extension (JCE – extensão de criptografia Java)](java-library-install_5.md#install-java-library_5).
+ Configure um [nome de usuário e senha de HSM](manage-hsm-users.md) válidos. As permissões do usuário de criptografia (CU) são suficientes para essas tarefas. O aplicativo usa essas credenciais para fazer login no HSM em cada exemplo.
+ Decida como fornecer credenciais ao provedor [JCE](java-library-install_5.md#java-library-credentials_5).
## Exemplos de código
Os exemplos de código a seguir mostram como usar o [provedor JCE AWS CloudHSM](java-library.md) para realizar tarefas básicas. Mais exemplos de código estão disponíveis em [GitHub](https://github.com/aws-samples/aws-cloudhsm-jce-examples/tree/sdk5).
+ [Log in to an HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java)
+ [Gerenciar chaves](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)
+ [Gerar chaves simétricas](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java)
+ [Gerar chaves assimétricas](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AsymmetricKeys.java)
+ [Encrypt and decrypt with AES-GCM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java)
+ [Encrypt and decrpyt with AES-CTR](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESCTREncryptDecryptRunner.java)
+ [https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/DESedeECBEncryptDecryptRunner.java](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/DESedeECBEncryptDecryptRunner.java)
+ [Assinatura e verificação com chaves RSA](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/RSAOperationsRunner.java)
+ [Assinatura e verificação com chaves EC](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/ECOperationsRunner.java)
+ [Use supported key attributes](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyAttributesRunner.java)
+ [ Use the CloudHSM key store](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyStoreExampleRunner.java)
[1] De acordo com a orientação do NIST, isso não é permitido em clusters no modo FIPS após 2023. Para clusters no modo não FIPS, isso ainda é permitido após 2023. Para mais detalhes, consulte [Conformidade com o FIPS 140: suspensão do mecanismo de 2024](compliance-dep-notif.md#compliance-dep-notif-1).
# AWS CloudHSM Javadocs, provedor de JCE
Use o Provedor JCE Javadocs para obter informações de uso sobre os tipos e métodos Java definidos no JCE do SDK do AWS CloudHSM. Para baixar os Javadocs mais recentes AWS CloudHSM, consulte a [AWS CloudHSM versão mais recente do SDK do cliente](latest-releases.md) seção na página Downloads.
Você pode importar Javadocs em um ambiente de desenvolvimento integrado (IDE) ou visualizá-los em um navegador da Web.
# AWS CloudHSM KeyStore Classe Java para Client SDK 5
A AWS CloudHSM `KeyStore` classe fornece um armazenamento de PKCS12 chaves para fins especiais. Este repositório de chaves pode armazenar certificados junto com os seus dados de chave e correlacioná-los com os dados da chave armazenados no AWS CloudHSM. A AWS CloudHSM `KeyStore` classe implementa a `KeyStore` Service Provider Interface (SPI) da Java Cryptography Extension (JCE). Para obter mais informações sobre o uso`KeyStore`, consulte [Classe KeyStore](https://devdocs.io/openjdk~8/java/security/keystore).
**nota**
Como os certificados são informações públicas e, para maximizar a capacidade de armazenamento de chaves criptográficas, AWS CloudHSM não oferece suporte ao armazenamento de certificados em HSMs.
## Escolha o armazenamento de chaves apropriado para o AWS CloudHSM Client SDK 5
O provedor de AWS CloudHSM Java Cryptographic Extension (JCE) oferece um AWS CloudHSM para fins especiais. KeyStore A AWS CloudHSM `KeyStore` classe oferece suporte ao descarregamento de operações-chave para o HSM, ao armazenamento local de certificados e às operações baseadas em certificados.
Carregue o CloudHSM para fins especiais da seguinte forma: KeyStore
```
KeyStore ks = KeyStore.getInstance("CloudHSM")
```
## Inicializar o AWS CloudHSM KeyStore Client SDK 5
Faça login AWS CloudHSM KeyStore da mesma forma que você faz login no provedor JCE. Você pode usar variáveis de ambiente ou o arquivo de propriedades do sistema e deve fazer login antes de começar a usar o CloudHSM KeyStore. Para obter um exemplo de login em um HSM usando o JCE, consulte [Login em um HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java).
Se desejar, você pode especificar uma senha para criptografar o PKCS12 arquivo local que contém os principais dados do armazenamento. Ao criar o AWS CloudHSM Keystore, você define a senha e a fornece ao usar os métodos load, set e get.
Instancie um novo objeto CloudHSM da seguinte forma: KeyStore
```
ks.load(null, null);
```
Grave dados de repositório de chaves em um arquivo usando o método `store`. A partir desse ponto, você pode carregar o repositório de chaves existente usando o método `load` com o arquivo de origem e a senha da seguinte forma:
```
ks.load(inputStream, password);
```
## Use AWS CloudHSM KeyStore nosso SDK de AWS CloudHSM cliente 5
AWS CloudHSM KeyStore está em conformidade com a KeyStore especificação da [classe](https://devdocs.io/openjdk~8/java/security/keystore) JCE e fornece as seguintes funções.
+ `load`
Carrega o repositório de chaves do fluxo de entrada fornecido. Se uma senha foi definida ao salvar o repositório de chaves, essa mesma senha deve ser fornecida para que o carregamento seja bem-sucedido. Defina ambos os parâmetros como null para inicializar um novo repositório de chaves vazio.
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
ks.load(inputStream, password);
```
+ `aliases`
Retorna uma enumeração dos nomes de alias de todas as entradas na instância de repositório de chaves dada. Os resultados incluem objetos armazenados localmente no PKCS12 arquivo e objetos residentes no HSM.
**Código de exemplo:**
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
for(Enumeration entry = ks.aliases(); entry.hasMoreElements();) {
String label = entry.nextElement();
System.out.println(label);
}
```
+ `containsalias`
Retorna true se o repositório de chaves tiver acesso a pelo menos um objeto com o alias especificado. O armazenamento de chaves verifica os objetos armazenados localmente no PKCS12 arquivo e os objetos residentes no HSM.
+ `deleteEntry`
Exclui uma entrada de certificado do PKCS12 arquivo local. A exclusão de dados-chave armazenados em um HSM não é suportada usando o. AWS CloudHSM KeyStore Você pode excluir chaves usando o método `destroy` da interface [Destrutível](https://devdocs.io/openjdk~8/javax/security/auth/destroyable#destroy--).
```
((Destroyable) key).destroy();
```
+ `getCertificate`
Retorna o certificado associado a um alias, se disponível. Se o alias não existir ou fizer referência a um objeto que não for um certificado, a função retornará NULL.
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
Certificate cert = ks.getCertificate(alias);
```
+ `getCertificateAlias`
Retorna o nome (alias) da primeira entrada de repositório de chaves cujos dados correspondem ao certificado fornecido.
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
String alias = ks.getCertificateAlias(cert);
```
+ `getCertificateChain`
Retorna a cadeia de certificados associada ao alias fornecido. Se o alias não existir ou fizer referência a um objeto que não for um certificado, a função retornará NULL.
+ `getCreationDate`
Retorna a data de criação da entrada identificada pelo alias fornecido. Se uma data de criação não estiver disponível, a função retornará a data em que o certificado se tornou válido.
+ `getKey`
GetKey é passado para o HSM e retorna um objeto chave correspondente ao rótulo fornecido. Ao consultar `getKey` diretamente o HSM, ela pode ser usada para qualquer chave no HSM, independentemente de ter sido gerada pelo. KeyStore
```
Key key = ks.getKey(keyLabel, null);
```
+ `isCertificateEntry`
Verifica se a entrada com o alias fornecido representa uma entrada de certificado.
+ `isKeyEntry`
Verifica se a entrada com o alias fornecido representa uma entrada de chave. A ação pesquisa o alias no PKCS12 arquivo e no HSM.
+ `setCertificateEntry`
Atribui o certificado fornecido ao alias fornecido. Se o alias fornecido já estiver sendo usado para identificar uma chave ou certificado, um `KeyStoreException` é lançado. Você pode usar o código JCE para obter o objeto chave e, em seguida, usar o KeyStore `SetKeyEntry` método para associar o certificado à chave.
+ `setKeyEntry` com chave `byte[]`
**No momento, essa API não é compatível com o Client SDK 5.**
+ `setKeyEntry` com objeto `Key`
Atribui a chave fornecida ao alias fornecido e armazena-a dentro do HSM. Se a chave ainda não existir dentro do HSM, ela será importada para o HSM como uma chave de sessão extraível.
Se o objeto `Key` for do tipo `PrivateKey`, ele deve ser acompanhado por uma cadeia de certificados correspondente.
Se o alias já existir, a `SetKeyEntry` chamada lança um `KeyStoreException` e impede que a chave seja substituída. Se a chave precisar ser substituída, use KMU ou JCE para esse fim.
+ `engineSize`
Retorna o número de entradas no repositório de chaves.
+ `store`
Armazena o armazenamento de chaves no fluxo de saída fornecido como um PKCS12 arquivo e o protege com a senha fornecida. Além disso, mantém todas as chaves carregadas (que são definidas usando chamadas `setKey`).
# Configurações avançadas para AWS CloudHSM JCE for Client SDK 5
O provedor de AWS CloudHSM JCE inclui as seguintes configurações avançadas, que não fazem parte das configurações gerais que a maioria dos clientes utiliza.
+ [Conectando-se a vários clusters](java-lib-configs-multi.md)
+ [Extração de chaves usando JCE](java-lib-configs-getencoded.md)
+ [Repita a configuração para JCE](java-lib-configs-retry.md)
# Conectando-se a vários AWS CloudHSM clusters com o provedor JCE
Essa configuração permite que uma única instância cliente se comunique com vários clusters do AWS CloudHSM . Comparado a ter uma única instância se comunicando apenas com um único cluster, esse pode ser um atributo de economia de custos para alguns casos de uso. A `CloudHsmProvider` classe é a implementação AWS CloudHSM da [classe Provider da Java Security](https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html). Cada instância dessa classe representa uma conexão com todo o AWS CloudHSM cluster. Você instancia essa classe e a adiciona à lista do provedor de segurança Java para poder interagir com ela usando classes JCE padrão.
O exemplo a seguir instancia essa classe e a adiciona à lista do provedor de segurança Java:
```
if (Security.getProvider(CloudHsmProvider.PROVIDER_NAME) == null) {
Security.addProvider(new CloudHsmProvider());
}
```
`CloudHsmProvider`pode ser configurado de duas maneiras:
1. Configurar com arquivo (configuração padrão)
1. Configurar usando código
Os tópicos a seguir descrevem essas configurações e como se conectar a vários clusters.
**Topics**
+ [Configurar a classe `CloudHsmProvider` do AWS CloudHSM com um arquivo (configuração padrão)](java-lib-configs-default.md)
+ [Configurar a classe `CloudHsmProvider` do AWS CloudHSM usando código](java-lib-configs-using-code.md)
+ [Conecte-se a vários AWS CloudHSM clusters](java-lib-connecting-to-multiclusters.md)
# Configurar a classe `CloudHsmProvider` do AWS CloudHSM com um arquivo (configuração padrão)
A forma padrão de configurar a AWS CloudHSM `CloudHsmProvider` classe é com um arquivo.
Quando você instancia `CloudHsmProvider` usando o construtor padrão, por padrão, ele procurará o arquivo de configuração no `/opt/cloudhsm/etc/cloudhsm-jce.cfg` caminho no Linux. Esse arquivo de configuração pode ser configurado usando `configure-jce`.
Um objeto criado usando o construtor padrão usará o nome padrão do provedor do CloudHSM `CloudHSM`. O nome do provedor é útil para interagir com o JCE para que ele saiba qual provedor usar para várias operações. Um exemplo de uso do nome do provedor CloudHSM para a operação Cipher é o seguinte:
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "CloudHSM");
```
# Configurar a classe `CloudHsmProvider` do AWS CloudHSM usando código
A partir do Client SDK versão 5.8.0, você também pode configurar a AWS CloudHSM `CloudHsmProvider` classe usando o código Java. A maneira de fazer isso é usando um objeto de `CloudHsmProviderConfig` classe. Você pode criar esse objeto usando`CloudHsmProviderConfigBuilder`.
`CloudHsmProvider`tem outro construtor que pega o `CloudHsmProviderConfig` objeto, como mostra o exemplo a seguir.
**Example**
```
CloudHsmProviderConfig config = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath)
.withClusterUniqueIdentifier("CloudHsmCluster1")
.withServer(CloudHsmServer.builder().withHostIP(hostName).build())
.build())
.build();
CloudHsmProvider provider = new CloudHsmProvider(config);
```
Neste exemplo, o nome do provedor JCE é `CloudHsmCluster1`. Este é o nome que a aplicação pode então usar para interagir com o JCE:
**Example**
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "CloudHsmCluster1");
```
Como alternativa, os aplicativos também podem usar o objeto provedor criado acima para informar à JCE que deve usar esse provedor para a operação:
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider);
```
Se um identificador exclusivo não for especificado com o método `withClusterUniqueIdentifier`, um nome de provedor gerado aleatoriamente será criado para você. Para obter esse identificador gerado aleatoriamente, os aplicativos podem chamar `provider.getName()` para obter o identificador.
# Conecte-se a vários AWS CloudHSM clusters
Cada um `CloudHsmProvider` representa uma conexão com seu AWS CloudHSM cluster. Se quiser se comunicar com outro cluster do mesmo aplicativo, você pode criar outro objeto de `CloudHsmProvider` com configurações para seu outro cluster e interagir com esse outro cluster usando o objeto provedor ou usando o nome do provedor, conforme mostrado no exemplo a seguir.
**Example**
```
CloudHsmProviderConfig config = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath)
.withClusterUniqueIdentifier("CloudHsmCluster1")
.withServer(CloudHsmServer.builder().withHostIP(hostName).build())
.build())
.build();
CloudHsmProvider provider1 = new CloudHsmProvider(config);
if (Security.getProvider(provider1.getName()) == null) {
Security.addProvider(provider1);
}
CloudHsmProviderConfig config2 = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath2)
.withClusterUniqueIdentifier("CloudHsmCluster2")
.withServer(CloudHsmServer.builder().withHostIP(hostName2).build())
.build())
.build();
CloudHsmProvider provider2 = new CloudHsmProvider(config2);
if (Security.getProvider(provider2.getName()) == null) {
Security.addProvider(provider2);
}
```
Depois de configurar os dois provedores (os dois clusters) acima, você pode interagir com eles usando o objeto do provedor ou usando o nome do provedor.
Expandindo esse exemplo que mostra como falar com`cluster1`, você pode usar o exemplo a seguir para uma AES/GCM/NoPadding operação:
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider1);
```
E no mesmo aplicativo para fazer a geração da chave “AES” no segundo cluster usando o nome do provedor, você também pode usar o seguinte exemplo:
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider2.getName());
```
# Extração de chaves usando JCE para AWS CloudHSM
A Java Cryptography Extension (JCE) usa uma arquitetura que permite que diferentes implementações de criptografia sejam conectadas. AWS CloudHSM envia um desses fornecedores de JCE que transfere operações criptográficas para o HSM. Para que a maioria dos outros provedores de JCE trabalhem com chaves armazenadas no AWS CloudHSM, eles devem extrair os bytes HSMs da chave em texto não criptografado na memória da sua máquina para serem usados. HSMs normalmente só permitem que as chaves sejam extraídas como objetos agrupados, não como texto claro. No entanto, para oferecer suporte a casos de uso de integração entre provedores, AWS CloudHSM permite uma opção de configuração opcional para permitir a extração dos bytes da chave em branco.
**Importante**
A JCE transfere as operações para AWS CloudHSM sempre que o provedor do AWS CloudHSM é especificado ou um objeto chave é usado. AWS CloudHSM Você não precisa extrair as chaves de forma clara se você espera que sua operação ocorra dentro do HSM. A extração de chaves em texto não criptografado só é necessária quando seu aplicativo não pode usar mecanismos seguros, como empacotar e desempacotar uma chave devido a restrições de uma biblioteca terceirizada ou de um provedor de JCE.
O provedor AWS CloudHSM JCE permite a extração de **chaves públicas** para funcionar com provedores JCE externos por padrão. Os seguintes métodos são sempre permitidos:
| Classe | Método | Format (getEncoded) |
| --- | --- | --- |
| EcPublicKey | getEncoded() | X.509 |
| | getW() | N/D |
| RSAPublicChave | getEncoded() | X.509 |
| | getPublicExponent() | N/D |
| CloudHsmRsaPrivateCrtKey | getPublicExponent() | N/D |
O provedor AWS CloudHSM JCE não permite a extração de bytes de chave em branco para as chaves **privadas** ou **secretas** por padrão. Se seu caso de uso exigir isso, você pode habilitar a extração de bytes de chave em branco para chaves **privadas** ou **secretas** nas seguintes condições:
1. O `EXTRACTABLE` atributo para chaves privadas e secretas é definido como **verdadeiro**.
+ Por padrão, o `EXTRACTABLE` atributo para chaves privadas e secretas é definido como **verdadeiro**. Chaves `EXTRACTABLE` são chaves que podem ser exportadas para fora do HSM. Para obter mais informações, consulte Atributos Java compatíveis para o [Client SDK 5](java-lib-attributes_5.md).
1. O `WRAP_WITH_TRUSTED` atributo para chaves privadas e secretas é definido como **falso**.
+ `getEncoded`,`getPrivateExponent`, e `getS` não podem ser usados com chaves privadas que não podem ser exportadas em branco. `WRAP_WITH_TRUSTED` não permite que suas chaves privadas sejam exportadas do HSM em branco. Para obter mais informações, consulte [Usando chaves confiáveis para controlar o desencapsulamento de chaves](manage-keys-using-trusted-keys.md).
# Permita que o provedor de JCE extraia segredos de chave privada do AWS CloudHSM
Use as etapas a seguir para permitir que o provedor de AWS CloudHSM JCE extraia seus segredos de chave privada.
**Importante**
Essa alteração de configuração permite a extração de todos os bytes de `EXTRACTABLE` chave em branco do seu cluster HSM. Para maior segurança, você deve considerar o uso de [métodos de encapsulamento de chaves](java-lib-supported_5.md) para extrair a chave do HSM com segurança. Isso evita a extração não intencional dos seus bytes de chave do HSM.
1. Use os comandos a seguir para permitir que suas chaves **privadas** ou **secretas** sejam extraídas no JCE:
------
#### [ Linux ]
```
$ /opt/cloudhsm/bin/configure-jce --enable-clear-key-extraction-in-software
```
------
#### [ Windows ]
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --enable-clear-key-extraction-in-software
```
------
1. Depois de ativar a extração da chave em branco, os métodos a seguir são habilitados para extrair chaves privadas na memória.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/cloudhsm/latest/userguide/get-encoded-take-out-private-keys.html)
Se você quiser restaurar o comportamento padrão e não permitir que o JCE exporte as chaves em branco, execute o seguinte comando:
------
#### [ Linux ]
```
$ /opt/cloudhsm/bin/configure-jce --disable-clear-key-extraction-in-software
```
------
#### [ Windows ]
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --disable-clear-key-extraction-in-software
```
------
# Repita os comandos do JCE para AWS CloudHSM
AWS CloudHSM O SDK do cliente 5.8.0 e versões posteriores têm uma estratégia de repetição automática integrada que repetirá as operações controladas pelo HSM do lado do cliente. Quando um HSM acelera as operações porque está muito ocupado executando operações anteriores e não pode receber mais solicitações, o cliente SDKs tentará repetir as operações limitadas até 3 vezes enquanto recua exponencialmente. Essa estratégia de repetição automática pode ser configurada para um dos dois modos: **desativado** e **padrão**.
+ **desativado**: o Client SDK não executará nenhuma estratégia de repetição para nenhuma operação com controle de utilização pelo HSM.
+ **padrão**: esse é o modo padrão para o Client SDK 5.8.0 e versões posteriores. Nesse modo, o cliente SDKs repetirá automaticamente as operações limitadas recuando exponencialmente.
Para obter mais informações, consulte [Controle de utilização do HSM](troubleshoot-hsm-throttling.md).
## Definir os comandos de repetição para o modo desativado
------
#### [ Linux ]
**Para definir comandos de repetição **off** para o Client SDK 5 no Linux**
+ Use os comandos a seguir para gerenciar as configurações do modo **off**:
```
$ sudo /opt/cloudhsm/bin/configure-jce --default-retry-mode off
```
------
#### [ Windows ]
**Para definir comandos de repetição **off** para o Client SDK 5 no Windows**
+ Use os comandos a seguir para gerenciar as configurações do modo **off**:
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --default-retry-mode off
```
------