imSymKey - AWS CloudHSM
SintaxeExemplosParâmetrosTópicos relacionados da

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

imSymKey

O comando imSymKey na ferramenta key_mgmt_uti importa uma cópia em texto simples de uma chave simétrica de um arquivo no HSM. Você pode usá-lo para importar chaves geradas por qualquer método fora do HSM e chaves que foram exportadas de um HSM, como as chaves que o exSymKeycomando grava em um arquivo.

Durante o processo de importação, imSymKey usa uma chave AES que você seleciona (a chave de encapsulamento) para encapsular (criptografar) e depois desencapsular (descriptografar) a chave a ser importada. No entanto, imSymKey funciona apenas em arquivos que contenham chaves em texto simples. Para exportar e importar chaves criptografadas, use o WrapKey e unWrapKeyos comandos.

Além disso, o comando imSymKey importa apenas chaves simétricas. Para importar chaves públicas, use importPubKey. Para importar chaves privadas, use importPrivateKeyou WrapKey.

nota

Não é possível importar uma chave PEM protegida por senha usando uma chave simétrica ou privada.

As chaves importadas funcionam muito como as chaves geradas no HSM. No entanto, o valor do atributo OBJ_ATTR_LOCAL é zero, o que indica que não foi gerado localmente. Você pode usar o comando a seguir para compartilhar uma chave simétrica ao importá-la. Você pode usar o comando shareKey em cloudhsm_mgmt_util para compartilhar a chave após ela ser importada. 

imSymKey -l aesShared -t 31 -f kms.key -w 3296 -u 5

Depois de importar uma chave, certifique-se de marcar ou excluir o arquivo de chave. Esse comando não impede que você importe o mesmo material de chave várias vezes. O resultado, várias chaves com identificadores de chave distintos e o mesmo material de chave, dificultam o rastreamento do uso do material de chave e impedem que ela exceda seus limites criptográficos.

Antes de executar um comando key_mgmt_util, você deve iniciar key_mgmt_util e fazer login no HSM como um usuário de criptografia (CU).

Sintaxe

imSymKey -h

imSymKey -f <key-file>
         -w <wrapping-key-handle>  
         -t <key-type>
         -l <label>
         [-id <key-ID>]
         [-sess]
         [-wk <wrapping-key-file> ]
         [-attest]
         [-min_srv <minimum-number-of-servers>]
         [-timeout <number-of-seconds> ]
         [-u <user-ids>]

Exemplos

Estes exemplos mostram como usar imSymKey para importar chaves simétricas em seus HSMs.

exemplo : Importar uma chave simétrica AES

Este exemplo usa imSymKey para importar uma chave simétrica AES nos HSMs.

O primeiro comando usa o OpenSSL para gerar uma chave AES simétrica aleatória de 256 bits. Ele salva a chave no arquivo aes256.key.

$  openssl rand -out aes256-forImport.key 32

O segundo comando usa imSymKey para importar a chave AES do arquivo aes256.key para os HSMs. Ele usa a chave 20, uma chave AES no HSM, como a chave de encapsulamento e especifica um rótulo de imported. Ao contrário do ID, o rótulo não precisa ser exclusivo no cluster. O valor do parâmetro -t (tipo) é 31, que representa o AES.

A saída mostra que a chave no arquivo foi encapsulada e desencapsulada, e depois importada para o HSM, onde recebeu o identificador de chave 262180.

Command:  imSymKey -f aes256.key -w 20 -t 31 -l imported

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 262180

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 2 and err state 0x00000000 : HSM Return: SUCCESS

O próximo comando usa getAttribute para obter o atributo OBJ_ATTR_LOCAL (atributo 355) da chave recém-importada e o grava no arquivo attr_262180.

Command:  getAttribute -o 262180 -a 355 -out attributes/attr_262180
Attributes dumped into attributes/attr_262180_imported file

        Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS

Ao examinar o arquivo de atributo, você pode ver que o valor do atributo OBJ_ATTR_LOCAL é zero, o que indica que o material de chave não foi gerado no HSM. 

$  cat attributes/attr_262180_local
OBJ_ATTR_LOCAL
0x00000000
exemplo : mover uma chave simétrica entre clusters

Este exemplo mostra como usar exSymKeye imSymKey mover uma chave AES de texto simples entre clusters. Você pode usar um processo como esse para criar um encapsulamento AES que existe HSMs em ambos os clusters. Depois que a chave de empacotamento compartilhada estiver em vigor, você poderá usar WrapKey unWrapKeye mover chaves criptografadas entre os clusters.

O usuário CU que realiza essa operação deve ter permissão para fazer login nos HSMs em ambos os clusters.

O primeiro comando é usado exSymKeypara exportar a chave 14, uma chave AES de 32 bits, do cluster 1 para o aes.key arquivo. Ele usa a chave 6, uma chave AES nos HSMs do cluster 1, como a chave de encapsulamento. 

