Noções básicas sobre atributos Atributos compatíveis Definir atributos para uma chave Reunir todos os componentes

Atributos de chave suportados para o Client SDK 3

Este tópico descreve como usar uma extensão proprietária para a biblioteca Java versão 3.1 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
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.

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 #11 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 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_TOKEN`	`FALSE`	`FALSE`	`FALSE`	Uma chave permanente que é replicada em todos os HSMs no cluster e incluída em backups. CKA_TOKEN = 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_LABEL`				Uma string definida pelo usuário. Ela permite identificar chaves no HSM de forma conveniente.
`CKA_EXTRACTABLE`	`TRUE`		`TRUE`	True indica que você pode exportar essa chave para fora do HSM.
`CKA_ENCRYPT`	`TRUE`	`TRUE`		True indica que você pode usar a chave para criptografar qualquer buffer.
`CKA_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 CKA_WRAP esteja definido como true.
`CKA_WRAP`	`TRUE`	`TRUE`		True indica que você pode usar a chave para encapsular outra chave. Geralmente, isso é definido como FALSE para chaves privadas.
`CKA_UNWRAP`	`TRUE`		`TRUE`	True indica que você pode usar a chave para desencapsular (importar) outra chave.
`CKA_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.
`CKA_VERIFY`	`TRUE`	`TRUE`		True indica que você pode usar a chave para verificar uma assinatura. Isso geralmente é definido como FALSE para chaves privadas.
`CKA_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 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 #11. Para obter mais informações, consulte Atributos PKCS #11 compatíveis.

Definir atributos para uma chave

O CloudHsmKeyAttributesMap é 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 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 do `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 compatíveis.

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 e a amostra em. 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:

Instancie CloudHsmKeyAttributesMap para chaves simétricas ou CloudHsmKeyPairAttributesMap para par de chaves.
Defina o objeto de atributos do passo 1 com os atributos e valores de chave necessários.
Instancie uma classe Cavium*ParameterSpec, correspondente ao tipo de chave específico e passe este objeto de atributos configurados para o construtor.
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)`
Secreta	`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);

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Mecanismos

Exemplos de código