Funzioni della crittografia AEAD

Le seguenti sezioni descrivono le funzioni di crittografia AEAD supportate da BigQuery. Per una descrizione del funzionamento della crittografia AEAD, consulta i concetti di crittografia AEAD.

KEYS.NEW_KEYSET

KEYS.NEW_KEYSET(key_type)

Descrizione

Restituisce un set di chiavi serializzato contenente una nuova chiave basata su key_type. Il set di chiavi restituito è una rappresentazione BYTES in serie di google.crypto.tink.Keyset che contiene una chiave di crittografia primaria e nessuna chiave aggiuntiva. Puoi utilizzare il set di chiavi con le funzioni AEAD.ENCRYPT, AEAD.DECRYPT_BYTES e AEAD.DECRYPT_STRING per la crittografia e la decriptazione, nonché con il gruppo KEYS di funzioni relative a chiavi e set di chiavi.

key_type è una rappresentazione letterale STRING del tipo di chiave da creare. key_type non può essere NULL. key_type può essere:

• AEAD_AES_GCM_256: crea una chiave a 256 bit con il generatore di numeri pseudocasuali fornito da boringSSL. La chiave utilizza AES-GCM per le operazioni di crittografia e decriptazione.

Tipo di dati per i resi

BYTES

Esempio

La seguente query crea un set di chiavi per ogni riga in CustomerIds, che può essere utilizzato per criptare i dati. Ogni set di chiavi contiene una singola chiave di crittografia con dati delle chiavi generati in modo casuale. Ogni riga dell'output contiene una customer_id e una chiave 'AEAD_AES_GCM_256' in 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)

Descrizione

Restituisce un set di chiavi serializzato come BYTES con l'aggiunta di una chiave a keyset in base a key_type e raw_key_bytes.

La chiave di crittografia principale rimane la stessa di keyset. La lunghezza prevista di raw_key_bytes dipende dal valore di key_type. Sono supportati i seguenti key_types:

• 'AES_CBC_PKCS': crea una chiave per la decriptazione AES tramite concatenamento di blocchi di crittografia e spaziatura interna PKCS. Si prevede che raw_key_bytes sia un valore della chiave non elaborata BYTES di lunghezza pari a 16, 24 o 32; queste lunghezze hanno rispettivamente dimensioni di 128, 192 e 256 bit. Le funzioni AEAD di BigQuery non supportano chiavi di crittografia di questo tipo; preferire piuttosto le chiavi 'AEAD_AES_GCM_256' o 'AES_GCM'.
• 'AES_GCM': crea una chiave per la decriptazione o la crittografia AES utilizzando la modalità Galois/Counter. raw_key_bytes deve essere un valore chiave BYTES non elaborato di lunghezza pari a 16 o 32; queste lunghezze hanno rispettivamente dimensioni di 128 e 256 bit. Quando le chiavi di questo tipo vengono inserite in AEAD.ENCRYPT, il testo crittografato dell'output non ha un prefisso specifico di Tink che indica quale chiave è stata utilizzata come input.

Tipo di dati per i resi

BYTES

Esempio

La seguente query crea una tabella di ID cliente con byte di chiave non elaborati, chiamati CustomerRawKeys, e una tabella di ID univoci, chiamata CustomerIds. Crea un nuovo set di chiavi 'AEAD_AES_GCM_256' per ogni customer_id, quindi aggiunge una nuova chiave a ciascun set di chiavi, utilizzando il valore raw_key_bytes corrispondente customer_id. L'output è una tabella in cui ogni riga contiene un customer_id e un set di chiavi in BYTES, che contiene la chiave non elaborata aggiunta utilizzando 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;

Ciascun set di chiavi di output contiene due elementi: la chiave di crittografia primaria creata utilizzando KEYS.NEW_KEYSET('AEAD_AES_GCM_256') e la chiave non elaborata aggiunta utilizzando KEYS.ADD_KEY_FROM_RAW_BYTES. Se un set di chiavi nell'output viene utilizzato con AEAD.ENCRYPT, BigQuery utilizza la chiave di crittografia principale creata utilizzando KEYS.NEW_KEYSET('AEAD_AES_GCM_256') per criptare il testo non crittografato di input. Se il set di chiavi viene utilizzato con AEAD.DECRYPT_STRING o AEAD.DECRYPT_BYTES, BigQuery restituisce il testo non crittografato risultante se una delle chiavi ha esito positivo nella decriptazione del testo crittografato.