Command: exSymKey -k 14 -w 6 -out aes.key

        Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS


Wrapped Symmetric Key written to file "aes.key"

O usuário então faz login em key_mgmt_util no cluster 2 e executa um comando imSymKey para importar a chave no arquivo aes.key para os HSMs no cluster 2. Esse comando usa a chave 252152, uma chave AES nos HSMs do cluster 2, como a chave de encapsulamento.

Como as chaves de agrupamento imSymKey usadas agrupam exSymKeye desempacotam imediatamente as chaves de destino, as chaves de agrupamento nos diferentes clusters não precisam ser as mesmas.

A saída mostra que a chave foi importada com sucesso no cluster 2 e recebeu um identificador de chave de 21. 

Command:  imSymKey -f aes.key -w 262152 -t 31 -l xcluster

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 21

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 2 and err state 0x00000000 : HSM Return: SUCCESS

Para provar que a chave 14 no cluster 1 e a chave 21 no cluster 2 possuem o mesmo material de chave, obtenha o valor de verificação de chave (KCV) de cada uma. Se os valores do KCV forem iguais, o material da chave é o mesmo.

O seguinte comando usa getAttribute no cluster 1 para gravar o valor do atributo KCV (atributo 371) da chave 14 no arquivo attr_14_kcv. Em seguida, ele usa um comando cat para obter o conteúdo do arquivo attr_14_kcv.

Command:  getAttribute -o 14 -a 371 -out attr_14_kcv
Attributes dumped into attr_14_kcv file

$  cat attr_14_kcv
OBJ_ATTR_KCV
0xc33cbd

Esse comando semelhante usa getAttribute no cluster 2 para gravar o valor do atributo KCV (atributo 371) da chave 21 no arquivo attr_21_kcv. Em seguida, ele usa um comando cat para obter o conteúdo do arquivo attr_21_kcv.

Command:  getAttribute -o 21 -a 371 -out attr_21_kcv
Attributes dumped into attr_21_kcv file

$  cat attr_21_kcv
OBJ_ATTR_KCV
0xc33cbd

A saída mostra que os valores KCV das duas chaves são os mesmos, o que prova que o material de chave é o mesmo.

Como o mesmo material de chave existe nos HSMs de ambos os clusters, agora você pode compartilhar chaves criptografadas entre eles sem nunca expor a chave em texto simples. Por exemplo, você pode usar o comando wrapKey com a chave de encapsulamento 14 para exportar uma chave criptografada do cluster 1 e, em seguida, usar unWrapKey com a chave de encapsulamento 21 para importar a chave criptografada para o cluster 2.

exemplo : Importar uma chave de sessão

Esse comando usa os parâmetros -sess de imSymKey para importar uma chave Triple DES de 192 bits que é válida apenas na sessão atual.

O comando usa o parâmetro -f para especificar o arquivo que contém a chave a ser importada, o parâmetro -t para especificar o tipo de chave e o parâmetro -w para especificar a chave de encapsulamento. Ele usa o parâmetro -l para especificar um rótulo que categoriza a chave e o parâmetro -id para criar um identificador amigável, mas exclusivo, para ela. Ele também usa o parâmetro -attest para verificar o firmware que está importando a chave.

A saída mostra que a chave foi encapsulada e desencapsulada com sucesso, importada para o HSM e recebeu o identificador de chave 37. Além disso, a verificação de atestado foi aprovada, o que indica que o firmware não foi adulterado.

Command:  imSymKey -f 3des192.key -w 6 -t 21 -l temp -id test01 -sess -attest

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 37

        Attestation Check : [PASS]

        Cluster Error Status
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

Em seguida, você pode usar os comandos getAttribute ou findKey para verificar os atributos da chave recém-importada. O comando a seguir usa findKey para verificar se a chave 37 possui o tipo, o rótulo e o ID especificados pelo comando e se ela é uma chave de sessão. Como mostrado na linha 5 da saída, findKey informa que a única chave que corresponde a todos os atributos é a chave 37. 

Command:  findKey -t 21 -l temp -id test01 -sess 1
Total number of keys present 1

 number of keys matched from start index 0::0
37

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 2 and err state 0x00000000 : HSM Return: SUCCESS

        Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS

Parâmetros

-attest

Executa uma verificação de integridade que verifica se o firmware no qual o cluster é executado não foi adulterado.

Padrão: sem verificação de atestado.

Obrigatório: não

-f

Especifica o arquivo que contém essa chave a ser importada.

O arquivo deve conter uma cópia em texto simples de uma chave AES ou Triple DES com o comprimento especificado. As chaves RC4 e DES não são válidas em HSMs no modo FIPS.

  • AES: 16, 24 ou 32 bytes

  • Triple DES (3DES): 24 bytes

