Exemplos do AWS KMS usando oAWS CLI
Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando o AWS Command Line Interface com o AWS KMS.
Ações são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.
Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.
Tópicos
Ações
O código de exemplo a seguir mostra como usar cancel-key-deletion
.
- AWS CLI
-
Como programar a exclusão de uma chave do KMS gerenciada pelo cliente
O exemplo
cancel-key-deletion
a seguir cancela a exclusão agendada de uma chave do KMS gerenciada pelo cliente.aws kms cancel-key-deletion \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
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 comandoenable-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.
-
Para ver detalhes da API, consulte CancelKeyDeletion
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar connect-custom-key-store
.
- AWS CLI
-
Como conectar um repositório de chaves personalizado
O exemplo
connect-custom-key-store
a seguir reconecta o repositório de chaves personalizadas especificado. É possível usar um comando como esse para conectar um repositório de chaves personalizado pela primeira vez ou para reconectar um repositório de chaves que foi desconectado.É possível usar esse comando para conectar um repositório de chaves do AWS CloudHSM ou um repositório de chaves externo.
aws kms connect-custom-key-store \ --custom-key-store-id
cks-1234567890abcdef0
Esse comando não retorna nenhuma saída. Use o comando
describe-custom-key-stores
para verificar se o comando está em vigor.Para obter informações sobre como conectar um repositório de chaves do AWS CloudHSM, consulte Conectar e desconectar um repositório de chaves do AWS CloudHSM 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.
-
Para ver detalhes da API, consulte ConnectCustomKeyStore
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar create-alias
.
- AWS CLI
-
Como criar um alias para uma chave do KMS
O comando
create-alias
a seguir cria um alias com o nomeexample-alias
para a chave do KMS identificada pelo ID de chave1234abcd-12ab-34cd-56ef-1234567890ab
.Os nomes de alias devem começar com
alias/
. Não use nomes de alias que comecem comalias/aws
. Eles são reservados para uso pela AWS.aws kms create-alias \ --alias-name
alias/example-alias
\ --target-key-id1234abcd-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.
-
Para obter detalhes da API, consulte CreateAlias
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar create-custom-key-store
.
- AWS CLI
-
Exemplo 1: criar um repositório de chaves do AWS CloudHSM
O exemplo
create-custom-key-store
a seguir cria um repositório de chaves do AWS CloudHSM apoiado por um cluster do AWS CloudHSM usando os parâmetros necessários. Também é possível adicionar ocustom-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 prefixofile://
.aws kms create-custom-key-store \ --custom-key-store-name
ExampleCloudHSMKeyStore
\ --cloud-hsm-cluster-idcluster-1a23b4cdefg
\ --key-store-passwordkmsPswd
\ --trust-anchor-certificatefile://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-typeEXTERNAL_KEY_STORE
\ --xks-proxy-connectivityPUBLIC_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-typeEXTERNAL_KEY_STORE
\ --xks-proxy-connectivityVPC_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.
-
Para ver detalhes da API, consulte CreateCustomKeyStore
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar create-grant
.
- AWS CLI
-
Como criar uma concessão
O exemplo de
create-grant
a seguir cria uma concessão que permite que o usuárioexampleUser
use o comandodecrypt
na chave do KMS1234abcd-12ab-34cd-56ef-1234567890ab
de exemplo. A entidade principal descontinuada é o perfiladminRole
. A concessão usa a restrição de concessãoEncryptionContextSubset
para conceder essa permissão apenas quando o contexto de criptografia na solicitaçãodecrypt
incluir o par de chave/valor"Department": "IT"
.aws kms create-grant \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
\ --grantee-principalarn:aws:iam::123456789012:user/exampleUser
\ --operationsDecrypt
\ --constraintsEncryptionContextSubset={Department=IT}
\ --retiring-principalarn: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.
-
Para obter detalhes da API, consulte CreateGrant
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar create-key
.
- AWS CLI
-
Exemplo 1: como criar uma chave do KMS gerenciada pelo cliente no AWS KMS
O exemplo de
create-key
a seguir cria uma chave do KMS de criptografia simétrica.Não é necessário especificar parâmetros para criar a chave básica do KMS (uma chave de criptografia simétrica). Os valores padrão desses parâmetros criam uma chave de criptografia simétrica.
Como esse comando não especifica uma política de chave, a chave do KMS adota a política de chave padrão para chaves do KMS criadas programaticamente. Use o comando
get-key-policy
para visualizar a política de chave. Use o comandoput-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. Uselist-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 comandocreate-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-usageENCRYPT_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, emboraSIGN_VERIFY
seja o único valor válido para chaves ECC do KMS.aws kms create-key \ --key-spec
ECC_NIST_P521
\ --key-usageSIGN_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 valorGENERATE_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-usageGENERATE_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
comoEXTERNAL
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-idcks-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 serEXTERNAL_KEY_STORE
. O parâmetrocustom-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.
-
Para obter detalhes da API, consulte CreateKey
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar decrypt
.
- AWS CLI
-
Exemplo 1: como descriptografar uma mensagem criptografada com uma chave simétrica do KMS (Linux e macOS)
O exemplo de comando
decrypt
a seguir demonstra a forma recomendada de descriptografar dados com a AWS CLI. Esta versão mostra como descriptografar dados com uma chave simétrica do KMS.Forneça o texto cifrado em um arquivo. No valor do parâmetro
--ciphertext-blob
, use o prefixofileb://
, 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 campoPlaintext
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âmetroPlaintext
para o utilitário Base64, que o decodifica. Em seguida, ele redireciona ( > ) a saída decodificada para o arquivoExamplePlaintext
.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-id1234abcd-12ab-34cd-56ef-1234567890ab
\ --outputtext
\ --queryPlaintext
|
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-blobfileb://ExampleEncryptedFile
^
--key-id1234abcd-12ab-34cd-56ef-1234567890ab
^
--outputtext
^
--queryPlaintext
>
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-id0987dcba-09fe-87dc-65ba-ab0987654321
\ --encryption-algorithmRSAES_OAEP_SHA_256
\ --outputtext
\ --queryPlaintext
|
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.
-
Para obter detalhes da API, consulte Decrypt
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar delete-alias
.
- AWS CLI
-
Como excluir um alias do AWS KMS
O exemplo de
delete-alias
a seguir exclui o aliasalias/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 obter detalhes da API, consulte DeleteAlias
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar delete-custom-key-store
.
- AWS CLI
-
Para excluir um repositório de chaves personalizado
O exemplo
delete-custom-key-store
a seguir exclui o repositório de chaves personalizado especificado.A exclusão de um repositório de chaves do AWS CloudHSM não afeta o cluster do CloudHSM associado. A exclusão de um repositório de chaves externo não afeta o proxy do repositório de chaves externo, o gerenciador de chaves externas ou chaves externas associadas.
OBSERVAÇÃO: antes de excluir um repositório de chaves personalizado, é necessário agendar a exclusão de todas as chaves KMS no repositório de chaves personalizadas e esperar que essas chaves KMS sejam excluídas. Então, é necessário desconectar o repositório de chaves personalizado. Para obter ajuda para descobrir as chaves do KMS em seu repositório de chaves personalizado, consulte Excluir um repositório de chaves do AWS CloudHSM (API) 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 ver detalhes da API, consulte DeleteCustomKeyStore
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar delete-imported-key-material
.
- AWS CLI
-
Para excluir material de chave importado de uma chave do KMS
O exemplo
delete-imported-key-material
a seguir exclui o material de chave importado para uma chave do KMS.aws kms delete-imported-key-material \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
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 dePendingImport
ouPendingDeletion
.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.
-
Para ver detalhes da API, consulte DeleteImportedKeyMaterial
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar derive-shared-secret
.
- AWS CLI
-
Como derivar um segredo compartilhado
O exemplo
derive-shared-secret
a seguir deriva um segredo compartilhado usando um algoritmo de acordo de chave.É necessário usar um par de chave do KMS de curva elíptica assimétrica recomendado pela NIST (ECC) ou SM2 (somente nas regiões da China) com um valor de
KeyUsage
igual aKEY_AGREEMENT
para chamar DeriveSharedSecret.aws kms derive-shared-secret \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
\ --key-agreement-algorithmECDH
\ --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.
-
Para ver detalhes da API, consulte DeriveSharedSecret
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar describe-custom-key-stores
.
- AWS CLI
-
Exemplo 1: obter detalhes sobre um repositório de chaves do AWS CloudHSM
O exemplo
describe-custom-key-store
a seguir exibe os detalhes sobre o repositório de chaves AWS CloudHSM especificado. O comando é o mesmo para todos os tipos de repositório de chaves personalizadas, mas a saída difere conforme o tipo de repositório de chaves e, para um repositório de chaves externo, conforme sua opção de conectividade.Por padrão, esse comando exibe informações sobre todos os repositórios de chave personalizados na conta e região. Para exibir informações sobre um repositório de chaves personalizado específico, use o parâmetro
custom-key-store-name
oucustom-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 campoConnectionErrorCode
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
oucustom-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 campoConnectionErrorCode
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
oucustom-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 campoConnectionErrorCode
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.
-
Para ver detalhes da API, consulte DescribeCustomKeyStores
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar describe-key
.
- AWS CLI
-
Exemplo 1: como localizar informações detalhadas sobre uma chave do KMS
O exemplo de
describe-key
a seguir obtém informações detalhadas sobre a chave gerenciada da AWS para o Amazon S3 na conta e região do exemplo. Você pode usar esse comando para encontrar detalhes sobre chaves gerenciadas pela AWS e pelo cliente.Use o parâmetro
key-id
para especificar a chave do KMS. Este exemplo usa um valor de nome de alias, mas você pode usar um ID de chave, o ARN da chave, o nome do alias ou o ARN do alias neste comando.aws kms describe-key \ --key-id
alias/aws/s3
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 comandodescribe-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 obter detalhes da API, consulte DescribeKey
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar disable-key-rotation
.
- AWS CLI
-
Para desativar a rotação automática de uma chave do KMS
O exemplo
disable-key-rotation
a seguir desativa a rotação automática de uma chave do KMS gerenciada pelo cliente. Para reativar a rotação automática, use o comandoenable-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.
-
Para ver detalhes da API, consulte DisableKeyRotation
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar disable-key
.
- AWS CLI
-
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 oenable-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.
-
Para obter detalhes da API, consulte DisableKey
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar disconnect-custom-key-store
.
- AWS CLI
-
Como desconectar um repositório de chaves personalizado
O exemplo
disconnect-custom-key-store
a seguir desconecta um repositório de chaves personalizado do cluster do AWS CloudHSM. Pode ser desejável desconectar um repositório de chaves para solucionar um problema, atualizar suas configurações ou impedir que as chaves do KMS no repositório de chaves sejam usadas em operações criptográficas.Esse comando é o mesmo para todos os repositórios de chaves personalizados, inclusive os armazenamentos de chaves do AWS CloudHSM e repositórios de chaves externos.
Antes de executar um comando como esse, substitua o ID de exemplo do armazenamento de chaves personalizado por um válido.
$ aws kms disconnect-custom-key-store \ --custom-key-store-id cks-1234567890abcdef0
Este comando não produz saída. Para confirmar a efetividade do comando, use o comando
describe-custom-key-stores
.Para obter mais informações sobre como desconectar um repositório de chaves do AWS CloudHSM, consulte Conectar e desconectar um repositório de chaves do AWS CloudHSM 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.
-
Para ver detalhes da API, consulte DisconnectCustomKeyStore
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar enable-key-rotation
.
- AWS CLI
-
Como ativar a rotação automática de uma chave do KMS
O exemplo de
enable-key-rotation
a seguir viabiliza a alternância automática de uma chave do KMS gerenciada pelo cliente com um período de alternância de 180 dias. A chave do KMS será alternada em um ano (aproximadamente 365 dias) a partir da data em que esse comando for concluído e todos os anos a partir de então.O parâmetro
--key-id
identifica a chave do KMS. Este exemplo usa o valor do ARN da chave, mas é possível usar o ID da chave ou o ARN da chave do KMS. O parâmetro--rotation-period-in-days
especifica o número de dias entre as datas de cada rotação. Especifique um valor entre 90 e 2.560 dias. Se nenhum valor for especificado, o valor padrão será de 365 dias.aws kms enable-key-rotation \ --key-id
arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\ --rotation-period-in-days180
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 ver detalhes da API, consulte EnableKeyRotation
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar enable-key
.
- AWS CLI
-
Para habilitar uma chave do KMS
O exemplo de
enable-key
a seguir habilita uma chave gerenciada pelo cliente. Você pode usar um comando como esse para habilitar uma chave do KMS que foi temporariamente desabilitada usando o comandodisable-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 camposKeyState
eEnabled
na saídadescribe-key
.Para obter mais informações, consulte Enabling and Disabling Keys no Guia do desenvolvedor do AWS Key Management Service.
-
Para obter detalhes da API, consulte EnableKey
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar encrypt
.
- AWS CLI
-
Exemplo 1: como criptografar o conteúdo de um arquivo no Linux ou no macOS
O comando
encrypt
a seguir demonstra a forma recomendada de criptografar dados com a AWS CLI.aws kms encrypt \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
\ --plaintextfileb://ExamplePlaintextFile
\ --outputtext
\ --queryCiphertextBlob
|
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âmetroplaintext
deve ser codificado em base64, ou você deve usar o prefixofileb://
, 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
oufileb://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 Parametersno 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áriobase64
para decodificar a saída extraída em dados binários. O texto cifrado retornado por um comandoencrypt
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 dobase64
. Esse procedimento requer dois comandos, conforme mostrado no exemplo a seguir.aws kms encrypt \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
\ --plaintextfileb://ExamplePlaintextFile
\ --outputtext
\ --queryCiphertextBlob
>
C:\Temp\ExampleEncryptedFile.base64certutil
-decode
C:\Temp\ExampleEncryptedFile.base64 C:\Temp\ExampleEncryptedFileExemplo 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 daencrypt
CLI, o parâmetroplaintext
deve ser codificado em base64 ou você deve usar o prefixofileb://
, que informa a AWS CLI para ler os dados binários do arquivo.aws kms encrypt \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
\ --encryption-algorithmRSAES_OAEP_SHA_256
\ --plaintextfileb://ExamplePlaintextFile
\ --outputtext
\ --queryCiphertextBlob
|
base64
\ --decode>
ExampleEncryptedFile
Este comando não produz saída.
-
Para obter detalhes da API, consulte Encrypt
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar generate-data-key-pair-without-plaintext
.
- AWS CLI
-
Para gerar um par de chaves de dados assimétricos ECC NIST 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 deECC_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 aSYMMETRIC_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-specECC_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
ePrivateKeyCiphertextBlob
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 ver detalhes da API, consulte GenerateDataKeyPairWithoutPlaintext
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar generate-data-key-pair
.
- AWS CLI
-
Para gerar um par de chaves de dados assimétricos RSA de 2048 bits
O exemplo
generate-data-key-pair
a seguir solicita uma par de chave de dados assimétrico RSA de 2048 bits para uso fora da AWS. O comando retorna uma chave de dados em texto simples para uso e exclusão imediatos e uma cópia da chave de dados criptografada na chave do KMS especificada. A chave de dados criptografada pode ser armazenada com segurança junto com os dados criptografados.Para solicitar um par de chave de dados assimétrico RSA de 2048 bits, use o parâmetro
key-pair-spec
com o valorRSA_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 aSYMMETRIC_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-specRSA_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
ePrivateKeyCiphertextBlob
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 ver detalhes da API, consulte GenerateDataKeyPair
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar generate-data-key-without-plaintext
.
- AWS CLI
-
Como gerar uma chave de dados simétrica de 256 bits sem uma chave de texto simples
O exemplo de
generate-data-key-without-plaintext
a seguir solicita uma cópia criptografada de uma chave de dados simétrica de 256 bits para uso externo à AWS. Você pode chamar o AWS KMS para descriptografar a chave de dados quando quiser usá-la.Use o parâmetro
key-spec
com um valor deAES_256
para solicitar uma chave de dados de 256 bits. Use o parâmetrokey-spec
com um valor deAES_128
para solicitar uma chave de dados de 128 bits. Para todos os outros comprimentos de chave de dados, use o parâmetronumber-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-specAES_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.
-
Para obter detalhes da API, consulte GenerateDataKeyWithoutPlaintext
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar generate-data-key
.
- AWS CLI
-
Exemplo 1: como gerar uma chave de dados simétrica de 256 bits
O exemplo
generate-data-key
a seguir solicita uma chave de dados simétrica de 256 bits para uso externo à AWS. O comando retorna uma chave de dados em texto simples para uso e exclusão imediatos e uma cópia da chave de dados criptografada na chave do KMS especificada. A chave de dados criptografada pode ser armazenada com segurança junto com os dados criptografados.Use o parâmetro
key-spec
com um valor deAES_256
para solicitar uma chave de dados de 256 bits. Use o parâmetrokey-spec
com um valor deAES_128
para solicitar uma chave de dados de 128 bits. Para todos os outros comprimentos de chave de dados, use o parâmetronumber-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-specAES_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 aCiphertextBlob
(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âmetronumber-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-bytes64
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) eCiphertextBlob
(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.
-
Para obter detalhes da API, consulte GenerateDataKey
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar generate-random
.
- AWS CLI
-
Exemplo 1: como gerar uma string de bytes aleatória de 256 bits (Linux ou macOS)
O exemplo de
generate-random
a seguir gera uma string de bytes aleatórios de 256 bits (32 bytes) codificada em base64. O exemplo decodifica a string de bytes e a salva no arquivo aleatório.Ao executar esse comando, use o parâmetro
number-of-bytes
para especificar o tamanho do valor aleatório em bytes.Você não especifica uma chave do KMS ao executar esse comando. A sequência de bytes aleatória não está relacionada a nenhuma chave do KMS.
Por padrão, o AWS KMS gera o número aleatório. No entanto, se você especificar um repositório de chaves personalizado <https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.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 de32
para solicitar uma string de 32 bytes (256 bits). Ele usa o parâmetro--output
com o valor detext
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 propriedadePlaintext
da resposta. Ele canaliza ( | ) a saída do comando para o utilitáriobase64
, que decodifica a saída extraída. Ele usa o operador de redirecionamento ( > ) para salvar a string de bytes decodificada no arquivoExampleRandom
. 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áriocertutil
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
\ --outputtext
\ --queryPlaintext
>
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 arquivoExampleRandom.base64
. Em seguida, ele salva a string de bytes decodificada no arquivoExampleRandom
.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.
-
Para obter detalhes da API, consulte GenerateRandom
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar get-key-policy
.
- AWS CLI
-
Como copiar uma política de chave de uma chave do KMS para outra chave do KMS
O exemplo de
get-key-policy
a seguir obtém a política de chave de uma chave do KMS e a salva em um arquivo de texto. Em seguida, ele substitui a política de uma chave diferente do KMS usando o arquivo de texto como a entrada da política.Como o parâmetro
--policy
deput-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-id1234abcd-12ab-34cd-56ef-1234567890ab
\ --queryPolicy
\ --outputtext
>
policy.txt
aws
kms
put-key-policy
\ --policy-namedefault
\ --key-id0987dcba-09fe-87dc-65ba-ab0987654321
\ --policyfile://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 obter detalhes da API, consulte GetKeyPolicy
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar get-key-rotation-status
.
- AWS CLI
-
Para recuperar o status de rotação de uma chave do KMS.
O exemplo
get-key-rotation-status
a seguir retorna informações sobre o status de rotação da chave do KMS especificada, incluindo se a rotação automática está ativada, o período de rotação e a próxima data de rotação programada. É possível usar esse comando em chaves do KMS gerenciadas pelo cliente e chaves do KMS gerenciadas pela AWS. No entanto, todas as chaves do KMS gerenciadas pela AWS são alternadas automaticamente a cada ano.aws kms get-key-rotation-status \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
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 ver detalhes da API, consulte GetKeyRotationStatus
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar get-parameters-for-import
.
- AWS CLI
-
Para obter os itens necessários para importar material de chave para uma chave do KMS
O exemplo
get-parameters-for-import
a seguir obtém a chave pública e o token de importação necessários para importar material de chave para uma chave do KMS. Ao usar o comandoimport-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 comandoget-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-algorithmRSAES_OAEP_SHA_256
\ --wrapping-key-specRSA_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.
-
Para ver detalhes da API, consulte GetParametersForImport
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar get-public-key
.
- AWS CLI
-
Exemplo 1: baixar a chave pública de uma chave do KMS assimétrica
O exemplo
get-public-key
a seguir baixa a chave pública de uma chave do KMS assimétrica.Além de retornar a chave pública, a saída inclui informações necessárias para usar a chave pública com segurança fora do AWS KMS, inclusive o uso da chave e os algoritmos de criptografia compatíveis.
aws kms get-public-key \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
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 propriedadePublicKey
como texto. Ele decodifica aPublicKey
em Base64 e a salva no arquivopublic_key.der
. O parâmetrooutput
retorna a saída como texto, em vez de JSON. O parâmetro--query
obtém somente a propriedadePublicKey
, 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
\ --outputtext
\ --queryPublicKey
|
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 ver detalhes da API, consulte GetPublicKey
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar import-key-material
.
- AWS CLI
-
Para importar o material de chave para uma chave do KMS
O exemplo
import-key-material
a seguir carrega material da chave em uma chave do KMS que criada sem material de chave. O estado da chave do KMS deve serPendingImport
.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 comandoget-parameters-for-import
.O parâmetro
expiration-model
indica que o material da chave expira automaticamente na data e hora especificadas pelo parâmetrovalid-to
. Quando o material de chave expira, o AWS KMS exclui o material de chave, o estado da chave do KMS é alterado paraPending 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-materialfileb://EncryptedKeyMaterial.bin
\ --import-tokenfileb://ImportToken.bin
\ --expiration-modelKEY_MATERIAL_EXPIRES
\ --valid-to2021-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.
-
Para ver detalhes da API, consulte ImportKeyMaterial
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar list-aliases
.
- AWS CLI
-
Exemplo 1: listar todos os aliases em uma conta e região da AWS
O exemplo a seguir usa o comando
list-aliases
para listar todos os aliases na região padrão da conta da AWS. A saída inclui aliases associados às chaves do KMS gerenciadas pela AWS e pelo cliente.aws kms list-aliases
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âmetrokey-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.
-
Para obter detalhes da API, consulte ListAliases
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar list-grants
.
- AWS CLI
-
Como visualizar as concessões de uma chave do AWS KMS
O exemplo de
list-grants
a seguir exibe todas as concessões da chave especificada do KMS gerenciada pela AWS para o Amazon DynamoDB na conta. Essa concessão permite que o DynamoDB use a chave do KMS em seu nome para criptografar uma tabela do DynamoDB antes de gravá-la no disco. Você pode usar um comando como esse para visualizar as concessões nas chaves do KMS gerenciadas pela AWS e nas chaves do KMS gerenciadas pelo cliente na conta e na região da AWS.Este comando usa o parâmetro
key-id
com um ID de chave para identificar a chave do KMS. Você pode usar um ID de chave ou o ARN da chave para identificar a chave do KMS. Para obter o ID da chave ou o ARN da chave de uma chave do KMS gerenciada pela AWS, use o comandolist-keys
ou olist-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çãoEncryptionContextSubset
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.
-
Para obter detalhes da API, consulte ListGrants
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar list-key-policies
.
- AWS CLI
-
Como obter os nomes das políticas de chave de uma chave do KMS
O exemplo de
list-key-policies
a seguir obtém os nomes das políticas de chave de uma chave gerenciada pelo cliente na conta e região de exemplo. Você pode usar esse comando para encontrar os nomes das políticas de chave de chaves gerenciadas pela AWS e pelo cliente.Como o único nome de política de chave válido é
default
, esse comando não é muito útil.Use o parâmetro
key-id
para especificar a chave do KMS. Este exemplo usa um valor de ID de chave, mas você pode usar um ID de chave ou o ARN da chave neste comando.aws kms list-key-policies \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
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 obter detalhes da API, consulte ListKeyPolicies
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar list-key-rotations
.
- AWS CLI
-
Para recuperar informações sobre todas as rotações de materiais de chave concluídas
O exemplo
list-key-rotations
a seguir lista informações sobre todas as rotações de materiais de chave concluídas para a chave do KMS especificada.aws kms list-key-rotations \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
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.
-
Para ver detalhes da API, consulte ListKeyRotations
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar list-keys
.
- AWS CLI
-
Como obter chaves do KMS em uma conta e região
O exemplo
list-keys
a seguir obtém as chaves do KMS em uma conta e região. Esse comando retorna chaves gerenciadas pela AWS e pelo cliente.aws kms list-keys
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 detalhes da API, consulte ListKeys
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar list-resource-tags
.
- AWS CLI
-
Para obter as tags em uma chave do KMS
O exemplo
list-resource-tags
a seguir obtém as tags de uma chave do KMS. Para adicionar ou substituir tags de recursos das chaves do KMS, use o comandotag-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.
-
Para ver detalhes da API, consulte ListResourceTags
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar list-retirable-grants
.
- AWS CLI
-
Como visualizar as concessões que uma entidade principal pode retirar
O exemplo
list-retirable-grants
a seguir exibe todas as concessões que o usuárioExampleAdmin
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 comandolist-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.
-
Para ver detalhes da API, consulte ListRetirableGrants
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar put-key-policy
.
- AWS CLI
-
Como alterar a política de chaves de uma chave do KMS
O exemplo de
put-key-policy
a seguir altera a política de chave de uma chave gerenciada pelo cliente.Para começar, crie uma política de chave e salve-a em um arquivo JSON local. Neste exemplo, o arquivo é
key_policy.json
. Você também pode especificar a política de chave como o valor da string do parâmetropolicy
.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 comandosdescribe-key
elist-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 prefixofile://
necessário. Esse prefixo é necessário para identificar arquivos em todos os sistemas operacionais compatíveis. Por fim, o comando usa o parâmetropolicy-name
com um valordefault
. 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-id1234abcd-12ab-34cd-56ef-1234567890ab
\ --policyfile://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âmetrooutput
com o valortext
retorna um formato de texto fácil de ler.aws kms get-key-policy \ --policy-name
default
\ --key-id1234abcd-12ab-34cd-56ef-1234567890ab
\ --outputtext
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.
-
Para obter detalhes da API, consulte PutKeyPolicy
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar re-encrypt
.
- AWS CLI
-
Exemplo 1: como criptografar novamente uma mensagem criptografada com uma chave simétrica diferente do KMS (Linux e macOS).
O exemplo de comando
re-encrypt
a seguir demonstra a forma recomendada de recriptografar dados com a AWS CLI.Forneça o texto cifrado em um arquivo. No valor do parâmetro
--ciphertext-blob
, use o prefixofileb://
, 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 campoPlaintext
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âmetroPlaintext
para o utilitário Base64, que o decodifica. Em seguida, ele redireciona ( > ) a saída decodificada para o arquivoExamplePlaintext
.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-id1234abcd-12ab-34cd-56ef-1234567890ab
\ --destination-key-id0987dcba-09fe-87dc-65ba-ab0987654321
\ --queryCiphertextBlob
\ --outputtext
|
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áriocertutil
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-blobfileb://ExampleEncryptedFile
^
--source-key-id1234abcd-12ab-34cd-56ef-1234567890ab
^
--destination-key-id0987dcba-09fe-87dc-65ba-ab0987654321
^
--queryCiphertextBlob
^
--outputtext
>
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.
-
Para obter detalhes da API, consulte ReEncrypt
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar retire-grant
.
- AWS CLI
-
Como descontinuar uma concessão em uma chave mestra do cliente
O exemplo de
retire-grant
a seguir exclui a concessão de uma chave do KMS.O comando de exemplo a seguir especifica os parâmetros
grant-id
ekey-id
. O valor do parâmetrokey-id
deve ser o ARN de chave da chave do KMS.aws kms retire-grant \ --grant-id
1234a2345b8a4e350500d432bccf8ecd6506710e1391880c4f7f7140160c9af3
\ --key-idarn: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.
-
Para obter detalhes da API, consulte RetireGrant
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar revoke-grant
.
- AWS CLI
-
Como revogar uma concessão em uma chave mestra do cliente
O exemplo de
revoke-grant
a seguir exclui a concessão de uma chave do KMS. O comando de exemplo a seguir especifica os parâmetrosgrant-id
ekey-id
. O valor do parâmetrokey-id
pode ser o ID ou o ARN de chave da chave do KMS.aws kms revoke-grant \ --grant-id
1234a2345b8a4e350500d432bccf8ecd6506710e1391880c4f7f7140160c9af3
\ --key-id1234abcd-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.
-
Para obter detalhes da API, consulte RevokeGrant
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar rotate-key-on-demand
.
- AWS CLI
-
Como realizar a rotação sob demanda de uma chave do KMS
O exemplo
rotate-key-on-demand
a seguir inicia imediatamente a rotação do material de chave para a chave do KMS especificada.aws kms rotate-key-on-demand \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
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.
-
Para ver detalhes da API, consulte RotateKeyOnDemand
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar schedule-key-deletion
.
- AWS CLI
-
Como programar a exclusão de uma chave do KMS gerenciada pelo cliente.
O exemplo de
schedule-key-deletion
a seguir programa a chave do KMS gerenciada pelo cliente especificada pala ser excluída em 15 dias.O parâmetro
--key-id
identifica a chave do KMS. Este exemplo usa o valor do ARN da chave, mas você pode usar o ID da chave ou o ARN da chave do KMS. O parâmetro--pending-window-in-days
especifica a duração do período de espera (7 a 30 dias). Por padrão, o período de espera é de 30 dias. Este exemplo especifica o valor de 15, que informa à AWS para excluir a chave do KMS permanentemente 15 dias após a conclusão do comando.aws kms schedule-key-deletion \ --key-id arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab \ --pending-window-in-days 15
A resposta inclui o ARN da chave, o estado da chave, o período de espera (
PendingWindowInDays
) e a data de exclusão no horário Unix. Use o console do AWS KMS para visualizar a data de exclusão no horário local. As chaves do KMS no estadoPendingDeletion
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.
-
Para obter detalhes da API, consulte ScheduleKeyDeletion
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar sign
.
- AWS CLI
-
Exemplo 1: gerar uma assinatura digital para uma mensagem
O exemplo de
sign
a seguir gera uma assinatura criptográfica para uma mensagem curta. A saída do comando inclui um campoSignature
codificado em base 64 que pode ser verificado usando o comandoverify
.É 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 prefixofileb://
, 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 propriedadeSignature
da resposta, decodifica a resposta em base64 e salva a resposta no arquivo ExampleSignature. É possível usar o arquivo de assinatura em um comandoverify
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 comandodescribe-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 ver detalhes da API, consulte Sign
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar tag-resource
.
- AWS CLI
-
Para adicionar uma tag a uma chave do KMS
O exemplo de
tag-resource
a seguir adiciona as tags"Purpose":"Test"
e"Dept":"IT"
a uma chave do KMS gerenciada pelo cliente. É possível usar tags como essas para identificar chaves do KMS e criar categorias de chaves do KMS para permissões e auditoria.Use o parâmetro
key-id
para especificar a chave do KMS. Este exemplo usa um valor de ID de chave, mas você pode usar um ID de chave ou o ARN da chave neste comando.aws kms tag-resource \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
\ --tags TagKey='Purpose',TagValue='Test' TagKey='Dept',TagValue='IT'Este comando não produz saída. Para visualizar as tags em uma chave do AWS KMS, use o comando
list-resource-tags
.Para obter mais informações sobre como usar tags no AWS KMS, consulte Marcar chaves no Guia do desenvolvedor do AWS Key Management Service.
-
Para obter detalhes da API, consulte TagResource
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar untag-resource
.
- AWS CLI
-
Para excluir uma tag de uma chave do KMS
O exemplo
untag-resource
a seguir exclui a tag com a chave"Purpose"
de uma chave do KMS gerenciada pelo cliente.Use o parâmetro
key-id
para especificar a chave do KMS. Este exemplo usa um valor de ID de chave, mas você pode usar um ID de chave ou o ARN da chave neste comando. Antes de executar esse comando, substitua o ID de chave de exemplo por um ID de chave válido da sua conta da AWS.aws kms untag-resource \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
\ --tag-key 'Purpose
'Este comando não produz saída. Para visualizar as tags em uma chave do AWS KMS, use o comando
list-resource-tags
.Para obter mais informações sobre como usar tags no AWS KMS, consulte Marcar chaves no Guia do desenvolvedor do AWS Key Management Service.
-
Para obter detalhes sobre a API, consulte UntagResource
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar update-alias
.
- AWS CLI
-
Como associar um alias a uma chave do KMS diferente
O exemplo de
update-alias
a seguir associa o aliasalias/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 comalias/
. 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.
-
Para obter detalhes da API, consulte UpdateAlias
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar update-custom-key-store
.
- AWS CLI
-
Exemplo 1: editar o nome amigável de um repositório de chaves personalizado
O exemplo
update-custom-key-store
a seguir altera o nome do repositório de chaves personalizado. Este exemplo funciona para um repositório de chaves do AWS CloudHSM ou repositório de chaves externo.Use o
custom-key-store-id
para identificar o repositório de chaves. Use o parâmetronew-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 comandodescribe-custom-key-store
.aws kms update-custom-key-store \ --custom-key-store-id
cks-1234567890abcdef0
\ --new-custom-key-store-nameExampleKeyStore
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 senhakmsuser
para a senha atual dokmsuser
no cluster do CloudHSM associado ao repositório de chaves especificado. Esse comando não altera a senhakmsuser
do cluster. Ele apenas informa ao AWS KMS a senha atual. Se o KMS não tiver a senha atualkmsuser
, 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 comandoconnect-custom-key-store
.aws kms update-custom-key-store \ --custom-key-store-id
cks-1234567890abcdef0
\ --key-store-passwordExamplePassword
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 comandoconnect-custom-key-store
.aws kms update-custom-key-store \ --custom-key-store-id
cks-1234567890abcdef0
\ --cloud-hsm-cluster-idcluster-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 oaccess-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 dexks-proxy-uri-endpoint
para refletir o nome DNS privado associado ao serviço de endpoint da VPC. Também é necessário adicionar um valor dexks-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 comandoconnect-custom-key-store
.aws kms update-custom-key-store \ --custom-key-store-id
cks-1234567890abcdef0
\ --xks-proxy-connectivityVPC_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.
-
Para ver detalhes da API, consulte UpdateCustomKeyStore
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar update-key-description
.
- AWS CLI
-
Exemplo 1: adicionar ou alterar uma descrição em uma chave do KMS gerenciada pelo cliente
O exemplo
update-key-description
a seguir adiciona uma descrição uma chave do KMS gerenciada pelo cliente. É possível usar o mesmo comando para alterar uma descrição existente.O parâmetro
--key-id
identifica a chave do KMS no comando. Este exemplo usa o valor do ARN da chave, mas é possível usar o ID da chave ou o ARN da chave do KMS. O parâmetro--description
especifica a nova descrição. O valor desse parâmetro substitui a descrição atual da chave do KMS, se houver.aws kms update-key-description \ --key-id arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab \ --description "IT Department test key"
Este comando não produz saída. Para visualizar a descrição de uma chave do KMS, use o comando
describe-key
.Para obter mais informações, consulte UpdateKeyDescription 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.
-
Para ver detalhes da API, consulte UpdateKeyDescription
na Referência de comandos da AWS CLI.
-
O código de exemplo a seguir mostra como usar verify
.
- AWS CLI
-
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 comandosign
, consulte os exemplos do comandosign
.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 comandoverify
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
\ --messagefileb://EncodedMessage
\ --message-typeRAW
\ --signing-algorithmRSASSA_PKCS1_V1_5_SHA_256
\ --signaturefileb://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.
-
Para ver detalhes da API, consulte Verify
na Referência de comandos da AWS CLI.
-