Referência do formato de mensagens do SDK de criptografia da AWS - SDK de criptografia da AWS

Se fornecermos uma tradução da versão em inglês do guia, a versão em inglês prevalecerá caso haja qualquer conflito entre as versões. A tradução é fornecida com o uso de tradução por máquina.

Referência do formato de mensagens do SDK de criptografia da AWS

As informações nesta página são uma referência para criar sua própria biblioteca de criptografia compatível com o SDK de criptografia da AWS. Se você não está criando sua própria biblioteca de criptografia compatível, você provavelmente não precisa dessas informações.

Para usar o SDK de criptografia da AWS em uma das linguagens de programação compatíveis, consulte Linguagens de programação.

Para a especificação que define os elementos de uma implementação adequada do SDK de criptografia da AWS, consulte a Especificação do SDK de criptografia da AWS no repositório aws-encryption-sdk-specification no GitHub.

As operações de criptografia no SDK de criptografia da AWS retornam uma única estrutura de dados ou mensagem que contém os dados criptografados (texto cifrado) e todas as chaves de dados criptografadas. Para compreender essa estrutura de dados ou para criar bibliotecas que a leem ou gravam nela, você precisa compreender o formato da mensagem.

O formato da mensagem consiste em pelo menos duas partes: um cabeçalho e um corpo. Em alguns casos, o formato da mensagem consiste em uma terceira parte, um rodapé. O formato da mensagem define uma sequência ordenada de bytes em ordem de bytes de rede, também chamado de formato big-endian. O formato da mensagem começa com o cabeçalho, seguido pelo corpo, seguido pelo rodapé (se houver).

Estrutura do cabeçalho

O cabeçalho da mensagem contém a chave de dados criptografada e informações sobre como o corpo da mensagem é formado. A tabela a seguir descreve os campos que formam o cabeçalho. Os bytes são anexados na ordem mostrada.

Estrutura do cabeçalho
Campo Tamanho (bytes)
Versão 1
Type 1
ID do algoritmo 2.
ID de mensagem 16
Tamanho do AAD

2.

Quando o contexto de criptografia está vazio, o tamanho do AAD é 0.

AAD

Variável Igual ao valor especificado nos 2 bytes anteriores (tamanho do AAD).

Quando o contexto de criptografia está vazio, não há um campo AAD no cabeçalho.

Contagem de chaves de dados criptografadas 2.
Chaves de dados criptografadas Variável Determinado pelo número de chaves de dados criptografadas e pelo tamanho de cada uma delas.
Content-Type 1
Reservado 4
Tamanho do IV 1
Tamanho da moldura 4.
Autenticação do cabeçalho Variável Determinado pelo algoritmo que gerou a mensagem.
Versão

A versão do formato desta mensagem. A versão atual é 1.0, codificada como o byte 01 em notação hexadecimal.

Type

O tipo deste formato de mensagem. O tipo indica o tipo da estrutura. O único tipo suportado é descrito como dados criptografados e autenticados pelo cliente. Seu valor de tipo é 128 bytes, codificado como byte 80 em notação hexadecimal.

ID do algoritmo

Um identificador para o algoritmo usado. É um valor de 2 bytes interpretado como um inteiro não assinado de 16 bits. Para obter mais informações sobre os algoritmos, consulte Referência de algoritmos do SDK de criptografia da AWS.

ID de mensagem

Um valor de 128 bits gerado aleatoriamente que identifica a mensagem. O ID da mensagem:

  • Identifica exclusivamente a mensagem criptografada.

  • Associa levemente o cabeçalho da mensagem ao corpo da mensagem.

  • Fornece um mecanismo para reutilizar uma chave de dados com segurança com várias mensagens criptografadas.

  • Protege contra a reutilização acidental de uma chave de dados ou contra o desgaste de chaves no SDK de criptografia da AWS.

Tamanho do AAD

O tamanho dos dados autenticados adicionais (AAD). É um valor de 2 bytes interpretado como um número inteiro não assinado de 16 bits que especifica o número de bytes que contém o AAD.

Quando o contexto de criptografia está vazio, o tamanho do AAD é 0.

