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

exSymKey

O comando exSymKey na ferramenta key_mgmt_util exporta uma cópia em texto simples de uma chave simétrica do HSM e a salva em um arquivo no disco. Para exportar uma cópia criptografada (encapsulada) de uma chave, use wrapKey. Para importar uma chave de texto simples, como as que exSymKey exportam, use. imSymKey

Durante o processo de exportação, exSymKey usa uma chave AES que você especifica (a chave de encapsulamento) para encapsular (criptografar) e depois desencapsular (descriptografar) a chave a ser exportada. No entanto, o resultado da operação de exportação é uma chave em texto simples (desencapsulada) no disco.

Somente o proprietário de uma chave, ou seja, o usuário CU que a criou, pode exportá-la. Os usuários que compartilham a chave podem usá-la em operações de criptografia, mas não podem exportá-la.

A operação exSymKey copia o material da chave para um arquivo que você especifica, mas não remove a chave do HSM, altera seus atributos de chave ou impede que você a use em operações criptográficas. É possível exportar a mesma chave várias vezes.

exSymKey exporta apenas chaves simétricas. Para exportar chaves públicas, use exportPubKey. Para exportar chaves privadas, use exportPrivateKey.

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

exSymKey -h

exSymKey -k <key-to-export>
         -w <wrapping-key>
         -out <key-file>
         [-m 4] 
         [-wk <unwrapping-key-file> ]

Exemplos

Esses exemplos mostram como usar exSymKey para exportar chaves simétricas que você possui dos seus HSMs.

exemplo : Exportar uma chave simétrica 3DES

Esse comando exporta uma chave simétrica Triple DES (3DES) (identificador de chave 7). Ele usa uma chave AES existente (identificador de chave 6) no HSM como chave de encapsulamento. Em seguida, ele grava o texto simples da chave 3DES no arquivo 3DES.key.

A saída mostra que a chave 7 (a tecla 3DES) foi encapsulada e desencapsulada com êxito e, em seguida, gravada no arquivo 3DES.key.

Atenção

Embora a saída diga que uma "Chave simétrica encapsulada" foi gravada no arquivo de saída, este último contém uma chave em texto simples (desencapsulada).

        Command: exSymKey -k 7 -w 6 -out 3DES.key

       Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS


Wrapped Symmetric Key written to file "3DES.key"
exemplo : Exportar com a chave de encapsulamento somente para sessão

Este exemplo mostra como usar uma chave que existe apenas na sessão como a chave de encapsulamento. Como a chave a ser exportada é encapsulada, imediatamente desencapsulada e fornecida como texto simples, não há necessidade de reter a chave de encapsulamento.

Esta série de comandos exporta uma chave AES com o identificador de chave 8 do HSM. Ela usa uma chave de sessão AES criada especialmente para esse propósito.

O primeiro comando é usado genSymKeypara criar uma chave AES de 256 bits. Ele usa o parâmetro -sess para criar uma chave que existe apenas na sessão atual.

A saída mostra que o HSM cria a chave 262168.

        Command:  genSymKey -t 31 -s 32 -l AES-wrapping-key -sess

        Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 262168

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

Em seguida, o exemplo verifica se a chave 8, a chave a ser exportada, é uma chave simétrica extraível. Ele também verifica se a chave de encapsulamento, 262168, é uma chave AES que existe apenas na sessão. Você pode usar o comando findKey, mas esse exemplo exporta os atributos de ambas as chaves para arquivos e, em seguida, usa grep para encontrar valores de atributos relevantes no arquivo.

Esses comandos usam getAttribute com um valor -a de 512 (tudo) para obter todos os atributos para as chaves 8 e 262168. Para obter informações sobre os atributos de chaves, consulte Referência de atributos de chave.

getAttribute -o 8 -a 512 -out attributes/attr_8
getAttribute -o 262168 -a 512 -out attributes/attr_262168

Esses comandos usam grep para verificar os atributos da chave a ser exportada (chave 8) e da chave de encapsulamento somente da sessão (chave 262168).

    // Verify that the key to be exported is a symmetric key.
    $  grep -A 1 "OBJ_ATTR_CLASS" attributes/attr_8    
    OBJ_ATTR_CLASS
    0x04
   
    // Verify that the key to be exported is extractable.
    $  grep -A 1 "OBJ_ATTR_KEY_TYPE" attributes/attr_8
    OBJ_ATTR_EXTRACTABLE
    0x00000001

    // Verify that the wrapping key is an AES key
    $  grep -A 1 "OBJ_ATTR_KEY_TYPE" attributes/attr_262168
    OBJ_ATTR_KEY_TYPE
    0x1f

    // Verify that the wrapping key is a session key
    $  grep -A 1 "OBJ_ATTR_TOKEN" attributes/attr_262168
    OBJ_ATTR_TOKEN
    0x00    
    
    // Verify that the wrapping key can be used for wrapping
     $  grep -A 1 "OBJ_ATTR_WRAP" attributes/attr_262168
    OBJ_ATTR_WRAP
    0x00000001

