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 cheraw_key_bytes
sia un valore della chiave non elaborataBYTES
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 chiaveBYTES
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 inAEAD.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 |
+-----------+