Funciones de encriptación AEAD en SQL estándar

En las siguientes secciones, se describen las funciones de encriptación AEAD que se admiten en BigQuery. Para obtener una descripción de cómo se usan las funciones de encriptación AEAD, consulta Conceptos de encriptación AEAD.

KEYS.NEW_KEYSET

KEYS.NEW_KEYSET(key_type)

Descripción

Muestra un conjunto de claves serializado que contiene una clave nueva basada en key_type. El conjunto de claves que se muestra es una representación serializada en BYTES de google.crypto.tink.Keyset que contiene una clave criptográfica, sin claves adicionales. Puedes utilizar el conjunto de claves con las funciones AEAD.ENCRYPT, AEAD.DECRYPT_BYTES y AEAD.DECRYPT_STRING para la encriptación y desencriptación, así como con el grupo KEYS de funciones relacionadas con claves y conjuntos de claves.

key_type es una representación literal en STRING del tipo de clave que se creará. key_type no puede tener un valor NULL. El único valor que se admite actualmente para key_type es AEAD_AES_GCM_256. KEYS.NEW_KEYSET(AEAD_AES_GCM_256) crea una clave de 256 bits con el generador de números seudoaleatorio que proporciona OpenSSL. La clave utilizará AES-GCM para las operaciones de encriptación y desencriptación.

Tipo de datos que muestra

BYTES

Ejemplo

En la siguiente consulta, se crea un conjunto de claves para cada fila en CustomerIds, que puede usarse después a fin de encriptar los datos. Cada conjunto de claves contiene una sola clave de encriptación con datos de claves generados aleatoriamente. Cada fila del resultado contiene un customer_id y una clave '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)

Descripción

Muestra un conjunto de claves serializado en BYTES y agrega una clave al keyset según los valores de key_type y raw_key_bytes.

La clave criptográfica principal sigue siendo la misma que en el keyset. La longitud prevista de raw_key_bytes depende del valor de key_type. Estos son los key_types admitidos:

  • 'AES_CBC_PKCS': Crea una clave para la desencriptación AES con cadena de bloques de cifrado y relleno PKCS. Se espera que raw_key_bytes sea un valor en BYTES clave sin procesar con una longitud de 16, 24 o 32. Estas longitudes tienen tamaños de 128, 192 y 256 bits, respectivamente. Las funciones AEAD de BigQuery no admiten claves de estos tipos para la encriptación; en su lugar, es mejor usar claves 'AEAD_AES_GCM_256' o 'AES_GCM'.

  • 'AES_GCM': Crea una clave para la desencriptación o encriptación AES con el modo Galois/contador. raw_key_bytes debe ser un valor de BYTES de clave sin procesar con una longitud de 16 o 32. Estas longitudes tienen tamaños de 128 y 256 bits, respectivamente. Cuando se usan claves de este tipo como entrada para AEAD.ENCRYPT, el cifrado resultante no tiene un prefijo específico de Tink que indique cuál fue la clave usada.

Tipo de datos que muestra

BYTES

Ejemplo

La siguiente consulta crea una tabla de ID de cliente junto con bytes de clave sin procesar, denominados CustomerRawKeys, y una tabla de ID únicos, denominados CustomerIds. Crea un nuevo conjunto de claves 'AEAD_AES_GCM_256' por cada customer_id; luego, agrega una clave nueva a cada conjunto de claves con el valor de raw_key_bytes correspondiente a ese customer_id. El resultado es una tabla en la que cada fila contiene un customer_id y un conjunto de claves en BYTES, que contiene la clave sin procesar que se agregó con 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 uno de los conjuntos de claves resultantes contiene dos elementos: la clave criptográfica primaria, que se crea con KEYS.NEW_KEYSET('AEAD_AES_GCM_256'), y la clave sin procesar, que se agrega con KEYS.ADD_KEY_FROM_RAW_BYTES. Si uno de los conjuntos de claves de la salida se usa con AEAD.ENCRYPT, BigQuery usa la clave criptográfica primaria creada con KEYS.NEW_KEYSET('AEAD_AES_GCM_256') para encriptar la entrada de texto sin formato. Si el conjunto de claves se usa con AEAD.DECRYPT_STRING o AEAD.DECRYPT_BYTES, BigQuery muestra el texto sin formato resultante si alguna de las claves logra desencriptar el cifrado.

AEAD.DECRYPT_BYTES

AEAD.DECRYPT_BYTES(keyset, ciphertext, additional_data)

Descripción

Utiliza la clave coincidente del keyset para desencriptar el ciphertext y verifica la integridad de los datos con additional_data. Muestra un error si la desencriptación o la verificación fallan.

keyset es un valor serializado en BYTES resultante de una de las funciones KEYS. keyset debe contener la clave que se usó para encriptar el ciphertext, y la clave debe tener un estado 'ENABLED' (de lo contrario, la función muestra un error). AEAD.DECRYPT_BYTES identifica la clave coincidente en el keyset. Para ello, busca la clave con el ID de clave correspondiente al que está encriptado en el ciphertext.

ciphertext es un valor en BYTES obtenido de una llamada a AEAD.ENCRYPT en la que el plaintext de entrada fue del tipo BYTES.