AAD

Os dados autenticados adicionais. O AAD é uma codificação do contexto de criptografia, uma matriz de pares de chave-valor onde cada chave e o valor é uma string de caracteres codificados em UTF-8. O contexto de criptografia é convertido em uma sequência de bytes e usado para o valor do AAD. Quando o contexto de criptografia está vazio, não há um campo AAD no cabeçalho.

Quando o algoritmos com assinatura são utilizados, o contexto de encriptação deve conter o par de valor-chave {'aws-crypto-public-key', Qtxt}. O Qtxt representa o ponto de curva elíptica Q comprimido de acordo com SEC 1 versão 2.0 e depois a base64. O contexto de criptografia pode conter valores adicionais, mas o tamanho máximo do construído AAD é 2^16 - 1 bytes.

A tabela a seguir descreve os campos que formam o AAD. Os pares de chave-valor são classificados, por chave, em ordem crescente de acordo com o código de caracteres UTF-8. Os bytes são anexados na ordem mostrada.

Estrutura do AAD
Campo Tamanho (bytes)
Contagem de pares de chave-valor 2.
Comprimento da chave 2
Chave Variável Igual ao valor especificado nos 2 bytes anteriores (tamanho da chave).
Tamanho do valor 2.
Valor Variável Igual ao valor especificado nos 2 bytes anteriores (tamanho do valor).
Contagem de pares de chave-valor

O número de pares chave-valor no AAD. É um valor de 2 bytes interpretado como um número inteiro não assinado de 16 bits que especifica o número de pares de chave-valor no AAD. O número máximo de pares chave-valor no AAD é 2^16 - 1.

Quando não houver um contexto de criptografia ou o contexto de criptografia estiver vazio, esse campo não estará presente na estrutura do AAD.

Comprimento da chave

O tamanho da chave do par de chave-valor. É um valor de 2 bytes interpretado como um número inteiro não assinado de 16 bits que especifica o número de bytes que contém a chave.

Chave

A chave do par de chave-valor. É uma sequência de bytes codificados em UTF-8.

Tamanho do valor

O tamanho do valor do par de chave-valor. É um valor de 2 bytes interpretado como um número inteiro não assinado de 16 bits que especifica o número de bytes que contém o valor.

Valor

O valor do par de chave-valor. É uma sequência de bytes codificados em UTF-8.

Contagem de chaves de dados criptografadas

O número de chaves de dados criptografadas. É um valor de 2 bytes interpretado como um número inteiro não assinado de 16 bits que especifica o número de chaves de dados criptografadas.

Chaves de dados criptografadas

Uma sequência de chaves de dados criptografadas. O tamanho da sequência é determinado pelo número de chaves de dados criptografadas e pelo tamanho de cada uma delas. A sequência contém pelo menos uma chave de dados criptografada.

A tabela a seguir descreve os campos que formam cada chave de dados criptografada. Os bytes são anexados na ordem mostrada.

Estrutura da chave de dados criptografada
Campo Tamanho, em bytes
Tamanho do ID do provedor de chave 2.
ID do provedor de chave Variável Igual ao valor especificado nos 2 bytes anteriores (tamanho do ID do provedor de chave).
Tamanho das informações do provedor de chave 2.
Informações do provedor de chave Variável Igual ao valor especificado nos 2 bytes anteriores (tamanho das informações do provedor de chave).
Tamanho da chave de dados criptografada 2.
Chave de dados criptografada Variável Igual ao valor especificado nos 2 bytes anteriores (tamanho da chave de dados criptografada).
Tamanho do ID do provedor de chave

O tamanho do identificador do provedor de chave. É um valor de 2 bytes interpretado como um número inteiro não assinado de 16 bits que especifica o número de bytes que contém o ID do provedor de chave.

ID do provedor de chave

O identificador do provedor de chave. É usado para indicar o provedor da chave de dados criptografada e deve ser extensível.

Tamanho das informações do provedor de chave

O tamanho das informações do provedor de chave. É um valor de 2 bytes interpretado como um número inteiro não assinado de 16 bits que especifica o número de bytes que contém as informações do provedor de chave.

