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

# Importe uma chave simétrica de texto simples usando KMU AWS CloudHSM
<a name="key_mgmt_util-imSymKey"></a>

Use o **imSymKey** comando na ferramenta AWS CloudHSM key\_mgmt\_util para importar uma cópia em texto simples de uma chave simétrica de um arquivo para o módulo de segurança de hardware (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 [exSymKey](key_mgmt_util-exSymKey.md)comando 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](key_mgmt_util-wrapKey.md) e [unWrapKey](key_mgmt_util-unwrapKey.md)os comandos. 

Além disso, o comando **imSymKey** importa apenas chaves simétricas. Para importar chaves públicas, use [importPubKey](key_mgmt_util-importPubKey.md). Para importar chaves privadas, use [importPrivateKey](key_mgmt_util-importPrivateKey.md)ou [wrapKey](key_mgmt_util-wrapKey.md). 

**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](key-attribute-table.md) é 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](cloudhsm_mgmt_util.md) 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](key_mgmt_util-setup.md#key_mgmt_util-start) e [fazer login](key_mgmt_util-log-in.md) no HSM como um usuário de criptografia (CU). 

## Sintaxe
<a name="imSymKey-syntax"></a>

```
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
<a name="imSymKey-examples"></a>

Esses exemplos mostram como usar **imSymKey** para importar chaves simétricas para o seu HSMs.

**Example : Importar uma chave simétrica AES**  
Este exemplo usa **imSymKey** para importar uma chave simétrica AES para o. 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.key 32
```
O segundo comando é usado **imSymKey** para importar a chave AES do `aes256.key` arquivo para HSMs o. 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](key_mgmt_util-getAttribute.md) para obter o atributo OBJ\_ATTR\_LOCAL ([atributo 355](key-attribute-table.md)) 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
```

**Example : mover uma chave simétrica entre clusters**  
Este exemplo mostra como usar [exSymKey](key_mgmt_util-exSymKey.md) e **imSymKey** para mover uma chave AES de texto simples entre clusters. Você pode usar um processo como esse para criar um encapsulamento AES que exista nos HSMs dois clusters. Depois que a chave de empacotamento compartilhada estiver em vigor, você poderá usar [WrapKey [unWrapKey](key_mgmt_util-unwrapKey.md)](key_mgmt_util-wrapKey.md)e mover chaves criptografadas entre os clusters.  
O usuário da UC que executa essa operação deve ter permissão para fazer login no em ambos os clusters. HSMs   
O primeiro comando usa [exSymKey](key_mgmt_util-exSymKey.md) para exportar a chave 14, uma chave AES de 32 bits, do cluster 1 para o arquivo `aes.key`. Ele usa a chave 6, uma chave AES HSMs no cluster 1, como chave de empacotamento.   

```
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"
```
Em seguida, o usuário faz login no key\_mgmt\_util no cluster 2 e executa um **imSymKey** comando para importar a chave no `aes.key` arquivo para o cluster 2. HSMs Esse comando usa a chave 252152, uma chave AES HSMs no cluster 2, como chave de encapsulamento.   
Como as chaves de encapsulamento usadas por [exSymKey](key_mgmt_util-exSymKey.md) e **imSymKey** encapsulam e imediatamente desencapsulam as chaves de destino, as chaves de encapsulamento nos diferentes clusters não precisam ser iguais.   
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](key_mgmt_util-getAttribute.md) 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](key_mgmt_util-getAttribute.md) 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 HSMs de chave existe nos dois clusters, agora você pode compartilhar chaves criptografadas entre os clusters sem nunca expor a chave de 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.

**Example : 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](key_mgmt_util-getAttribute.md) ou [findKey](key_mgmt_util-findKey.md) 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
<a name="imSymKey-params"></a>

**-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 DES tripla do tamanho especificado. RC4 e as chaves DES não são válidas no modo FIPS HSMs.  
+ **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 HSMs no qual a chave é sincronizada antes que o valor do `-timeout` parâmetro expire. 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 acelerar seu processo, defina o valor de `min_srv` como menor 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 encapsulamento 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](key_mgmt_util-setAttribute.md).  
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 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:   
+ 21: [Triple DES (3DES)](https://en.wikipedia.org/wiki/Triple_DES).
+ 31: [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)
Obrigatório: Sim

**-u**  
Compartilha a chave que você está importando com usuários especificados. Esse parâmetro dá permissão a outros usuários de criptografia do HSM (CUs) para usar essa chave em operações criptográficas.   
Digite um ID ou uma lista separada por vírgulas do usuário do HSM IDs, 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](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_mgmt_util-listUsers.html) na ferramenta de linha de comando cloudhsm\_mgmt\_util ou o comando [listUsers](https://docs.aws.amazon.com/cloudhsm/latest/userguide/key_mgmt_util-listUsers.html) 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](key_mgmt_util-findKey.md).  
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](key_mgmt_util-getAttribute.md) para obter o valor do atributo `OBJ_ATTR_WRAP` (262). Para criar uma chave de encapsulamento, use [genSymKey](key_mgmt_util-genSymKey.md) a fim de criar uma chave AES (digite 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.  
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
<a name="imSymKey-seealso"></a>
+ [genSymKey](key_mgmt_util-genSymKey.md)
+ [exSymKey](key_mgmt_util-exSymKey.md)
+ [wrapKey](key_mgmt_util-wrapKey.md)
+ [unWrapKey](key_mgmt_util-unwrapKey.md)
+ [exportPrivateKey](key_mgmt_util-exportPrivateKey.md)
+ [exportPubKey](key_mgmt_util-exportPubKey.md)