AEAD.DECRYPT_BYTES

AEAD.DECRYPT_BYTES(keyset, ciphertext, additional_data)

Descrizione

Utilizza la chiave corrispondente da keyset per decriptare ciphertext e verifica l'integrità dei dati utilizzando additional_data. Restituisce un errore se la decriptazione o la verifica non va a buon fine.

keyset è un valore BYTES serializzato restituito da una delle funzioni KEYS o un valore STRUCT restituito da KEYS.KEYSET_CHAIN. keyset deve contenere la chiave utilizzata per criptare ciphertext e la chiave deve essere in stato 'ENABLED', altrimenti la funzione restituisce un errore. AEAD.DECRYPT_BYTES identifica la chiave corrispondente in keyset trovandola con l'ID chiave corrispondente a quello criptato in ciphertext.

ciphertext è un valore di BYTES che è il risultato di una chiamata a AEAD.ENCRYPT in cui l'input plaintext era di tipo BYTES.

Se ciphertext include un vettore di inizializzazione (IV), deve essere il primo byte di ciphertext. Se ciphertext include un tag di autenticazione, devono essere gli ultimi byte di ciphertext. Se il IV e il tag autentico sono uno (SIV), devono essere i primi byte di ciphertext. In genere, il tag di autenticazione e IV richiede 16 byte, ma le dimensioni possono variare.

additional_data è un valore STRING o BYTES che garantisce l'autenticità e l'integrità dei dati criptati. Questa funzione trasmette qualsiasi valore STRING a BYTES. Deve essere uguale al additional_data fornito a AEAD.ENCRYPT per crittografare ciphertext, ignorando il tipo, altrimenti la funzione restituisce un errore.

Tipo di dati per i resi

BYTES

Esempio

Questo esempio crea una tabella di ID univoci con valori e set di chiavi associati. Poi, utilizza questi set di chiavi per criptare i valori del testo non crittografato come BYTES e archiviarli in una nuova tabella. Infine, utilizza AEAD.DECRYPT_BYTES per decriptare i valori criptati e visualizzarli come testo non crittografato.

La seguente istruzione crea una tabella CustomerKeysets contenente una colonna con ID univoci, una colonna per i set di chiavi AEAD_AES_GCM_256 e una colonna con gli animali preferiti.

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

La seguente istruzione crea una tabella EncryptedCustomerData contenente una colonna di ID univoci e una colonna di testo crittografato. L'istruzione cripta il testo non crittografato favorite_animal utilizzando il valore del set di chiavi del valore CustomerKeysets corrispondente a ogni ID univoco.

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

La seguente query utilizza i set di chiavi nella tabella CustomerKeysets per decriptare i dati nella tabella EncryptedCustomerData.

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

AEAD.DECRYPT_STRING

AEAD.DECRYPT_STRING(keyset, ciphertext, additional_data)

Descrizione

Ad esempio AEAD.DECRYPT_BYTES, ma dove plaintext è di tipo STRING.

Tipo di dati per i resi

STRING

AEAD.ENCRYPT

AEAD.ENCRYPT(keyset, plaintext, additional_data)

Descrizione

Cripta plaintext utilizzando la chiave di crittografia principale in keyset. L'algoritmo della chiave primaria deve essere AEAD_AES_GCM_256. Incorpora additional_data nel testo crittografato restituito. Restituisce NULL se un input è NULL.

keyset è un valore BYTES serializzato restituito da una delle funzioni KEYS o un valore STRUCT restituito da KEYS.KEYSET_CHAIN.

plaintext è il valore STRING o BYTES da criptare.

additional_data è un valore STRING o BYTES da incorporare nel testo crittografato restituito. plaintext e additional_data devono essere dello stesso tipo. AEAD.ENCRYPT(keyset, string1, string2) equivale a AEAD.ENCRYPT(keyset, CAST(string1 AS BYTES), CAST(string2 AS BYTES)).