Informações do provedor de chave

As informações do provedor de chave. São determinadas pelo provedor de chaves.

Quando o AWS KMS é o provedor de chaves mestras ou você está usando um Token de autenticação do AWS KMS, esse valor contém o nome de recurso da Amazon (ARN) da Chave mestra do cliente (CMK) do AWS KMS.

Tamanho da chave de dados criptografada

O tamanho da chave de dados criptografada. É um valor de 2 bytes interpretado como um número inteiro não assinado de 16 bits que especifica o número de bytes que contém a chave de dados criptografada.

Chave de dados criptografada

A chave de dados criptografada. É a chave de criptografia dos dados criptografada pelo provedor de chaves.

Content-Type

O tipo de dados encriptados, não emoldurados ou emoldurados.

nota

Sempre que possível, use dados com moldura. O SDK de criptografia da AWS oferece suporte a dados sem moldura apenas para uso herdado. Algumas implementações de linguagem do SDK de criptografia da AWS ainda podem gerar texto cifrado sem moldura. Todas as implementações de linguagem com suporte podem descriptografar texto cifrado com moldura e sem moldura.

Os dados emoldurados são divididos em partes iguais; cada parte é encriptada separadamente. O conteúdo com moldura é do tipo 2, codificado como o byte 02 em notação hexadecimal.

Os dados não processados não estão divididos; é um blobo encriptado único. O conteúdo sem moldura é do tipo 1, codificado como o byte 01 em notação hexadecimal.

Reservado

Uma sequência reservada de 4 bytes. Esse valor deve ser 0. Ele é codificado como os bytes 00 00 00 00 em notação hexadecimal (ou seja, uma sequência de 4 bytes de um valor inteiro de 32 bits igual a 0).

Tamanho do IV

O tamanho do IV (initialization vector - vetor de inicialização). É um valor de 1 byte interpretado como um número inteiro não assinado de 8 bits que especifica o número de bytes que contém o IV. Esse valor é determinado pelo valor de bytes do IV do algoritmo que gerou a mensagem.

Tamanho da moldura

O comprimento de cada fotograma de dados emoldurados. É um valor de 4 bytes interpretado como um número inteiro não assinado de 32 bits que especifica o número de bytes em cada fotograma. Quando os dados não são moldados, ou seja, quando o valor do Content Type campo é 1, este valor tem de ser 0.

nota

Sempre que possível, use dados com moldura. O SDK de criptografia da AWS oferece suporte a dados sem moldura apenas para uso herdado. Algumas implementações de linguagem do SDK de criptografia da AWS ainda podem gerar texto cifrado sem moldura. Todas as implementações de linguagem com suporte podem descriptografar texto cifrado com moldura e sem moldura.

Autenticação do cabeçalho

A autenticação do cabeçalho é determinada pelo algoritmo que gerou a mensagem. A autenticação do cabeçalho é calculada sobre o cabeçalho inteiro. Consiste em um IV e uma tag de autenticação. Os bytes são anexados na ordem mostrada.

Estrutura da autenticação do cabeçalho
Campo Tamanho, em bytes
IV Variável Determinada pelo valor de bytes do IV do algoritmo que gerou a mensagem.
Tag de autenticação Variável Determinada pelo valor dos bytes da tag de autenticação do algoritmo que gerou a mensagem.
IV

O vetor de inicialização (IV) usado para calcular a tag de autenticação do cabeçalho.

Tag de autenticação

O valor da autenticação do cabeçalho. É usado para autenticar todo o conteúdo do cabeçalho.

Estrutura do corpo

O corpo da mensagem contém os dados criptografados, chamados de texto cifrado. A estrutura do corpo depende do tipo de conteúdo (sem moldura ou com moldura). As seções a seguir descrevem o formato do corpo da mensagem para cada tipo de conteúdo.

Dados sem moldura

Os dados sem moldura são criptografados em um único blob com um IV exclusivo e AAD do corpo.

nota

