Fonctions de chiffrement AEAD en langage SQL standard

Les sections suivantes décrivent les fonctions de chiffrement AEAD compatibles avec BigQuery. Pour savoir comment fonctionne le chiffrement AEAD, consultez la page Concepts de chiffrement AEAD.

KEYS.NEW_KEYSET

KEYS.NEW_KEYSET(key_type)

Description

Renvoie une collection de clés sérialisée contenant une nouvelle clé basée sur key_type. La collection de clés renvoyée est une représentation BYTES sérialisée de google.crypto.tink.Keyset contenant une clé cryptographique principale et aucune clé supplémentaire. La collection de clés peut être utilisée avec les fonctions AEAD.ENCRYPT, AEAD.DECRYPT_BYTES et AEAD.DECRYPT_STRING pour les opérations de chiffrement et de déchiffrement, ainsi qu'avec le groupe de clés et de fonctions associées à la collection de clés KEYS.

key_type est une représentation littérale de chaîne STRING du type de la clé à créer. La valeur key_type ne peut pas être NULL. La seule valeur actuellement acceptée pour key_type est AEAD_AES_GCM_256. La fonction KEYS.NEW_KEYSET(AEAD_AES_GCM_256) crée une clé de 256 bits avec le générateur de nombres pseudo-aléatoires fourni par OpenSSL. La clé utilise l'algorithme AES-GCM pour les opérations de chiffrement et de déchiffrement.

Types de données renvoyées

BYTES

Exemple

La requête suivante crée une collection de clés pour chaque ligne de valeurs CustomerIds, qui peut ensuite être utilisée pour chiffrer les données. Chaque collection de clés contient une seule clé de chiffrement à partir de données de clé générées aléatoirement. Chaque ligne de résultat contient une valeur customer_id et une clé 'AEAD_AES_GCM_256' en 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)

Description

Renvoie une collection de clés sérialisée représentée en BYTES contenant une clé supplémentaire ajoutée à keyset, basée sur les valeurs key_type et raw_key_bytes.

La clé cryptographique principale reste identique à celle de keyset. La longueur attendue de la chaîne raw_key_bytes dépend de la valeur de key_type. Les key_types acceptés sont les suivants :

  • 'AES_CBC_PKCS' : crée une clé de déchiffrement AES en mode CBC (chiffrement par chaînage de blocs) et remplissage selon la norme PKCS (Public-Key Cryptography Standards). La clé raw_key_bytes obtenue doit être une chaîne de valeurs brutes de 16, 24 ou 32 BYTES, respectivement de 128, 192 et 256 bits. Les fonctions AED de BigQuery ne sont pas compatibles avec les clés de ce type pour les opérations de chiffrement. Utilisez à la place les clés 'AEAD_AES_GCM_256' ou 'AES_GCM'.

  • 'AES_GCM' : crée une clé de déchiffrement ou de chiffrement AES en mode GCM (Galois/Counter Mode). La clé raw_key_bytes doit être une chaîne de valeurs brutes de 16 ou 32 BYTES, respectivement de 128 et 256 bits. Lors de la saisie de clés de ce type dans AEAD.ENCRYPT, le texte chiffré en sortie ne comporte pas de préfixe Tink spécifique indiquant la clé qui a été utilisée en entrée.

Types de données renvoyées

BYTES

Exemple

La requête suivante crée une table d'ID clients ainsi que des octets de clés brutes, nommée CustomerRawKeys, ainsi qu'une table d'ID uniques, nommée CustomerIds. Une collection de clés 'AEAD_AES_GCM_256' est créée pour chaque customer_id, puis une nouvelle clé est ajoutée à chaque collection, en utilisant la valeur raw_key_bytes correspondant à ce customer_id. La sortie affiche une table où chaque ligne contient un customer_id et une collection de clés en BYTES, qui contient la clé brute ajoutée à l'aide de la fonction 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;

Les collections de clés en sortie contiennent chacune deux éléments : la clé cryptographique principale créée à l'aide de KEYS.NEW_KEYSET('AEAD_AES_GCM_256'), et la clé brute ajoutée à l'aide de KEYS.ADD_KEY_FROM_RAW_BYTES. Si une collection de clés en sortie est utilisée avec AEAD.ENCRYPT, BigQuery applique la clé cryptographique principale créée à l'aide de la fonction KEYS.NEW_KEYSET('AEAD_AES_GCM_256') pour chiffrer l'entrée en texte brut. Si la collection de clés est utilisée avec AEAD.DECRYPT_STRING ou AEAD.DECRYPT_BYTES, BigQuery renvoie le résultat en texte brut si l'une des clés parvient à déchiffrer le texte chiffré.

AEAD.DECRYPT_BYTES

AEAD.DECRYPT_BYTES(keyset, ciphertext, additional_data)

Description

Utilise la clé correspondante de keyset pour déchiffrer le ciphertext et vérifie l'intégrité des données à l'aide de additional_data. Renvoie une erreur en cas d'échec du déchiffrement ou de la vérification.

keyset est une valeur BYTES sérialisée renvoyée par l'une des fonctions KEYS. keyset doit contenir la clé utilisée pour chiffrer l'élément ciphertext dont l'état doit être 'ENABLED', sinon la fonction renvoie une erreur. La fonction AEAD.DECRYPT_BYTES identifie la clé correspondante dans keyset en effectuant une recherche à l'aide de l'ID de clé qui correspond à celle chiffrée dans ciphertext.

ciphertext est une valeur BYTES représentant le résultat d'un appel de la fonction AEAD.ENCRYPT où l'entrée plaintext était de type BYTES.

