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á.
# 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
```
------