Todos os produtos
Search

Este produto

    Key Management Service:AdvanceEncrypt

    Central de documentação

    Key Management Service:AdvanceEncrypt

    Última atualização: Jun 27, 2026

    Criptografa texto simples em texto cifrado usando a versão primária de uma chave simétrica em uma instância de gerenciamento de chaves por software do Key Management Service (KMS).

    Descrição da operação

    Tanto o AdvanceEncrypt quanto a operação Encrypt convertem texto simples em texto cifrado, mas diferem na versão da chave utilizada e na operação de descriptografia compatível:

    AdvanceEncrypt

    **Encrypt**

    Versão da chave utilizada

    Versão primária

    Versão inicial

    Operação de descriptografia compatível

    Apenas AdvanceDecrypt

    Decrypt ou AdvanceDecrypt
    Importante

    Se a rotação automática de chaves estiver ativada, utilize o AdvanceEncrypt em vez do Encrypt para garantir o funcionamento correto desse recurso. Para mais informações, consulte Configure key rotation.

    Esta operação é suportada apenas para chaves simétricas em instâncias de gerenciamento de chaves por software do KMS. Para especificações de chave, algoritmos de criptografia e versões de chave suportadas, consulte Key types and specifications.

    Observações de uso

    O corpo da requisição não deve exceder 3 MB após a codificação com Protocol Buffers. Caso contrário, o servidor retorna HTTP 413. Limite o tamanho dos dados a 6 KB por operação. Para cargas maiores, utilize a envelope encryption.

    Nota

    Cargas de dados grandes aumentam o risco de falhas de rede, prolongam o tempo de transmissão e reduzem a performance das operações de criptografia e descriptografia do KMS.

    Parâmetros da requisição

    ParâmetroTipoObrigatórioExemploDescrição
    KeyIdstringSimkey-hzz62f1cb66fa42qo****ID globalmente exclusivo da chave ou um alias vinculado a ela. A chave deve ser simétrica e pertencer a uma instância de gerenciamento de chaves por software do KMS.
    PlaintextbytesSimDados bináriosTexto simples a ser criptografado.
    AlgorithmstringNãoAES_GCMAlgoritmo de criptografia. Se não for definido, assume o padrão configurado para a chave. Para valores suportados, consulte Key types and specifications.
    IvbytesNãoDados bináriosVetor de inicialização (IV). Aplica-se apenas quando Algorithm é AES_GCM ou AES_CBC. Se omitido, o KMS gera um valor aleatório. Tamanhos válidos: 12 bytes para AES_GCM e 16 bytes para AES_CBC.
    Importante

    Recomendamos que você não defina este parâmetro.

    AadbinaryNãoDados bináriosDados autenticados adicionais (AAD) para o modo GCM. Aplica-se somente quando Algorithm é AES_GCM, sendo opcional conforme suas necessidades de negócio. Se definido, transmita o mesmo valor ao chamar AdvanceDecrypt.
    PaddingModestringNãoPKCS7_PADDINGModo de preenchimento. Necessário apenas quando Algorithm é AES_CBC ou AES_ECB. Valores válidos: PKCS7_PADDING (padrão) e NO_PADDING. Com PKCS7_PADDING, o sistema preenche a entrada com K-(L mod K) bytes, onde K é o tamanho do bloco de cifra e L é o comprimento da entrada. Já com NO_PADDING, o tamanho do texto simples deve ser um múltiplo inteiro do tamanho do bloco de cifra.

    Parâmetros de resposta

    Parâmetro

    Tipo

    Exemplo

    Descrição

    CiphertextBlob

    bytes

    Dados binários

    Texto cifrado resultante. Contém metadados incorporados para KeyId, Algorithm, PaddingMode e Iv — transmita apenas CiphertextBlob ao chamar AdvanceDecrypt.

    Algorithm

    string

    AES_GCM

    Algoritmo de criptografia utilizado.

    KeyId

    string

    key-hzz62f1cb66fa42qo****

    ID globalmente exclusivo da chave. Se um alias foi passado na requisição, o sistema retorna o ID da chave vinculada a esse alias.

    KeyVersionId

    string

    key-hzz62f1cb66fa42qopd9s-17kedv****

    Versão da chave usada para criptografar os dados. Sempre corresponde à versão primária.

    Iv

    bytes

    Dados binários

    Vetor de inicialização utilizado. Retornado apenas quando Algorithm é AES_GCM ou AES_CBC; caso contrário, permanece vazio.

    PaddingMode

    string

    PKCS7_PADDING

    Modo de preenchimento aplicado. Retornado somente se Algorithm for AES_CBC ou AES_ECB; vazio nos demais casos.

    RequestId

    string

    c0037a6d-7784-4ef2-a692-288fdefc7b9d

    ID da requisição, utilizado para localizar e solucionar problemas.

    Códigos de erro

    Código de status HTTP

    Código de erro

    Mensagem de erro

    Descrição

    404

    Forbidden.OnlySymmetricKeySupported

    The key %s is not a symmetric key. The API only supports symmetric keys.

    A chave especificada não é simétrica. Esta API suporta exclusivamente chaves simétricas. Chaves assimétricas destinam-se a criptografia de dados entre domínios de segurança distintos ou troca de chaves, cenários em que o KMS não participa de um dos lados.

    Para obter a lista completa de códigos de erro, consulte Service error codes.