Skip to main content

​
Criptografia de envelope

Operações criptográficas são apenas API. Criptografar, descriptografar, gerar chave de dados, assinar e verificar não têm controles de console. O console cria chaves, as inspeciona e as desliga; as operações que usam uma chave são executadas a partir de sua aplicação, ao lado do texto sem formatação no qual elas atuam.
POST /v1/keys/{key_id}/encrypt envia seu texto simples para o KMS e recebe o texto cifrado de volta. Isso é bom para algo pequeno e raro — um valor de configuração, um token de API. É a forma errada para qualquer outra coisa, porque cada byte atravessa a rede duas vezes e cada operação custa uma viagem de ida e volta. A alternativa é uma chave de dados: o KMS cria uma chave aleatória nova, entrega duas cópias dela e nunca a armazena.
Você criptografa seus dados localmente com plaintext, então joga plaintext fora e armazena ciphertext ao lado dos dados que ele protege. Para ler os dados de volta, envie ciphertext para POST /v1/keys/{key_id}/decrypt e você terá a chave de dados novamente. Seus dados em massa nunca saem do processo, uma chamada KMS cobre um lote inteiro e a chave KMS permanece uma chave de criptografia de chave — a única coisa que ela envolve são outras chaves.
Nunca persistir a chave de dados plaintext. Armazená-lo ao lado de ciphertext derrota todo o arranjo: qualquer um que alcance seu armazenamento terá tanto o bloqueio quanto a chave, e revogar a chave KMS não protege mais nada.
number_of_bytes aceita 16, 32 ou 64 e nada mais — 16 para AES-128, 32 para AES-256 (o padrão), 64 para HMAC-SHA512. Qualquer outro valor falha.

​
Quando a criptografia direta se esgota

Uma chave RSA não pode criptografar mais do que algumas centenas de bytes. RSA-OAEP só pode carregar uma mensagem menor que o módulo: com SHA-256 que é k - 2·32 - 2 bytes, então 190 bytes para rsa-2048 e 446 bytes para rsa-4096 (RFC 8017 §7.1.1). Não há fragmentação por trás da API. Além desse tamanho, a operação falha e uma chave de dados é a única rota.
Uma chave simétrica não tem um limite algorítmico comparável, mas o corpo da solicitação ainda tem que caber em uma chamada HTTP e você ainda paga uma viagem de ida e volta por operação. Trate a criptografia direta como uma conveniência para valores pequenos e infrequentes, e procure uma chave de dados para tudo o mais.

​
Contexto de criptografia

aad é opcional, dados autenticados adicionais. Ele está ligado à tag AES-GCM, então um texto cifrado só será aberto se o mesmo contexto for apresentado novamente - útil para fixar um blob à coisa a que pertence, então um texto cifrado roubado não pode ser reproduzido contra um registro diferente.
O contexto deve corresponder ao decrypt exatamente, incluindo sua ausência. Fornecer aad para descriptografar um texto cifrado que foi selado sem um é recusado em vez de ignorado — um contexto que é apenas às vezes verificado não é uma verificação. Criptografar sem aad e descriptografar com ele falha com 400 INVALID_INPUT.
Somente uma chave simétrica pode vincular um contexto. Enviar aad para criptografar sob uma chave RSA é recusado com 400 KMS_INVALID_KEY_SPEC — RSA-OAEP não tem onde carregar uma, então aceitá-la deixaria cair a ligação enquanto você continuava tratando-a como uma verificação de integridade. A recusa acontece no selo, onde você ainda pode escolher uma chave diferente.