additional_data est une valeur STRING ou BYTES qui garantit l'authenticité et l'intégrité des données chiffrées. Cette fonction convertit les valeurs STRING en BYTES. Ces valeurs doivent être les mêmes que les additional_data fournies à AEAD.ENCRYPT pour chiffrer l'élément ciphertext, en ignorant son type, sinon la fonction renvoie une erreur.

Types de données renvoyées

BYTES

Exemple

Cet exemple crée une table d'ID uniques contenant des valeurs en texte brut et des collections de clés associées. Ensuite, ces collections de clés sont utilisées pour chiffrer les valeurs en texte brut en BYTES et les stocker dans une nouvelle table. Enfin, la fonction AEAD.DECRYPT_BYTES est appelée pour déchiffrer les valeurs chiffrées et les afficher en texte brut.

L'instruction suivante crée une table CustomerKeysets contenant une colonne d'ID uniques, une colonne de collections de clés AEAD_AES_GCM_256 AEAD_AES_GCM_256 et une colonne d'animaux favoris.

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;

L'instruction suivante crée une table EncryptedCustomerData contenant une colonne d'ID uniques et une colonne de texte chiffré. L'instruction effectue le chiffrement du texte brut favorite_animal à l'aide de la valeur keyset de CustomerKeysets correspondant à chaque ID unique.

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;

La requête suivante utilise les collections de clés de la table CustomerKeysets pour déchiffrer les données de la table 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)

Description

Semblable à la fonction AEAD.DECRYPT_BYTES, mais l'élément ciphertext représente la sortie BYTES de AEAD.ENCRYPT où l'entrée plaintext de AEAD.ENCRYPT est de type STRING, et pas de type BYTES.

Types de données renvoyées

STRING

AEAD.ENCRYPT

AEAD.ENCRYPT(keyset, plaintext, additional_data)

Description

Effectue le chiffrement du texte brut à l'aide de l'algorithme et de la clé cryptographique principale de la collection de données keyset. Incorpore les additional_data dans le texte chiffré renvoyé. Renvoie une valeur NULL si l'une des entrées est NULL.

keyset est une valeur BYTES sérialisée renvoyée par l'une des fonctions KEYS.

plaintext est la valeur STRING ou BYTES à chiffrer.

additional_data est une valeur STRING ou BYTES à incorporer dans le texte chiffré renvoyé. Les valeurs plaintext et additional_data doivent être du même type. La fonction AEAD.ENCRYPT(keyset, string1, string2) est semblable à la fonction AEAD.ENCRYPT(keyset, CAST(string1 AS BYTES), CAST(string2 AS BYTES)).

La sortie est constituée de texte chiffré en BYTES. Le texte chiffré contient un préfixe spécifique à Tink indiquant la clé utilisée pour effectuer le chiffrement, sauf si elle-ci est une clé 'AES_GCM'.

Types de données renvoyées

BYTES

Exemple

La requête suivante utilise les collections de clés de chaque customer_id de la table CustomerKeysets pour chiffrer la valeur du texte brut favorite_animal dans la table PlaintextCustomerData correspondant à ce customer_id. La sortie contient une colonne de valeurs customer_id et une colonne de sortie correspondante en texte chiffré en 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)

Description

Renvoie l'entrée json_keyset STRING en tant que valeur BYTES sérialisée, laquelle est une entrée valide pour les autres fonctions KEYS et AEAD. La valeur JSON STRING doit être compatible avec la définition du message tampon de protocole google.crypto.tink.Keyset : la collection de clés JSON doit être un objet JSON contenant des objets et des paires nom/valeur correspondant à ceux du message "keyset" dans la définition de google.crypto.tink.Keyset. Vous pouvez reconvertir la représentation sérialisée en BYTES de la sortie en représentation JSON STRING à l'aide de la fonction KEYS.KEYSET_TO_JSON.

Types de données renvoyées

BYTES

Exemple

La fonction KEYS.KEYSET_FROM_JSON utilise des valeurs STRING au format JSON semblables à ce qui suit :

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

La requête suivante crée une collection de clés à partir d'un ensemble json_keyset au format STRING :

SELECT KEYS.KEYSET_FROM_JSON(json_keyset);

L'opération renvoie l'ensemble json_keyset sérialisé en BYTES sous la forme suivante :

\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)

Description

Renvoie une représentation STRING au format JSON de l'entrée keyset. La valeur JSON STRING renvoyée est compatible avec la définition du message tampon de protocole google.crypto.tink.Keyset. Vous pouvez reconvertir la représentation JSON STRING en BYTES à l'aide de la fonction KEYS.KEYSET_FROM_JSON.

Types de données renvoyées

STRING

Exemple

La requête suivante renvoie une nouvelle collection de clés 'AEAD_AES_GCM_256' sous forme de STRING au format JSON.

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

Le résultat obtenu est une chaîne STRING comme ci-dessous :

{
  "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)

Description

Ajoute une nouvelle clé à la collection keyset basée sur la valeur key_type. Cette nouvelle clé devient la clé cryptographique principale de la nouvelle collection de clés. Renvoie la nouvelle collection de clés sérialisée en BYTES.

L'ancienne clé cryptographique principale de l'entrée keyset reste une clé supplémentaire dans la collection de clés renvoyée.

Types de données renvoyées

BYTES

Exemple

L'instruction suivante crée une table contenant une colonne de valeurs customer_id uniques et des collections de clés 'AEAD_AES_GCM_256'. Ensuite, une clé cryptographique principale est créée dans chaque collection de clés de la table source à l'aide de la fonction KEYS.ROTATE_KEYSET. Chaque ligne de sortie contient une valeur customer_id et une collection de clés 'AEAD_AES_GCM_256' en 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;
Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.