Funções de criptografia AEAD no SQL padrão

Nas seções a seguir, descreveremos as funções de criptografia AEAD compatíveis com o BigQuery. Para uma descrição dessas funções, consulte Conceitos de criptografia AEAD.

KEYS.NEW_KEYSET

KEYS.NEW_KEYSET(key_type)

Descrição

Retorna um conjunto de chaves serializado contendo uma nova chave com base em key_type. O conjunto de chaves retornado é uma representação BYTES serializada de google.crypto.tink.Keyset , que contém uma chave de criptografia principal e nenhuma outra chave. É possível usar o conjunto de chaves com as funções AEAD.ENCRYPT, AEAD.DECRYPT_BYTES e AEAD.DECRYPT_STRING para criptografia e descriptografia, bem como com o grupo KEYS de funções relacionadas à chave e ao conjunto de chaves.

key_type é uma representação literal de STRING do tipo de chave a ser criado. key_type não pode ser NULL. O único valor aceito para key_type é AEAD_AES_GCM_256. KEYS.NEW_KEYSET(AEAD_AES_GCM_256) cria uma chave de 256 bits com o gerador de números pseudo-aleatórios fornecido pelo OpenSSL. A chave usará o AES-GCM para operações de criptografia e descriptografia.

Tipo de dados retornados

BYTES

Exemplo

A consulta a seguir cria um conjunto de chaves para cada linha em CustomerIds, que pode ser usado posteriormente para criptografar dados. Cada conjunto de chaves contém uma única chave de criptografia com dados de chave gerados aleatoriamente. Cada linha na saída contém um customer_id e uma chave 'AEAD_AES_GCM_256' em BYTES.

SELECT customer_id, KEYS.NEW_KEYSET('AEAD_AES_GCM_256') AS keyset
FROM (
  SELECT 1 AS customer_id UNION ALL
  SELECT 2 UNION ALL
  SELECT 3
) AS CustomerIds;

KEYS.ADD_KEY_FROM_RAW_BYTES

KEYS.ADD_KEY_FROM_RAW_BYTES(keyset, key_type, raw_key_bytes)

Descrição

Retorna um conjunto de chaves serializado como BYTES com a adição de uma chave ao keyset com base em key_type e raw_key_bytes.

A chave de criptografia principal permanece igual à de keyset. O comprimento esperado de raw_key_bytes depende do valor de key_type. Os key_types a seguir são aceitos:

  • 'AES_CBC_PKCS': cria uma chave para descriptografia AES usando encadeamento de blocos de criptografia e padding PKCS. raw_key_bytes precisa ser um valor BYTES de chave bruta com comprimento de 16, 24 ou 32. Esses comprimentos têm tamanhos de 128, 192 e 256 bits, respectivamente. As funções AEAD do BigQuery não aceitam chaves desse tipo para criptografia. Em vez disso, prefira chaves 'AEAD_AES_GCM_256' ou 'AES_GCM'.

  • 'AES_GCM': cria uma chave para descriptografia ou criptografia AES usando o modo GCM (Galois/Counter Mode). raw_key_bytes precisa ser um valor BYTES de chave bruta com comprimento de 16 ou 32. Esses comprimentos têm tamanhos de 128 e 256 bits, respectivamente. Quando chaves desse tipo são inseridas em AEAD.ENCRYPT, o texto criptografado de saída não tem um prefixo específico de Tink indicando que chave foi usada como entrada.

Tipo de dados retornados

BYTES

Exemplo

A consulta a seguir cria uma tabela de IDs de cliente com bytes de chave bruta, chamada CustomerRawKeys, e uma tabela de códigos exclusivos, chamada CustomerIds. Ela cria um novo conjunto de chaves 'AEAD_AES_GCM_256' para cada customer_id. Em seguida, adiciona uma nova chave a cada conjunto, usando o valor raw_key_bytes correspondente a esse customer_id . A saída é uma tabela em que cada linha contém um customer_id e um conjunto de chaves em BYTES, que contém a chave bruta adicionada com KEYS.ADD_KEY_FROM_RAW_BYTES.