L'output è il testo crittografato BYTES. Il testo crittografato contiene un prefisso specifico per Tink che indica la chiave utilizzata per eseguire la crittografia.

Tipo di dati per i resi

BYTES

Esempio

La seguente query utilizza i set di chiavi per ogni customer_id nella tabella CustomerKeysets per criptare il valore del testo non crittografato favorite_animal nella tabella PlaintextCustomerData corrispondente al criterio customer_id. L'output contiene una colonna con valori customer_id e una colonna con output di testo corrispondente come 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_CHAIN

KEYS.KEYSET_CHAIN(kms_resource_name, first_level_keyset)

Descrizione

Può essere utilizzato al posto dell'argomento keyset in AEAD

per trasmettere un set di chiavi criptato con una chiave Cloud KMS. Ciò ti consente di utilizzare le funzioni AEAD senza includere chiavi di testo non crittografato in una query.

kms_resource_name è un valore STRING che contiene il percorso della risorsa per la chiave Cloud KMS utilizzata per decriptare first_level_keyset. La stringa completa deve iniziare con gcp-kms:// ed essere nel seguente formato: gcp-kms://projects/{id}/locations/{location}/keyRings/{id}/cryptoKeys/{id}. La chiave Cloud KMS deve risiedere nella stessa area geografica Cloud della query.

first_level_keyset è un valore BYTES contenente il testo crittografato prodotto mediante crittografia di un set di chiavi Tink serializzato con la chiave KMS specificata.

Sia kms_resource_name sia first_level_keyset devono essere valori costanti.

Tipo di dati per i resi

STRUCT

Esempio

Questo esempio crea una tabella di dati di esempio con cui viene mostrato come criptare tali dati utilizzando un set di chiavi con wrapping (criptato). Infine, mostra come eseguire query sulla versione criptata dei dati.

La seguente istruzione crea una tabella RawCustomerData contenente una colonna con gli ID cliente e una colonna degli animali preferiti.

CREATE TABLE aead.RawCustomerData AS
SELECT
  1 AS customer_id,
  b'jaguar' AS favorite_animal
UNION ALL
SELECT
  2 AS customer_id,
  b'zebra' AS favorite_animal
UNION ALL
SELECT
  3 AS customer_id,
  b'zebra' AS favorite_animal;

La seguente istruzione crea una tabella EncryptedCustomerData contenente una colonna di ID univoci e una colonna di testo crittografato. L'istruzione cripta il testo non crittografato favorite_animal utilizzando il valore first_level_keyset fornito.

SET kms_resource_name = 'gcp-kms://projects/my-project/locations/us/keyRings/my-key-ring/cryptoKeys/my-crypto-key';
SET first_level_keyset = b'\012\044\000\107\275\360\176\264\206\332\235\215\304...';

CREATE TABLE aead.EncryptedCustomerData AS
SELECT
  customer_id,
  AEAD.ENCRYPT(
    KEYS.KEYSET_CHAIN(kms_resource_name, first_level_keyset),
    favorite_animal,
    CAST(CAST(customer_id AS STRING) AS BYTES)
  ) AS encrypted_animal
FROM
  aead.RawCustomerData;

La seguente query utilizza il valore first_level_keyset per decriptare i dati nella tabella EncryptedCustomerData.

SET kms_resource_name = 'gcp-kms://projects/my-project/locations/us/keyRings/my-key-ring/cryptoKeys/my-crypto-key';
SET first_level_keyset = b'\012\044\000\107\275\360\176\264\206\332\235\215\304...';

SELECT
  customer_id,
  AEAD.DECRYPT_BYTES(
    KEYS.KEYSET_CHAIN(kms_resource_name, first_level_keyset)
    encrypted_animal,
    CAST(CAST(customer_id AS STRING) AS BYTES)
  ) AS favorite_animal
FROM aead.EncryptedCustomerData;

KEYS.KEYSET_FROM_JSON

KEYS.KEYSET_FROM_JSON(json_keyset)

