GenerateDataKey - Key Management Service: Central de Documentação do Alibaba Cloud

Descrição da operação

Para obter informações sobre as permissões necessárias para chamar esta operação, consulte Resource Access Management.
Esta operação pode ser chamada usando um gateway compartilhado ou um gateway dedicado. Para obter mais informações, consulte Alibaba Cloud SDK.
- Gateway compartilhado: Você pode acessar o KMS pela Internet ou por uma VPC. Para acessar o KMS pela Internet, você deve ativar o endpoint público. Para obter mais informações, consulte Chaves de acesso em uma instância KMS pela Internet.
- Gateway dedicado: Você pode acessar o KMS usando o endpoint privado do KMS (<YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com).

Limites de QPS

Se você usar um gateway compartilhado para chamar esta operação, o limite de consultas por segundo (QPS) para um único usuário é de 1.000. Se o limite for excedido, as chamadas de API serão limitadas. Isso pode afetar seus negócios. Recomendamos que você chame esta operação a uma taxa razoável.
Se você usar um gateway dedicado para chamar esta operação, o limite de QPS para um único usuário será baseado no desempenho de computação da sua instância KMS. Para obter mais informações, consulte Métricas de desempenho.

Descrição

Esta operação gera uma chave de dados aleatória, criptografa a chave de dados usando a chave mestra do cliente (CMK) especificada e retorna o texto simples e o texto cifrado da chave de dados. Você pode usar o texto simples da chave de dados para criptografar dados localmente e fora do KMS. Ao armazenar os dados criptografados, você também deve armazenar o texto cifrado da chave de dados. Você pode obter o texto simples da chave de dados no campo Plaintext e o texto cifrado da chave de dados no campo CiphertextBlob na resposta.

A CMK especificada na solicitação é usada apenas para criptografar a chave de dados. Ela não está envolvida na geração da chave de dados. O KMS não registra nem armazena a chave de dados gerada aleatoriamente. Você é responsável pela persistência do texto cifrado da chave de dados.

Recomendamos que você execute as seguintes etapas para criptografar dados localmente:

1. Chame a operação GenerateDataKey para obter uma chave de dados para criptografia de dados.

2. Use o texto simples da chave de dados retornado no campo Plaintext da resposta para criptografar dados localmente. Em seguida, limpe o texto simples da chave de dados da memória.

3. Armazene o texto cifrado da chave de dados retornado no campo CiphertextBlob da resposta junto com os dados criptografados.

Para descriptografar dados localmente:

Chame a operação Decrypt para descriptografar o texto cifrado armazenado da chave de dados. Esta operação retorna o texto simples da chave de dados.
Use o texto simples da chave de dados para descriptografar dados localmente. Em seguida, limpe o texto simples da chave de dados da memória.

Este tópico fornece um exemplo de como gerar uma chave de dados aleatória para uma chave com o ID key-hzz630494463ejqjx****.

Experimente agora

Experimente esta API no OpenAPI Explorer, sem necessidade de assinatura manual. Chamadas bem-sucedidas geram automaticamente código SDK correspondente aos seus parâmetros. Faça o download com segurança de credenciais integrada para uso local.

Testar

Autorização RAM

