genSymKey

O comando genSymKey na ferramenta key_mgmt_util gera uma chave simétrica nos seus HSMs. Você pode especificar o tipo de chave e o tamanho, atribuir um ID e um rótulo e compartilhar a chave com outros usuários do HSM. Você também pode criar chaves não extraíveis e chaves que expiram quando a sessão termina. Quando o comando for bem-sucedido, ele retornará um identificador de chave que o HSM atribui à chave. Você pode usar o identificador de chave para identificar as chaves para outros comandos.

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

genSymKey -h

genSymKey -t <key-type>
          -s <key-size> 
          -l <label> 
          [-id <key-ID>] 
          [-min_srv <minimum-number-of-servers>] 
          [-m_value <0..8>]
          [-nex] 
          [-sess] 
          [-timeout <number-of-seconds> ]
          [-u <user-ids>] 
          [-attest] 

Exemplos

Estes exemplos mostram como usar o genSymKey para criar chaves simétricas nos seus HSMs.

dica

Para usar as chaves criadas com esses exemplos para operações HMAC, você deve definir OBJ_ATTR_SIGN e OBJ_ATTR_VERIFY para TRUE depois de gerar a chave. Para definir esses valores, use setAttribute no CloudHSM Management Utility (CMU). Para obter mais informações, consulte setAttribute.

exemplo : Gerar uma chave de AES

Esse comando cria uma chave AES de 256 bits com um rótulo aes256. A saída mostra que o identificador da nova chave é 6.

Command: genSymKey -t 31 -s 32 -l aes256

        Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 6

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

exemplo : Criar uma chave de sessão

Este comando cria uma chave AES de 192 bits não extraível que é válida apenas na sessão atual. Você talvez queira criar uma chave como essa para encapsular (e depois imediatamente desencapsular) uma chave que está sendo exportada.

Command: genSymKey -t 31 -s 24 -l tmpAES -id wrap01 -nex -sess 

exemplo : Retornar rapidamente

Esse comando cria uma chave de 512 bytes genérica com um rótulo de IT_test_key. O comando não aguarda a chave a ser sincronizada para todos os HSMs no cluster. Em vez disso, ele é retornado assim que a chave é criada em qualquer HSM (-min_srv 1) ou em 1 segundo (-timeout 1), o que for mais curto. Se a chave não for sincronizada com o número mínimo especificado de HSMs antes do término do tempo limite, ela não será gerada. Você pode querer usar um comando como esse em um script que cria várias chaves, como o loop for no exemplo a seguir.

Command: genSymKey -t 16 -s 512 -l IT_test_key -min_srv 1 -timeout 1

$  for i in {1..30}; 
     do /opt/cloudhsm/bin/key_mgmt_util singlecmd loginHSM -u CU -s example_user -p example_pwd genSymKey -l aes -t 31 -s 32 -min_srv 1 -timeout 1; 
 done;

exemplo : Criar uma chave genérica autorizada de quorum

Esse comando cria uma chave secreta genérica de 2048 bits com o rótulo generic-mV2. O comando usa o parâmetro -u para compartilhar a chave com outro CU, o usuário 6. Ele usa o parâmetro -m_value para exigir um quorum de pelo menos duas aprovações para quaisquer operações criptográficas que usam a chave. O comando também usa o parâmetro -attest para verificar a integridade do firmware no qual a chave é gerada.

A saída mostra que o comando gerou uma chave com o identificador de chave 9 e que a verificação de comprovação no firmware de cluster foi aprovada.

                Command:  genSymKey -t 16 -s 2048 -l generic-mV2 -m_value 2 -u 6 -attest

        Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 9

        Attestation Check : [PASS]

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

exemplo : Criar e examinar uma chave

Esse comando cria uma chave DES Tripla com um rótulo 3DES_shared e um ID de IT-02. A chave pode ser usada pelo usuário atual e pelos usuários 4 e 5. O comando falhará se o ID não for exclusivo no cluster ou se o usuário atual for o usuário 4 ou 5.

A saída mostra que a nova chave tem o identificador de chave 7.

Command: genSymKey -t 21 -s 24 -l 3DES_shared -id IT-02 -u 4,5

       Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 7

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

Para verificar se a nova chave 3DES é de propriedade do usuário atual e compartilhada com os usuários 4 e 5, use getKeyInfo. O comando usa o identificador que foi atribuído à nova chave (Key Handle: 7).

A saída confirma que a chave é de propriedade do usuário 3 e está compartilhada com os usuários 4 e 5.

Command:  getKeyInfo -k 7

        Cfm3GetKey returned: 0x00 : HSM Return: SUCCESS

        Owned by user 3

        also, shared to following 2 user(s):

                 4, 5

Para confirmar as outras propriedades da chave, use getAttribute. O primeiro comando usa getAttribute para obter todos os atributos (-a 512) do identificador de chave 7 (-o 7). Ele os grava no arquivo attr_7. O segundo comando usa cat para obter o conteúdo do arquivo attr_7.

