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á.
# Atributos de chave Java compatíveis com o AWS CloudHSM Client SDK 3
Este tópico descreve como usar uma extensão proprietária para a biblioteca Java versão 3.1 para definir os principais atributos AWS CloudHSM do Client SDK 3. 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
+ Desencapsulamento de chaves
**nota**
A extensão para definir atributos de chave personalizados é um recurso opcional Se você já tem o código que funciona na biblioteca Java versão 3.0, não é necessário modificá-lo. As chaves criadas continuarão contendo os mesmos atributos de antes.
**Topics**
+ [Noções básicas sobre atributos](#java-understanding-attributes)
+ [Atributos do compatíveis](#java-attributes)
+ [Definir atributos para uma chave](#java-setting-attributes)
+ [Reunir todos os componentes](#java-attributes-summary)
## Noções básicas sobre atributos
Use atributos 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.
No entanto, a Java Cryptography Extension (JCE) não especifica como você deve definir valores em atributos de chave, portanto, a maioria das ações era permitida por padrão. Em contrapartida, o padrão PKCS \$111 define um conjunto de atributos abrangente com padrões mais restritivos. A partir da biblioteca Java versão 3.1, o CloudHSM fornece uma extensão proprietária que permite definir valores mais restritivos para atributos usados frequentemente.
## 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, o CloudHSM utilizará 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 | |
| CKA\$1TOKEN | FALSE | FALSE | FALSE | Uma chave permanente que é replicada HSMs em todo o cluster e incluída nos backups. CKA\$1TOKEN = FALSE requer uma chave de sessão, que é carregada somente em um HSM e apagada automaticamente quando a conexão com o HSM é interrompida. |
| CKA\$1LABEL | | | | Uma string definida pelo usuário. Ela permite identificar chaves no HSM de forma conveniente. |
| CKA\$1EXTRACTABLE | TRUE | | TRUE | True indica que você pode exportar essa chave para fora do HSM. |
| CKA\$1ENCRYPT | TRUE | TRUE | | True indica que você pode usar a chave para criptografar qualquer buffer. |
| CKA\$1DECRYPT | TRUE | | TRUE | True indica que você pode usar a chave para descriptografar qualquer buffer. Geralmente, você define isso como FALSE para uma chave cujo CKA\$1WRAP esteja definido como true. |
| CKA\$1WRAP | TRUE | TRUE | | True indica que você pode usar a chave para encapsular outra chave. Geralmente, isso é definido como FALSE para chaves privadas. |
| CKA\$1UNWRAP | TRUE | | TRUE | True indica que você pode usar a chave para desencapsular (importar) outra chave. |
| CKA\$1SIGN | 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. |
| CKA\$1VERIFY | TRUE | TRUE | | True indica que você pode usar a chave para verificar uma assinatura. Isso geralmente é definido como FALSE para chaves privadas. |
| CKA\$1PRIVATE | 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 as chaves no CloudHSM até que sejam autenticados, mesmo se esse atributo estiver definido como FALSE. |
**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 `CloudHsmKeyAttributesMap` é um objeto semelhante ao [Mapa Java](https://devdocs.io/openjdk~8/java/util/map), que pode ser usado para definir valores de atributos para objetos de chave. Os métodos para a função `CloudHsmKeyAttributesMap` 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 `CloudHSMKeyAttributesMap` |
| --- | --- | --- |
| 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).
### Exemplo de padrão do construtor
Geralmente, para os desenvolvedores será mais conveniente usar classes por meio do padrão do Construtor. Conforme os exemplos:
```
import com.amazonaws.cloudhsm.CloudHsmKeyAttributes;
import com.amazonaws.cloudhsm.CloudHsmKeyAttributesMap;
import com.amazonaws.cloudhsm.CloudHsmKeyPairAttributesMap;
CloudHsmKeyAttributesMap keyAttributesSessionDecryptionKey =
new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_LABEL, "ExtractableSessionKeyEncryptDecrypt")
.put(CloudHsmKeyAttributes.CKA_WRAP, false)
.put(CloudHsmKeyAttributes.CKA_UNWRAP, false)
.put(CloudHsmKeyAttributes.CKA_SIGN, false)
.put(CloudHsmKeyAttributes.CKA_VERIFY, false)
.build();
CloudHsmKeyAttributesMap keyAttributesTokenWrappingKey =
new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_LABEL, "TokenWrappingKey")
.put(CloudHsmKeyAttributes.CKA_TOKEN, true)
.put(CloudHsmKeyAttributes.CKA_ENCRYPT, false)
.put(CloudHsmKeyAttributes.CKA_DECRYPT, false)
.put(CloudHsmKeyAttributes.CKA_SIGN, false)
.put(CloudHsmKeyAttributes.CKA_VERIFY, false)
.build();
```
Os desenvolvedores também podem utilizar conjuntos de atributos predefinidos como uma forma conveniente para aplicar as melhores práticas em modelos de chave. Exemplo:
```
//best practice template for wrapping keys
CloudHsmKeyAttributesMap commonKeyAttrs = new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_EXTRACTABLE, false)
.put(CloudHsmKeyAttributes.CKA_DECRYPT, false)
.build();
// initialize a new instance of CloudHsmKeyAttributesMap by copying commonKeyAttrs
// but with an appropriate label
CloudHsmKeyAttributesMap firstKeyAttrs = new CloudHsmKeyAttributesMap(commonKeyAttrs);
firstKeyAttrs.put(CloudHsmKeyAttributes.CKA_LABEL, "key label");
// alternatively, putAll() will overwrite existing values to enforce conformance
CloudHsmKeyAttributesMap secondKeyAttrs = new CloudHsmKeyAttributesMap();
secondKeyAttrs.put(CloudHsmKeyAttributes.CKA_DECRYPT, true);
secondKeyAttrs.put(CloudHsmKeyAttributes.CKA_ENCRYPT, true);
secondKeyAttrs.put(CloudHsmKeyAttributes.CKA_LABEL, “safe wrapping key”);
secondKeyAttrs.putAll(commonKeyAttrs); // will overwrite CKA_DECRYPT to be FALSE
```
### Definir atributos para um par de chaves
Use a classe Java `CloudHsmKeyPairAttributesMap` para manipular atributos de chave para um par de chaves. O `CloudHsmKeyPairAttributesMap` encapsula dois objetos `CloudHsmKeyAttributesMap`; 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 `CloudHsmKeyAttributes` 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.
### Exemplo de padrão do construtor
Geralmente, para os desenvolvedores será mais conveniente definir atributos de chave usando o padrão do Construtor. Por exemplo:
```
import com.amazonaws.cloudhsm.CloudHsmKeyAttributes;
import com.amazonaws.cloudhsm.CloudHsmKeyAttributesMap;
import com.amazonaws.cloudhsm.CloudHsmKeyPairAttributesMap;
//specify attributes up-front
CloudHsmKeyAttributesMap keyAttributes =
new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_SIGN, false)
.put(CloudHsmKeyAttributes.CKA_LABEL, "PublicCertSerial12345")
.build();
CloudHsmKeyPairAttributesMap keyPairAttributes =
new CloudHsmKeyPairAttributesMap.Builder()
.withPublic(keyAttributes)
.withPrivate(
new CloudHsmKeyAttributesMap.Builder() //or specify them inline
.put(CloudHsmKeyAttributes.CKA_LABEL, "PrivateCertSerial12345")
.put (CloudHSMKeyAttributes.CKA_WRAP, FALSE)
.build()
)
.build();
```
**nota**
[Para obter mais informações sobre essa extensão proprietária, consulte o arquivo [Javadoc](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Docs/CloudHsm_CustomKeyAttributes_Javadoc.zip) e a amostra em.](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/CustomKeyAttributesRunner.java) GitHub Para explorar o Javadoc, faça download do arquivo e expanda-o.
## Reunir todos os componentes
Para especificar os atributos de chave com as suas operações de chave, siga estes passos:
1. Instancie `CloudHsmKeyAttributesMap` para chaves simétricas ou `CloudHsmKeyPairAttributesMap` para par de chaves.
1. Defina o objeto de atributos do passo 1 com os atributos e valores de chave necessários.
1. Instancie uma classe `Cavium*ParameterSpec`, correspondente ao tipo de chave específico e passe este objeto de atributos configurados para o construtor.
1. Passe esse objeto `Cavium*ParameterSpec` para uma classe ou método de criptografia correspondente.
Para referência, a tabela a seguir contém as classes e os métodos `Cavium*ParameterSpec` que oferecem suporte aos atributos de chave personalizados.
****
| Tipo de chave | Classe de especificação de parâmetros | Exemplo de construtores |
| --- | --- | --- |
| Classe base | CaviumKeyGenAlgorithmParameterSpec | CaviumKeyGenAlgorithmParameterSpec(CloudHsmKeyAttributesMap keyAttributesMap) |
| DES | CaviumDESKeyGenParameterSpec | CaviumDESKeyGenParameterSpec(int keySize, byte[] iv, CloudHsmKeyAttributesMap keyAttributesMap) |
| RSA | CaviumRSAKeyGenParameterSpec | CaviumRSAKeyGenParameterSpec(int keysize, BigInteger publicExponent, CloudHsmKeyPairAttributesMap keyPairAttributesMap) |
| Secret | CaviumGenericSecretKeyGenParameterSpec | CaviumGenericSecretKeyGenParameterSpec(int size, CloudHsmKeyAttributesMap keyAttributesMap) |
| AES | CaviumAESKeyGenParameterSpec | CaviumAESKeyGenParameterSpec(int keySize, byte[] iv, CloudHsmKeyAttributesMap keyAttributesMap) |
| EC | CaviumECGenParameterSpec | CaviumECGenParameterSpec(String stdName, CloudHsmKeyPairAttributesMap keyPairAttributesMap) |
### Código de exemplo: gerar e encapsular uma chave
Estes exemplos de código demonstram as etapas para duas operações diferentes: geração de chaves e encapsulamento de chaves:
```
// Set up the desired key attributes
KeyGenerator keyGen = KeyGenerator.getInstance("AES", "Cavium");
CaviumAESKeyGenParameterSpec keyAttributes = new CaviumAESKeyGenParameterSpec(
256,
new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_LABEL, "MyPersistentAESKey")
.put(CloudHsmKeyAttributes.CKA_EXTRACTABLE, true)
.put(CloudHsmKeyAttributes.CKA_TOKEN, true)
.build()
);
// Assume we already have a handle to the myWrappingKey
// Assume we already have the wrappedBytes to unwrap
// Unwrap a key using Custom Key Attributes
CaviumUnwrapParameterSpec unwrapSpec = new CaviumUnwrapParameterSpec(myInitializationVector, keyAttributes);
Cipher unwrapCipher = Cipher.getInstance("AESWrap", "Cavium");
unwrapCipher.init(Cipher.UNWRAP_MODE, myWrappingKey, unwrapSpec);
Key unwrappedKey = unwrapCipher.unwrap(wrappedBytes, "AES", Cipher.SECRET_KEY);
```