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

Descrição da operação

Para obter detalhes sobre a política de acesso necessária para que usuários ou funções do Resource Access Management (RAM) chamem esta operação de API, consulte Controle de acesso.
Você pode chamar esta operação de API por meio de um gateway compartilhado ou um gateway dedicado. Para obter mais informações, consulte Alibaba Cloud SDK.
- Gateway compartilhado: Acesse o KMS pela Internet ou por meio de um endpoint de VPC. Este método exige que você ative o acesso à rede pública. Para obter mais informações, consulte Chaves de acesso em uma instância do KMS pela Internet.
- Gateway dedicado: Acesse o KMS por meio do endpoint privado do KMS (<YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com).

Limites de QPS

Gateway compartilhado: O limite de QPS por usuário para esta operação de API é de 1.000 chamadas por segundo. Se o limite for excedido, as chamadas de API serão limitadas, o que pode afetar seus negócios. Faça chamadas de API em uma frequência razoável.
Gateway dedicado: O limite de QPS por usuário para esta operação de API depende das especificações de desempenho de computação da sua instância do KMS. Para obter mais informações, consulte Dados de desempenho.

Descrição

A chave de dados (DK) gerada aleatoriamente é criptografada usando a chave mestra do cliente (CMK) especificada, e o texto cifrado e o texto simples da DK são retornados. Você pode usar o texto simples da DK retornado para criptografar dados localmente fora do KMS. Ao armazenar os dados criptografados, você também deve armazenar o texto cifrado da DK. Você pode obter o texto simples da DK no campo Plaintext da resposta e o texto cifrado da DK no campo CiphertextBlob.

A CMK especificada na solicitação é usada apenas para criptografar a DK e não está envolvida na geração da DK. O KMS não registra nem armazena a DK gerada aleatoriamente. Você é responsável por persistir o texto cifrado da DK.

Recomendamos que você use o seguinte método para criptografar dados localmente:

Chame a operação GenerateDataKey para obter uma chave para criptografia de dados.
Use o texto simples da DK retornado no campo Plaintext da resposta para concluir a criptografia de dados offline localmente e, em seguida, limpe o texto simples da DK da memória.
Armazene o texto cifrado da DK retornado no campo CiphertextBlob da resposta junto com os dados criptografados localmente.

Para descriptografar dados localmente:

Chame a operação Decrypt para descriptografar o texto cifrado da DK no armazenamento local. Esta operação retorna o texto simples da DK.
Use o texto simples da DK para concluir a descriptografia de dados offline localmente e, em seguida, limpe o texto simples da DK da memória.

Este tópico fornece um exemplo de geração de uma DK 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

A tabela abaixo descreve a autorização necessária para chamar esta API. Você pode defini-la em uma política do Resource Access Management (RAM). As colunas da tabela estão detalhadas abaixo:

Ação: As ações que podem ser usadas no elemento Action das instruções de política de permissão do RAM para conceder permissões para executar a operação.
API: A API que você pode chamar para executar a ação.
Nível de acesso: O nível de acesso predefinido concedido para cada API. Valores válidos: create, list, get, update e delete.
Tipo de recurso: O tipo de recurso que suporta autorização para executar a ação. Indica se a ação suporta permissão em nível de recurso. O recurso especificado deve ser compatível com a ação. Caso contrário, a política será ineficaz.
- Para APIs com permissões em nível de recurso, os tipos de recursos obrigatórios são marcados com um asterisco (*). Especifique o Nome de Recurso Alibaba Cloud (ARN) correspondente no elemento Resource da política.
- Para APIs sem permissões em nível de recurso, é exibido como Todos os Recursos. Use um asterisco (*) no elemento Resource da política.
Chave de condição: As chaves de condição definidas pelo serviço. A chave permite controle granular, aplicando-se somente a ações ou a ações associadas a recursos específicos. Além das chaves de condição específicas do serviço, o Alibaba Cloud fornece um conjunto de chaves de condição comuns aplicáveis a todos os serviços compatíveis com RAM.
Ação dependente: As ações dependentes necessárias para executar a ação. Para concluir a ação, o usuário RAM ou a função RAM deve ter permissões para executar todas as ações dependentes.

Ação

Nível de acesso

Tipo de recurso

Chave de condição

Ação dependente

kms:GenerateDataKey

get

*Chave.

