Atributos de chave Java compatíveis

Este tópico fornece informações sobre os atributos de chave Java compatíveis com o 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.

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 #11 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 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_TYPE				Usado para identificar o tipo de chave (AES, DeSede, genérica secreta, 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_CLASS				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.
TOKEN	FALSE	FALSE	FALSE	Uma chave permanente que é replicada em todos os HSMs no cluster e incluída em 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_WITH_TRUSTED	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_WITH_TRUSTED 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.

nota

Você obterá maior suporte para atributos na biblioteca PKCS #11. Para obter mais informações, consulte Atributos PKCS #11 compatíveis.

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 do 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 compatíveis.

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.