Trabalhar com concessões - AWS Key Management Service

Trabalhar com concessões

Os exemplos deste tópico usam a API do AWS KMS para criar, visualizar, retirar e revogar concessões em AWS KMS keys. Para obter mais detalhes sobre como usar concessões no AWS KMS, consulte Concessões no AWS KMS.

Criar uma concessão

Para criar uma concessão para uma AWS KMS key, use a operação CreateGrant. A resposta inclui apenas o ID de concessão e o token de concessão. Para obter informações detalhadas sobre a concessão, use a operação ListGrants, conforme mostrado em Visualizar uma concessão.

Estes exemplos criam uma concessão que permite que Alice, um usuário do IAM na conta, chame a operação GenerateDataKey na chave do KMS identificada pelo parâmetro KeyId.

Em linguagens que exigem um objeto cliente, esses exemplos usam o objeto cliente do AWS KMS criado em Criar um cliente.

Java

Para obter detalhes, consulte o Método createGrant, na Referência de APIs do AWS SDK for Java.

// Create a grant // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; String granteePrincipal = "arn:aws:iam::111122223333:user/Alice"; String operation = GrantOperation.GenerateDataKey.toString(); CreateGrantRequest request = new CreateGrantRequest() .withKeyId(keyId) .withGranteePrincipal(granteePrincipal) .withOperations(operation); CreateGrantResult result = kmsClient.createGrant(request);
C#

Para obter detalhes, consulte o Método CreateGrant no AWS SDK for .NET.

// Create a grant // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; String granteePrincipal = "arn:aws:iam::111122223333:user/Alice"; String operation = GrantOperation.GenerateDataKey; CreateGrantRequest createGrantRequest = new CreateGrantRequest() { KeyId = keyId, GranteePrincipal = granteePrincipal, Operations = new List<string>() { operation } }; CreateGrantResponse createGrantResult = kmsClient.CreateGrant(createGrantRequest);
Python

Para obter detalhes, consulte o Método create_grant no AWS SDK for Python (Boto3).

# Create a grant # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' grantee_principal = 'arn:aws:iam::111122223333:user/Alice' operation = ['GenerateDataKey'] response = kms_client.create_grant( KeyId=key_id, GranteePrincipal=grantee_principal, Operations=operation )
Ruby

Para obter detalhes, consulte o método de instância create_grant no AWS SDK for Ruby.

# Create a grant # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' grantee_principal = 'arn:aws:iam::111122223333:user/Alice' operation = ['GenerateDataKey'] response = kmsClient.create_grant({ key_id: key_id, grantee_principal: grantee_principal, operations: operation })
PHP

Para obter detalhes, consulte o Método CreateGrant no AWS SDK for PHP.

// Create a grant // // Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $granteePrincipal = "arn:aws:iam::111122223333:user/Alice"; $operation = ['GenerateDataKey'] $result = $KmsClient->createGrant([ 'GranteePrincipal' => $granteePrincipal, 'KeyId' => $keyId, 'Operations' => $operation ]);
Node.js

Para obter mais detalhes, consulte a propriedade createGrant, no AWSSDK for JavaScript in Node.js.

// Create a grant // // Replace the following example key ARN with a valid key ID or key ARN const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; const GranteePrincipal = 'arn:aws:iam::111122223333:user/Alice'; const Operations: ["GenerateDataKey"]; kmsClient.createGrant({ KeyId, GranteePrincipal, Operations }, (err, data) => { ... });
PowerShell

Para criar uma concessão, use o cmdlet New-KMSGrant.

# Create a grant # Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' $granteePrincipal = 'arn:aws:iam::111122223333:user/Alice' $operation = 'GenerateDataKey' $response = New-KMSGrant -GranteePrincipal $granteePrincipal -KeyId $keyId -Operation $operation

Para usar os cmdlets do PowerShell AWS KMS, instale o módulo AWS.Tools.KeyManagementService. Para obter mais informações, consulte o Manual do usuário do AWS Tools for Windows PowerShell.