Sempre que possível, use dados com moldura. O SDK de criptografia da AWS oferece suporte a dados sem moldura apenas para uso herdado. Algumas implementações de linguagem do SDK de criptografia da AWS ainda podem gerar texto cifrado sem moldura. Todas as implementações de linguagem com suporte podem descriptografar texto cifrado com moldura e sem moldura.

A tabela a seguir descreve os campos que formam os dados sem moldura. Os bytes são anexados na ordem mostrada.

Estrutura de corpo sem moldura
Campo Tamanho, em bytes
IV Variável Igual ao valor especificado no byte do Tamanho do IV do cabeçalho.
Tamanho do conteúdo criptografado 8.
Conteúdo criptografado Variável Igual ao valor especificado nos 8 bytes anteriores (tamanho do conteúdo criptografado).
Tag de autenticação Variável Determinado pela implementação do algoritmo usado.
IV

O vetor de inicialização (IV) para uso com o algoritmo de criptografia.

Tamanho do conteúdo criptografado

O tamanho do conteúdo criptografado ou do texto cifrado. É um valor de 8 bytes interpretado como um número inteiro não assinado de 64 bits que especifica o número de bytes que contém o conteúdo criptografado.

Tecnicamente, o valor máximo permitido é 2^63 - 1 ou 8 exbibytes (8 EiB). No entanto, na prática, o valor máximo é 2^36 - 32 ou 64 gibibytes (64 GiB), devido às restrições impostas pelos algoritmos implementados.

nota

A implementação Java deste SDK restringe ainda mais esse valor para 2^31 - 1 ou 2 gibibytes (2 GiB), devido às restrições da linguagem.

Conteúdo criptografado

O conteúdo criptografado (texto cifrado) como retornado pelo algoritmo de criptografia.

Tag de autenticação

O valor da autenticação do corpo. É usado para autenticar o corpo da mensagem.

Dados com moldura

Em dados com moldura, os dados de texto simples são divididos em partes iguais chamadas molduras. O SDK de criptografia da AWS criptografa cada moldura separadamente com um IV exclusivo e um AAD do corpo.

nota

Sempre que possível, use dados com moldura. O SDK de criptografia da AWS oferece suporte a dados sem moldura apenas para uso herdado. Algumas implementações de linguagem do SDK de criptografia da AWS ainda podem gerar texto cifrado sem moldura. Todas as implementações de linguagem com suporte podem descriptografar texto cifrado com moldura e sem moldura.

O tamanho da moldura, que é o tamanho do conteúdo criptografado na moldura, pode ser diferente para cada mensagem. O número máximo de bytes em uma moldura é 2^32 - 1. O número máximo de molduras em uma mensagem é 2^32 - 1.

Há dois tipos de moldura: normal e final. Cada mensagem deve consistir ou incluir uma moldura final.

Todas as molduras normais em uma mensagem têm o mesmo tamanho de moldura. A moldura final pode ter um tamanho de moldura diferente.

A composição das molduras em dados com molduras varia de acordo com o tamanho do conteúdo criptografado.

  • Igual ao comprimento da estrutura — Quando o comprimento do conteúdo encriptado é igual ao comprimento do frame das armações normais, a mensagem pode consistir numa estrutura regular que contém os dados, seguida de uma moldura final de zero (0) comprimento. Ou, a mensagem pode consistir apenas em um a moldura que contém os dados. Nesse caso, a moldura final tem o mesmo tamanho de moldura que as molduras normais.

  • Múltiplo do comprimento da estrutura — Quando o comprimento do conteúdo encriptado é um múltiplo exato do comprimento da estrutura das armações normais, a mensagem pode terminar numa estrutura regular que contenha os dados, seguida de uma moldura final de zero (0) comprimento. Ou, a mensagem pode terminar em uma moldura final que contém os dados. Nesse caso, a moldura final tem o mesmo tamanho de moldura que as molduras normais.

  • Não é um múltiplo do comprimento da estrutura — Quando o comprimento do conteúdo encriptado não é um múltiplo exato do comprimento da estrutura dos fotogramas normais, a moldura final contém os restantes dados. O tamanho da moldura final é menor que o tamanho das molduras normais.

  • Inferior ao comprimento da estrutura — Quando o comprimento do conteúdo encriptado é inferior ao comprimento do frame dos fotogramas normais, a mensagem consiste numa moldura final que contém todos os dados. O tamanho da moldura final é menor que o tamanho das molduras normais.