WITH CustomerRawKeys AS (
  SELECT 1 AS customer_id, b'0123456789012345' AS raw_key_bytes UNION ALL
  SELECT 2, b'9876543210543210' UNION ALL
  SELECT 3, b'0123012301230123'
), CustomerIds AS (
  SELECT 1 AS customer_id UNION ALL
  SELECT 2 UNION ALL
  SELECT 3
)
SELECT
  ci.customer_id,
  KEYS.ADD_KEY_FROM_RAW_BYTES(
    KEYS.NEW_KEYSET('AEAD_AES_GCM_256'),
    'AES_CBC_PKCS',
    (SELECT raw_key_bytes FROM CustomerRawKeys AS crk
     WHERE crk.customer_id = ci.customer_id)
  ) AS keyset
FROM CustomerIds AS ci;

Cada conjunto de chaves de saída contém dois itens: a chave de criptografia principal criada usando KEYS.NEW_KEYSET('AEAD_AES_GCM_256') e a chave bruta adicionada usando KEYS.ADD_KEY_FROM_RAW_BYTES. Se um conjunto de chaves na saída for usado com AEAD.ENCRYPT, o BigQuery usará a chave de criptografia principal criada usando KEYS.NEW_KEYSET('AEAD_AES_GCM_256') para criptografar o texto simples de entrada. Se o conjunto de chaves for usado com AEAD.DECRYPT_STRING ou AEAD.DECRYPT_BYTES, o BigQuery retornará o texto simples resultante se uma das chaves conseguir descriptografar o texto.

AEAD.DECRYPT_BYTES

AEAD.DECRYPT_BYTES(keyset, ciphertext, additional_data)

Descrição

Usa a chave correspondente do keyset para descriptografar o ciphertext e verifica a integridade dos dados usando additional_data. Retornará um erro se a descriptografia ou a verificação falhar.

keyset é um valor de BYTES serializado retornado por uma das funções KEYS. keyset precisa conter a chave que foi usada para criptografar o ciphertext, e a chave precisa estar em um estado 'ENABLED', caso contrário, a função retornará um erro. AEAD.DECRYPT_BYTES identifica a chave correspondente no keyset localizando a chave com o código que corresponde àquela criptografada no ciphertext.

ciphertext é um valor de BYTES que resulta de uma chamada para AEAD.ENCRYPT em que a entrada plaintext era do tipo BYTES.

additional_data é um valor de STRING ou BYTES que garante a autenticidade e a integridade dos dados criptografados. Essa função transmite qualquer valor STRING para BYTES. Ela precisa ser igual a additional_data fornecido ao AEAD.ENCRYPT para criptografar o ciphertext, ignorando o tipo. Do contrário, a função retornará um erro.

Tipo de dados retornados

BYTES

Exemplo

Neste exemplo, será criada uma tabela de códigos exclusivos com valores de texto simples e conjuntos de chaves associados. Em seguida, esses conjuntos de chaves serão usados para criptografar os valores de texto simples como BYTES e armazená-los em uma nova tabela. Por fim, AEAD.DECRYPT_BYTES será usado para descriptografar os valores criptografados e exibi-los como texto simples.

A instrução a seguir cria uma tabela CustomerKeysets contendo uma coluna de códigos exclusivos, outra de conjuntos de dados AEAD_AES_GCM_256 e uma terceira de animais favoritos.

CREATE TABLE aead.CustomerKeysets AS
SELECT
  1 AS customer_id,
  KEYS.NEW_KEYSET('AEAD_AES_GCM_256') AS keyset,
  'jaguar' AS favorite_animal
UNION ALL
SELECT
  2 AS customer_id,
  KEYS.NEW_KEYSET('AEAD_AES_GCM_256') AS keyset,
  'zebra' AS favorite_animal
UNION ALL
SELECT
  3 AS customer_id,
  KEYS.NEW_KEYSET('AEAD_AES_GCM_256') AS keyset,
  'nautilus' AS favorite_animal;

A instrução a seguir cria uma tabela EncryptedCustomerData contendo uma coluna de códigos exclusivos e outra de texto criptografado. A instrução criptografa o texto simples favorite_animal usando o valor de conjunto de chaves de CustomerKeysets correspondente a cada código exclusivo.