Visualizar uma concessão

Para obter informações detalhadas sobre as concessões em uma chave do KMS, use a operação ListGrants.

nota

O campo GranteePrincipal na resposta ListGrants geralmente contém o principal favorecido da concessão. No entanto, quando a entidade principal receptora na concessão é um serviço da AWS, o campo GranteePrincipal contém a entidade principal de serviço, que pode representar várias entidades principais entidade receptoras de concessão diferentes.

Em linguagens que exigem um objeto cliente, esses exemplos usam o objeto cliente do AWS KMS criado em Criar um cliente.

Esses exemplos usam o parâmetro Limits opcional, que determina o número de concessões que a operação retorna.

Java

Para obter detalhes sobre a implementação de Java, consulte o Método listGrants, na Referência de APIs do AWS SDK for Java.

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; Integer limit = 10; ListGrantsRequest req = new ListGrantsRequest().withKeyId(keyId).withLimit(limit); ListGrantsResult result = kmsClient.listGrants(req);
C#

Para obter detalhes, consulte o Método ListGrants no AWS SDK for .NET.

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; int limit = 10; ListGrantsRequest listGrantsRequest = new ListGrantsRequest() { KeyId = keyId, Limit = limit }; ListGrantsResponse listGrantsResponse = kmsClient.ListGrants(listGrantsRequest);
Python

Para obter detalhes, consulte o Método list_grants no AWS SDK for Python (Boto3).

# Listing grants on a KMS key # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kms_client.list_grants( KeyId=key_id, Limit=10 )
Ruby

Para obter detalhes, consulte o método de instância list_grants no AWS SDK for Ruby.

# Listing grants on a KMS key # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kmsClient.list_grants({ key_id: key_id, limit: 10 })
PHP

Para obter detalhes, consulte o Método ListGrants no AWS SDK for PHP.

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $limit = 10; $result = $KmsClient->listGrants([ 'KeyId' => $keyId, 'Limit' => $limit, ]);
Node.js

Para obter mais detalhes, consulte a propriedade listGrants, no AWSSDK for JavaScript in Node.js.

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; const Limit = 10; kmsClient.listGrants({ KeyId, Limit }, (err, data) => { ... });
PowerShell

Para visualizar os detalhes de todas as concessões do AWS KMS para uma chave do KMS, use o cmdlet Get-KMSGrantList.

Para limitar o número de objetos de saída, este exemplo usa o cmdlet Select-Object em vez do parâmetro Limit, que está defasado nos cmdlets da lista. Para obter ajuda com a saída da paginação no AWS Tools for PowerShell, consulte Paginação de saída com o AWS Tools for PowerShell.

# Listing grants on a KMS key # Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' $limit = 10 $response = Get-KMSGrantList -KeyId $keyId | Select-Object -First $limit

Para usar os cmdlets do PowerShell AWS KMS, instale o módulo AWS.Tools.KeyManagementService. Para obter mais informações, consulte o Manual do usuário do AWS Tools for Windows PowerShell.

Você deve especificar a chave do KMS em todas as operações ListGrants. No entanto, você pode filtrar ainda mais a lista de concessões especificando o ID de concessão ou a entidade principal receptora da concessão. Os exemplos a seguir obtêm apenas as concessões para uma chave do KMS e que a função test-engineer é a entidade principal receptora da concessão.

Java

Para obter detalhes sobre a implementação de Java, consulte o Método listGrants, na Referência de APIs do AWS SDK for Java.

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; String grantee = "arn:aws:iam::111122223333:role/test-engineer"; ListGrantsRequest req = new ListGrantsRequest().withKeyId(keyId).withGranteePrincipal(grantee); ListGrantsResult result = kmsClient.listGrants(req);
C#

