Desencapsular uma chave do AWS CloudHSM usando o KMU
Use o comando unWrapKey na ferramenta key_mgmt_util do AWS CloudHSM para importar uma chave simétrica ou privada encapsulada (criptografada) de um arquivo para o HSM. Ele é projetado para importar chaves criptografadas que foram encapsuladas pelo comando wrapKey em key_mgmt_util, mas também pode ser usado para desencapsular chaves que foram encapsuladas com outras ferramentas. No entanto, nessas situações, recomendamos usar as bibliotecas de software PKCS#11 ou JCE para desencapsular a chave.
As chaves importadas funcionam como as chaves geradas pelo AWS CloudHSM. No entanto, o valor de seu atributo OBJ_ATTR_LOCAL é zero, o que indica que não foi gerada localmente.
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 elas excedam seus limites de criptografia.
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
unWrapKey -h unWrapKey -f<key-file-name>-w<wrapping-key-handle>[-sess] [-min_srv<minimum-number-of-HSMs>] [-timeout<number-of-seconds>] [-aad<additional authenticated data filename>] [-tag_size<tag size>] [-iv_file<IV file>] [-attest] [-m<wrapping-mechanism>] [-t<hash-type>] [-nex] [-u<user id list>] [-m_value<number of users needed for approval>] [-noheader] [-l<key-label>] [-id<key-id>] [-kt<key-type>] [-kc<key-class] [-i<unwrapping-IV>]
Exemplo
Esses exemplos mostram como usar unWrapKey para importar uma chave encapsulada de um arquivo para os HSMs. No primeiro exemplo, desencapsulamos uma chave que foi encapsulada com o comando wrapKey key_mgmt_util e que, portanto, tem um cabeçalho. No segundo exemplo, desencapsulamos uma chave que foi encapsulada fora da key_mgmt_util e que, portanto, não tem um cabeçalho.
exemplo : desencapsular uma chave (com cabeçalho)
Esse comando importa uma cópia encapsulada de uma chave simétrica 3DES em um HSM. A chave é desencapsulada com uma chave AES com rótulo 6, que é criptograficamente idêntica a que foi usada para encapsular a chave 3DES. A saída mostra que a chave no arquivo foi desencapsulada e importada, e que o identificador da chave importada é 29.
Command:unWrapKey -f 3DES.key -w 6 -m 4Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS Key Unwrapped. Key Handle: 29 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
exemplo : desencapsular uma chave (sem cabeçalho)
Esse comando importa uma cópia encapsulada de uma chave simétrica 3DES em um HSM. A chave é desencapsulada com uma chave AES com rótulo 6, que é criptograficamente idêntica a que foi usada para encapsular a chave 3DES. Como essa chave 3DES não foi encapsulada com key_mgmt_util, o parâmetro noheader é especificado, juntamente com seus parâmetros de acompanhamento necessários: um rótulo de chave (unwrapped3DES), uma classe de chave (4) e um tipo de chave (21). A saída mostra que a chave no arquivo foi desencapsulada e importada, e que o identificador da chave importada é 8.
Command:unWrapKey -f 3DES.key -w 6 -noheader -l unwrapped3DES -kc 4 -kt 21 -m 4Cfm3CreateUnwrapTemplate2 returned: 0x00 : HSM Return: SUCCESS Cfm2UnWrapWithTemplate3 returned: 0x00 : HSM Return: SUCCESS Key Unwrapped. Key Handle: 8 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Parâmetros
- -h
-
Exibe a ajuda referente ao comando.
Obrigatório: Sim
- -f
-
O caminho e o nome do arquivo que contém a chave encapsulada.
Obrigatório: Sim
- -w
-
Especifica a chave de empacotamento. Insira o identificador de uma chave AES ou chave RSA no HSM. Esse parâmetro é obrigatório. Para encontrar os identificadores de chave, use o comando findKey.
Para criar uma chave de encapsulamento, use gensymKey para gerar uma chave AES (tipo 31) ou genRSAKeypair para gerar um par de chaves RSA (tipo 0). Se você estiver usando um par de chaves RSA, certifique-se de encapsular a chave com uma das chaves e desencapsular com a outra. Para determinar se uma chave pode ser usada como uma chave de empacotamento, use getAttribute para obter o valor do atributo
OBJ_ATTR_WRAP, que é representado pela constante262.Obrigatório: Sim
- -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
- -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.O AWS CloudHSM sincroniza automaticamente todas as chaves com todos os HSMs no cluster. Para agilizar o processo, configure o valor de
min_srvcomo 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
- -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_srvtambé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
- -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
- -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
- -m
-
O valor que representa o mecanismo de encapsulamento. O CloudHSM é compatível com os seguintes mecanismos:
Mecanismo Valor AES_KEY_WRAP_PAD_PKCS54 NIST_AES_WRAP_NO_PAD5 NIST_AES_WRAP_PAD6 RSA_AES7 RSA_OAEP(para obter o tamanho máximo dos dados, consulte a observação mais adiante nesta seção)8 AES_GCM10 CLOUDHSM_AES_GCM11 RSA_PKCS(para obter o tamanho máximo dos dados, consulte a observação mais adiante nesta seção). Consulte a nota 1 abaixo para ver uma mudança futura.12 Obrigatório: Sim
nota
Ao usar o mecanismo de encapsulamento
RSA_OAEP, o tamanho máximo da chave que você pode encapsular é determinado pelo módulo da chave RSA e pelo comprimento do hash especificados como: tamanho máximo da chave = modulusLengthInBytes-(2*hashLengthInBytes)-2.Ao usar o mecanismo de encapsulamento RSA_PKCS, o tamanho máximo da chave que você pode encapsular é determinado pelo módulo da chave RSA especificados como: tamanho máximo da chave = (modulusLengthInBytes -11).
- -t
-
Algoritmo hash Valor SHA12 SHA2563 SHA3844 SHA5125 SHA224(válido paraRSA_AES e RSA_OAEPmecanismos)6 Obrigatório: Não
- -noheader
-
Se estiver desencapsulando uma chave que foi encapsulada fora de key_mgmt_util, você deverá especificar esse parâmetro e todos os outros parâmetros associados.
Obrigatório: Não
nota
Se especificar esse parâmetro, você também deverá especificar os seguintes parâmetros
-noheader:-
-l
Especifica o rótulo a ser adicionado à chave desencapsulada.
Obrigatório: Sim
-
-kc
Especifica a classe da chave a ser desencapsulada. Os seguintes valores são aceitáveis:
3 = chave privada de um par de chaves pública/privada
4 = chave secreta (simétrica).
Obrigatório: Sim
-
-kt
Especifica o tipo da chave a ser desencapsulada. Os seguintes valores são aceitáveis:
0 =
RSA1 =
DSA3 =
ECC16 =
GENERIC_SECRET21 =
DES331 =
AESObrigatório: Sim
Você também pode opcionalmente especificar os seguintes parâmetros
-noheader:-
-id
O ID a ser adicionado à chave desencapsulada.
Obrigatório: Não
-
-i
O desencapsulamento do vetor de inicialização (IV) a ser usado.
Obrigatório: Não
-
[1] De acordo com a orientação do NIST, isso não é permitido em clusters no modo FIPS após 2023. Para clusters no modo não FIPS, isso ainda é permitido após 2023. Para mais detalhes, consulte Conformidade com o FIPS 140: suspensão do mecanismo de 2024.
Tópicos relacionados da