As tabelas a seguir descrevem os campos que formam as molduras. Os bytes são anexados na ordem mostrada.

Estrutura de corpo com moldura, moldura normal
Campo Tamanho, em bytes
Número de sequência 4.
IV Variável Igual ao valor especificado no byte do Tamanho do IV do cabeçalho.
Conteúdo criptografado Variável Igual ao valor especificado no Tamanho da moldura do cabeçalho.
Tag de autenticação Variável Determinada pelo algoritmo usado, conforme especificado no ID do algoritmo do cabeçalho.
Número de sequência

O número sequencial da moldura. É um número do contador incremental da moldura. É um valor de 4 bytes interpretado como um inteiro não assinado de 32 bits.

Os dados com moldura devem começar no número sequencial 1. As molduras subsequentes devem estar em ordem e devem conter um incremento de 1 da moldura anterior. Caso contrário, o processo de descriptografia será interrompido e relatará um erro.

IV

O vetor de inicialização (IV) da moldura. O SDK usa um método determinístico para construir um IV diferente para cada moldura na mensagem. O tamanho é especificado pelo pacote de algoritmos usado.

Conteúdo criptografado

O conteúdo criptografado (texto cifrado) da moldura, conforme retornado pelo algoritmo de criptografia.

Tag de autenticação

O valor da autenticação da moldura. É usado para autenticar a moldura inteira.

Estrutura de corpo com moldura, moldura final
Campo Tamanho, em bytes
Fim dos números sequenciais 4.
Número de sequência 4.
IV Variável Igual ao valor especificado no byte do Tamanho do IV do cabeçalho.
Tamanho do conteúdo criptografado 4.
Conteúdo criptografado Variável Igual ao valor especificado nos 4 bytes anteriores (tamanho do conteúdo criptografado).
Tag de autenticação Variável Determinada pelo algoritmo usado, conforme especificado no ID do algoritmo do cabeçalho.
Fim dos números sequenciais

Um indicador para a moldura final. O valor é codificado como 4 bytes FF FF FF FF em notação hexadecimal.

Número de sequência

O número sequencial da moldura. É um número do contador incremental da moldura. É um valor de 4 bytes interpretado como um inteiro não assinado de 32 bits.

Os dados com moldura devem começar no número sequencial 1. As molduras subsequentes devem estar em ordem e devem conter um incremento de 1 da moldura anterior. Caso contrário, o processo de descriptografia será interrompido e relatará um erro.

IV

O vetor de inicialização (IV) da moldura. O SDK usa um método determinístico para construir um IV diferente para cada moldura na mensagem. O tamanho do IV é especificado pelo pacote de algoritmos.

Tamanho do conteúdo criptografado

O tamanho do conteúdo criptografado. É um valor de 4 bytes interpretado como um número inteiro não assinado de 32 bits que especifica o número de bytes que contém o conteúdo criptografado da moldura.

Conteúdo criptografado

O conteúdo criptografado (texto cifrado) da moldura, conforme retornado pelo algoritmo de criptografia.

Tag de autenticação

O valor da autenticação da moldura. É usado para autenticar a moldura inteira.

Quando os algoritmos com assinatura são usados, o formato da mensagem contém um rodapé. O rodapé da mensagem contém uma assinatura calculada sobre o cabeçalho e o corpo da mensagem. A tabela a seguir descreve os campos que formam o rodapé. Os bytes são anexados na ordem mostrada.

Estrutura do rodapé
Campo Tamanho, em bytes
Tamanho da assinatura 2.
Assinatura Variável Igual ao valor especificado nos 2 bytes anteriores (tamanho da assinatura).
Tamanho da assinatura

O tamanho da assinatura. É um valor de 2 bytes interpretado como um número inteiro não assinado de 16 bits que especifica o número de bytes que contém a assinatura.

Assinatura

A assinatura. É usada para autenticar o cabeçalho e o corpo da mensagem.