Descrizione

Restituisce l'input json_keyset STRING come serializzato su BYTES, che è un input valido per altre funzioni KEYS e AEAD. Il file JSON STRING deve essere compatibile con la definizione del messaggio del buffer di protocollo google.crypto.tink.Keyset: il set di chiavi JSON deve essere un oggetto JSON contenente oggetti e coppie nome-valore corrispondenti a quelli nel messaggio "google.crypto.tink.Keyset". Puoi riconvertire la rappresentazione serializzata di BYTES in un file JSON STRING utilizzando KEYS.KEYSET_TO_JSON.

Tipo di dati per i resi

BYTES

Esempio

KEYS.KEYSET_FROM_JSON prevede valori STRING nel formato JSON come segue:

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

La seguente query crea un nuovo set di chiavi da un formato in formato JSON: STRING json_keyset:

SELECT KEYS.KEYSET_FROM_JSON(json_keyset);

Ciò restituisce il numero di serie json_keyset come BYTES, come segue:

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

Descrizione

Restituisce una rappresentazione STRING JSON dell'input keyset. Il JSON restituito STRING è compatibile con la definizione del messaggio del buffer di protocollo google.crypto.tink.Keyset. Puoi riconvertire la rappresentazione JSON STRING in BYTES utilizzando KEYS.KEYSET_FROM_JSON.

Tipo di dati per i resi

STRING

Esempio

La seguente query restituisce un nuovo set di chiavi 'AEAD_AES_GCM_256' come STRING in formato JSON.

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

Il risultato è un STRING come il seguente.

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

Descrizione

Aggiunge una nuova chiave a keyset in base a key_type. Questa nuova chiave diventa la chiave crittografica principale del nuovo set di chiavi. Restituisce il nuovo set di chiavi serializzato come BYTES.

La vecchia chiave di crittografia primaria dell'input keyset rimane una chiave aggiuntiva nel set di chiavi restituito.

Il nuovo key_type deve corrispondere al tipo di chiavi esistenti in keyset.

Tipo di dati per i resi

BYTES

Esempio

La seguente istruzione crea una tabella contenente una colonna di valori customer_id univoci e set di chiavi 'AEAD_AES_GCM_256'. Quindi, crea una nuova chiave di crittografia primaria all'interno di ciascun set di chiavi nella tabella di origine utilizzando KEYS.ROTATE_KEYSET. Ogni riga dell'output contiene un set di chiavi customer_id e 'AEAD_AES_GCM_256' in 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;

KEYS.KEYSET_LENGTH

KEYS.KEYSET_LENGTH(keyset)

Descrizione

Restituisce il numero di chiavi nel set di chiavi fornito.

Tipo di dati per i resi

INT64

Esempio

Questo esempio fa riferimento a una stringa in formato JSON chiamata json_keyset contenente due chiavi:

{
   "primaryKeyId":1354994251,
   "key":[
      {
         "keyData":{
            "keyMaterialType":"SYMMETRIC",
            "typeUrl":"type.googleapis.com/google.crypto.tink.AesGcmKey",
            "value":"GiD9sxQRgFj4aYN78vaIlxInjZkG/uvyWSY9a8GN+ELV2Q=="
         },
         "keyId":1354994251,
         "outputPrefixType":"TINK",
         "status":"ENABLED"
      }
   ],
   "key":[
      {
         "keyData":{
            "keyMaterialType":"SYMMETRIC",
            "typeUrl":"type.googleapis.com/google.crypto.tink.AesGcmKey",
            "value":"PRn76sxQRgFj4aYN00vaIlxInjZkG/uvyWSY9a2bLRm"
         },
         "keyId":852264701,
         "outputPrefixType":"TINK",
         "status":"DISABLED"
      }
   ]
}

La seguente query converte json_keyset in un set di chiavi, quindi restituisce il numero di chiavi nel set di chiavi:

SELECT KEYS.KEYSET_LENGTH(KEYS.KEYSET_FROM_JSON(json_keyset)) as key_count;

+-----------+
| key_count |
+-----------+
| 2         |
+-----------+