Para obter detalhes, consulte o Método ListGrants no AWS SDK for .NET.

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; String grantee = "arn:aws:iam::111122223333:role/test-engineer"; ListGrantsRequest listGrantsRequest = new ListGrantsRequest() { KeyId = keyId, GranteePrincipal = grantee }; ListGrantsResponse listGrantsResponse = kmsClient.ListGrants(listGrantsRequest);
Python

Para obter detalhes, consulte o Método list_grants no AWS SDK for Python (Boto3).

# Listing grants on a KMS key # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' grantee = 'arn:aws:iam::111122223333:role/test-engineer' response = kms_client.list_grants( KeyId=key_id, GranteePrincipal=grantee )
Ruby

Para obter detalhes, consulte o método de instância list_grants no AWS SDK for Ruby.

# Listing grants on a KMS key # Replace the following example key ARN with a valid key ID or key ARN keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' grantee = 'arn:aws:iam::111122223333:role/test-engineer' response = kmsClient.list_grants({ key_id: keyId, grantee_principal: grantee })
PHP

Para obter detalhes, consulte o Método ListGrants no AWS SDK for PHP.

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $grantee = 'arn:aws:iam::111122223333:role/test-engineer'; $result = $KmsClient->listGrants([ 'KeyId' => $keyId, 'GranteePrincipal' => $grantee, ]);
Node.js

Para obter mais detalhes, consulte a propriedade listGrants, no AWSSDK for JavaScript in Node.js.

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; const Grantee = 'arn:aws:iam::111122223333:role/test-engineer'; kmsClient.listGrants({ KeyId, Grantee }, (err, data) => { ... });
PowerShell

Para visualizar os detalhes de todas as concessões do AWS KMS para uma chave do KMS, use o cmdlet Get-KMSGrantList.

# Listing grants on a KMS key # Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' $grantee = 'arn:aws:iam::111122223333:role/test-engineer' $response = Get-KMSGrantList -KeyId $keyId -GranteePrincipal $grantee

Para usar os cmdlets do PowerShell AWS KMS, instale o módulo AWS.Tools.KeyManagementService. Para obter mais informações, consulte o Manual do usuário do AWS Tools for Windows PowerShell.

Remover uma concessão

Para retirar uma concessão de uma chave do KMS, use a operação RetireGrant. Você deve remover uma concessão para limpá-la depois de terminar de usá-la.

Para retirar uma concessão, forneça o token da concessão ou o ID de concessão e o ID da chave do KMS. Para essa operação, o ID da chave do KMS deve ser o Amazon Resource Name (ARN) da chave do KMS. O token de concessão é retornado pela operação CreateGrant. O ID de concessão é retornado pelas operações CreateGrant e ListGrants.

RetireGrant não retorna uma resposta. Para verificar se ele entrou em vigor, use a operação ListGrants.

Em linguagens que exigem um objeto cliente, esses exemplos usam o objeto cliente do AWS KMS criado em Criar um cliente.

Java

Para obter detalhes, consulte o Método retireGrant, na Referência de APIs do AWS SDK for Java.

// Retire a grant // String grantToken = Place your grant token here; RetireGrantRequest req = new RetireGrantRequest().withGrantToken(grantToken); kmsClient.retireGrant(req);
C#

Para obter detalhes, consulte o Método RetireGrant no AWS SDK for .NET.

// Retire a grant // String grantToken = "Place your grant token here"; RetireGrantRequest retireGrantRequest = new RetireGrantRequest() { GrantToken = grantToken }; kmsClient.RetireGrant(retireGrantRequest);
Python

Para obter detalhes, consulte o Método retire_grant no AWS SDK for Python (Boto3).

# Retire a grant grant_token = Place your grant token here response = kms_client.retire_grant( GrantToken=grant_token )
Ruby

Para obter detalhes, consulte o método de instância retire_grant no AWS SDK for Ruby.

# Retire a grant grant_token = Place your grant token here response = kmsClient.retire_grant({ grant_token: grant_token })
PHP

Para obter detalhes, consulte o Método RetireGrant no AWS SDK for PHP.