Obrigatório: Sim

-h

Exibe a ajuda referente ao comando.

Obrigatório: Sim

-id

Especifica o identificador da chave definida pelo usuário. Digite uma string exclusiva no cluster. O padrão é uma string vazia.

Padrão: sem valor de ID.

Obrigatório: não

-l

Especifica o rótulo da chave privada definida pelo usuário para a chave. Digite uma string.

É possível usar qualquer frase que ajude a identificar a chave. Como o rótulo não precisa ser exclusivo, é possível usá-lo para agrupar e categorizar chaves.

Obrigatório: Sim

-min_srv

Especifica o número mínimo de HSMs nos quais a chave importada é sincronizada antes da expiração do valor do parâmetro -timeout. Se a chave não for sincronizada com o número especificado de servidores na hora alocada, ela não será criada.

AWS CloudHSM sincroniza automaticamente todas as chaves com cada HSM no cluster. Para agilizar o processo, configure o valor de min_srv como menos que o número de HSMs no cluster e defina um valor de tempo limite baixo. No entanto, algumas solicitações talvez não gerem uma chave.

Padrão: 1

Obrigatório: não

-sess

Cria uma chave que existe apenas na sessão atual. A chave não pode ser recuperada após o término da sessão.

Use esse parâmetro quando precisar de uma chave apenas brevemente, como uma chave de empacotamento que criptografa e, em seguida, descriptografa rapidamente outra chave. Não use uma chave de sessão para criptografar dados que você talvez precise descriptografar após o término da sessão.

Para transformar uma chave de sessão em uma chave persistente (token), use setAttribute.

Padrão: a chave é persistente.

Obrigatório: não

-timeout

Especifica por quanto tempo (em segundos) o comando espera que uma chave seja sincronizada com o número de HSMs especificado pelo parâmetro min_srv.

Este parâmetro é válido somente quando o parâmetro min_srv também é usado no comando.

Padrão: sem limite de tempo. O comando espera indefinidamente e retorna somente quando a chave é sincronizada com o número mínimo de servidores.

Obrigatório: não

-t

Especifica o tipo da chave simétrica. Insira a constante que representa o tipo de chave. Por exemplo, para criar uma chave AES, insira -t 31.

Valores válidos:

Obrigatório: Sim

-u

Compartilha a chave que você está importando com usuários especificados. Esse parâmetro dá a outros usuários de criptografia (CUs) do HSM permissão para usar essa chave em operações de criptografia.

Digite um ID ou uma lista separada por vírgulas de IDs de usuários do HSM, como -u 5,6. Não inclua o ID do usuário atual do HSM. Para encontrar um ID, você pode usar o comando listUsers na ferramenta de linha de comando cloudhsm_mgmt_util ou o comando listUsers na ferramenta de linha de comando key_mgmt_util.

Obrigatório: não

-w

Especifica o identificador de chave da chave de encapsulamento. Esse parâmetro é obrigatório. Para encontrar os identificadores de chave, use o comando findKey.

Uma chave de encapsulamento é uma chave no HSM que é usada para criptografar (encapsular) e depois descriptografar (desencapsular) a chave durante o processo de importação. Somente as chaves AES podem ser usadas como chaves de encapsulamento.

Você pode usar qualquer chave do AES (de qualquer tamanho) como uma chave de encapsulamento. Como a chave de encapsulamento encapsula e depois desencapsula imediatamente a chave de destino, você pode usar como chave AES somente de sessão como uma chave de encapsulamento. Para determinar se uma chave pode ser usada como uma chave de encapsulamento, use getAttribute para obter o valor do atributo OBJ_ATTR_WRAP (262). Para criar uma chave de empacotamento, use genSymKeypara criar uma chave AES (tipo 31).

Se você usar o parâmetro -wk para especificar uma chave de encapsulamento externa, a chave de encapsulamento -w será usada para desencapsular, mas não para encapsular, a chave que está sendo importada.

nota

A chave 4 é uma chave interna sem suporte. Recomendamos usar uma chave AES criada e gerenciada por você como a chave de encapsulamento.

Obrigatório: Sim

-wk

Use a chave AES no arquivo especificado para encapsular a chave que está sendo importada. Insira o caminho e o nome de um arquivo que contém uma chave AES de texto simples.

Durante a inclusão desse parâmetro. imSymKey usa a chave no arquivo -wk para encapsular a chave que está sendo importada e usa a chave no HSM que é especificada pelo parâmetro -w para desencapsulá-la. Os valores dos parâmetros -w e -wk devem ser resolvidos para a mesma chave de texto simples.

Padrão: use a chave de encapsulamento no HSM para desencapsular.

Obrigatório: não

Tópicos relacionados da