CREATE TABLE aead.EncryptedCustomerData AS
SELECT
  customer_id,
  AEAD.ENCRYPT(keyset, favorite_animal, CAST(customer_id AS STRING))
   AS encrypted_animal
FROM
  aead.CustomerKeysets AS ck;

A consulta a seguir usa os conjuntos de chaves na tabela CustomerKeysets para descriptografar dados na tabela EncryptedCustomerData.

SELECT
  ecd.customer_id,
  AEAD.DECRYPT_STRING(
    (SELECT ck.keyset
     FROM aead.CustomerKeysets AS ck
     WHERE ecd.customer_id = ck.customer_id),
    ecd.encrypted_animal,
    CAST(ecd.customer_id AS STRING)
  ) AS favorite_animal
FROM aead.EncryptedCustomerData AS ecd;

AEAD.DECRYPT_STRING

AEAD.DECRYPT_STRING(keyset, ciphertext, additional_data)

Descrição

Igual a AEAD.DECRYPT_BYTES, mas ciphertext é a saída BYTES de AEAD.ENCRYPT em que a entrada de plaintext para AEAD.ENCRYPT é do tipo STRING, não do tipo BYTES.

Tipo de dados retornados

STRING

AEAD.ENCRYPT

AEAD.ENCRYPT(keyset, plaintext, additional_data)

Descrição

Criptografa texto simples usando o algoritmo e a chave de criptografia principal no keyset. Incorpora additional_data ao texto criptografado retornado. Retorna NULL se alguma entrada for NULL.

keyset é um valor de BYTES serializado retornado por uma das funções KEYS.

plaintext é o valor de STRING ou BYTES a ser criptografado.

additional_data é um valor STRING ou BYTES a ser incorporado ao texto criptografado retornado. plaintext e additional_data precisam ser do mesmo tipo. AEAD.ENCRYPT(keyset, string1, string2) é equivalente a AEAD.ENCRYPT(keyset, CAST(string1 AS BYTES), CAST(string2 AS BYTES)).

A saída é o texto criptografado BYTES. Esse texto conterá um prefixo específico de Tink, indicando a chave usada para executar a criptografia, exceto quando essa chave for 'AES_GCM'.

Tipo de dados retornados

BYTES

Exemplo

A consulta a seguir usa os conjuntos de chaves de cada customer_id na tabela CustomerKeysets para criptografar o valor do texto simples favorite_animal na tabela PlaintextCustomerData correspondente ao customer_id. A saída contém uma coluna de valores customer_id e outra de saída de texto criptografado correspondente como BYTES.

WITH CustomerKeysets AS (
  SELECT 1 AS customer_id, KEYS.NEW_KEYSET('AEAD_AES_GCM_256') AS keyset UNION ALL
  SELECT 2, KEYS.NEW_KEYSET('AEAD_AES_GCM_256') UNION ALL
  SELECT 3, KEYS.NEW_KEYSET('AEAD_AES_GCM_256')
), PlaintextCustomerData AS (
  SELECT 1 AS customer_id, 'elephant' AS favorite_animal UNION ALL
  SELECT 2, 'walrus' UNION ALL
  SELECT 3, 'leopard'
)
SELECT
  pcd.customer_id,
  AEAD.ENCRYPT(
    (SELECT keyset
     FROM CustomerKeysets AS ck
     WHERE ck.customer_id = pcd.customer_id),
    pcd.favorite_animal,
    CAST(pcd.customer_id AS STRING)
  ) AS encrypted_animal
FROM PlaintextCustomerData AS pcd;

KEYS.KEYSET_FROM_JSON

KEYS.KEYSET_FROM_JSON(json_keyset)

Descrição

Retorna a json_keyset STRING como BYTES serializados, que é uma entrada válida para outras funções KEYS e AEAD. A STRING JSON precisa ser compatível com a definição da mensagem do buffer de protocolo google.crypto.tink.Keyset: o conjunto de chaves JSON precisa ser um objeto JSON contendo objetos e pares de nome-valor correspondentes àqueles na mensagem "keyset" na definição google.crypto.tink.Keyset. É possível converter a representação BYTES serializada de saída de volta a uma STRING JSON usando KEYS.KEYSET_TO_JSON.

