# AWS KMS Exemplos do usando a AWS CLI
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS Command Line Interface com o AWS KMS.
*Ações* são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
**Topics**
+ [Ações](#actions)
## Ações
### `cancel-key-deletion`
O código de exemplo a seguir mostra como usar `cancel-key-deletion`.
**AWS CLI**
**Como programar a exclusão de uma chave do KMS gerenciada pelo cliente**
O exemplo `cancel-key-deletion` a seguir cancela a exclusão agendada de uma chave do KMS gerenciada pelo cliente.
```
aws kms cancel-key-deletion \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Resultado:
```
{
"KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
```
Quando o comando `cancel-key-deletion` é bem-sucedido, a exclusão programada é cancelada. No entanto, o estado da chave do KMS será `Disabled`, portanto, não é possível usar a chave do KMS em operações de criptografia. Para restaurar sua funcionalidade, use o comando `enable-key`.
Para obter mais informações, consulte [Programação e cancelamento de exclusão de chaves](https://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys.html#deleting-keys-scheduling-key-deletion) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [CancelKeyDeletion](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/cancel-key-deletion.html) na *Referência de comandos da AWS CLI*.
### `connect-custom-key-store`
O código de exemplo a seguir mostra como usar `connect-custom-key-store`.
**AWS CLI**
**Como conectar um repositório de chaves personalizado**
O exemplo `connect-custom-key-store` a seguir reconecta o repositório de chaves personalizadas especificado. É possível usar um comando como esse para conectar um repositório de chaves personalizado pela primeira vez ou para reconectar um repositório de chaves que foi desconectado.
É possível usar esse comando para conectar um repositório de chaves do AWS CloudHSM ou um repositório de chaves externo.
```
aws kms connect-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0
```
Esse comando não retorna nenhuma saída. Use o comando `describe-custom-key-stores` para verificar se o comando está em vigor.
Para obter informações sobre como conectar um repositório de chaves do AWS CloudHSM, consulte [Conectar e desconectar um repositório de chaves do AWS CloudHSM](https://docs.aws.amazon.com/kms/latest/developerguide/disconnect-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
Para obter informações sobre como conectar um repositório de chaves externo, consulte [Conectar e desconectar um repositório de chaves externo](https://docs.aws.amazon.com/kms/latest/developerguide/xks-connect-disconnect.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [ConnectCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/connect-custom-key-store.html) na *Referência de comandos da AWS CLI*.
### `create-alias`
O código de exemplo a seguir mostra como usar `create-alias`.
**AWS CLI**
**Como criar um alias para uma chave do KMS**
O comando `create-alias` a seguir cria um alias com o nome `example-alias` para a chave do KMS identificada pelo ID de chave `1234abcd-12ab-34cd-56ef-1234567890ab`.
Os nomes de alias devem começar com `alias/`. Não use nomes de alias que comecem com `alias/aws`. Eles são reservados para uso pela AWS.
```
aws kms create-alias \
--alias-name alias/example-alias \
--target-key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Esse comando não retorna resultados. Use o `list-aliases` comando para visualizar o novo alias.
Para obter mais informações, consulte [Using aliases](https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [CreateAlias](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/create-alias.html) na *Referência de comandos da AWS CLI*.
### `create-custom-key-store`
O código de exemplo a seguir mostra como usar `create-custom-key-store`.
**AWS CLI**
**Exemplo 1: criar um repositório de chaves do AWS CloudHSM**
O exemplo `create-custom-key-store` a seguir cria um repositório de chaves do AWS CloudHSM apoiado por um cluster do AWS CloudHSM usando os parâmetros necessários. Também é possível adicionar o `custom-key-store-type``parameter with the default value: ``AWS_CLOUDHSM`.
Para especificar a entrada do arquivo para o comando `trust-anchor-certificate` na AWS CLI, é necessário o prefixo `file://`.
```
aws kms create-custom-key-store \
--custom-key-store-name ExampleCloudHSMKeyStore \
--cloud-hsm-cluster-id cluster-1a23b4cdefg \
--key-store-password kmsPswd \
--trust-anchor-certificate file://customerCA.crt
```
Resultado:
```
{
"CustomKeyStoreId": cks-1234567890abcdef0
}
```
Para obter mais informações, consulte [Criar um repositório de chaves do AWS CloudHSM](https://docs.aws.amazon.com/kms/latest/developerguide/create-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 2: criar um repositório de chaves externo com conectividade de endpoint público**
O exemplo `create-custom-key-store` a seguir cria um repositório de chaves externo (XKS) que se comunica com o AWS KMS pela Internet.
Neste exemplo, o `XksProxyUriPath` usa um prefixo opcional de`example-prefix`.
OBSERVAÇÃO: se a versão 1.0 da AWS CLI está sendo usada, execute o comando a seguir antes de especificar um parâmetro com um valor HTTP ou HTTPS, como o parâmetro XksProxyUriEndpoint.
```
aws configure set cli_follow_urlparam false
```
Caso contrário, a versão 1.0 da AWS substitui o valor do parâmetro pelo conteúdo encontrado nesse endereço de URI.
```
aws kms create-custom-key-store \
--custom-key-store-name ExamplePublicEndpointXKS \
--custom-key-store-type EXTERNAL_KEY_STORE \
--xks-proxy-connectivity PUBLIC_ENDPOINT \
--xks-proxy-uri-endpoint "https://myproxy.xks.example.com" \
--xks-proxy-uri-path "/example-prefix/kms/xks/v1" \
--xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="
```
Resultado:
```
{
"CustomKeyStoreId": cks-2234567890abcdef0
}
```
Para obter mais informações, consulte [Criar um repositório de chaves externo](https://docs.aws.amazon.com/kms/latest/developerguide/create-keystorecreate-xks-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 3: criar um repositório de chaves externo com conectividade de serviço de endpoint da VPC**
O exemplo `create-custom-key-store` a seguir cria um repositório de chaves externo (XKS) que usa um serviço de endpoint da VPC da Amazon para se comunicar com o AWS KMS.
OBSERVAÇÃO: se a versão 1.0 da AWS CLI está sendo usada, execute o comando a seguir antes de especificar um parâmetro com um valor HTTP ou HTTPS, como o parâmetro XksProxyUriEndpoint.
```
aws configure set cli_follow_urlparam false
```
Caso contrário, a versão 1.0 da AWS substitui o valor do parâmetro pelo conteúdo encontrado nesse endereço de URI.
```
aws kms create-custom-key-store \
--custom-key-store-name ExampleVPCEndpointXKS \
--custom-key-store-type EXTERNAL_KEY_STORE \
--xks-proxy-connectivity VPC_ENDPOINT_SERVICE \
--xks-proxy-uri-endpoint "https://myproxy-private.xks.example.com" \
--xks-proxy-uri-path "/kms/xks/v1" \
--xks-proxy-vpc-endpoint-service-name "com.amazonaws.vpce.us-east-1.vpce-svc-example1" \
--xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="
```
Resultado:
```
{
"CustomKeyStoreId": cks-3234567890abcdef0
}
```
Para obter mais informações, consulte [Criar um repositório de chaves externo](https://docs.aws.amazon.com/kms/latest/developerguide/create-keystorecreate-xks-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [CreateCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/create-custom-key-store.html) na *Referência de comandos da AWS CLI*.
### `create-grant`
O código de exemplo a seguir mostra como usar `create-grant`.
**AWS CLI**
**Como criar uma concessão**
O exemplo de `create-grant` a seguir cria uma concessão que permite que o usuário `exampleUser` use o comando `decrypt` na chave do KMS `1234abcd-12ab-34cd-56ef-1234567890ab` de exemplo. A entidade principal descontinuada é o perfil `adminRole`. A concessão usa a restrição de concessão `EncryptionContextSubset` para conceder essa permissão apenas quando o contexto de criptografia na solicitação `decrypt` incluir o par de chave/valor `"Department": "IT"`.
```
aws kms create-grant \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--grantee-principal arn:aws:iam::123456789012:user/exampleUser \
--operations Decrypt \
--constraints EncryptionContextSubset={Department=IT} \
--retiring-principal arn:aws:iam::123456789012:role/adminRole
```
Resultado:
```
{
"GrantId": "1a2b3c4d2f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2",
"GrantToken": ""
}
```
Use o `list-grants` comando para visualizar informações detalhadas sobre a concessão.
Para obter mais informações, consulte [Grants in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [CreateGrant](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/create-grant.html) na *Referência de comandos da AWS CLI*.
### `create-key`
O código de exemplo a seguir mostra como usar `create-key`.
**AWS CLI**
**Exemplo 1: como criar uma chave do KMS gerenciada pelo cliente no AWS KMS**
O exemplo de `create-key` a seguir cria uma chave do KMS de criptografia simétrica.
Não é necessário especificar parâmetros para criar a chave básica do KMS (uma chave de criptografia simétrica). Os valores padrão desses parâmetros criam uma chave de criptografia simétrica.
Como esse comando não especifica uma política de chave, a chave do KMS adota a [política de chave padrão](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default) para chaves do KMS criadas programaticamente. Use o comando `get-key-policy` para visualizar a política de chave. Use o comando `put-key-policy` para alterar a política de chave.
```
aws kms create-key
```
O comando `create-key` retorna os metadados da chave, incluindo o ID da chave e o ARN da nova chave do KMS. Use esses valores para identificar a chave do KMS em outras operações do AWS KMS. A saída não inclui as tags. Use `list-resource-tags command` para visualizar as tags de uma chave do KMS.
Resultado:
```
{
"KeyMetadata": {
"AWSAccountId": "111122223333",
"Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": "2017-07-05T14:04:55-07:00",
"CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"Description": "",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "AWS_KMS"
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
]
}
}
```
Observação: o comando `create-key` não permite especificar um alias. Use o comando `create-alias` para especificar um alias para a nova chave do KMS.
Para obter mais informações, consulte [Creating keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 2: como criar uma chave RSA assimétrica do KMS para criptografia e decodificação**
O exemplo de `create-key` a seguir cria uma chave do KMS que contém um par de chaves RSA assimétrico para criptografia e descriptografia. A especificação da chave e o uso da chave não podem ser alterados depois que a chave é criada.
```
aws kms create-key \
--key-spec RSA_4096 \
--key-usage ENCRYPT_DECRYPT
```
Resultado:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2021-04-05T14:04:55-07:00",
"CustomerMasterKeySpec": "RSA_4096",
"Description": "",
"Enabled": true,
"EncryptionAlgorithms": [
"RSAES_OAEP_SHA_1",
"RSAES_OAEP_SHA_256"
],
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "RSA_4096",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "AWS_KMS"
}
}
```
Para obter mais informações, consulte [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 3: como criar uma chave do KMS de curva elíptica assimétrica para assinatura e verificação**
Como criar uma chave do KMS assimétrica que contém um par de chaves com curva elíptica (ECC) assimétrica para assinatura e verificação. O parâmetro `--key-usage` é obrigatório, embora `SIGN_VERIFY` seja o único valor válido para chaves ECC do KMS. A especificação da chave e o uso da chave não podem ser alterados depois que a chave é criada.
```
aws kms create-key \
--key-spec ECC_NIST_P521 \
--key-usage SIGN_VERIFY
```
Resultado:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2019-12-02T07:48:55-07:00",
"CustomerMasterKeySpec": "ECC_NIST_P521",
"Description": "",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "ECC_NIST_P521",
"KeyState": "Enabled",
"KeyUsage": "SIGN_VERIFY",
"MultiRegion": false,
"Origin": "AWS_KMS",
"SigningAlgorithms": [
"ECDSA_SHA_512"
]
}
}
```
Para obter mais informações, consulte [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 4: criar uma chave ML-DSA assimétrica do KMS para assinatura e verificação**
Este exemplo cria uma chave do algoritmo de assinatura digital baseado em rede de módulos (ML-DSA) para assinatura e verificação. O parâmetro key-usage é obrigatório, embora `SIGN_VERIFY` seja o único valor válido para chaves ML-DSA.
```
aws kms create-key \
--key-spec ML_DSA_65 \
--key-usage SIGN_VERIFY
```
Resultado:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2019-12-02T07:48:55-07:00",
"Description": "",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "ML_DSA_65",
"KeyState": "Enabled",
"KeyUsage": "SIGN_VERIFY",
"MultiRegion": false,
"Origin": "AWS_KMS",
"SigningAlgorithms": [
"ML_DSA_SHAKE_256"
]
}
}
```
Para obter mais informações, consulte [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 5: criar uma chave HMAC do KMS**
O exemplo de `create-key` a seguir cria uma chave do KMS com HMAC de 384 bits. O valor `GENERATE_VERIFY_MAC` é obrigatório para o parâmetro `--key-usage`, mesmo que seja o único valor válido para chaves do KMS com HMAC.
```
aws kms create-key \
--key-spec HMAC_384 \
--key-usage GENERATE_VERIFY_MAC
```
Resultado:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2022-04-05T14:04:55-07:00",
"CustomerMasterKeySpec": "HMAC_384",
"Description": "",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "HMAC_384",
"KeyState": "Enabled",
"KeyUsage": "GENERATE_VERIFY_MAC",
"MacAlgorithms": [
"HMAC_SHA_384"
],
"MultiRegion": false,
"Origin": "AWS_KMS"
}
}
```
Para obter mais informações, consulte [HMAC keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 6: criar uma chave do KMS primária multirregional**
O exemplo de `create-key` a seguir cria uma chave primária de criptografia simétrica multirregional. Como os valores padrão de todos os parâmetros criam uma chave de criptografia simétrica, somente o parâmetro `--multi-region` é necessário para a chave do KMS. Na AWS CLI, especifique o nome do parâmetro para indicar que o parâmetro booleano é verdadeiro.
```
aws kms create-key \
--multi-region
```
Resultado:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab",
"AWSAccountId": "111122223333",
"CreationDate": "2021-09-02T016:15:21-09:00",
"CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"Description": "",
"Enabled": true,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyId": "mrk-1234abcd12ab34cd56ef12345678990ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": true,
"MultiRegionConfiguration": {
"MultiRegionKeyType": "PRIMARY",
"PrimaryKey": {
"Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab",
"Region": "us-west-2"
},
"ReplicaKeys": []
},
"Origin": "AWS_KMS"
}
}
```
Para obter mais informações, consulte [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 7: criar uma chave do KMS para material de chave importada**
O exemplo de `create-key` a seguir cria uma chave do KMS sem material de chave. Quando a operação for concluída, você poderá importar seu próprio material de chave na chave do KMS. Defina o parâmetro `--origin` como `EXTERNAL` para criar a chave do KMS.
```
aws kms create-key \
--origin EXTERNAL
```
Resultado:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2019-12-02T07:48:55-07:00",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"Description": "",
"Enabled": false,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "PendingImport",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "EXTERNAL"
}
}
```
Para obter mais informações, consulte [Importing key material in AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 6: como criar uma chave do KMS em um repositório de chaves do AWS CloudHSM**
O exemplo de `create-key` a seguir cria uma chave do KMS no repositório de chaves do AWS CloudHSM especificado. A operação cria a chave do KMS e seus metadados no AWS KMS e cria o material da chave no cluster do AWS CloudHSM associado ao repositório de chaves personalizadas. Os parâmetros `--custom-key-store-id` e `--origin` são obrigatórios.
```
aws kms create-key \
--origin AWS_CLOUDHSM \
--custom-key-store-id cks-1234567890abcdef0
```
Resultado:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"CreationDate": "2019-12-02T07:48:55-07:00",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"Description": "",
"Enabled": true,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "AWS_CLOUDHSM"
}
}
```
Para obter mais informações, consulte [AWS CloudHSM key stores](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 8: criar uma chave do KMS em um repositório de chaves externo**
O exemplo de `create-key` a seguir cria uma chave do KMS no repositório de chaves externo especificado. Os parâmetros `--custom-key-store-id`, `--origin` e `--xks-key-id` são obrigatórios neste comando.
O parâmetro `--xks-key-id` especifica o ID de uma chave de criptografia simétrica existente no gerenciador de chaves externo. Essa chave serve como o material de chave externo para a chave do KMS. O valor do parâmetro `--origin` deve ser `EXTERNAL_KEY_STORE`. O parâmetro `custom-key-store-id` deve identificar um repositório de chaves externo conectado ao proxy do repositório de chaves externo.
```
aws kms create-key \
--origin EXTERNAL_KEY_STORE \
--custom-key-store-id cks-9876543210fedcba9 \
--xks-key-id bb8562717f809024
```
Resultado:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2022-12-02T07:48:55-07:00",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"CustomKeyStoreId": "cks-9876543210fedcba9",
"Description": "",
"Enabled": true,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "EXTERNAL_KEY_STORE",
"XksKeyConfiguration": {
"Id": "bb8562717f809024"
}
}
}
```
Para obter mais informações, consulte [External key stores](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [CreateKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/create-key.html) na *Referência de comandos da AWS CLI*.
### `decrypt`
O código de exemplo a seguir mostra como usar `decrypt`.
**AWS CLI**
**Exemplo 1: como descriptografar uma mensagem criptografada com uma chave simétrica do KMS (Linux e macOS)**
O exemplo de comando `decrypt` a seguir demonstra a forma recomendada de descriptografar dados com a AWS CLI. Esta versão mostra como descriptografar dados com uma chave simétrica do KMS.
Forneça o texto cifrado em um arquivo. No valor do parâmetro `--ciphertext-blob`, use o prefixo `fileb://`, que instrui a CLI a ler os dados de um arquivo binário. Se o arquivo não estiver no diretório atual, digite o caminho completo para o arquivo. Para obter mais informações sobre a leitura de valores de parâmetro da AWS CLI de um arquivo, consulte Carregar os parâmetros da AWS CLI de um arquivo (https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-file.html) no *Guia do usuário da AWS Command Line Interface* e Best Practices for Local File Parameters (https://aws.amazon.com/blogs/developer/best-practices-for-local-file-parameters/) no *AWS Command Line Tool Blog*. Especifique a chave do KMS para descriptografar o texto cifrado. O parâmetro `--key-id` não é necessário ao descriptografar com uma chave do KMS simétrica. O AWS KMS pode obter o ID de chave da chave do KMS usada para criptografar os dados dos metadados no texto cifrado. Porém, sempre é uma prática recomendada especificar a chave do KMS que você está usando. Esta prática garante que você use a chave do KMS desejada e impede que você descriptografe um texto cifrado acidentalmente usando uma chave do KMS em que você não confia. Solicite a saída de texto simples como um valor de texto. O parâmetro `--query` instrui a CLI obter somente o valor do campo `Plaintext` da saída. O parâmetro `--output` retorna a saída como texto. Decodifique o texto simples em Base64 e salve-o em um arquivo. O seguinte exemplo canaliza ( \$1 ) o valor do parâmetro `Plaintext` para o utilitário Base64, que o decodifica. Em seguida, ele redireciona ( > ) a saída decodificada para o arquivo `ExamplePlaintext`.
Antes de executar esse comando, substitua o ID de chave de exemplo por um ID de chave válido da sua conta da AWS.
```
aws kms decrypt \
--ciphertext-blob fileb://ExampleEncryptedFile \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--output text \
--query Plaintext | base64 \
--decode > ExamplePlaintextFile
```
Este comando não produz saída. A saída do comando `decrypt` é decodificada em base64 e salva em um arquivo.
Para obter mais informações, consulte [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) na *Referência da API do AWS Key Management Service*.
**Exemplo 2: como descriptografar uma mensagem criptografada com uma chave simétrica do KMS (prompt de comando do Windows)**
O exemplo a seguir é igual ao anterior, mas ele usa o utilitário `certutil` para decodificar em Base64 os dados em texto simples. Esse procedimento requer dois comandos, conforme mostrado nos exemplos a seguir.
Antes de executar esse comando, substitua o ID de chave de exemplo por um ID de chave válido da sua conta da AWS.
```
aws kms decrypt ^
--ciphertext-blob fileb://ExampleEncryptedFile ^
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab ^
--output text ^
--query Plaintext > ExamplePlaintextFile.base64
```
Execute o comando `certutil`.
```
certutil -decode ExamplePlaintextFile.base64 ExamplePlaintextFile
```
Resultado:
```
Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.
```
Para obter mais informações, consulte [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) na *Referência da API do AWS Key Management Service*.
**Exemplo 3: como descriptografar uma mensagem criptografada com uma chave assimétrica do KMS (Linux e macOS)**
O exemplo de comando `decrypt` a seguir mostra como descriptografar dados criptografados sob uma chave RSA assimétrica do KMS.
Ao usar uma chave assimétrica do KMS, o parâmetro `encryption-algorithm`, que especifica o algoritmo usado para criptografar o texto simples, é necessário.
Antes de executar esse comando, substitua o ID de chave de exemplo por um ID de chave válido da sua conta da AWS.
```
aws kms decrypt \
--ciphertext-blob fileb://ExampleEncryptedFile \
--key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
--encryption-algorithm RSAES_OAEP_SHA_256 \
--output text \
--query Plaintext | base64 \
--decode > ExamplePlaintextFile
```
Este comando não produz saída. A saída do comando `decrypt` é decodificada em base64 e salva em um arquivo.
Para obter mais informações, consulte [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [Decrypt](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/decrypt.html) na *Referência de comandos da AWS CLI*.
### `delete-alias`
O código de exemplo a seguir mostra como usar `delete-alias`.
**AWS CLI**
**Como excluir um alias do AWS KMS**
O exemplo de `delete-alias` a seguir exclui o alias `alias/example-alias`. O nome de alias deve começar com alias/.
```
aws kms delete-alias \
--alias-name alias/example-alias
```
Este comando não produz saída. Use o `list-aliases` comando para localizar o alias.
Para obter mais informações, consulte [Deleting an alias](https://docs.aws.amazon.com/kms/latest/developerguide/alias-manage.html#alias-delete) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [DeleteAlias](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/delete-alias.html) na *Referência de comandos da AWS CLI*.
### `delete-custom-key-store`
O código de exemplo a seguir mostra como usar `delete-custom-key-store`.
**AWS CLI**
**Para excluir um repositório de chaves personalizado**
O exemplo `delete-custom-key-store` a seguir exclui o repositório de chaves personalizado especificado.
A exclusão de um repositório de chaves do AWS CloudHSM não afeta o cluster do CloudHSM associado. A exclusão de um repositório de chaves externo não afeta o proxy do repositório de chaves externo, o gerenciador de chaves externas ou chaves externas associadas.
**OBSERVAÇÃO:** antes de excluir um repositório de chaves personalizado, é necessário agendar a exclusão de todas as chaves KMS no repositório de chaves personalizadas e esperar que essas chaves KMS sejam excluídas. Então, é necessário desconectar o repositório de chaves personalizado. Para obter ajuda para descobrir as chaves do KMS em seu repositório de chaves personalizado, consulte [Excluir um repositório de chaves do AWS CloudHSM (API)](https://docs.aws.amazon.com/kms/latest/developerguide/delete-keystore.html#delete-keystore-api) no *Guia do desenvolvedor do AWS Key Management Service*.
```
delete-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0
```
Esse comando não retorna nenhuma saída. Para verificar se o repositório de chaves personalizadas excluído, use o comando `describe-custom-key-stores`.
Para obter informações sobre como excluir um repositório de chaves do AWS CloudHSM, consulte [Excluir um repositório de chaves do AWS CloudHSM](https://docs.aws.amazon.com/kms/latest/developerguide/delete-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
Para obter informações sobre como excluir repositórios de chaves externos, consulte [Excluir um repositório de chaves externo](https://docs.aws.amazon.com/kms/latest/developerguide/delete-xks.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [DeleteCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/delete-custom-key-store.html) na *Referência de comandos da AWS CLI*.
### `delete-imported-key-material`
O código de exemplo a seguir mostra como usar `delete-imported-key-material`.
**AWS CLI**
**Para excluir material de chave importado de uma chave do KMS**
O exemplo `delete-imported-key-material` a seguir exclui o material de chave importado para uma chave do KMS.
```
aws kms delete-imported-key-material \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Resultado:
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}
```
Para ter mais informações, consulte [Deleting imported key material](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-delete-key-material.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [DeleteImportedKeyMaterial](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/delete-imported-key-material.html) na *Referência de comandos da AWS CLI*.
### `derive-shared-secret`
O código de exemplo a seguir mostra como usar `derive-shared-secret`.
**AWS CLI**
**Como derivar um segredo compartilhado**
O exemplo `derive-shared-secret` a seguir deriva um segredo compartilhado usando um algoritmo de acordo de chave.
É necessário usar um par de chave do KMS de curva elíptica assimétrica recomendado pela NIST (ECC) ou SM2 (somente nas regiões da China) com um valor de `KeyUsage` igual a `KEY_AGREEMENT` para chamar DeriveSharedSecret.
```
aws kms derive-shared-secret \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--key-agreement-algorithm ECDH \
--public-key "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvH3Yj0wbkLEpUl95Cv1cJVjsVNSjwGq3tCLnzXfhVwVvmzGN8pYj3U8nKwgouaHbBWNJYjP5VutbbkKS4Kv4GojwZBJyHN17kmxo8yTjRmjR15SKIQ8cqRA2uaERMLnpztIXdZp232PQPbWGxDyXYJ0aJ5EFSag"
```
Resultado:
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"SharedSecret": "MEYCIQCKZLWyTk5runarx6XiAkU9gv3lbwPO/pHa+DXFehzdDwIhANwpsIV2g/9SPWLLsF6p/hiSskuIXMTRwqrMdVKWTMHG",
"KeyAgreementAlgorithm": "ECDH",
"KeyOrigin": "AWS_KMS"
}
```
Para obter mais informações, consulte [DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) na *Referência da API do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [DeriveSharedSecret](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/derive-shared-secret.html) na *Referência de comandos da AWS CLI*.
### `describe-custom-key-stores`
O código de exemplo a seguir mostra como usar `describe-custom-key-stores`.
**AWS CLI**
**Exemplo 1: obter detalhes sobre um repositório de chaves do AWS CloudHSM**
O exemplo `describe-custom-key-store` a seguir exibe os detalhes sobre o repositório de chaves AWS CloudHSM especificado. O comando é o mesmo para todos os tipos de repositório de chaves personalizadas, mas a saída difere conforme o tipo de repositório de chaves e, para um repositório de chaves externo, conforme sua opção de conectividade.
Por padrão, esse comando exibe informações sobre todos os repositórios de chave personalizados na conta e região. Para exibir informações sobre um repositório de chaves personalizado específico, use o parâmetro `custom-key-store-name` ou `custom-key-store-id`.
```
aws kms describe-custom-key-stores \
--custom-key-store-name ExampleCloudHSMKeyStore
```
A saída desse comando inclui detalhes úteis sobre o repositório de chaves do AWS CloudHSM, incluindo seu estado de conexão (`ConnectionState`). Se o estado da conexão é `FAILED`, o resultado também inclui um campo `ConnectionErrorCode` que descreve o problema.
Resultado:
```
{
"CustomKeyStores": [
{
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionState": "CONNECTED",
"CreationDate": "2022-04-05T14:04:55-07:00",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleExternalKeyStore",
"TrustAnchorCertificate": ""
}
]
}
```
Para obter mais informações, consulte [Visualizar um repositório de chaves do AWS CloudHSM](https://docs.aws.amazon.com/kms/latest/developerguide/view-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 2: obter detalhes sobre um repositório de chaves externo com conectividade de endpoint público**
O exemplo `describe-custom-key-store` a seguir exibe os detalhes sobre o repositório de chaves externo. O comando é o mesmo para todos os tipos de repositório de chaves personalizadas, mas a saída difere conforme o tipo de repositório de chaves e, para um repositório de chaves externo, conforme sua opção de conectividade.
Por padrão, esse comando exibe informações sobre todos os repositórios de chave personalizados na conta e região. Para exibir informações sobre um repositório de chaves personalizado específico, use o parâmetro `custom-key-store-name` ou `custom-key-store-id`.
```
aws kms describe-custom-key-stores \
--custom-key-store-id cks-9876543210fedcba9
```
A saída desse comando inclui detalhes úteis sobre o repositório de chaves externo, incluindo seu estado de conexão (`ConnectionState`). Se o estado da conexão é `FAILED`, o resultado também inclui um campo `ConnectionErrorCode` que descreve o problema.
Resultado:
```
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-9876543210fedcba9",
"CustomKeyStoreName": "ExampleXKS",
"ConnectionState": "CONNECTED",
"CreationDate": "2022-12-02T07:48:55-07:00",
"CustomKeyStoreType": "EXTERNAL_KEY_STORE",
"XksProxyConfiguration": {
"AccessKeyId": "ABCDE12345670EXAMPLE",
"Connectivity": "PUBLIC_ENDPOINT",
"UriEndpoint": "https://myproxy.xks.example.com",
"UriPath": "/example-prefix/kms/xks/v1"
}
}
]
}
```
Para obter mais informações, consulte [Visualizar um repositório de chaves externo](https://docs.aws.amazon.com/kms/latest/developerguide/view-xks-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 3: obter detalhes sobre um repositório de chaves externo com conectividade de serviço de endpoint da VPC**
O exemplo `describe-custom-key-store` a seguir exibe os detalhes sobre o repositório de chaves externo. O comando é o mesmo para todos os tipos de repositório de chaves personalizadas, mas a saída difere conforme o tipo de repositório de chaves e, para um repositório de chaves externo, conforme sua opção de conectividade.
Por padrão, esse comando exibe informações sobre todos os repositórios de chave personalizados na conta e região. Para exibir informações sobre um repositório de chaves personalizado específico, use o parâmetro `custom-key-store-name` ou `custom-key-store-id`.
```
aws kms describe-custom-key-stores \
--custom-key-store-id cks-2234567890abcdef0
```
A saída desse comando inclui detalhes úteis sobre o repositório de chaves externo, incluindo seu estado de conexão (`ConnectionState`). Se o estado da conexão é `FAILED`, o resultado também inclui um campo `ConnectionErrorCode` que descreve o problema.
Resultado:
```
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-3234567890abcdef0",
"CustomKeyStoreName": "ExampleVPCExternalKeyStore",
"ConnectionState": "CONNECTED",
"CreationDate": "2022-12-22T07:48:55-07:00",
"CustomKeyStoreType": "EXTERNAL_KEY_STORE",
"XksProxyConfiguration": {
"AccessKeyId": "ABCDE12345670EXAMPLE",
"Connectivity": "VPC_ENDPOINT_SERVICE",
"UriEndpoint": "https://myproxy-private.xks.example.com",
"UriPath": "/kms/xks/v1",
"VpcEndpointServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-example1"
}
}
]
}
```
Para obter mais informações, consulte [Visualizar um repositório de chaves externo](https://docs.aws.amazon.com/kms/latest/developerguide/view-xks-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [DescribeCustomKeyStores](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/describe-custom-key-stores.html) na *Referência de comandos da AWS CLI*.
### `describe-key`
O código de exemplo a seguir mostra como usar `describe-key`.
**AWS CLI**
**Exemplo 1: como localizar informações detalhadas sobre uma chave do KMS**
O exemplo de `describe-key` a seguir obtém informações detalhadas sobre a chave gerenciada da AWS para o Amazon S3 na conta e região do exemplo. Você pode usar esse comando para encontrar detalhes sobre chaves gerenciadas pela AWS e pelo cliente.
Use o parâmetro `key-id` para especificar a chave do KMS. Este exemplo usa um valor de nome de alias, mas você pode usar um ID de chave, o ARN da chave, o nome do alias ou o ARN do alias neste comando.
```
aws kms describe-key \
--key-id alias/aws/s3
```
Resultado:
```
{
"KeyMetadata": {
"AWSAccountId": "846764612917",
"KeyId": "b8a9477d-836c-491f-857e-07937918959b",
"Arn": "arn:aws:kms:us-west-2:846764612917:key/b8a9477d-836c-491f-857e-07937918959b",
"CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"CreationDate": 2017-06-30T21:44:32.140000+00:00,
"Enabled": true,
"Description": "Default KMS key that protects my S3 objects when no other key is defined",
"KeyUsage": "ENCRYPT_DECRYPT",
"KeyState": "Enabled",
"Origin": "AWS_KMS",
"KeyManager": "AWS",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
]
}
}
```
Para obter mais informações, consulte [Viewing keys](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 2: como obter detalhes sobre uma chave RSA assimétrica do KMS**
O exemplo de `describe-key` a seguir obtém informações detalhadas sobre uma chave RSA assimétrica do KMS usada para assinatura e verificação.
```
aws kms describe-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Resultado:
```
{
"KeyMetadata": {
"AWSAccountId": "111122223333",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": "2019-12-02T19:47:14.861000+00:00",
"CustomerMasterKeySpec": "RSA_2048",
"Enabled": false,
"Description": "",
"KeyState": "Disabled",
"Origin": "AWS_KMS",
"MultiRegion": false,
"KeyManager": "CUSTOMER",
"KeySpec": "RSA_2048",
"KeyUsage": "SIGN_VERIFY",
"SigningAlgorithms": [
"RSASSA_PKCS1_V1_5_SHA_256",
"RSASSA_PKCS1_V1_5_SHA_384",
"RSASSA_PKCS1_V1_5_SHA_512",
"RSASSA_PSS_SHA_256",
"RSASSA_PSS_SHA_384",
"RSASSA_PSS_SHA_512"
]
}
}
```
**Exemplo 3: como obter detalhes sobre uma chave de réplica multirregional**
O exemplo de `describe-key` a seguir os obtém metadados de uma chave de réplica multirregional. Essa chave multirregional é uma chave de criptografia simétrica. A saída de um comando `describe-key` para qualquer chave multirregional retorna informações sobre a chave primária e todas as suas réplicas.
```
aws kms describe-key \
--key-id arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab
```
Resultado:
```
{
"KeyMetadata": {
"MultiRegion": true,
"AWSAccountId": "111122223333",
"Arn": "arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"CreationDate": "2021-06-28T21:09:16.114000+00:00",
"CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"Description": "",
"Enabled": true,
"KeyId": "mrk-1234abcd12ab34cd56ef1234567890ab",
"KeyManager": "CUSTOMER",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"Origin": "AWS_KMS",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"MultiRegionConfiguration": {
"MultiRegionKeyType": "PRIMARY",
"PrimaryKey": {
"Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "us-west-2"
},
"ReplicaKeys": [
{
"Arn": "arn:aws:kms:eu-west-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "eu-west-1"
},
{
"Arn": "arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "ap-northeast-1"
},
{
"Arn": "arn:aws:kms:sa-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "sa-east-1"
}
]
}
}
}
```
**Exemplo 4: como obter detalhes sobre uma chave do KMS com HMAC**
O exemplo de `describe-key` a seguir obtém informações detalhadas sobre uma chave do KMS com HMAC.
```
aws kms describe-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Resultado:
```
{
"KeyMetadata": {
"AWSAccountId": "123456789012",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Arn": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": "2022-04-03T22:23:10.194000+00:00",
"Enabled": true,
"Description": "Test key",
"KeyUsage": "GENERATE_VERIFY_MAC",
"KeyState": "Enabled",
"Origin": "AWS_KMS",
"KeyManager": "CUSTOMER",
"CustomerMasterKeySpec": "HMAC_256",
"MacAlgorithms": [
"HMAC_SHA_256"
],
"MultiRegion": false
}
}
```
+ Consulte detalhes da API em [DescribeKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/describe-key.html) na *Referência de comandos da AWS CLI*.
### `disable-key-rotation`
O código de exemplo a seguir mostra como usar `disable-key-rotation`.
**AWS CLI**
**Para desativar a rotação automática de uma chave do KMS**
O exemplo `disable-key-rotation` a seguir desativa a rotação automática de uma chave do KMS gerenciada pelo cliente. Para reativar a rotação automática, use o comando `enable-key-rotation`.
```
aws kms disable-key-rotation \
--key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
Este comando não produz saída. Para verificar se a rotação automática está desativada para a chave do KMS, use o comando `get-key-rotation-status`.
Para obter mais informações, consulte [Rotacionar chaves](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [DisableKeyRotation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/disable-key-rotation.html) na *Referência de comandos da AWS CLI*.
### `disable-key`
O código de exemplo a seguir mostra como usar `disable-key`.
**AWS CLI**
**Como desativar uma chave do KMS temporariamente**
O exemplo `disable-key` a seguir desabilita uma chave do KMS gerenciada pelo cliente. Use o `enable-key` comando para reabilitar a chave do KMS.
```
aws kms disable-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Este comando não produz saída.
Para obter mais informações, consulte [Enabling and Disabling Keys](https://docs.aws.amazon.com/kms/latest/developerguide/enabling-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [DisableKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/disable-key.html) na *Referência de comandos da AWS CLI*.
### `disconnect-custom-key-store`
O código de exemplo a seguir mostra como usar `disconnect-custom-key-store`.
**AWS CLI**
**Como desconectar um repositório de chaves personalizado**
O exemplo `disconnect-custom-key-store` a seguir desconecta um repositório de chaves personalizado do cluster do AWS CloudHSM. Pode ser desejável desconectar um repositório de chaves para solucionar um problema, atualizar suas configurações ou impedir que as chaves do KMS no repositório de chaves sejam usadas em operações criptográficas.
Esse comando é o mesmo para todos os repositórios de chaves personalizados, inclusive os armazenamentos de chaves do AWS CloudHSM e repositórios de chaves externos.
Antes de executar um comando como esse, substitua o ID de exemplo do armazenamento de chaves personalizado por um válido.
```
$ aws kms disconnect-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0
```
Este comando não produz saída. Para confirmar a efetividade do comando, use o comando `describe-custom-key-stores`.
Para obter mais informações sobre como desconectar um repositório de chaves do AWS CloudHSM, consulte [Conectar e desconectar um repositório de chaves do AWS CloudHSM](https://docs.aws.amazon.com/kms/latest/developerguide/disconnect-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
Para obter mais informações sobre como desconectar um repositório de chaves externo, consulte [Conectar e desconectar um repositório de chaves externo](https://docs.aws.amazon.com/kms/latest/developerguide/xks-connect-disconnect.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [DisconnectCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/disconnect-custom-key-store.html) na *Referência de comandos da AWS CLI*.
### `enable-key-rotation`
O código de exemplo a seguir mostra como usar `enable-key-rotation`.
**AWS CLI**
**Como ativar a rotação automática de uma chave do KMS**
O exemplo de `enable-key-rotation` a seguir viabiliza a alternância automática de uma chave do KMS gerenciada pelo cliente com um período de alternância de 180 dias. A chave do KMS será alternada em um ano (aproximadamente 365 dias) a partir da data em que esse comando for concluído e todos os anos a partir de então.
O parâmetro `--key-id` identifica a chave do KMS. Este exemplo usa o valor do ARN da chave, mas é possível usar o ID da chave ou o ARN da chave do KMS. O parâmetro `--rotation-period-in-days` especifica o número de dias entre as datas de cada rotação. Especifique um valor entre 90 e 2.560 dias. Se nenhum valor for especificado, o valor padrão será de 365 dias.
```
aws kms enable-key-rotation \
--key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
--rotation-period-in-days 180
```
Este comando não produz saída. Use o `get-key-rotation-status` comando para verificar se a chave KMS está habilitada.
Para obter mais informações, consulte [Rotacionar chaves](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [EnableKeyRotation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/enable-key-rotation.html) na *Referência de comandos da AWS CLI*.
### `enable-key`
O código de exemplo a seguir mostra como usar `enable-key`.
**AWS CLI**
**Para habilitar uma chave do KMS**
O exemplo de `enable-key` a seguir habilita uma chave gerenciada pelo cliente. Você pode usar um comando como esse para habilitar uma chave do KMS que foi temporariamente desabilitada usando o comando `disable-key`. Você também pode usá-lo para habilitar uma chave do KMS que está desabilitada porque foi programada para exclusão, mas a exclusão foi cancelada.
Use o parâmetro `key-id` para especificar a chave do KMS. Este exemplo usa um valor de ID de chave, mas você pode usar um ID de chave ou o valor do ARN da chave neste comando.
Antes de executar esse comando, substitua o ID da chave de exemplo por um ID válido.
```
aws kms enable-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Este comando não produz saída. Use o `describe-key` comando para verificar se a chave KMS está habilitada. Consulte os valores dos campos `KeyState` e `Enabled` na saída `describe-key`.
Para obter mais informações, consulte [Enabling and Disabling Keys](https://docs.aws.amazon.com/kms/latest/developerguide/enabling-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [EnableKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/enable-key.html) na *Referência de comandos da AWS CLI*.
### `encrypt`
O código de exemplo a seguir mostra como usar `encrypt`.
**AWS CLI**
**Exemplo 1: como criptografar o conteúdo de um arquivo no Linux ou no macOS**
O comando `encrypt` a seguir demonstra a forma recomendada de criptografar dados com a AWS CLI.
```
aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob | base64 \
--decode > ExampleEncryptedFile
```
O comando realiza diversas ações:
Usa o parâmetro `--plaintext` para indicar os dados a serem criptografados. Esse valor de parâmetro deve ser codificado em base64. O valor do parâmetro `plaintext` deve ser codificado em base64, ou você deve usar o prefixo `fileb://`, que informa a AWS CLI para que leia os dados binários do arquivo. Se o arquivo não estiver no diretório atual, digite o caminho completo do arquivo. Por exemplo: `fileb:///var/tmp/ExamplePlaintextFile` ou `fileb://C:\Temp\ExamplePlaintextFile`. Para ter mais informações sobre a leitura de valores de parâmetros da AWS CLI em um arquivo, consulte [Carregar um parâmetro de um arquivo](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#cli-using-param-file) na *Referência de comandos da AWS Command Line Interface* e [Best Practices for Local File Parameters](https://blogs.aws.amazon.com/cli/post/TxLWWN1O25V1HE/Best-Practices-for-Local-File-Parameters) no AWS Developer Tools Blog. Usa o `--output` e o `--query` para controlar a saída do comando. Esses parâmetros extraem os dados criptografados, denominados *texto cifrado* da saída do comando. Para ter mais informações sobre como controlar a saída, consulte [Controle de saída do comando](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html) no *Guia do usuário da AWS Command Line Interface*. Usa o utilitário `base64` para decodificar a saída extraída para dados binários. O texto cifrado exibido por um comando `encrypt` bem-sucedido é um texto codificado em base64. Você deve codificar o texto antes de usar a AWS CLI para descriptografá-lo. Salva o texto cifrado binário em um arquivo. A parte final do comando (`> ExampleEncryptedFile`) salva o texto cifrado binário em um arquivo para facilitar a descriptografia. Consulte os exemplos de descriptografia para ver um comando de exemplo que usa a AWS CLI para descriptografar dados.
**Exemplo 2: como usar a AWS CLI para criptografar dados no Windows**
Esse exemplo é igual ao exemplo anterior, mas usa a ferramenta `certutil` em vez do `base64`. Esse procedimento requer dois comandos, conforme mostrado no exemplo a seguir.
```
aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob > C:\Temp\ExampleEncryptedFile.base64
certutil -decode C:\Temp\ExampleEncryptedFile.base64 C:\Temp\ExampleEncryptedFile
```
**Exemplo 3: criptografia com uma chave do KMS assimétrica**
O comando `encrypt` a seguir mostra como criptografar texto simples com uma chave assimétrica do KMS. O parâmetro `--encryption-algorithm` é obrigatório. Como em todos os comandos da `encrypt` CLI, o parâmetro `plaintext` deve ser codificado em base64 ou você deve usar o prefixo `fileb://`, que informa a AWS CLI para ler os dados binários do arquivo.
```
aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--encryption-algorithm RSAES_OAEP_SHA_256 \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob | base64 \
--decode > ExampleEncryptedFile
```
Este comando não produz saída.
+ Consulte detalhes da API em [Encrypt](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/encrypt.html) na *Referência de comandos da AWS CLI*.
### `generate-data-key-pair-without-plaintext`
O código de exemplo a seguir mostra como usar `generate-data-key-pair-without-plaintext`.
**AWS CLI**
**Para gerar um par de chaves de dados assimétricos ECC NIST P**
O exemplo `generate-data-key-pair-without-plaintext` a seguir solicita um par de chaves ECC NIST P384 para uso fora da AWS.
O comando retorna uma chave pública de texto descriptografado e uma cópia da chave privada criptografada na chave do KMS especificada. Ele não retorna uma chave privada de texto descriptografado. É possível armazenar a chave privada criptografada com os dados criptografados com segurança, e chamar o AWS KMS para descriptografar a chave privada quando precisar usá-la.
Para solicitar um par de chaves de dados assimétricos ECC NIST P384, use o parâmetro `key-pair-spec` com um valor de `ECC_NIST_P384`.
A chave do KMS especificada deve ser uma chave de criptografia simétrica do KMS, ou seja, uma chave do KMS com um valor de `KeySpec` igual a `SYMMETRIC_DEFAULT`.
OBSERVAÇÃO: os valores na saída deste exemplo são truncados para exibição.
```
aws kms generate-data-key-pair-without-plaintext \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--key-pair-spec ECC_NIST_P384
```
Resultado:
```
{
"PrivateKeyCiphertextBlob": "AQIDAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAFFxmiD134doUDzMGmfCEtcAAAHaTCCB2UGCSqGSIb3DQEHBqCCB1...",
"PublicKey": "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA3A3eGMyPrvSn7+LdlJE1oUoQV5HpEuHAVbdOyND+NmYDH/mL1OSIEuLrcdZ5hrMH4pk83r40l...",
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"KeyPairSpec": "ECC_NIST_P384"
}
```
As `PublicKey` e `PrivateKeyCiphertextBlob` são retornadas no formato codificado em base64.
Para obter mais informações, consulte [Pares de chaves de dados](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-key-pairs) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [GenerateDataKeyPairWithoutPlaintext](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-data-key-pair-without-plaintext.html) na *Referência de comandos da AWS CLI*.
### `generate-data-key-pair`
O código de exemplo a seguir mostra como usar `generate-data-key-pair`.
**AWS CLI**
**Para gerar um par de chaves de dados assimétricos RSA de 2048 bits**
O exemplo `generate-data-key-pair` a seguir solicita uma par de chave de dados assimétrico RSA de 2048 bits para uso fora da AWS. O comando retorna uma chave de dados em texto simples para uso e exclusão imediatos e uma cópia da chave de dados criptografada na chave do KMS especificada. A chave de dados criptografada pode ser armazenada com segurança junto com os dados criptografados.
Para solicitar um par de chave de dados assimétrico RSA de 2048 bits, use o parâmetro `key-pair-spec` com o valor `RSA_2048`.
A chave do KMS especificada deve ser uma chave de criptografia simétrica do KMS, ou seja, uma chave do KMS com um valor de `KeySpec` igual a `SYMMETRIC_DEFAULT`.
OBSERVAÇÃO: os valores na saída deste exemplo são truncados para exibição.
```
aws kms generate-data-key-pair \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--key-pair-spec RSA_2048
```
Resultado:
```
{
"PrivateKeyCiphertextBlob": "AQIDAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAFFxmiD134doUDzMGmfCEtcAAAHaTCCB2UGCSqGSIb3DQEHBqCCB1...",
"PrivateKeyPlaintext": "MIIG/QIBADANBgkqhkiG9w0BAQEFAASCBucwggbjAgEAAoIBgQDcDd4YzI+u9Kfv4t2UkTWhShBXkekS4cBVt07I0P42ZgMf+YvU5IgS4ut...",
"PublicKey": "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA3A3eGMyPrvSn7+LdlJE1oUoQV5HpEuHAVbdOyND+NmYDH/mL1OSIEuLrcdZ5hrMH4pk83r40l...",
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
"KeyPairSpec": "RSA_2048"
}
```
As `PublicKey`, `PrivateKeyPlaintext` e `PrivateKeyCiphertextBlob` são retornadas no formato codificado em base64.
Para obter mais informações, consulte [Pares de chaves de dados](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-key-pairs) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [GenerateDataKeyPair](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-data-key-pair.html) na *Referência de comandos da AWS CLI*.
### `generate-data-key-without-plaintext`
O código de exemplo a seguir mostra como usar `generate-data-key-without-plaintext`.
**AWS CLI**
**Como gerar uma chave de dados simétrica de 256 bits sem uma chave de texto simples**
O exemplo de `generate-data-key-without-plaintext` a seguir solicita uma cópia criptografada de uma chave de dados simétrica de 256 bits para uso externo à AWS. Você pode chamar o AWS KMS para descriptografar a chave de dados quando quiser usá-la.
Use o parâmetro `key-spec` com um valor de `AES_256` para solicitar uma chave de dados de 256 bits. Use o parâmetro `key-spec` com um valor de `AES_128` para solicitar uma chave de dados de 128 bits. Para todos os outros comprimentos de chave de dados, use o parâmetro `number-of-bytes`.
A chave do KMS especificada deve ser uma chave de criptografia simétrica do KMS, ou seja, uma chave do KMS com um valor de especificação de chave de SYMMETRIC\$1DEFAULT.
```
aws kms generate-data-key-without-plaintext \
--key-id "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
--key-spec AES_256
```
Resultado:
```
{
"CiphertextBlob": "AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDEFogL",
"KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}
```
A `CiphertextBlob` (chave de dados criptografada) é retornada em um formato codificado em base64.
Para obter mais informações, consulte [Data keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [GenerateDataKeyWithoutPlaintext](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-data-key-without-plaintext.html) na *Referência de comandos da AWS CLI*.
### `generate-data-key`
O código de exemplo a seguir mostra como usar `generate-data-key`.
**AWS CLI**
**Exemplo 1: como gerar uma chave de dados simétrica de 256 bits**
O exemplo `generate-data-key` a seguir solicita uma chave de dados simétrica de 256 bits para uso externo à AWS. O comando retorna uma chave de dados em texto simples para uso e exclusão imediatos e uma cópia da chave de dados criptografada na chave do KMS especificada. A chave de dados criptografada pode ser armazenada com segurança junto com os dados criptografados.
Use o parâmetro `key-spec` com um valor de `AES_256` para solicitar uma chave de dados de 256 bits. Use o parâmetro `key-spec` com um valor de `AES_128` para solicitar uma chave de dados de 128 bits. Para todos os outros comprimentos de chave de dados, use o parâmetro `number-of-bytes`.
A chave do KMS especificada deve ser uma chave de criptografia simétrica do KMS, ou seja, uma chave do KMS com um valor de especificação de chave de SYMMETRIC\$1DEFAULT.
```
aws kms generate-data-key \
--key-id alias/ExampleAlias \
--key-spec AES_256
```
Resultado:
```
{
"Plaintext": "VdzKNHGzUAzJeRBVY+uUmofUGGiDzyB3+i9fVkh3piw=",
"KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"CiphertextBlob": "AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDEFogLqPWZconQhwHAIBEIA7d9AC7GeJJM34njQvg4Wf1d5sw0NIo1MrBqZa+YdhV8MrkBQPeac0ReRVNDt9qleAt+SHgIRF8P0H+7U="
}
```
A `Plaintext` (chave de dados em texto simples) e a `CiphertextBlob` (chave de dados criptografada) são retornadas no formato codificado em base64.
Para obter mais informações, consulte [Data keys](https://docs.aws.amazon.com/kms/latest/developerguide/data-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*. **Exemplo 2: como gerar uma chave de dados simétrica de 512 bits**
O exemplo de `generate-data-key` a seguir solicita uma chave de dados simétrica de 512 bits para criptografia e descriptografia. O comando retorna uma chave de dados em texto simples para uso e exclusão imediatos e uma cópia da chave de dados criptografada na chave do KMS especificada. A chave de dados criptografada pode ser armazenada com segurança junto com os dados criptografados.
Use o parâmetro `number-of-bytes` para solicitar um comprimento de chave diferente de 128 ou 256 bits. Para solicitar uma chave de dados de 512 bits, o exemplo a seguir usa o parâmetro `number-of-bytes` com um valor de 64 (bytes).
A chave do KMS especificada deve ser uma chave de criptografia simétrica do KMS, ou seja, uma chave do KMS com um valor de especificação de chave de SYMMETRIC\$1DEFAULT.
OBSERVAÇÃO: os valores na saída deste exemplo são truncados para exibição.
```
aws kms generate-data-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--number-of-bytes 64
```
Resultado:
```
{
"CiphertextBlob": "AQIBAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAEnX/QQNmMwDfg2korNMEc8AAACaDCCAmQGCSqGSIb3DQEHBqCCAlUwggJRAgEAMIICSgYJKoZ...",
"Plaintext": "ty8Lr0Bk6OF07M2BWt6qbFdNB+G00ZLtf5MSEb4al3R2UKWGOp06njAwy2n72VRm2m7z/Pm9Wpbvttz6a4lSo9hgPvKhZ5y6RTm4OovEXiVfBveyX3DQxDzRSwbKDPk/...",
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}
```
`Plaintext` (chave de dados em texto simples) e `CiphertextBlob` (chave de dados criptografada) são retornadas no formato codificado em base64.
Para obter mais informações, consulte [Data keys](https://docs.aws.amazon.com/kms/latest/developerguide/data-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [GenerateDataKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-data-key.html) na *Referência de comandos da AWS CLI*.
### `generate-mac`
O código de exemplo a seguir mostra como usar `generate-mac`.
**AWS CLI**
**Exemplo 1: gerar um HMAC para uma mensagem**
O comando `generate-mac` a seguir gera um HMAC para uma mensagem, uma chave HMAC do KMS e um algoritmo MAC. A chave HMAC especificada do KMS deve ser compatível com o algoritmo.
Na AWS CLI v2, o valor do parâmetro `message` deve ser codificado em base64. Também é possível salvar a mensagem em um arquivo e usar o prefixo `fileb://`, que instrui a AWS CLI a ler dados binários do arquivo.
Antes de executar esse comando, substitua o ID de chave de exemplo por um ID de chave válido da sua conta da AWS. O ID da chave deverá representar uma chave HMAC do KMS com o uso da chave `GENERATE_VERIFY_MAC`.
```
msg=(echo 'Hello World' | base64)
aws kms generate-mac \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://Message \
--mac-algorithm HMAC_SHA_384
```
Resultado:
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"Mac": "",
"MacAlgorithm": "HMAC_SHA_384"
}
```
Para ter mais informações sobre como usar chaves HMAC do KMS no AWS KMS, consulte [HMAC keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 2: salvar um HMAC em um arquivo (Linux e macOS)**
O exemplo `generate-mac` a seguir gera um HMAC para uma mensagem curta armazenada em um arquivo local. O comando também obtém a propriedade `Mac` da resposta, decodifica a resposta em base64 e salva a resposta no arquivo ExampleMac. É possível usar o arquivo MAC em um comando `verify-mac` que verifique o MAC.
O comando `generate-mac` requer uma mensagem codificada em base64 e um algoritmo MAC compatível com sua chave HMAC do KMS. Para obter os algoritmos MAC compatíveis com sua chave do KMS, use o comando `describe-key`.
Antes de executar esse comando, substitua o ID de chave de exemplo por um ID de chave válido da sua conta da AWS. O ID da chave deve representar uma chave assimétrica do KMS com o uso da chave GENERATE\$1VERIFY\$1MAC.
```
echo 'hello world' | base64 > EncodedMessage
aws kms generate-mac \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://EncodedMessage \
--mac-algorithm HMAC_SHA_384 \
--output text \
--query Mac | base64 --decode > ExampleMac
```
Este comando não produz saída. Este exemplo extrai a propriedade `Mac` da saída e a salva em um arquivo.
Para ter mais informações sobre como usar chaves HMAC do KMS no AWS KMS, consulte [HMAC keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [GenerateMac](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-mac.html) na *Referência de comandos da AWS CLI*.
### `generate-random`
O código de exemplo a seguir mostra como usar `generate-random`.
**AWS CLI**
**Exemplo 1: como gerar uma string de bytes aleatória de 256 bits (Linux ou macOS)**
O exemplo de `generate-random` a seguir gera uma string de bytes aleatórios de 256 bits (32 bytes) codificada em base64. O exemplo decodifica a string de bytes e a salva no arquivo aleatório.
Ao executar esse comando, use o parâmetro `number-of-bytes` para especificar o tamanho do valor aleatório em bytes.
Você não especifica uma chave do KMS ao executar esse comando. A sequência de bytes aleatória não está relacionada a nenhuma chave do KMS.
Por padrão, o AWS KMS gera o número aleatório. No entanto, se você especificar um [repositório de chaves personalizado](https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html), a sequência de bytes aleatória será gerada no cluster do AWS CloudHSM associado ao repositório de chaves personalizado.
Este exemplo usa os seguintes parâmetros e valores:
Ele usa o parâmetro obrigatório `--number-of-bytes` com o valor de `32` para solicitar uma string de 32 bytes (256 bits). Ele usa o parâmetro `--output` com o valor de `text` para direcionar a AWS CLI a retornar a saída como texto em vez de um JSON. Ele usa `--query parameter` para extrair o valor da propriedade `Plaintext` da resposta. Ele canaliza ( \$1 ) a saída do comando para o utilitário `base64`, que decodifica a saída extraída. Ele usa o operador de redirecionamento ( > ) para salvar a string de bytes decodificada no arquivo `ExampleRandom`. Ele usa o operador de redirecionamento ( > ) para salvar o texto cifrado binário em um arquivo.
```
aws kms generate-random \
--number-of-bytes 32 \
--output text \
--query Plaintext | base64 --decode > ExampleRandom
```
Este comando não produz saída.
Para obter mais informações, consulte [GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom.html) na *Referência da API do AWS Key Management Service*.
**Exemplo 2: como gerar um número aleatório de 256 bits (prompt de comando do Windows)**
O exemplo a seguir usa o comando `generate-random` para gerar uma string aleatória de 256 bits (32 bytes) codificada em base64. O exemplo decodifica a string de bytes e a salva no arquivo aleatório. Esse exemplo é igual ao exemplo anterior, mas usa o utilitário `certutil` no Windows para decodificar em base64 a string de bytes aleatória antes de salvá-la em um arquivo.
Primeiro, gere uma string de bytes aleatória codificada em base64 e salve-a em um arquivo temporário (`ExampleRandom.base64`).
```
aws kms generate-random \
--number-of-bytes 32 \
--output text \
--query Plaintext > ExampleRandom.base64
```
Como a saída do comando `generate-random` é salva em um arquivo, esse exemplo não produz nenhuma saída.
Use o comando `certutil -decode` para decodificar a string de bytes codificada em base64 no arquivo `ExampleRandom.base64`. Em seguida, ele salva a string de bytes decodificada no arquivo `ExampleRandom`.
```
certutil -decode ExampleRandom.base64 ExampleRandom
```
Resultado:
```
Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.
```
Para obter mais informações, consulte [GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom.html) na *Referência da API do AWS Key Management Service*.
+ Consulte detalhes da API em [GenerateRandom](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-random.html) na *Referência de comandos da AWS CLI*.
### `get-key-policy`
O código de exemplo a seguir mostra como usar `get-key-policy`.
**AWS CLI**
**Como copiar uma política de chave de uma chave do KMS para outra chave do KMS**
O exemplo de `get-key-policy` a seguir obtém a política de chave de uma chave do KMS e a salva em um arquivo de texto. Em seguida, ele substitui a política de uma chave diferente do KMS usando o arquivo de texto como a entrada da política.
Como o parâmetro `--policy` de `put-key-policy` requer uma string, você deve usar a opção `--output text` para retornar a saída como uma string de texto em vez de JSON.
```
aws kms get-key-policy \
--policy-name default \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--query Policy \
--output text > policy.txt
aws kms put-key-policy \
--policy-name default \
--key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
--policy file://policy.txt
```
Este comando não produz saída.
Para obter mais informações, consulte [PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) na *Referência da API do AWS KMS*.
+ Consulte detalhes da API em [GetKeyPolicy](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/get-key-policy.html) na *Referência de comandos da AWS CLI*.
### `get-key-rotation-status`
O código de exemplo a seguir mostra como usar `get-key-rotation-status`.
**AWS CLI**
**Para recuperar o status de rotação de uma chave do KMS.**
O exemplo `get-key-rotation-status` a seguir retorna informações sobre o status de rotação da chave do KMS especificada, incluindo se a rotação automática está ativada, o período de rotação e a próxima data de rotação programada. É possível usar esse comando em chaves do KMS gerenciadas pelo cliente e chaves do KMS gerenciadas pela AWS. No entanto, todas as chaves do KMS gerenciadas pela AWS são alternadas automaticamente a cada ano.
```
aws kms get-key-rotation-status \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Resultado:
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyRotationEnabled": true,
"NextRotationDate": "2024-02-14T18:14:33.587000+00:00",
"RotationPeriodInDays": 365
}
```
Para obter mais informações, consulte [Rotacionar chaves](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [GetKeyRotationStatus](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/get-key-rotation-status.html) na *Referência de comandos da AWS CLI*.
### `get-parameters-for-import`
O código de exemplo a seguir mostra como usar `get-parameters-for-import`.
**AWS CLI**
**Para obter os itens necessários para importar material de chave para uma chave do KMS**
O exemplo `get-parameters-for-import` a seguir obtém a chave pública e o token de importação necessários para importar material de chave para uma chave do KMS. Ao usar o comando `import-key-material`, certifique-se de usar o token de importação e o material da chave criptografados pela chave pública que foram retornados no mesmo comando `get-parameters-for-import`. Além disso, o algoritmo de encapsulamento especificado neste comando deve ser usado para criptografar o material de chave com a chave pública.
Use o parâmetro `key-id` para especificar a chave do KMS. Este exemplo usa um valor de ID de chave, mas é possível usar o ID ou ARN da chave neste comando.
```
aws kms get-parameters-for-import \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--wrapping-algorithm RSAES_OAEP_SHA_256 \
--wrapping-key-spec RSA_2048
```
Resultado:
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"PublicKey": "",
"ImportToken": "",
"ParametersValidTo": 1593893322.32
}
```
Para obter mais informações, consulte [Baixar a chave pública e o token de importação](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-get-public-key-and-token.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [GetParametersForImport](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/get-parameters-for-import.html) na *Referência de comandos da AWS CLI*.
### `get-public-key`
O código de exemplo a seguir mostra como usar `get-public-key`.
**AWS CLI**
**Exemplo 1: baixar a chave pública de uma chave do KMS assimétrica**
O exemplo `get-public-key` a seguir baixa a chave pública de uma chave do KMS assimétrica.
Além de retornar a chave pública, a saída inclui informações necessárias para usar a chave pública com segurança fora do AWS KMS, inclusive o uso da chave e os algoritmos de criptografia compatíveis.
```
aws kms get-public-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Resultado:
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"PublicKey": "jANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAl5epvg1/QtJhxSi2g9SDEVg8QV/...",
"CustomerMasterKeySpec": "RSA_4096",
"KeyUsage": "ENCRYPT_DECRYPT",
"EncryptionAlgorithms": [
"RSAES_OAEP_SHA_1",
"RSAES_OAEP_SHA_256"
]
}
```
Para obter mais informações sobre o uso de chaves assimétricas do KMS no AWS KMS, consulte [Chaves assimétricas no AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) no *Guia do desenvolvedor do AWS Key Management Service*. **Exemplo 2: converter uma chave pública para o formato DER (Linux e macOS)**
O exemplo `get-public-key` a seguir baixa a chave pública de uma chave do KMS assimétrica e a salva em um arquivo DER.
Ao usar o comando `get-public-key` na AWS CLI, ele retorna uma chave pública X.509 codificada em DER, que é codificada em Base64. Este exemplo obtém o valor da propriedade `PublicKey` como texto. Ele decodifica a `PublicKey` em Base64 e a salva no arquivo `public_key.der`. O parâmetro `output` retorna a saída como texto, em vez de JSON. O parâmetro `--query` obtém somente a propriedade `PublicKey`, não as propriedades necessárias para usar a chave pública com segurança fora do AWS KMS.
Antes de executar esse comando, substitua o ID de chave de exemplo por um ID de chave válido da sua conta da AWS.
```
aws kms get-public-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--output text \
--query PublicKey | base64 --decode > public_key.der
```
Este comando não produz saída.
Para obter mais informações sobre o uso de chaves assimétricas do KMS no AWS KMS, consulte [Chaves assimétricas no AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [GetPublicKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/get-public-key.html) na *Referência de comandos da AWS CLI*.
### `import-key-material`
O código de exemplo a seguir mostra como usar `import-key-material`.
**AWS CLI**
**Para importar o material de chave para uma chave do KMS**
O exemplo `import-key-material` a seguir carrega material da chave em uma chave do KMS que criada sem material de chave. O estado da chave do KMS deve ser `PendingImport`.
Esse comando usa o material da chave criptografada com a chave pública que o comando `get-parameters-for-import` retornou. Ele também usa o token de importação do mesmo comando `get-parameters-for-import`.
O parâmetro `expiration-model` indica que o material da chave expira automaticamente na data e hora especificadas pelo parâmetro `valid-to`. Quando o material de chave expira, o AWS KMS exclui o material de chave, o estado da chave do KMS é alterado para `Pending import` e a chave do KMS se torna inutilizável. Para restaurar a chave do KMS, é necessário reimportar o mesmo material de chave. Para usar outro material de chave, é necessário criar uma nova chave do KMS.
Antes de executar esse comando, substitua o ID de chave de exemplo por um ID ou ARN de chave válidos da sua conta da AWS.
```
aws kms import-key-material \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--encrypted-key-material fileb://EncryptedKeyMaterial.bin \
--import-token fileb://ImportToken.bin \
--expiration-model KEY_MATERIAL_EXPIRES \
--valid-to 2021-09-21T19:00:00Z
```
Resultado:
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}
```
Para obter mais informações sobre como importar material de chave, consulte [Importar material de chave](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [ImportKeyMaterial](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/import-key-material.html) na *Referência de comandos da AWS CLI*.
### `list-aliases`
O código de exemplo a seguir mostra como usar `list-aliases`.
**AWS CLI**
**Exemplo 1: listar todos os aliases em uma conta e região da AWS**
O exemplo a seguir usa o comando `list-aliases` para listar todos os aliases na região padrão da conta da AWS. A saída inclui aliases associados às chaves do KMS gerenciadas pela AWS e pelo cliente.
```
aws kms list-aliases
```
Resultado:
```
{
"Aliases": [
{
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/testKey",
"AliasName": "alias/testKey",
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
},
{
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/FinanceDept",
"AliasName": "alias/FinanceDept",
"TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321"
},
{
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/dynamodb",
"AliasName": "alias/aws/dynamodb",
"TargetKeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
},
{
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/ebs",
"AliasName": "alias/aws/ebs",
"TargetKeyId": "0987ab65-43cd-21ef-09ab-87654321cdef"
},
...
]
}
```
**Exemplo 2: como listar todos os aliases de uma chave específica do KMS**
O exemplo a seguir usa o comando `list-aliases` e seu parâmetro `key-id` para listar todos os aliases associados a uma determinada chave do KMS.
Cada alias é associado a apenas um chave do KMS, mas uma chave do KMS pode ter vários aliases. Esse comando é muito útil porque o console do AWS KMS lista somente um alias para cada chave do KMS. Você deve usar o comando `list-aliases` para localizar todos os aliases de uma chave do KMS.
Este exemplo usa o ID de chave da chave do KMS no parâmetro `--key-id`, mas você pode usar um ID de chave, o ARN da chave, o nome do alias ou o ARN do alias neste comando.
```
aws kms list-aliases --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Resultado:
```
{
"Aliases": [
{
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/oregon-test-key",
"AliasName": "alias/oregon-test-key"
},
{
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/project121-test",
"AliasName": "alias/project121-test"
}
]
}
```
Para obter mais informações, consulte [Working with aliases](https://docs.aws.amazon.com/kms/latest/developerguide/programming-aliases.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [ListAliases](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-aliases.html) na *Referência de comandos da AWS CLI*.
### `list-grants`
O código de exemplo a seguir mostra como usar `list-grants`.
**AWS CLI**
**Como visualizar as concessões de uma chave do AWS KMS**
O exemplo de `list-grants` a seguir exibe todas as concessões da chave especificada do KMS gerenciada pela AWS para o Amazon DynamoDB na conta. Essa concessão permite que o DynamoDB use a chave do KMS em seu nome para criptografar uma tabela do DynamoDB antes de gravá-la no disco. Você pode usar um comando como esse para visualizar as concessões nas chaves do KMS gerenciadas pela AWS e nas chaves do KMS gerenciadas pelo cliente na conta e na região da AWS.
Este comando usa o parâmetro `key-id` com um ID de chave para identificar a chave do KMS. Você pode usar um ID de chave ou o ARN da chave para identificar a chave do KMS. Para obter o ID da chave ou o ARN da chave de uma chave do KMS gerenciada pela AWS, use o comando `list-keys` ou o `list-aliases`.
```
aws kms list-grants \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
O resultado mostra que a concessão fornece ao Amazon DynamoDB permissão para usar a chave do KMS para operações criptográficas e permite que ele visualize detalhes sobre a chave do KMS (`DescribeKey`) e descontinue concessões (`RetireGrant`). A restrição `EncryptionContextSubset` limita a permissão às solicitações que incluem os pares de contexto de criptografia especificados. Como resultado, as permissões na concessão são efetivas somente na conta especificada e na tabela do DynamoDB.
```
{
"Grants": [
{
"Constraints": {
"EncryptionContextSubset": {
"aws:dynamodb:subscriberId": "123456789012",
"aws:dynamodb:tableName": "Services"
}
},
"IssuingAccount": "arn:aws:iam::123456789012:root",
"Name": "8276b9a6-6cf0-46f1-b2f0-7993a7f8c89a",
"Operations": [
"Decrypt",
"Encrypt",
"GenerateDataKey",
"ReEncryptFrom",
"ReEncryptTo",
"RetireGrant",
"DescribeKey"
],
"GrantId": "1667b97d27cf748cf05b487217dd4179526c949d14fb3903858e25193253fe59",
"KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"RetiringPrincipal": "dynamodb.us-west-2.amazonaws.com",
"GranteePrincipal": "dynamodb.us-west-2.amazonaws.com",
"CreationDate": "2021-05-13T18:32:45.144000+00:00"
}
]
}
```
Para obter mais informações, consulte [Grants in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [ListGrants](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-grants.html) na *Referência de comandos da AWS CLI*.
### `list-key-policies`
O código de exemplo a seguir mostra como usar `list-key-policies`.
**AWS CLI**
**Como obter os nomes das políticas de chave de uma chave do KMS**
O exemplo de `list-key-policies` a seguir obtém os nomes das políticas de chave de uma chave gerenciada pelo cliente na conta e região de exemplo. Você pode usar esse comando para encontrar os nomes das políticas de chave de chaves gerenciadas pela AWS e pelo cliente.
Como o único nome de política de chave válido é `default`, esse comando não é muito útil.
Use o parâmetro `key-id` para especificar a chave do KMS. Este exemplo usa um valor de ID de chave, mas você pode usar um ID de chave ou o ARN da chave neste comando.
```
aws kms list-key-policies \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Resultado:
```
{
"PolicyNames": [
"default"
]
}
```
Para obter mais informações sobre as políticas de chave do AWS KMS, consulte [Using Key Policies in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [ListKeyPolicies](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-key-policies.html) na *Referência de comandos da AWS CLI*.
### `list-key-rotations`
O código de exemplo a seguir mostra como usar `list-key-rotations`.
**AWS CLI**
**Para recuperar informações sobre todas as rotações de materiais de chave concluídas**
O exemplo `list-key-rotations` a seguir lista informações sobre todas as rotações de materiais de chave concluídas para a chave do KMS especificada.
```
aws kms list-key-rotations \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Resultado:
```
{
"Rotations": [
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"RotationDate": "2024-03-02T10:11:36.564000+00:00",
"RotationType": "AUTOMATIC"
},
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"RotationDate": "2024-04-05T15:14:47.757000+00:00",
"RotationType": "ON_DEMAND"
}
],
"Truncated": false
}
```
Para obter mais informações, consulte [Rotacionar chaves](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [ListKeyRotations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-key-rotations.html) na *Referência de comandos da AWS CLI*.
### `list-keys`
O código de exemplo a seguir mostra como usar `list-keys`.
**AWS CLI**
**Como obter chaves do KMS em uma conta e região**
O exemplo `list-keys` a seguir obtém as chaves do KMS em uma conta e região. Esse comando retorna chaves gerenciadas pela AWS e pelo cliente.
```
aws kms list-keys
```
Resultado:
```
{
"Keys": [
{
"KeyArn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
},
{
"KeyArn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
"KeyId": "0987dcba-09fe-87dc-65ba-ab0987654321"
},
{
"KeyArn": "arn:aws:kms:us-east-2:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d",
"KeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
}
]
}
```
Para obter mais informações, consulte [Viewing Keys](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [ListKeys](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-keys.html) na *Referência de comandos da AWS CLI*.
### `list-resource-tags`
O código de exemplo a seguir mostra como usar `list-resource-tags`.
**AWS CLI**
**Para obter as tags em uma chave do KMS**
O exemplo `list-resource-tags` a seguir obtém as tags de uma chave do KMS. Para adicionar ou substituir tags de recursos das chaves do KMS, use o comando `tag-resource`. A saída mostra que essa chave do KMS tem duas tags de recursos, cada uma com uma chave e um valor.
Use o parâmetro `key-id` para especificar a chave do KMS. Este exemplo usa um valor de ID de chave, mas você pode usar um ID de chave ou o ARN da chave neste comando.
```
aws kms list-resource-tags \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Resultado:
```
{
"Tags": [
{
"TagKey": "Dept",
"TagValue": "IT"
},
{
"TagKey": "Purpose",
"TagValue": "Test"
}
],
"Truncated": false
}
```
Para obter mais informações sobre como usar tags no AWS KMS, consulte [Marcar chaves](https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [ListResourceTags](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-resource-tags.html) na *Referência de comandos da AWS CLI*.
### `list-retirable-grants`
O código de exemplo a seguir mostra como usar `list-retirable-grants`.
**AWS CLI**
**Como visualizar as concessões que uma entidade principal pode retirar**
O exemplo `list-retirable-grants` a seguir exibe todas as concessões que o usuário `ExampleAdmin` pode retirar das chaves do KMS em uma conta e região da AWS. É possível usar uma linha de comando como essa para visualizar as concessões que qualquer entidade principal da conta pode retirar nas chaves do KMS na conta e região da AWS.
O valor do parâmetro obrigatório `retiring-principal` deve ser o nome do recurso da Amazon (ARN) de uma conta, usuário ou perfil.
Não é possível especificar um serviço para o valor de `retiring-principal` neste comando, mesmo que um serviço seja a entidade principal que esteja retirando. Para encontrar as concessões nas quais um determinado serviço é a entidade principal que esteja retirando, use o comando `list-grants`.
A saída mostra que o usuário `ExampleAdmin` tem permissão para retirar concessões em duas chaves do KMS diferentes na conta e região. Além da entidade principal que está retirando, a conta tem permissão para retirar qualquer concessão desta conta.
```
aws kms list-retirable-grants \
--retiring-principal arn:aws:iam::111122223333:user/ExampleAdmin
```
Resultado:
```
{
"Grants": [
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"GrantId": "156b69c63cb154aa21f59929ff19760717be8d9d82b99df53e18b94a15a5e88e",
"Name": "",
"CreationDate": 2021-01-14T20:17:36.419000+00:00,
"GranteePrincipal": "arn:aws:iam::111122223333:user/ExampleUser",
"RetiringPrincipal": "arn:aws:iam::111122223333:user/ExampleAdmin",
"IssuingAccount": "arn:aws:iam::111122223333:root",
"Operations": [
"Encrypt"
],
"Constraints": {
"EncryptionContextSubset": {
"Department": "IT"
}
}
},
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
"GrantId": "8c94d1f12f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2",
"Name": "",
"CreationDate": "2021-02-02T19:49:49.638000+00:00",
"GranteePrincipal": "arn:aws:iam::111122223333:role/ExampleRole",
"RetiringPrincipal": "arn:aws:iam::111122223333:user/ExampleAdmin",
"IssuingAccount": "arn:aws:iam::111122223333:root",
"Operations": [
"Decrypt"
],
"Constraints": {
"EncryptionContextSubset": {
"Department": "IT"
}
}
}
],
"Truncated": false
}
```
Para obter mais informações, consulte [Grants in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [ListRetirableGrants](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-retirable-grants.html) na *Referência de comandos da AWS CLI*.
### `put-key-policy`
O código de exemplo a seguir mostra como usar `put-key-policy`.
**AWS CLI**
**Como alterar a política de chaves de uma chave do KMS**
O exemplo de `put-key-policy` a seguir altera a política de chave de uma chave gerenciada pelo cliente.
Para começar, crie uma política de chave e salve-a em um arquivo JSON local. Neste exemplo, o arquivo é `key_policy.json`. Você também pode especificar a política de chave como o valor da string do parâmetro `policy`.
A primeira instrução nesta política de chave fornece à conta da AWS permissão para usar as políticas do IAM para controlar o acesso à chave do KMS. A segunda instrução fornece permissão de usuário ao `test-user` para executar os comandos `describe-key` e `list-keys` na chave do KMS.
Conteúdo de `key_policy.json`:
```
{
"Version":"2012-10-17",
"Id" : "key-default-1",
"Statement" : [
{
"Sid" : "Enable IAM User Permissions",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:root"
},
"Action" : "kms:*",
"Resource" : "*"
},
{
"Sid" : "Allow Use of Key",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:user/test-user"
},
"Action" : [
"kms:DescribeKey",
"kms:ListKeys"
],
"Resource" : "*"
}
]
}
```
Este exemplo usa o ID de chave para identificar a chave do KMS, mas também é possível usar um ARN de chave. O comando usa o parâmetro `policy` para especificar a política de chave. Para indicar que a política está em um arquivo, ela usa o prefixo `file://` necessário. Esse prefixo é necessário para identificar arquivos em todos os sistemas operacionais compatíveis. Por fim, o comando usa o parâmetro `policy-name` com um valor `default`. Se não for especificado um nome de política, o valor padrão será `default`. O único valor válido é `default`.
```
aws kms put-key-policy \
--policy-name default \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--policy file://key_policy.json
```
Esse comando não produz nenhuma saída. Use o comando `get-key-policy` para verificar se o comando está em vigor. O comando de exemplo a seguir recupera a política de chave da mesma chave do KMS. O parâmetro `output` com o valor `text` retorna um formato de texto fácil de ler.
```
aws kms get-key-policy \
--policy-name default \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--output text
```
Resultado:
```
{
"Version":"2012-10-17",
"Id" : "key-default-1",
"Statement" : [
{
"Sid" : "Enable IAM User Permissions",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:root"
},
"Action" : "kms:*",
"Resource" : "*"
},
{
"Sid" : "Allow Use of Key",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:user/test-user"
},
"Action" : [ "kms:Describe", "kms:List" ],
"Resource" : "*"
}
]
}
```
Para obter mais informações, consulte [Changing a Key Policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [PutKeyPolicy](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/put-key-policy.html) na *Referência de comandos da AWS CLI*.
### `re-encrypt`
O código de exemplo a seguir mostra como usar `re-encrypt`.
**AWS CLI**
**Exemplo 1: como criptografar novamente uma mensagem criptografada com uma chave simétrica diferente do KMS (Linux e macOS).**
O exemplo de comando `re-encrypt` a seguir demonstra a forma recomendada de recriptografar dados com a AWS CLI.
Forneça o texto cifrado em um arquivo. No valor do parâmetro `--ciphertext-blob`, use o prefixo `fileb://`, que instrui a CLI a ler os dados de um arquivo binário. Se o arquivo não estiver no diretório atual, digite o caminho completo para o arquivo. Para ter mais informações sobre como ler valores de parâmetro da AWS CLI por meio de um arquivo, consulte [Carregar um parâmetro de um arquivo na AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-file.html) no *Guia do usuário da versão 2 da AWS Command Line Interface* e [Best Practices for Local File Parameters](https://aws.amazon.com/blogs/developer/best-practices-for-local-file-parameters/) no *AWS Developer Tools Blog*. Especifique a chave do KMS, que descriptografa o texto cifrado. O parâmetro `--source-key-id` não é obrigatório ao descriptografar com chaves do KMS de criptografia simétrica. O AWS KMS pode recuperar a chave do KMS que foi usada para criptografar os dados dos metadados no blob de texto cifrado. Porém, sempre é uma prática recomendada especificar a chave do KMS que você está usando. Essa prática garante que você use a chave do KMS desejada e impede que você descriptografe um texto cifrado acidentalmente usando uma chave do KMS em que você não confia. Especifique a chave do KMS de destino, que criptografa os dados novamente. O parâmetro `--destination-key-id` é sempre obrigatório. Este exemplo usa um ARN de chave, mas você pode usar qualquer identificador de chave válido. Solicite a saída de texto simples como um valor de texto. O parâmetro `--query` informa à CLI para obter somente o valor do campo `Plaintext` da saída. O parâmetro `--output` retorna a saída como texto. Decodifique o texto simples em Base64 e salve-o em um arquivo. O seguinte exemplo canaliza ( \$1 ) o valor do parâmetro `Plaintext` para o utilitário Base64, que o decodifica. Em seguida, ele redireciona ( > ) a saída decodificada para o arquivo `ExamplePlaintext`.
Antes de executar esse comando, substitua os IDs de chave de exemplo por identificadores de chave válidos de sua conta da AWS.
```
aws kms re-encrypt \
--ciphertext-blob fileb://ExampleEncryptedFile \
--source-key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--destination-key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
--query CiphertextBlob \
--output text | base64 --decode > ExampleReEncryptedFile
```
Este comando não produz saída. A saída do comando `re-encrypt` é decodificada em base64 e salva em um arquivo.
Para ter mais informações, consulte [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) na *Referência de API do AWS Key Management Service*.
**Exemplo 2: como criptografar novamente uma mensagem criptografada com uma chave simétrica diferente do KMS (prompt de comando do Windows).**
O exemplo de comando `re-encrypt` a seguir é o mesmo que o anterior, mas ele usa o utilitário `certutil` para decodificar em Base64 os dados em texto simples. Esse procedimento requer dois comandos, conforme mostrado nos exemplos a seguir.
Antes de executar esse comando, substitua o ID de chave de exemplo por um ID de chave válido da sua conta da AWS.
```
aws kms re-encrypt ^
--ciphertext-blob fileb://ExampleEncryptedFile ^
--source-key-id 1234abcd-12ab-34cd-56ef-1234567890ab ^
--destination-key-id 0987dcba-09fe-87dc-65ba-ab0987654321 ^
--query CiphertextBlob ^
--output text > ExampleReEncryptedFile.base64
```
Em seguida, use o utilitário `certutil`.
```
certutil -decode ExamplePlaintextFile.base64 ExamplePlaintextFile
```
Resultado:
```
Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.
```
Para ter mais informações, consulte [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) na *Referência de API do AWS Key Management Service*.
+ Consulte detalhes da API em [ReEncrypt](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/re-encrypt.html) na *Referência de comandos da AWS CLI*.
### `retire-grant`
O código de exemplo a seguir mostra como usar `retire-grant`.
**AWS CLI**
**Como descontinuar uma concessão em uma chave mestra do cliente**
O exemplo de `retire-grant` a seguir exclui a concessão de uma chave do KMS.
O comando de exemplo a seguir especifica os parâmetros `grant-id` e `key-id`. O valor do parâmetro `key-id` deve ser o ARN de chave da chave do KMS.
```
aws kms retire-grant \
--grant-id 1234a2345b8a4e350500d432bccf8ecd6506710e1391880c4f7f7140160c9af3 \
--key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
Este comando não produz saída. Use o comando `list-grants` para confirmar a descontinuação da concessão.
Para obter mais informações, consulte [Retiring and revoking grants](https://docs.aws.amazon.com/kms/latest/developerguide/grant-manage.html#grant-delete) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [RetireGrant](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/retire-grant.html) na *Referência de comandos da AWS CLI*.
### `revoke-grant`
O código de exemplo a seguir mostra como usar `revoke-grant`.
**AWS CLI**
**Como revogar uma concessão em uma chave mestra do cliente**
O exemplo de `revoke-grant` a seguir exclui a concessão de uma chave do KMS. O comando de exemplo a seguir especifica os parâmetros `grant-id` e `key-id`. O valor do parâmetro `key-id` pode ser o ID ou o ARN de chave da chave do KMS.
```
aws kms revoke-grant \
--grant-id 1234a2345b8a4e350500d432bccf8ecd6506710e1391880c4f7f7140160c9af3 \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Este comando não produz saída. Use o comando `list-grants` para confirmar que a concessão foi revogada.
Para obter mais informações, consulte [Retiring and revoking grants](https://docs.aws.amazon.com/kms/latest/developerguide/grant-manage.html#grant-delete) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [RevokeGrant](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/revoke-grant.html) na *Referência de comandos da AWS CLI*.
### `rotate-key-on-demand`
O código de exemplo a seguir mostra como usar `rotate-key-on-demand`.
**AWS CLI**
**Como realizar a rotação sob demanda de uma chave do KMS**
O exemplo `rotate-key-on-demand` a seguir inicia imediatamente a rotação do material de chave para a chave do KMS especificada.
```
aws kms rotate-key-on-demand \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Resultado:
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
}
```
Para obter mais informações, consulte [Como realizar uma rotação de chave sob demanda](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotating-keys-on-demand) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [RotateKeyOnDemand](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/rotate-key-on-demand.html) na *Referência de comandos da AWS CLI*.
### `schedule-key-deletion`
O código de exemplo a seguir mostra como usar `schedule-key-deletion`.
**AWS CLI**
**Como programar a exclusão de uma chave do KMS gerenciada pelo cliente.**
O exemplo de `schedule-key-deletion` a seguir programa a chave do KMS gerenciada pelo cliente especificada pala ser excluída em 15 dias.
O parâmetro `--key-id` identifica a chave do KMS. Este exemplo usa o valor do ARN da chave, mas você pode usar o ID da chave ou o ARN da chave do KMS. O parâmetro `--pending-window-in-days` especifica a duração do período de espera (7 a 30 dias). Por padrão, o período de espera é de 30 dias. Este exemplo especifica o valor de 15, que informa à AWS para excluir a chave do KMS permanentemente 15 dias após a conclusão do comando.
```
aws kms schedule-key-deletion \
--key-id arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab \
--pending-window-in-days 15
```
A resposta inclui o ARN da chave, o estado da chave, o período de espera (`PendingWindowInDays`) e a data de exclusão no horário Unix. Use o console do AWS KMS para visualizar a data de exclusão no horário local. As chaves do KMS no estado `PendingDeletion` não podem ser usadas em operações criptográficas.
```
{
"KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"DeletionDate": "2022-06-18T23:43:51.272000+00:00",
"KeyState": "PendingDeletion",
"PendingWindowInDays": 15
}
```
Para obter mais informações, consulte [Deleting keys](https://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [ScheduleKeyDeletion](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/schedule-key-deletion.html) na *Referência de comandos da AWS CLI*.
### `sign`
O código de exemplo a seguir mostra como usar `sign`.
**AWS CLI**
**Exemplo 1: gerar uma assinatura digital para uma mensagem**
O exemplo de `sign` a seguir gera uma assinatura criptográfica para uma mensagem curta. A saída do comando inclui um campo `Signature` codificado em base 64 que pode ser verificado usando o comando `verify`.
É necessário especificar uma mensagem para assinar e um algoritmo de assinatura compatível com sua chave do KMS assimétrica. Para obter os algoritmos de assinatura para sua chave do KMS, use o comando `describe-key`.
Na AWS CLI v2, o valor do parâmetro `message` deve ser codificado em base64. Também é possível salvar a mensagem em um arquivo e usar o prefixo `fileb://`, que instrui a AWS CLI a ler dados binários do arquivo.
Antes de executar esse comando, substitua o ID de chave de exemplo por um ID de chave válido da sua conta da AWS. O ID da chave deverá representar uma chave assimétrica do KMS com o uso da chave SIGN\$1VERIFY.
```
msg=(echo 'Hello World' | base64)
aws kms sign \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://UnsignedMessage \
--message-type RAW \
--signing-algorithm RSASSA_PKCS1_V1_5_SHA_256
```
Resultado:
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"Signature": "ABCDEFhpyVYyTxbafE74ccSvEJLJr3zuoV1Hfymz4qv+/fxmxNLA7SE1SiF8lHw80fKZZ3bJ...",
"SigningAlgorithm": "RSASSA_PKCS1_V1_5_SHA_256"
}
```
Para obter mais informações sobre o uso de chaves assimétricas do KMS no AWS KMS, consulte [Chaves assimétricas no AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 2: salvar uma assinatura digital em um arquivo (Linux e macOS)**
O exemplo de `sign` a seguir gera uma assinatura criptográfica para uma mensagem curta armazenada em um arquivo local. O comando também obtém a propriedade `Signature` da resposta, decodifica a resposta em base64 e salva a resposta no arquivo ExampleSignature. É possível usar o arquivo de assinatura em um comando `verify` que verifique a assinatura.
O comando `sign` requer uma mensagem codificada em base64 e um algoritmo de assinatura compatível com sua chave assimétrica do KMS. Para obter os algoritmos de assinatura compatíveis com sua chave do KMS, use o comando `describe-key`.
Antes de executar esse comando, substitua o ID de chave de exemplo por um ID de chave válido da sua conta da AWS. O ID da chave deve representar uma chave KMS assimétrica com o uso da chave SIGN\$1VERIFY.
```
echo 'hello world' | base64 > EncodedMessage
aws kms sign \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://EncodedMessage \
--message-type RAW \
--signing-algorithm RSASSA_PKCS1_V1_5_SHA_256 \
--output text \
--query Signature | base64 --decode > ExampleSignature
```
Este comando não produz saída. Este exemplo extrai a propriedade `Signature` da saída e a salva em um arquivo.
Para obter mais informações sobre o uso de chaves assimétricas do KMS no AWS KMS, consulte [Chaves assimétricas no AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [Sign](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/sign.html) na *Referência de comandos da AWS CLI*.
### `tag-resource`
O código de exemplo a seguir mostra como usar `tag-resource`.
**AWS CLI**
**Para adicionar uma tag a uma chave do KMS**
O exemplo de `tag-resource` a seguir adiciona as tags `"Purpose":"Test"` e `"Dept":"IT"` a uma chave do KMS gerenciada pelo cliente. É possível usar tags como essas para identificar chaves do KMS e criar categorias de chaves do KMS para permissões e auditoria.
Use o parâmetro `key-id` para especificar a chave do KMS. Este exemplo usa um valor de ID de chave, mas você pode usar um ID de chave ou o ARN da chave neste comando.
```
aws kms tag-resource \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--tags TagKey='Purpose',TagValue='Test' TagKey='Dept',TagValue='IT'
```
Este comando não produz saída. Para visualizar as tags em uma chave do AWS KMS, use o comando `list-resource-tags`.
Para obter mais informações sobre como usar tags no AWS KMS, consulte [Marcar chaves](https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [TagResource](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/tag-resource.html) na *Referência de comandos da AWS CLI*.
### `untag-resource`
O código de exemplo a seguir mostra como usar `untag-resource`.
**AWS CLI**
**Para excluir uma tag de uma chave do KMS**
O exemplo `untag-resource` a seguir exclui a tag com a chave `"Purpose"` de uma chave do KMS gerenciada pelo cliente.
Use o parâmetro `key-id` para especificar a chave do KMS. Este exemplo usa um valor de ID de chave, mas você pode usar um ID de chave ou o ARN da chave neste comando. Antes de executar esse comando, substitua o ID de chave de exemplo por um ID de chave válido da sua conta da AWS.
```
aws kms untag-resource \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--tag-key 'Purpose'
```
Este comando não produz saída. Para visualizar as tags em uma chave do AWS KMS, use o comando `list-resource-tags`.
Para obter mais informações sobre como usar tags no AWS KMS, consulte [Marcar chaves](https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para obter detalhes sobre a API, consulte [UntagResource](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/untag-resource.html) na *Referência de comandos da AWS CLI*.
### `update-alias`
O código de exemplo a seguir mostra como usar `update-alias`.
**AWS CLI**
**Como associar um alias a uma chave do KMS diferente**
O exemplo de `update-alias` a seguir associa o alias `alias/test-key` a uma chave do KMS diferente.
O parâmetro `--alias-name` especifica o alias. O valor do nome do alias deve começar com `alias/`. O parâmetro `--target-key-id` especifica a chave do KMS que deve ser associada ao alias. Não é necessário especificar a chave do KMS atual para o alias.
```
aws kms update-alias \
--alias-name alias/test-key \
--target-key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Este comando não produz saída. Use o `list-aliases` comando para localizar o alias.
Para obter mais informações, consulte [Updating aliases](https://docs.aws.amazon.com/kms/latest/developerguide/alias-manage.html#alias-update) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Consulte detalhes da API em [UpdateAlias](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/update-alias.html) na *Referência de comandos da AWS CLI*.
### `update-custom-key-store`
O código de exemplo a seguir mostra como usar `update-custom-key-store`.
**AWS CLI**
**Exemplo 1: editar o nome amigável de um repositório de chaves personalizado**
O exemplo `update-custom-key-store` a seguir altera o nome do repositório de chaves personalizado. Este exemplo funciona para um repositório de chaves do AWS CloudHSM ou repositório de chaves externo.
Use o `custom-key-store-id` para identificar o repositório de chaves. Use o parâmetro `new-custom-key-store-name` para especificar o novo nome amigável.
Para atualizar o nome amigável de um repositório de chaves do AWS CloudHSM, é necessário primeiro desconectar o repositório de chaves, por exemplo, usando o comando `disconnect-custom-key-store`. É possível atualizar o nome amigável de um repositório de chaves externo enquanto ele está conectado ou desconectado. Para descobrir o estado da conexão do repositório de chaves personalizado, use o comando `describe-custom-key-store`.
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--new-custom-key-store-name ExampleKeyStore
```
Esse comando não retorna nenhuma saída. Para verificar se o comando foi bem-sucedido, use um comando `describe-custom-key-stores`.
Para obter mais informações sobre a atualização de um repositório de chaves do AWS CloudHSM, consulte [Editar as configurações do repositório de chaves do AWS CloudHSM](https://docs.aws.amazon.com/kms/latest/developerguide/update-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
Para obter mais informações sobre a atualização de um repositório de chaves externo, consulte [Editar as propriedades do repositório de chaves externo](https://docs.aws.amazon.com/kms/latest/developerguide/update-xks-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 2: editar a senha kmsuser de um repositório de chaves do AWS CloudHSM**
O exemplo `update-custom-key-store` a seguir atualiza o valor da senha `kmsuser` para a senha atual do `kmsuser` no cluster do CloudHSM associado ao repositório de chaves especificado. Esse comando não altera a senha `kmsuser` do cluster. Ele apenas informa ao AWS KMS a senha atual. Se o KMS não tiver a senha atual `kmsuser`, ele não poderá se conectar ao repositório de chaves do AWS CloudHSM.
**OBSERVAÇÃO:** antes de atualizar um repositório de chaves do AWS CloudHSM, é necessário desconectá-lo. Use o comando `disconnect-custom-key-store`. Depois que o comando for concluído, é possível reconectar o repositório de chaves do AWS CloudHSM. Use o comando `connect-custom-key-store`.
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--key-store-password ExamplePassword
```
Esse comando não retorna nenhuma saída. Use o comando `describe-custom-key-stores` para verificar se a alteração foi concluída.
Para obter mais informações sobre a atualização de um repositório de chaves do AWS CloudHSM, consulte [Editar as configurações do repositório de chaves do AWS CloudHSM](https://docs.aws.amazon.com/kms/latest/developerguide/update-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 3: editar o cluster AWS CloudHSM de um repositório de chaves do AWS CloudHSM**
O exemplo a seguir altera o cluster do AWS CloudHSM associado a um repositório de chaves do AWS CloudHSM por um cluster relacionado, como um backup diferente do mesmo cluster.
**OBSERVAÇÃO:** antes de atualizar um repositório de chaves do AWS CloudHSM, é necessário desconectá-lo. Use o comando `disconnect-custom-key-store`. Depois que o comando for concluído, é possível reconectar o repositório de chaves do AWS CloudHSM. Use o comando `connect-custom-key-store`.
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--cloud-hsm-cluster-id cluster-1a23b4cdefg
```
Esse comando não retorna nenhuma saída. Use o comando `describe-custom-key-stores` para verificar se a alteração foi concluída.
Para obter mais informações sobre a atualização de um repositório de chaves do AWS CloudHSM, consulte [Editar as configurações do repositório de chaves do AWS CloudHSM](https://docs.aws.amazon.com/kms/latest/developerguide/update-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 4: editar a credencial de autenticação de proxy de um repositório de chaves externo**
O exemplo a seguir atualiza a credencial de autenticação de proxy do repositório de chaves externo. É necessário especificar a `raw-secret-access-key` e o `access-key-id`, mesmo que apenas um dos valores estejam sendo alterados. É possível usar esse atributo para corrigir uma credencial inválida ou para alterar a credencial quando o proxy do repositório de chaves externo faz a rotação.
Estabeleça a credencial de autenticação de proxy do AWS KMS em seu repositório de chaves externo. Em seguida, use esse comando para fornecer a credencial ao AWS KMS. O AWS KMS usa essa credencial para assinar suas solicitações no proxy de repositório de chaves externo.
É possível atualizar a credencial de autenticação de proxy enquanto o repositório de chaves externo está conectado ou desconectado. Para descobrir o estado da conexão do repositório de chaves personalizado, use o comando `describe-custom-key-store`.
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="
```
Esse comando não retorna nenhuma saída. Use o comando `describe-custom-key-stores` para verificar se a alteração foi concluída.
Para obter mais informações sobre a atualização de um repositório de chaves externo, consulte [Editar as propriedades do repositório de chaves externo](https://docs.aws.amazon.com/kms/latest/developerguide/update-xks-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
**Exemplo 5: editar a conectividade de proxy de um repositório de chaves externo**
O exemplo a seguir altera a opção de conectividade de proxy de repositório de chaves externo de conectividade de endpoint público para conectividade de serviço de endpoint da VPC. Além de alterar o valor de `xks-proxy-connectivity`, é necessário alterar o valor de `xks-proxy-uri-endpoint` para refletir o nome DNS privado associado ao serviço de endpoint da VPC. Também é necessário adicionar um valor de `xks-proxy-vpc-endpoint-service-name`.
**OBSERVAÇÃO:** antes de atualizar a conectividade proxy de um repositório externo, é necessário desconectá-lo. Use o comando `disconnect-custom-key-store`. Depois que o comando for concluído, é possível reconectar o repositório de chaves externo usando o comando `connect-custom-key-store`.
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-connectivity VPC_ENDPOINT_SERVICE \
--xks-proxy-uri-endpoint "https://myproxy-private.xks.example.com" \
--xks-proxy-vpc-endpoint-service-name "com.amazonaws.vpce.us-east-1.vpce-svc-example"
```
Esse comando não retorna nenhuma saída. Use o comando `describe-custom-key-stores` para verificar se a alteração foi concluída.
Para obter mais informações sobre a atualização de um repositório de chaves externo, consulte [Editar as propriedades do repositório de chaves externo](https://docs.aws.amazon.com/kms/latest/developerguide/update-xks-keystore.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [UpdateCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/update-custom-key-store.html) na *Referência de comandos da AWS CLI*.
### `update-key-description`
O código de exemplo a seguir mostra como usar `update-key-description`.
**AWS CLI**
**Exemplo 1: adicionar ou alterar uma descrição em uma chave do KMS gerenciada pelo cliente**
O exemplo `update-key-description` a seguir adiciona uma descrição uma chave do KMS gerenciada pelo cliente. É possível usar o mesmo comando para alterar uma descrição existente.
O parâmetro `--key-id` identifica a chave do KMS no comando. Este exemplo usa o valor do ARN da chave, mas é possível usar o ID da chave ou o ARN da chave do KMS. O parâmetro `--description` especifica a nova descrição. O valor desse parâmetro substitui a descrição atual da chave do KMS, se houver.
```
aws kms update-key-description \
--key-id arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab \
--description "IT Department test key"
```
Este comando não produz saída. Para visualizar a descrição de uma chave do KMS, use o comando `describe-key`.
Para obter mais informações, consulte [UpdateKeyDescription](https://docs.aws.amazon.com/cli/latest/reference/kms/update-key-description.html) na *Referência da API do AWS Key Management Service*.
**Exemplo 2: excluir a descrição de uma chave do KMS gerenciada pelo cliente**
O exemplo `update-key-description` a seguir adiciona uma descrição uma chave do KMS gerenciada pelo cliente.
O parâmetro `--key-id` identifica a chave do KMS no comando. Este exemplo usa o valor do ID da chave, mas é possível usar o ID da chave ou o ARN da chave da chave do KMS. O parâmetro `--description` com um valor de string vazia (") exclui a descrição existente.
```
aws kms update-key-description \
--key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
--description ''
```
Este comando não produz saída. Para visualizar a descrição de uma chave do KMS, use o comando describe-key.
Para obter mais informações, consulte [UpdateKeyDescription](https://docs.aws.amazon.com/cli/latest/reference/kms/update-key-description.html) na *Referência da API do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [UpdateKeyDescription](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/update-key-description.html) na *Referência de comandos da AWS CLI*.
### `verify-mac`
O código de exemplo a seguir mostra como usar `verify-mac`.
**AWS CLI**
**Exemplo 1: verificar um HMAC**
O comando `verify-mac` a seguir verifica um HMAC para uma mensagem específica, chaves HMAC do KMS e o algoritmo MAC. Um valor “true” no campo MacValid na resposta indica que o HMAC é válido.
Na AWS CLI v2, o valor do parâmetro `message` deve ser codificado em base64. Também é possível salvar a mensagem em um arquivo e usar o prefixo `fileb://`, que instrui a AWS CLI a ler dados binários do arquivo.
O MAC especificado não pode ter codificação em base64. Para obter ajuda na decodificação do MAC que o comando `generate-mac` retorna, consulte os exemplos do comando `generate-mac`.
Antes de executar esse comando, substitua o ID de chave de exemplo por um ID de chave válido da sua conta da AWS. O ID da chave deverá representar uma chave HMAC do KMS com o uso da chave `GENERATE_VERIFY_MAC`.
```
msg=(echo 'Hello World' | base64)
aws kms verify-mac \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://Message \
--mac-algorithm HMAC_SHA_384 \
--mac fileb://ExampleMac
```
Resultado:
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"MacValid": true,
"MacAlgorithm": "HMAC_SHA_384"
}
```
Para ter mais informações sobre como usar chaves HMAC do KMS no AWS KMS, consulte [HMAC keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [VerifyMac](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/verify-mac.html) na *Referência de comandos da AWS CLI*.
### `verify`
O código de exemplo a seguir mostra como usar `verify`.
**AWS CLI**
**Como verificar uma assinatura digital**
O comando `verify` a seguir verifica uma assinatura criptográfica para uma mensagem curta codificada em base64. O ID da chave, a mensagem, o tipo de mensagem e o algoritmo de assinatura devem ser os mesmos usados para assinar a mensagem.
Na AWS CLI v2, o valor do parâmetro `message` deve ser codificado em base64. Também é possível salvar a mensagem em um arquivo e usar o prefixo `fileb://`, que instrui a AWS CLI a ler dados binários do arquivo.
A assinatura que especificada não pode ter codificação base64. Para obter ajuda na decodificação da assinatura retornada pelo comando `sign`, consulte os exemplos do comando `sign`.
A saída do comando inclui um campo booleano `SignatureValid` que indica que a assinatura foi verificada. Se a validação da assinatura falhar, o comando `verify` também falhará.
Antes de executar esse comando, substitua o ID de chave de exemplo por um ID de chave válido da sua conta da AWS.
```
aws kms verify \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://EncodedMessage \
--message-type RAW \
--signing-algorithm RSASSA_PKCS1_V1_5_SHA_256 \
--signature fileb://ExampleSignature
```
Resultado:
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"SignatureValid": true,
"SigningAlgorithm": "RSASSA_PKCS1_V1_5_SHA_256"
}
```
Para obter mais informações sobre o uso de chaves assimétricas do KMS no AWS KMS, consulte [Usar chaves assimétricas](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) no *Guia do desenvolvedor do AWS Key Management Service*.
+ Para ver detalhes da API, consulte [Verify](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/verify.html) na *Referência de comandos da AWS CLI*.