Por último, usamos um comando exSymKey para exportar a chave 8 usando a chave de sessão (chave 262168) como a chave de encapsulamento.

Quando a sessão terminar, a chave 262168 não existirá mais.

        Command:  exSymKey -k 8 -w 262168 -out aes256_H8.key

        Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS


Wrapped Symmetric Key written to file "aes256_H8.key"
exemplo : Usar uma chave de desencapsulamento externa

Este exemplo mostra como usar uma chave de desencapsulamento externa para exportar uma chave do HSM.

Ao exportar uma chave do HSM, você especifica uma chave AES no HSM para ser a chave de encapsulamento. Por padrão, essa chave de encapsulamento é usada para encapsular e desencapsular a chave a ser exportada. No entanto, você pode usar o parâmetro -wk para instruir exSymKey a usar uma chave externa em um arquivo no disco para desencapsulamento. Ao fazer isso, a chave especificada pelo parâmetro -w encapsula a chave de destino e a chave no arquivo especificado pelo parâmetro -wk desencapsula a chave.

Como a chave de encapsulamento deve ser uma chave AES, que é simétrica, a chave de encapsulamento no HSM e a chave no disco devem ter o mesmo material de chave. Para fazer isso, você deve importar a chave de encapsulamento para o HSM ou exportá-la do HSM antes da operação de exportação.

Esse exemplo cria uma chave fora do HSM e a importa para o HSM. Ele usa a cópia interna da chave para encapsular uma chave simétrica que está sendo exportada e usa a cópia dessa chave no arquivo para desencapsulá-la.

O primeiro comando usa o OpenSSL para gerar uma chave AES de 256 bits. Ele salva a chave no arquivo aes256-forImport.key. O comando OpenSSL não retorna saída, mas você pode usar vários comandos para confirmar seu sucesso. Este exemplo usa a ferramenta wc (contagem de palavras), que confirma que o arquivo tem 32 bytes de dados.

$  openssl rand -out keys/aes256-forImport.key 32

$ wc keys/aes256-forImport.key
 0  2 32 keys/aes256-forImport.key

Esse comando usa o imSymKeycomando para importar a chave AES do aes256-forImport.key arquivo para o HSM. Quando o comando é concluído, a chave existe no HSM com o identificador de chave 262167 e no arquivo aes256-forImport.key.

Command:  imSymKey -f keys/aes256-forImport.key -t 31 -l aes256-imported -w 6

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 262167

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

Esse comando usa a chave em uma operação de exportação. O comando usa exSymKey para exportar a chave 21, uma chave AES de 192 bits. Para encapsular a chave, ele usa a chave 262167, que é a cópia que foi importada para o HSM. Para desempacotar a chave, ela usa o mesmo material de chave no arquivo aes256-forImport.key. Quando o comando for concluído, a chave 21 será exportada para o arquivo aes192_h21.key.

        Command:  exSymKey -k 21 -w 262167 -out aes192_H21.key -wk aes256-forImport.key

        Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

Wrapped Symmetric Key written to file "aes192_H21.key"

Parâmetros

-h

Exibe a ajuda referente ao comando.

Obrigatório: Sim

-k

Especifica o identificador de chave da chave a ser exportada. Esse parâmetro é obrigatório. Insira o identificador de chave de uma chave simétrica que você possui. Esse parâmetro é obrigatório. Para encontrar os identificadores de chave, use o comando findKey.

Para verificar se uma chave pode ser exportada, use o comando getAttribute para obter o valor do atributo OBJ_ATTR_EXTRACTABLE, que é representado pela constante 354. Além disso, você pode exportar apenas as chaves que você possui. Para encontrar o proprietário de uma chave, use o getKeyInfocomando.

Obrigatório: Sim

-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 a ser exportada. 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, que é representado pela constante 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 desencapsulamento externa, a chave de encapsulamento -w será usada para encapsular, mas não para desencapsular, a chave durante a exportação.

nota

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

Obrigatório: Sim

-out

Especifica o caminho e o nome do arquivo de saída. Quando o comando é bem-sucedido, esse arquivo contém a chave exportada em texto simples. Se o arquivo já existir, o comando o sobrescreverá sem aviso prévio.

Obrigatório: Sim

-m

Especifica o mecanismo de encapsulamento. O único valor válido é 4, que representa o mecanismo NIST_AES_WRAP.

Obrigatório: não

Padrão: 4

-wk

Use a chave AES no arquivo especificado para desencapsular a chave que está sendo exportada. 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. exSymKey usa a chave no arquivo no HSM especificada pelo parâmetro -w para encapsular a chave que está sendo exportada e usa a chave no arquivo -wk para desencapsulá-la. Os valores dos parâmetros -w e -wk devem ser resolvidos para a mesma chave de texto simples.

Obrigatório: não

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

Tópicos relacionados da