Esse comando confirma que a chave 7 é uma chave simétrica de 192 bits (OBJ_ATTR_VALUE_LEN 0x00000018 ou 24 bytes) 3DES (OBJ_ATTR_KEY_TYPE 0x15) (OBJ_ATTR_CLASS 0x04) com rótulo 3DES_shared (OBJ_ATTR_LABEL 3DES_shared) e ID IT_02 (OBJ_ATTR_ID IT-02). A chave é persistente (OBJ_ATTR_TOKEN 0x01) e extraível (OBJ_ATTR_EXTRACTABLE 0x01) e pode ser usada para criptografia, descriptografia e encapsulamento.

dica

Para encontrar os atributos de uma chave criada por você, como tipo, comprimento, rótulo e ID, use getAttribute. Para encontrar as chaves de um usuário específico, use getKeyInfo. Para encontrar chaves com base em seus valores de atributos, use FindKey.

Para obter ajuda sobre a interpretação dos principais atributos, consulte Referência de atributos de chave.

Command:  getAttribute -o 7 -a 512 -out attr_7

got all attributes of size 444 attr cnt 17
Attributes dumped into attr_7 file

        Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS


$  cat attr_7

OBJ_ATTR_CLASS
0x04
OBJ_ATTR_KEY_TYPE
0x15
OBJ_ATTR_TOKEN
0x01
OBJ_ATTR_PRIVATE
0x01
OBJ_ATTR_ENCRYPT
0x01
OBJ_ATTR_DECRYPT
0x01
OBJ_ATTR_WRAP
0x00
OBJ_ATTR_UNWRAP
0x00
OBJ_ATTR_SIGN
0x00
OBJ_ATTR_VERIFY
0x00
OBJ_ATTR_LOCAL
0x01
OBJ_ATTR_SENSITIVE
0x01
OBJ_ATTR_EXTRACTABLE
0x01
OBJ_ATTR_LABEL
3DES_shared
OBJ_ATTR_ID
IT-02
OBJ_ATTR_VALUE_LEN
0x00000018
OBJ_ATTR_KCV
0x59a46e

dica

Para usar as chaves criadas com esses exemplos para operações HMAC, você deve definir OBJ_ATTR_SIGN e OBJ_ATTR_VERIFY para TRUE depois de gerar a chave. Para definir esses valores, use setAttribute no CMU. Para obter mais informações, consulte setAttribute.

Parâmetros

-h

Exibe a ajuda referente ao comando.

Obrigatório: Sim

-t

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

Valores válidos:

• 16: GENERIC_SECRET. Uma chave secreta genérica é uma matriz de bytes que não está em conformidade com nenhum padrão específico, como os requisitos para uma chave AES.

• 18: RC4. Chaves RC4 não são válidas em HSMs no modo FIPS

• 21: Triple DES (3DES). De acordo com a orientação do NIST, isso não é permitido para clusters no modo FIPS após 2023. Para clusters no modo não FIPS, ainda é permitido após 2023. Para mais detalhes, consulte Conformidade com o FIPS 140: suspensão do mecanismo de 2024.

• 31: AES

Obrigatório: Sim

-s

Especifica o tamanho da chave em bytes. Por exemplo, para criar uma chave de 192 bits, digite 24.

Valores válidos para cada tipo de chave:

• AES: 16 (128 bits), 24 (192 bits), 32 (256 bits)

• 3DES: 24 (192 bits)

• Segredo genérico: <3584 (28.672 bits)

Obrigatório: Sim

-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

-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

-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

-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

-m_value

Especifica o número de usuários que devem aprovar qualquer operação criptográfica que use a chave importada. Digite um valor de 0 até 8.

Esse parâmetro estabelece um requisito de autenticação de quórum para a chave. O valor padrão, 0, desativa o atributo de autenticação de quórum para a chave. Quando a autenticação de quórum está habilitada, o número especificado de usuários deve assinar um token para aprovar operações criptográficas que usam a chave e operações que compartilham ou descompartilham a chave.

Para encontrar o m_value de uma chave, use getKeyInfo.

Esse parâmetro é válido somente quando o parâmetro -u no comando compartilha a chave com usuários o suficiente para atender ao requisito de m_value.

Padrão: 0

Obrigatório: Não

-nex

Torna a chave não extraível. A chave gerada não pode ser exportada do HSM.

Padrão: a chave é extraível.

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

-u

Compartilha a chave com o usuário especificado. 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 uma lista separada por vírgulas de IDs de usuário do HSM, como -u 5,6. Não inclua o ID do usuário atual do HSM. Para encontrar o ID do usuário de CUs no HSM, use listUsers. Em seguida, para compartilhar ou descompartilhar uma chave existente, use shareKey em cloudhsm_mgmt_util.

Padrão: somente o usuário atual pode utilizar a chave.

Obrigatório: Não

Tópicos relacionados da

• exSymKey

• Gênero A KeyPair

• GendSA KeyPair

• GeneCC KeyPair

• setAttribute