Referência do formato de mensagens do AWS Encryption SDK

As informações nesta página são uma referência para criar sua própria biblioteca de criptografia compatível com o AWS Encryption SDK. Se você não estiver criando sua própria biblioteca de criptografia compatível, provavelmente não precisará dessas informações. Para usar o AWS Encryption SDK em uma das linguagens de programação compatíveis, consulte Linguagens de programação. Para a especificação que define os elementos de uma AWS Encryption SDK implementação adequada, consulte a AWS Encryption SDKEspecificação em GitHub.

As operações de criptografia no AWS Encryption SDK retornam uma única estrutura de dados ou mensagem criptografada 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).

Os pacotes de algoritmos suportados pelo AWS Encryption SDK usam uma das duas versões de formato de mensagem. Os pacotes de algoritmos sem confirmação de chave usam formato de mensagem versão 1. Os pacotes de algoritmos com confirmação de chave usam formato de mensagem versão 2.

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 nas versões 1 e 2 do formato de mensagem. Os bytes são anexados na ordem mostrada.

O valor Não presente indica que o campo não existe nessa versão do formato de mensagem. O texto em negrito indica valores que são diferentes em cada versão.

nota

Talvez seja necessário rolar horizontalmente ou verticalmente para ver todos os dados nessa tabela.