additional_data es un valor en STRING o BYTES que garantiza la autenticidad y la integridad de los datos encriptados. Esta función convierte cualquier valor de STRING en BYTES. Este debe ser el mismo que el valor additional_data proporcionado a AEAD.ENCRYPT para encriptar el ciphertext, sin importar su tipo (si no lo es, la función muestra un error).

Tipo de datos que muestra

BYTES

Ejemplo

En este ejemplo, se crea una tabla de ID únicos con valores de texto sin formato y conjuntos de claves asociados. Luego, utiliza estos conjuntos de claves para encriptar los valores de texto sin formato como BYTES y almacenarlos en una tabla nueva. Por último, utiliza AEAD.DECRYPT_BYTES para desencriptar los valores encriptados y mostrarlos como texto sin formato.

La siguiente instrucción crea una tabla CustomerKeysets con una columna de ID únicos, una columna de conjuntos de claves AEAD_AES_GCM_256 y una columna de animales 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;

La siguiente instrucción crea una tabla EncryptedCustomerData que contiene una columna de ID únicos y una columna de cifrado. La instrucción encripta el texto sin formato favorite_animal con el valor de conjunto de claves de CustomerKeysets correspondiente a cada ID único.

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 siguiente consulta utiliza los conjuntos de claves de la tabla CustomerKeysets para desencriptar los datos de la tabla 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)

Descripción

Similar a AEAD.DECRYPT_BYTES, pero ciphertext es el resultado en BYTES de AEAD.ENCRYPT, en el que la entrada en plaintext de AEAD.ENCRYPT es de tipo STRING, en lugar de BYTES.

Tipo de datos que muestra

STRING

AEAD.ENCRYPT

AEAD.ENCRYPT(keyset, plaintext, additional_data)

Descripción

Encripta texto sin formato mediante el algoritmo y la clave criptográfica primaria del keyset. Incorpora additional_data en el cifrado resultante. Muestra NULL si alguna entrada es NULL.

keyset es un valor BYTES serializado mostrado por una de las funciones KEYS.

plaintext es el valor en STRING o BYTES que se encriptará.

additional_data es un valor en STRING o BYTES que se incorporará en el cifrado resultante. Los valores de plaintext y additional_data deben ser del mismo tipo. AEAD.ENCRYPT(keyset, string1, string2) es equivalente a AEAD.ENCRYPT(keyset, CAST(string1 AS BYTES), CAST(string2 AS BYTES)).

El resultado son BYTES de cifrado. El cifrado contendrá un prefijo específico de Tink que indica la clave que se usó para realizar la encriptación, salvo cuando esa clave es de tipo 'AES_GCM'.

Tipo de datos que muestra

BYTES

Ejemplo

La siguiente consulta utiliza los conjuntos de claves correspondientes a cada customer_id en la tabla CustomerKeysets para encriptar el valor del texto sin formato favorite_animal en la tabla PlaintextCustomerData que corresponde a ese customer_id. El resultado contiene una columna de valores customer_id y una columna con el cifrado resultante que le corresponde 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)

Descripción

Muestra la entrada json_keyset STRING en forma de BYTES serializados, lo que es una entrada válida para otras funciones KEYS y AEAD. La STRING JSON debe ser compatible con la definición del mensaje de búfer de protocolo google.crypto.tink.Keyset: el conjunto de claves JSON debe ser un objeto JSON que contenga objetos y pares de nombre-valor correspondientes a los del mensaje "keyset" de la definición de google.crypto.tink.Keyset. La representación resultante en BYTES serializados puede volver a convertirse en una STRING JSON mediante KEYS.KEYSET_TO_JSON.

Tipo de datos que muestra

BYTES

Ejemplo

KEYS.KEYSET_FROM_JSON acepta valores de STRING en formato JSON como los siguientes:

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

La siguiente consulta crea un nuevo conjunto de claves a partir de una STRING json_keyset en formato JSON:

SELECT KEYS.KEYSET_FROM_JSON(json_keyset);

Esto muestra el valor json_keyset serializado en BYTES, como en el siguiente ejemplo:

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

Descripción

Muestra una representación de tipo STRING JSON del keyset de entrada. La STRING JSON que se muestra es compatible con la definición del mensaje de búfer de protocolo google.crypto.tink.Keyset. La representación en STRING JSON puede volver a convertirse en BYTES mediante KEYS.KEYSET_FROM_JSON.

Tipo de datos que muestra

STRING

Ejemplo

La siguiente consulta muestra un nuevo conjunto de claves 'AEAD_AES_GCM_256' como una STRING con formato JSON.

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

El resultado es una STRING como la siguiente.

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

Descripción

Agrega una clave nueva al keyset según el key_type. Esta clave nueva se convierte en la clave criptográfica principal del nuevo conjunto de claves. Muestra el nuevo conjunto de claves serializado en BYTES.

La clave criptográfica principal anterior del keyset de entrada se conserva como clave adicional en el conjunto de claves mostrado.

Tipo de datos que muestra

BYTES

Ejemplo

La siguiente instrucción crea una tabla con una columna de valores customer_id únicos y conjuntos de claves 'AEAD_AES_GCM_256'. Luego, crea una clave criptográfica primaria nueva dentro de cada conjunto de claves de la tabla de origen mediante KEYS.ROTATE_KEYSET. Cada fila del resultado contiene un customer_id y un conjunto de claves '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;
¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.