Nenhuma autorização necessária para esta operação. Se você encontrar problemas com esta operação, entre em contato com o suporte técnico.

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
KeyId	string	Sim	O ID da chave. Você também pode especificar o alias ou o nome do recurso (ARN) da chave. Para obter mais informações sobre aliases, consulte Gerenciar aliases. Nota Ao acessar uma chave em outra conta da Alibaba Cloud, você deve inserir o ARN da chave. O ARN da chave está no formato `acs:kms:${region}:${account}:key/${keyid}`.	key-hzz630494463ejqjx****
KeySpec	string	Não	O comprimento da chave de dados a ser gerada. Valores válidos: AES_256: uma chave simétrica de 256 bits. AES_128: uma chave simétrica de 128 bits. Nota Recomendamos que você use o parâmetro KeySpec ou NumberOfBytes para especificar o comprimento de uma chave de dados. Se você não especificar nenhum dos parâmetros, o KMS gerará uma chave de dados de 256 bits. Se você especificar ambos os parâmetros, o KMS ignorará o parâmetro KeySpec.	AES_256
NumberOfBytes	integer	Não	O comprimento da chave de dados que você deseja gerar. Unidade: bytes. Valores válidos: 1 a 1024. Valores padrão: Se você definir KeySpec como AES_256, o valor padrão de NumberOfBytes será 32. Se você definir KeySpec como AES_128, o valor padrão de NumberOfBytes será 16.	256
EncryptionContext	object	Não	Uma string JSON que consiste em pares chave-valor. Se você especificar este parâmetro, também deverá especificar o mesmo parâmetro ao chamar a operação Decrypt. Para obter mais informações, consulte EncryptionContext.	{"Example":"Example"}
DryRun	string	Não	Especifica se o modo DryRun deve ser ativado. true: ativa o modo DryRun. false (padrão): desativa o modo DryRun. O modo DryRun é usado para testar a chamada de API. Ele verifica se você tem as permissões para acessar os recursos especificados e se os parâmetros da solicitação são válidos. Se você ativar o modo DryRun, o KMS sempre retornará uma resposta de falha e um motivo de falha. Os motivos de falha incluem os seguintes: DryRunOperationError: A solicitação é bem-sucedida se o parâmetro DryRun não for especificado. ValidationError: Os parâmetros especificados na solicitação são inválidos. AccessDeniedError: Você não está autorizado a realizar esta operação no recurso do KMS.	false

Para obter informações sobre parâmetros de solicitação comuns, consulte Parâmetros comuns.

Elementos de resposta

Elemento	Tipo	Descrição	Exemplo
	object
KeyVersionId	string	O identificador globalmente exclusivo da versão da chave.	2ab1a983-7072-4bbc-a582-584b5bd8****
KeyId	string	O ID da chave. Se você usar um alias de chave ou ARN de chave no parâmetro KeyId da solicitação, o ID da chave também será retornado na resposta.	key-hzz630494463ejqjx****
CiphertextBlob	string	O texto cifrado da chave de dados criptografado pela versão primária da chave especificada.	ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****
RequestId	string	O ID da solicitação, que é um identificador exclusivo gerado pela Alibaba Cloud para a solicitação. Você pode usar o ID da solicitação para solucionar e localizar problemas.	7021b6ec-4be7-4d3c-8a68-1e85d4d515a0
Plaintext	string	O texto simples da chave de dados codificado em Base64.	QmFzZTY0IGVuY29kZWQgcGxhaW50****

Exemplos

Resposta de sucesso

JSON formato

{
  "KeyVersionId": "2ab1a983-7072-4bbc-a582-584b5bd8****",
  "KeyId": "key-hzz630494463ejqjx****",
  "CiphertextBlob": "ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****",
  "RequestId": "7021b6ec-4be7-4d3c-8a68-1e85d4d515a0",
  "Plaintext": "QmFzZTY0IGVuY29kZWQgcGxhaW50****"
}

Códigos de erro

Código de status HTTP	Código de erro	Mensagem de erro	Descrição
400	UnsupportedOperation	This action is not supported.	The operation is not supported.
404	Forbidden.AliasNotFound	The specified Alias is not found.	The error message returned because the specified alias does not exist.
404	Forbidden.KeyNotFound	The specified Key is not found.	The error message returned because the specified CMK does not exist.
409	Rejected.Disabled	The request was rejected because the key state is Disabled.	The request was rejected because the key state is Disabled.
409	Rejected.PendingDeletion	The request was rejected because the key state is PendingDeletion.	The request was rejected because the key state is PendingDeletion.
409	Rejected.Unavailable	The request was rejected because the key state is Unavailable.	The request was denied because the key status is unavailable.

Consulte Códigos de Erro para uma lista completa.

Notas de versão

Consulte Notas de Versão para uma lista completa.