Estrutura do cabeçalho
Campo	Formato da mensagem versão 1 Tamanho (bytes)	Formato da mensagem versão 2 Tamanho (bytes)
Versão	1	1
Tipo	1	Não está presente
ID do algoritmo	2	2
ID de mensagem	16	32
Tamanho do AAD	2 Quando o contexto de criptografia está vazio, o valor do tamanho do AAD de 2 bytes é 0.	2 Quando o contexto de criptografia está vazio, o valor do tamanho do AAD de 2 bytes é 0.
AAD	Variável. O tamanho desse campo aparece nos 2 bytes anteriores (campo Tamanho do AAD). Quando o contexto de criptografia está vazio, não há um campo AAD no cabeçalho.	Variável. O tamanho desse campo aparece nos 2 bytes anteriores (campo 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	2
Chaves de dados criptografadas	Variável. Determinado pelo número de chaves de dados criptografadas e pelo tamanho de cada uma delas.	Variável. Determinado pelo número de chaves de dados criptografadas e pelo tamanho de cada uma delas.
Tipo de conteúdo	1	1
Reservado	4	Não está presente
Tamanho do IV	1	Não está presente
Tamanho da moldura	4	4
Dados do pacote de algoritmos	Não está presente	Variável. Determinado pelo algoritmo que gerou a mensagem.
Autenticação do cabeçalho	Variável. Determinado pelo algoritmo que gerou a mensagem.	Variável. Determinado pelo algoritmo que gerou a mensagem.

Versão

A versão do formato desta mensagem. A versão é 1 ou 2 codificado como o byte 01 ou 02 em notação hexadecimal

Tipo

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.

Esse campo não está presente na versão 2 do formato de mensagem.

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 AWS Encryption SDK.

ID de mensagem

Um valor 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 AWS Encryption SDK.

Esse valor é de 128 bits no formato de mensagem versão 1 e 256 bits na versão 2.

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 valor do campo de 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 os algoritmos com assinatura são usados, o contexto de criptografia deve conter o par de chave-valor {'aws-crypto-public-key', Qtxt}. Qtxt representa o ponto Q compactado da curva elíptica de acordo com o SEC 1 versão 2.0 e, em seguida, codificado em 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. O número máximo de chaves de dados criptografadas em cada registro é 65.535 (2^16 - 1).

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 (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 AWS KMS, esse valor contém o nome do atributo da Amazon (ARN) da AWS KMS key.

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.

Tipo de conteúdo

O tipo de conteúdo criptografado, com moldura ou sem moldura.

nota

Sempre que possível, use dados com moldura. O AWS Encryption SDK oferece suporte dados não emoldurados somente para uso herdado. Algumas implementações de linguagem do AWS Encryption SDK ainda podem gerar texto cifrado sem moldura. Todas as implementações de linguagem compatíveis podem descriptografar texto cifrado e não emoldurado.

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

Os dados não emoldurados não são divididos; são um único blob criptografado. 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).

Esse campo não está presente na versão 2 do formato de mensagem.

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.

Este campo não está presente no formato de mensagem versão 2, que somente é compatível com pacotes de algoritmos que usam valores IV determinísticos no cabeçalho da mensagem.

Tamanho da moldura

O tamanho de cada moldura do dado com moldura. É 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 forma cada estrutura. Quando o dado não for com moldura, isto é, quando o valor do campo do Content Type campo for 1, esse valor deve ser 0.

nota

Sempre que possível, use dados com moldura. O AWS Encryption SDK oferece suporte dados não emoldurados somente para uso herdado. Algumas implementações de linguagem do AWS Encryption SDK ainda podem gerar texto cifrado sem moldura. Todas as implementações de linguagem compatíveis podem descriptografar texto cifrado e não emoldurado.

Dados do pacote de algoritmos

Dados suplementares necessários pelo algoritmo que gerou a mensagem. O tamanho e o conteúdo são determinados pelo algoritmo. Seu tamanho pode ser 0.

Este campo não está presente na versão 1 do formato de mensagem.

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 na versão 1.0 (bytes)	Tamanho na versão 2.0 (bytes)
IV	Variável. Determinada pelo valor de bytes do IV do algoritmo que gerou a mensagem.	N/D
Tag de autenticação	Variável. Determinada pelo valor dos bytes da tag de autenticação do algoritmo que gerou a mensagem.	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.

Este campo não está presente na versão 2 do formato de mensagem. Este campo não está presente na versão 2 do formato de mensagem, que somente é compatível com pacotes de algoritmos que usam valores IV determinísticos no cabeçalho da mensagem.

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. A estrutura do corpo da mensagem é a mesma nas versões 1 e 2 do formato de mensagem.

Tópicos

• Dados sem moldura
• Dados com moldura

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 AWS Encryption SDK oferece suporte dados não emoldurados somente para uso herdado. Algumas implementações de linguagem do AWS Encryption SDK ainda podem gerar texto cifrado sem moldura. Todas as implementações de linguagem compatíveis podem descriptografar texto cifrado e não emoldurado.

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 AWS Encryption SDK criptografa cada moldura separadamente com um IV exclusivo e um AAD do corpo.

nota

Sempre que possível, use dados com moldura. O AWS Encryption SDK oferece suporte dados não emoldurados somente para uso herdado. Algumas implementações de linguagem do AWS Encryption SDK ainda podem gerar texto cifrado sem moldura. Todas as implementações de linguagem compatíveis podem descriptografar texto cifrado e não emoldurado.

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 tamanho do quadro: quando o tamanho do conteúdo criptografado é igual ao tamanho do quadro das molduras regulares, a mensagem pode consistir em um quadro normal que contém os dados, seguido por um quadro final de tamanho zero (0). 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 tamanho do quadro: quando o tamanho do conteúdo criptografado é um múltiplo exato do tamanho do quadro das molduras regulares, a mensagem pode terminar em um quadro regular que contém os dados, seguido por um quadro final de tamanho zero (0). 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 é múltiplo do tamanho do quadro: quando o tamanho do conteúdo criptografado não é um múltiplo exato do comprimento do quadro das molduras regulares, o quadro final contém os dados restantes. O tamanho da moldura final é menor que o tamanho das molduras normais.

• Menor que o tamanho do quadro: quando o tamanho do conteúdo criptografado é menor que o tamanho do quadro das molduras regulares, a mensagem consiste em um quadro 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.

Estrutura do rodapé

Quando os algoritmos com assinatura são usados, o formato da mensagem contém um rodapé. O rodapé da mensagem contém uma assinatura digital 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. A estrutura do rodapé da mensagem é a mesma nas versões 1 e 2 do formato de mensagem.

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.