acs:kms:{#regionId}:{#accountId}:key/{#KeyId}

kms:tag

Nenhuma

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 do Alibaba Cloud (ARN) da chave. Para obter mais informações sobre aliases, consulte Gerenciar aliases de chave. Nota Ao acessar uma chave que pertence a outra conta do Alibaba Cloud, você deve inserir o ARN da chave. O ARN de uma chave está no formato `acs:kms:${region}:${account}:key/${keyid}`.	key-hzz630494463ejqjx****
KeySpec	string	Não	Especifica o comprimento da DK gerada. Valores válidos: AES_256: Uma chave simétrica de 256 bits. AES_128: Uma chave simétrica de 128 bits. Nota Use KeySpec ou NumberOfBytes para especificar o comprimento da DK. Se nenhum parâmetro for especificado, o KMS gera uma DK de 256 bits. Se ambos os parâmetros forem especificados, o KMS ignora o parâmetro KeySpec.	AES_256
NumberOfBytes	integer	Não	Especifica o comprimento da DK gerada em bytes. Valores válidos: 1 a 1024. Valor padrão: Se KeySpec estiver definido como AES_256, o valor padrão de NumberOfBytes é 32. Se KeySpec estiver definido como AES_128, o valor padrão de NumberOfBytes é 16.	256
EncryptionContext	object	Não	A string JSON de pares chave-valor. Se este parâmetro for especificado, você deverá fornecer 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 dry run deve ser ativado. Valores válidos: true: Ativado. false: Desativado. Valor padrão: false. O modo dry run é usado para testar chamadas de API, verificar se você tem as permissões necessárias nos recursos e verificar se os parâmetros da solicitação estão configurados corretamente. Quando o modo dry run está ativado, o KMS sempre retorna uma falha e fornece a causa da falha. As causas incluem: DryRunOperationError: A solicitação seria bem-sucedida se o parâmetro DryRun não fosse especificado. ValidationError: Os parâmetros especificados na solicitação são inválidos. AccessDeniedError: Você não tem as permissões necessárias para realizar esta operação nos recursos do KMS.	false
Recipient	string	Não	As informações de autenticação do ambiente confiável. AttestationDocument // O documento de atestação do ambiente confiável em codificação Base64, que inclui informações como medições de ambiente, assinaturas e certificados. KeyEncryptionAlgorithm // O algoritmo de criptografia de chave. Apenas RSAES_OAEP_SHA_256 é suportado. Estrutura do AttestationDocument: quoted extendUserData // Os dados de extensão do usuário em codificação Base64. A estrutura decodificada é a seguinte: aud // O valor fixo "kms". iat // A hora de emissão, que é um carimbo de data/hora UNIX em segundos. exp // A hora de expiração, que é um carimbo de data/hora UNIX em segundos. pubKey // A chave pública RSA2048 no formato SPKI codificado em Base64. digestAlg // O algoritmo de resumo. Apenas "sha256" é suportado. ver // A versão do protocolo. Apenas "v1" é suportado. signature // A assinatura do relatório, que é usada para verificar a integridade de quoted e extendUserData. pcrInfo: pcrValues // As medições do Platform Configuration Register (PCR). pcrSelectionOut // As informações de seleção de PCR. pcrUpdateCounter // O número de atualizações de PCR. cert // O certificado de atestação da plataforma, que é usado para verificar a validade da assinatura. Importante Este parâmetro entra em vigor apenas quando você chama a operação de API por meio de um gateway dedicado.	{ "AttestationDocument":"base64-encoded-attestion-document", "KeyEncryptionAlgorithm":"RSAES_OAEP_SHA_256" }

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

Elementos de resposta

Elemento	Tipo	Descrição	Exemplo
	object
KeyVersionId	string	O ID da versão da chave. É o identificador globalmente exclusivo da versão da chave primária.	2ab1a983-7072-4bbc-a582-584b5bd8****
KeyId	string	O ID da chave. Se o parâmetro KeyId na solicitação estiver definido como o alias ou o ARN da chave, o ID da chave também será retornado na resposta.	key-hzz630494463ejqjx****
CiphertextBlob	string	O texto cifrado da DK criptografado usando a versão primária da chave especificada.	ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****
RequestId	string	O ID da solicitação. É um identificador exclusivo gerado pelo Alibaba Cloud para a solicitação e pode ser usado para solucionar e localizar problemas.	7021b6ec-4be7-4d3c-8a68-1e85d4d515a0
Plaintext	string	O texto simples da DK codificado em Base64.	QmFzZTY0IGVuY29kZWQgcGxhaW50****
CiphertextForRecipient	string	Quando o parâmetro Recipient é transmitido, a DK em texto simples é criptografada usando a chave pública no extendUserData do Recipient, e o resultado é codificado em Base64. Importante Este parâmetro entra em vigor apenas quando você chama a operação de API por meio de um gateway dedicado.	NIahY6pgjK4ZMP2R0EmsmBqntrv0AI2rcDyU7Su6uOT9Le7EOvlCpjHJfr9z3M0vkfulQoyuETmKSpYDfixE3auE4MwxloT6D9Gfsk6hm5FV2iAxL//Ms2kLv6K4z6yGi7lKm2yjX4***==

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****",
  "CiphertextForRecipient": "NIahY6pgjK4ZMP2R0EmsmBqntrv0AI2rcDyU7Su6uOT9Le7EOvlCpjHJfr9z3M0vkfulQoyuETmKSpYDfixE3auE4MwxloT6D9Gfsk6hm5FV2iAxL//Ms2kLv6K4z6yGi7lKm2yjX4***=="
}

Códigos de erro

Código de status HTTP	Código de erro	Mensagem de erro
400	UnsupportedOperation	This action is not supported.
404	Forbidden.AliasNotFound	The specified Alias is not found.
404	Forbidden.KeyNotFound	The specified Key is not found.
409	Rejected.Disabled	The request was rejected because the key state is Disabled.
409	Rejected.PendingDeletion	The request was rejected because the key state is PendingDeletion.
409	Rejected.Unavailable	The request was rejected because the key state is Unavailable.

Consulte Códigos de Erro para uma lista completa.

Notas de versão

Consulte Notas de Versão para uma lista completa.