// Retire a grant // $grantToken = 'Place your grant token here'; $result = $KmsClient->retireGrant([ 'GrantToken' => $grantToken, ]);
Node.js

Para obter mais detalhes, consulte a propriedade retireGrant, no AWSSDK for JavaScript in Node.js.

// Retire a grant // const GrantToken = 'Place your grant token here'; kmsClient.retireGrant({ GrantToken }, (err, data) => { ... });
PowerShell

Para retirar uma concessão, use o cmdlet Disable-KMSGrant. Para obter o token de concessão, use o cmdlet New-KMSGrant. O parâmetro GrantToken usa uma string, portanto, não é necessário converter a saída retornada pelo cmdlet Read-Host.

# Retire a grant $grantToken = Read-Host -Message Place your grant token here Disable-KMSGrant -GrantToken $grantToken

Para usar os cmdlets do PowerShell AWS KMS, instale o módulo AWS.Tools.KeyManagementService. Para obter mais informações, consulte o Manual do usuário do AWS Tools for Windows PowerShell.

Revogar uma concessão

Para revogar uma concessão de uma chave do KMS, use a operação RevokeGrant. Você pode revogar uma concessão para negar explicitamente as operações que dependem dela.

Em linguagens que exigem um objeto cliente, esses exemplos usam o objeto cliente do AWS KMS criado em Criar um cliente.

Java

Para obter detalhes, consulte o Método revokeGrant, na Referência de APIs do AWS SDK for Java.

// Revoke a grant on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; // &fake-grant-id; String grantId = "grant1"; RevokeGrantRequest req = new RevokeGrantRequest().withKeyId(keyId).withGrantId(grantId); kmsClient.revokeGrant(req);
C#

Para obter detalhes, consulte o Método RevokeGrant no AWS SDK for .NET.

// Revoke a grant on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; // &fake-grant-id; String grantId = "grant1"; RevokeGrantRequest revokeGrantRequest = new RevokeGrantRequest() { KeyId = keyId, GrantId = grantId }; kmsClient.RevokeGrant(revokeGrantRequest);

Para usar os cmdlets do PowerShell AWS KMS, instale o módulo AWS.Tools.KeyManagementService. Para obter mais informações, consulte o Manual do usuário do AWS Tools for Windows PowerShell.

Python

Para obter detalhes, consulte o Método revoke_grant no AWS SDK for Python (Boto3).

# Revoke a grant on a KMS key # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' # &fake-grant-id; grant_id = 'grant1' response = kms_client.revoke_grant( KeyId=key_id, GrantId=grant_id )
Ruby

Para obter detalhes, consulte o método de instância revoke_grant no AWS SDK for Ruby.

# Revoke a grant on a KMS key # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' # &fake-grant-id; grant_id = 'grant1' response = kmsClient.revoke_grant({ key_id: key_id, grant_id: grant_id })
PHP

Para obter detalhes, consulte o Método RevokeGrant no AWS SDK for PHP.

// Revoke a grant on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; // Replace the following example grant ID with a valid one $grantId = "grant1"; $result = $KmsClient->revokeGrant([ 'KeyId' => $keyId, 'GrantId' => $grantId, ]);
Node.js

Para obter mais detalhes, consulte a propriedade revokeGrant, no AWSSDK for JavaScript in Node.js.

// Revoke a grant on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; // Replace the following example grant ID with a valid one const GrantId = 'grant1'; kmsClient.revokeGrant({ GrantId, KeyId }, (err, data) => { ... });
PowerShell

Para revogar uma concessão, use o cmdlet Revoke-KMSGrant.

# Revoke a grant on a KMS key # Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' # Replace the following example grant ID with a valid one $grantId = 'grant1' Revoke-KMSGrant -KeyId $keyId -GrantId $grantId

Para usar os cmdlets do PowerShell AWS KMS, instale o módulo AWS.Tools.KeyManagementService. Para obter mais informações, consulte o Manual do usuário do AWS Tools for Windows PowerShell.