Tipo de dados retornados

BYTES

Exemplo

KEYS.KEYSET_FROM_JSON aceita valores STRING formatados em JSON como estes:

{
  "key":[
      {
        "keyData":{
          "keyMaterialType":"SYMMETRIC",
          "typeUrl":"type.googleapis.com/google.crypto.tink.AesGcmKey",
          "value":"GiD80Z8kL6AP3iSNHhqseZGAIvq7TVQzClT7FQy8YwK3OQ=="
        },
        "keyId":3101427138,
        "outputPrefixType":"TINK",
        "status":"ENABLED"
      }
    ],
  "primaryKeyId":3101427138
}

A consulta a seguir cria um novo conjunto de chaves com base em um STRING json_keyset formatado em JSON.

SELECT KEYS.KEYSET_FROM_JSON(json_keyset);

O json_keyset serializado é retornado como BYTES, conforme mostrado abaixo:

\x08\x9d\x8e\x85\x82\x09\x12d\x0aX\x0a0
type.googleapis.com/google.crypto.tink.AesGcmKey\x12\"\x1a qX\xe4IG\x87\x1f\xde
\xe3)+e\x98\x0a\x1c}\xfe\x88<\x12\xeb\xc1t\xb8\x83\x1a\xcd\xa8\x97\x84g\x18\x01
\x10\x01\x18\x9d\x8e\x85\x82\x09 \x01

KEYS.KEYSET_TO_JSON

KEYS.KEYSET_TO_JSON(keyset)

Descrição

Retorna uma representação de STRING JSON do keyset de entrada. A STRING JSON retornada é compatível com a definição da mensagem do buffer de protocolo google.crypto.tink.Keyset. É possível converter a representação de STRING JSON de volta a BYTES usando KEYS.KEYSET_FROM_JSON.

Tipo de dados retornados

STRING

Exemplo

A consulta a seguir retorna um novo conjunto de chaves 'AEAD_AES_GCM_256' como uma STRING formatada em JSON.

SELECT KEYS.KEYSET_TO_JSON(KEYS.NEW_KEYSET('AEAD_AES_GCM_256'));

O resultado é uma STRING como esta:

{
  "key":[
      {
        "keyData":{
          "keyMaterialType":"SYMMETRIC",
          "typeUrl":"type.googleapis.com/google.crypto.tink.AesGcmKey",
          "value":"GiD80Z8kL6AP3iSNHhqseZGAIvq7TVQzClT7FQy8YwK3OQ=="
        },
        "keyId":3101427138,
        "outputPrefixType":"TINK",
        "status":"ENABLED"
      }
    ],
  "primaryKeyId":3101427138
}

KEYS.ROTATE_KEYSET

KEYS.ROTATE_KEYSET(keyset, key_type)

Descrição

Adiciona uma nova chave ao keyset com base no key_type. Ela se torna a chave de criptografia principal do novo conjunto de chaves. Retorna o novo conjunto de chaves serializado como BYTES.

A chave de criptografia principal anterior do keyset de entrada permanece como outra chave no conjunto de chaves retornado.

Tipo de dados retornados

BYTES

Exemplo

A instrução a seguir cria uma tabela contendo uma coluna de valores customer_id exclusivos e conjuntos de chaves 'AEAD_AES_GCM_256'. Em seguida, ela cria uma nova chave de criptografia principal dentro de cada conjunto de chaves na tabela de origem usando KEYS.ROTATE_KEYSET. Cada linha na saída contém um customer_id e um conjunto de chaves 'AEAD_AES_GCM_256' em BYTES.

WITH ExistingKeysets AS (
SELECT 1 AS customer_id, KEYS.NEW_KEYSET('AEAD_AES_GCM_256') AS keyset
    UNION ALL
  SELECT 2, KEYS.NEW_KEYSET('AEAD_AES_GCM_256') UNION ALL
  SELECT 3, KEYS.NEW_KEYSET('AEAD_AES_GCM_256')
)
SELECT customer_id, KEYS.ROTATE_KEYSET(keyset, 'AEAD_AES_GCM_256') AS keyset
FROM ExistingKeysets;
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.