Exemplos do AWS KMS usando oAWS 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

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.

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 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 no Guia do desenvolvedor do AWS Key Management Service.

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 no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "CustomKeyStoreId": cks-1234567890abcdef0
}

Para obter mais informações, consulte Criar um repositório de chaves do AWS CloudHSM 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 deexample-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="

Saída:

{
    "CustomKeyStoreId": cks-2234567890abcdef0
}

Para obter mais informações, consulte Criar um repositório de chaves externo 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="

Saída:

{
    "CustomKeyStoreId": cks-3234567890abcdef0
}

Para obter mais informações, consulte Criar um repositório de chaves externo no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "GrantId": "1a2b3c4d2f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2",
    "GrantToken": "<grant token here>"
}

Use o list-grants comando para visualizar informações detalhadas sobre a concessão.

Para obter mais informações, consulte Grants in AWS KMS no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "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",
        "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 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.

aws kms create-key \
   --key-spec RSA_4096 \
   --key-usage ENCRYPT_DECRYPT

Saída:

{
    "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 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.

aws kms create-key \
    --key-spec ECC_NIST_P521 \
    --key-usage SIGN_VERIFY

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.

Exemplo 4: como criar uma chave do KMS com HMAC

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

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.

Exemplo 4: como 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

Saída:

{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab",
        "AWSAccountId": "111122223333",
        "CreationDate": "2021-09-02T016:15:21-09:00",
        "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 no Guia do desenvolvedor do AWS Key Management Service.

Exemplo 5: como 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

Saída:

{
     "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 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

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.

Exemplo 7: como 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

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.

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 ( | ) 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 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

Saída:

Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.

Para obter mais informações, consulte Decrypt 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 no Guia do desenvolvedor do AWS Key Management Service.

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 no Guia do desenvolvedor do AWS Key Management Service.

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) 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 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 no Guia do desenvolvedor do AWS Key Management Service.

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

Este comando não produz saída. Para verificar se o material da chave foi excluído, use o comando describe-key para procurar um estado de chave de PendingImport ou PendingDeletion.

Para obter mais informações, consulte Excluir material de chave importado <https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-delete-key-material.html> no Guia do desenvolvedor do AWS Key Management Service.

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"

Saída:

{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "SharedSecret": "MEYCIQCKZLWyTk5runarx6XiAkU9gv3lbwPO/pHa+DXFehzdDwIhANwpsIV2g/9SPWLLsF6p/hiSskuIXMTRwqrMdVKWTMHG",
    "KeyAgreementAlgorithm": "ECDH",
    "KeyOrigin": "AWS_KMS"
}

Para obter mais informações, consulte DeriveSharedSecret na Referência da API do AWS Key Management Service.

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.

Saída:

{
    "CustomKeyStores": [
        {
            "CloudHsmClusterId": "cluster-1a23b4cdefg",
            "ConnectionState": "CONNECTED",
            "CreationDate": "2022-04-05T14:04:55-07:00",
            "CustomKeyStoreId": "cks-1234567890abcdef0",
            "CustomKeyStoreName": "ExampleExternalKeyStore",
            "TrustAnchorCertificate": "<certificate appears here>"
        }
    ]
}

Para obter mais informações, consulte Visualizar um repositório de chaves do AWS CloudHSM 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.

Saída:

{
    "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 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.

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "KeyMetadata": {
        "AWSAccountId": "846764612917",
        "KeyId": "b8a9477d-836c-491f-857e-07937918959b",
        "Arn": "arn:aws:kms:us-west-2:846764612917:key/b8a9477d-836c-491f-857e-07937918959b",
        "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 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

Saída:

{
    "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

Saída:

{
    "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",
        "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

Saída:

{
    "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
    }
}

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 no Guia do desenvolvedor do AWS Key Management Service.

Como desativar uma chave do KMS temporariamente

O exemplo a seguir usa o comando disable-key para desabilitar 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 no Guia do desenvolvedor do AWS Key Management Service.

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 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 no Guia do desenvolvedor do AWS Key Management Service.

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 no Guia do desenvolvedor do AWS Key Management Service.

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 no Guia do desenvolvedor do AWS Key Management Service.

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 obter informações sobre como ler o valores de parâmetros da AWS CLI de um arquivo, consulte Loading Parameters from a File no Guia do usuário da AWS Command Line Interface e Best Practices for Local File Parameters no AWS Command Line Tool Blog. Usa os parâmetros --output e --query para controlar a saída do comando. Esses parâmetros extraem os dados criptografados, chamados de texto cifrado, da saída do comando. Para obter mais informações sobre como controlar a saída, consulte Controlling Command Output no Guia do usuário da AWS Command Line Interface. Usa o utilitário base64 para decodificar a saída extraída em dados binários. O texto cifrado retornado 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.

Para gerar um par de chaves de dados assimétricos ECC NIST P384

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

Saída:

{
    "PrivateKeyCiphertextBlob": "AQIDAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAFFxmiD134doUDzMGmfCEtcAAAHaTCCB2UGCSqGSIb3DQEHBqCCB1...",
    "PublicKey": "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA3A3eGMyPrvSn7+LdlJE1oUoQV5HpEuHAVbdOyND+NmYDH/mL1OSIEuLrcdZ5hrMH4pk83r40l...",
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "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 no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "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",
    "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 no Guia do desenvolvedor do AWS Key Management Service.

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

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

Saída:

{
    "CiphertextBlob": "AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDEFogL",
    "KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}

A CiphertextBlob (chave de dados criptografada) é retornada em um formato codificado em base64.

Para obter mais informações, consulte Data keys no Guia do desenvolvedor do AWS Key Management Service.

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

aws kms generate-data-key \
    --key-id alias/ExampleAlias \
    --key-spec AES_256

Saída:

{
    "Plaintext": "VdzKNHGzUAzJeRBVY+uUmofUGGiDzyB3+i9fVkh3piw=",
    "KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "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/concepts.html#data-keys) 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_DEFAULT.

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

Saída:

{
    "CiphertextBlob": "AQIBAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAEnX/QQNmMwDfg2korNMEc8AAACaDCCAmQGCSqGSIb3DQEHBqCCAlUwggJRAgEAMIICSgYJKoZ...",
    "Plaintext": "ty8Lr0Bk6OF07M2BWt6qbFdNB+G00ZLtf5MSEb4al3R2UKWGOp06njAwy2n72VRm2m7z/Pm9Wpbvttz6a4lSo9hgPvKhZ5y6RTm4OovEXiVfBveyX3DQxDzRSwbKDPk/...",
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}

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/concepts.html#data-keys) no Guia do desenvolvedor do AWS Key Management Service.

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.htm >, 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 ( | ) 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 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

Saída:

Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.

Para obter mais informações, consulte GenerateRandom na Referência da API do AWS Key Management Service.

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 na Referência da API do AWS KMS.

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

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "PublicKey": "<public key base64 encoded data>",
    "ImportToken": "<import token base64 encoded data>",
    "ParametersValidTo": 1593893322.32
}

Para obter mais informações, consulte Baixar a chave pública e o token de importação no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "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 Usar chaves assimétricas 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 Usar chaves assimétricas no Guia do desenvolvedor do AWS Key Management Service.

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

Este comando não produz saída.

Para obter mais informações sobre como importar material de chave, consulte Importar material de chave no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "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

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.

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 no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "PolicyNames": [
    "default"
    ]
}

Para obter mais informações sobre as políticas de chave do AWS KMS, consulte Using Key Policies in AWS KMS no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.

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 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 de origem, que descriptografa o texto cifrado. O parâmetro --source-key-id não é necessário ao fazer a descriptografia com chaves simétricas de criptografia do KMS. 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 ( | ) 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 obter mais informações, consulte ReEncrypt (https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) Referência da 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

Saída:

Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.

Para obter mais informações, consulte ReEncrypt (https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) Referência da API do AWS Key Management Service.

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 no Guia do desenvolvedor do AWS Key Management Service.

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 no Guia do desenvolvedor do AWS Key Management Service.

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

Saída:

{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
}

Para obter mais informações, consulte Como realizar uma rotação de chave sob demanda no Guia do desenvolvedor do AWS Key Management Service.

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 no Guia do desenvolvedor do AWS Key Management Service.

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 2.0, 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_VERIFY.

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

Saída:

{
    "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 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_VERIFY.

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 no Guia do desenvolvedor do AWS Key Management Service.

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 no Guia do desenvolvedor do AWS Key Management Service.

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 no Guia do desenvolvedor do AWS Key Management Service.

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 no Guia do desenvolvedor do AWS Key Management Service.

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 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 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 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 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 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 no Guia do desenvolvedor do AWS Key Management Service.

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 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 na Referência da API do AWS Key Management Service.

Como verificar uma assinatura digital

O exemplo de 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. 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

Saída:

{
    "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 no Guia do desenvolvedor do AWS Key Management Service.