AEAD-Verschlüsselungsfunktionen

In den folgenden Abschnitten werden die von BigQuery unterstützten AEAD-Verschlüsselungsfunktionen beschrieben. Eine Beschreibung der AEAD-Verschlüsselungsfunktionen finden Sie unter AEAD-Verschlüsselungskonzepte.

KEYS.NEW_KEYSET

KEYS.NEW_KEYSET(key_type)

Beschreibung

Gibt ein serialisiertes Keyset zurück, das einen neuen Schlüssel anhand von key_type enthält. Das zurückgegebene Keyset ist eine serialisierte BYTES-Darstellung von google.crypto.tink.Keyset, die einen primären kryptografischen Schlüssel und keine zusätzlichen Schlüssel enthält. Sie können das Keyset mit den Funktionen AEAD.ENCRYPT, AEAD.DECRYPT_BYTES und AEAD.DECRYPT_STRING zum Ver- und Entschlüsseln sowie mit der KEYS-Gruppe von Funktionen für Schlüssel und Keysets verwenden.

key_type ist eine literale Darstellung vom Typ STRING des zu erstellenden Schlüsseltyps. key_type darf nicht NULL sein. key_type kann Folgendes sein:

• AEAD_AES_GCM_256: Erstellt einen 256-Bit-Schlüssel mit dem von BoringSSL bereitgestellten Pseudozufallszahlengenerator. Der Schlüssel verwendet AES-GCM für Ver- und Entschlüsselungsvorgänge.
• DETERMINISTIC_AEAD_AES_SIV_CMAC_256: Erstellt einen 512-Bit-AES-SIV-CMAC-Schlüssel, der einen 256-Bit-AES-CTR- und einen 256-Bit-AES-CMAC-Schlüssel enthält. Der Schlüssel AES-SIV-CMAC wird mit einem von boringSSL bereitgestellten Pseudozufallszahlengenerator erstellt. Der Schlüssel verwendet AES-SIV für Ver- und Entschlüsselungsvorgänge.

Rückgabedatentyp

BYTES

Beispiel

Die folgende Abfrage erstellt ein Keyset für jede Zeile in CustomerIds, das anschließend zum Verschlüsseln von Daten verwendet werden kann. Jedes Keyset enthält einen einzelnen Verschlüsselungsschlüssel mit zufällig generierten Schlüsseldaten. Jede Zeile in der Ausgabe enthält eine customer_id und einen Schlüssel vom Typ '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)

Beschreibung

Gibt ein serialisiertes Keyset als BYTES und zusätzlich einen Schlüssel für das keyset auf der Grundlage von key_type und raw_key_bytes zurück.

Der primäre kryptografische Schlüssel bleibt derselbe wie im keyset. Die erwartete Länge von raw_key_bytes hängt vom Wert von key_type ab. Folgende key_types werden unterstützt:

• 'AES_CBC_PKCS': Erstellt einen Schlüssel für die AES-Entschlüsselung unter Verwendung von Cipher Block Chaining (CBC) oder PKCS-Padding. raw_key_bytes sollte ein BYTES-Wert eines Rohschlüssels der Länge 16, 24 oder 32 sein. Diese Längen haben eine Größe von jeweils 128, 192 bzw. 256 Bit. Schlüssel dieser Typen werden von BigQuery AEAD-Funktionen für die Verschlüsselung nicht unterstützt, daher sollten Schlüssel vom Typ 'AEAD_AES_GCM_256' oder 'AES_GCM' bevorzugt werden.
• 'AES_GCM': Erstellt einen Schlüssel für die AES-Entschlüsselung oder -Verschlüsselung im Galois/Counter Mode. raw_key_bytes muss ein BYTES-Wert eines Rohschlüssels der Länge 16 oder 32 sein. Diese Längen haben eine Größe von 128 bzw. 256 Bit. Wenn Schlüssel dieses Typs Eingaben in AEAD.ENCRYPT sind, hat der ausgegebene Geheimtext kein Tink-spezifisches Präfix, das angibt, welcher Schlüssel als Eingabe verwendet wurde.

Rückgabedatentyp

BYTES

Beispiel

Mit der folgenden Abfrage wird eine Tabelle mit Kundennummern zusammen mit den Rohschlüsselbyte CustomerRawKeys sowie eine Tabelle eindeutiger IDs mit der Bezeichnung CustomerIds erstellt. Für jede 'AEAD_AES_GCM_256' wird ein neues Keyset vom Typ customer_id erstellt. Dann wird unter Verwendung des Wertes raw_key_bytes, der dieser customer_id entspricht, jedem Keyset ein neuer Schlüssel hinzugefügt. Die Ausgabe ist eine Tabelle, in der jede Zeile eine customer_id und ein Keyset in BYTES enthält, das den mit KEYS.ADD_KEY_FROM_RAW_BYTES hinzugefügten Rohschlüssel enthält.

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;

Die Ausgabe-Keysets enthalten jeweils zwei Elemente: den mit KEYS.NEW_KEYSET('AEAD_AES_GCM_256') erstellten primären kryptografischen Schlüssel und den mit KEYS.ADD_KEY_FROM_RAW_BYTES hinzugefügten Rohschlüssel. Wenn ein Keyset in der Ausgabe mit AEAD.ENCRYPT verwendet wird, verwendet BigQuery den primären kryptografischen Schlüssel, der mit KEYS.NEW_KEYSET('AEAD_AES_GCM_256') erstellt wurde, um den Eingabeklartext zu verschlüsseln. Wenn das Keyset mit AEAD.DECRYPT_STRING oder AEAD.DECRYPT_BYTES verwendet wird, gibt BigQuery den resultierenden Klartext zurück, wenn einer der Schlüssel den Geheimtext erfolgreich entschlüsselt.

AEAD.DECRYPT_BYTES

AEAD.DECRYPT_BYTES(keyset, ciphertext, additional_data)

Beschreibung

Verwendet den passenden Schlüssel von keyset zum Entschlüsseln von ciphertext und überprüft die Integrität der Daten unter Verwendung von additional_data. Wenn die Entschlüsselung oder Überprüfung fehlschlägt, wird ein Fehler zurückgegeben.

keyset ist ein serialisierter BYTES-Wert, der von einer der KEYS-Funktionen oder einem STRUCT zurückgegeben wird, das von KEYS.KEYSET_CHAIN zurückgegeben wird. keyset muss den Schlüssel enthalten, der zum Verschlüsseln von ciphertext verwendet wurde. Dieser Schlüssel muss sich im Status 'ENABLED' befinden, andernfalls gibt die Funktion einen Fehler zurück. AEAD.DECRYPT_BYTES identifiziert den passenden Schlüssel im keyset, indem der Schlüssel mit der Schlüssel-ID identifiziert wird, die mit der im verschlüsselten ciphertext übereinstimmt.

ciphertext ist ein BYTES-Wert, der das Ergebnis eines Aufrufs von AEAD.ENCRYPT ist, wenn der plaintext der Eingabe vom Typ BYTES war.

Wenn ciphertext einen Initialisierungsvektor (IV) enthält, sollte dieser die ersten Bytes von ciphertext sein. Wenn ciphertext ein Authentifizierungs-Tag enthält, sollte dieses die letzten Bytes von ciphertext sein. Wenn der IV und das Authentifizierungs-Tag dasselbe sind (SIV), sollten es die ersten Bytes von ciphertext sein. Der IV und das Authentifizierungs-Tag erfordern in der Regel 16 Byte, aber die Größe kann variieren.

additional_data ist ein Wert vom Typ STRING oder BYTES, der die Authentizität und Integrität der verschlüsselten Daten gewährleistet. Diese Funktion wandelt jeden STRING-Wert in einen BYTES-Wert um. Dieser muss den additional_data entsprechen, die an AEAD.ENCRYPT übergeben wurden, um den ciphertext zu verschlüsseln, wobei der Typ ignoriert wird. Andernfalls gibt die Funktion einen Fehler zurück.

Rückgabedatentyp

BYTES

Beispiel

In diesem Beispiel wird eine Tabelle eindeutiger IDs mit verknüpften Klartextwerten und Keysets erstellt. Anschließend werden diese Keysets verwendet, um die Klartextwerte als BYTES zu verschlüsseln und in einer neuen Tabelle zu speichern. Schließlich werden die verschlüsselten Werte mithilfe von AEAD.DECRYPT_BYTES entschlüsselt und als Klartext angezeigt.

Mit der folgenden Anweisung wird die Tabelle CustomerKeysets erstellt, die eine Spalte mit eindeutigen IDs, eine Spalte mit Keysets AEAD_AES_GCM_256 und eine Spalte mit Lieblingstieren enthält.

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;

Die folgende Anweisung erstellt die Tabelle EncryptedCustomerData, die eine Spalte mit eindeutigen IDs und eine Spalte mit Geheimtext enthält. Mit der Anweisung wird der Klartext favorite_animal mit dem Keyset-Wert aus CustomerKeysets verschlüsselt, der jeder eindeutigen ID entspricht.

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;

Die folgende Abfrage verwendet die Keysets aus der Tabelle CustomerKeysets, um Daten in der Tabelle EncryptedCustomerData zu entschlüsseln.

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)

Beschreibung

Wie AEAD.DECRYPT_BYTES, wobei plaintext jedoch vom Typ STRING ist.

Rückgabedatentyp

STRING

AEAD.ENCRYPT

AEAD.ENCRYPT(keyset, plaintext, additional_data)

Beschreibung

Verschlüsselt plaintext mit dem primären kryptografischen Schlüssel im keyset. Der Algorithmus des Primärschlüssels muss AEAD_AES_GCM_256 sein. Fügt additional_data in den zurückgegebenen Geheimtext ein. Gibt NULL zurück, wenn eine beliebige Eingabe NULL ist.

keyset ist ein serialisierter BYTES-Wert, der von einer der KEYS-Funktionen oder einem STRUCT zurückgegeben wird, das von KEYS.KEYSET_CHAIN zurückgegeben wird.

plaintext ist der zu verschlüsselnde STRING- oder BYTES-Wert.

additional_data ist ein Wert vom Typ STRING oder BYTES, der in den zurückgegebenen Geheimtext aufgenommen werden soll. plaintext und additional_data müssen vom selben Typ sein. AEAD.ENCRYPT(keyset, string1, string2) entspricht AEAD.ENCRYPT(keyset, CAST(string1 AS BYTES), CAST(string2 AS BYTES)).

Die Ausgabe ist Geheimtext vom Typ BYTES. Der Geheimtext enthält ein Tink-spezifisches Präfix, das den für die Verschlüsselung verwendeten Schlüssel angibt.

Rückgabedatentyp

BYTES

Beispiel

Die folgende Abfrage verwendet die Keysets jeder customer_id in der Tabelle CustomerKeysets, um den Klartextwert favorite_animal in der Tabelle PlaintextCustomerData für die jeweils entsprechende customer_id zu verschlüsseln. Die Ausgabe enthält eine Spalte mit Werten vom Typ customer_id und eine Spalte mit der entsprechenden Geheimtextausgabe als 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;

DETERMINISTIC_DECRYPT_BYTES

DETERMINISTIC_DECRYPT_BYTES(keyset, ciphertext, additional_data)

Beschreibung

Verwendet den passenden Schlüssel von keyset zum Entschlüsseln von ciphertext und überprüft die Integrität der Daten unter Verwendung von additional_data. Wenn die Entschlüsselung fehlschlägt, wird ein Fehler zurückgegeben.

keyset ist ein serialisierter BYTES-Wert oder ein STRUCT-Wert, der von einer der KEYS-Funktionen zurückgegeben wird. keyset muss den Schlüssel enthalten, der zur Verschlüsselung von ciphertext verwendet wurde, der Schlüssel muss sich im Status 'ENABLED' befinden, und der Schlüssel muss vom Typ DETERMINISTIC_AEAD_AES_SIV_CMAC_256 sein, andernfalls gibt die Funktion einen Fehler zurück. DETERMINISTIC_DECRYPT_BYTES identifiziert den passenden Schlüssel im keyset, indem der Schlüssel mit der Schlüssel-ID identifiziert wird, die mit der im verschlüsselten ciphertext übereinstimmt.

ciphertext ist ein BYTES-Wert als Ergebnis eines Aufrufs von DETERMINISTIC_ENCRYPT, wenn die plaintext-Funktion der Eingabe vom Typ BYTES war.

Der Geheimtext muss dem Wire-Format von Tink folgen. Das erste Byte von ciphertext sollte eine Tink-Schlüsselversion gefolgt von einem 4-Byte-Schlüsselhinweis enthalten. Wenn ciphertext einen Initialisierungsvektor (IV) enthält, sollte dieser die nächsten Bytes von ciphertext sein. Wenn ciphertext ein Authentifizierungs-Tag enthält, sollte dieses die letzten Bytes von ciphertext sein. Wenn der IV und das Authentifizierungs-Tag dasselbe sind (SIV), sollten es die ersten Bytes von ciphertext sein. Der IV und das Authentifizierungs-Tag erfordern in der Regel 16 Byte, aber die Größe kann variieren.

additional_data ist ein Wert vom Typ STRING oder BYTES, der den Geheimtext an seinen Kontext bindet. Dadurch wird der Geheimtext beim Entschlüsseln in demselben Kontext erzwungen, mit dem er verschlüsselt wurde. Diese Funktion wandelt jeden STRING-Wert in einen BYTES-Wert um. Dieser muss den additional_data entsprechen, die an DETERMINISTIC_ENCRYPT übergeben wurden, um den ciphertext zu verschlüsseln, wobei der Typ ignoriert wird. Andernfalls gibt die Funktion einen Fehler zurück.

Rückgabedatentyp

BYTES

Beispiel

In diesem Beispiel wird eine Tabelle eindeutiger IDs mit verknüpften Klartextwerten und Keysets erstellt. Anschließend werden diese Keysets verwendet, um die Klartextwerte als BYTES zu verschlüsseln und in einer neuen Tabelle zu speichern. Schließlich werden die verschlüsselten Werte mithilfe von DETERMINISTIC_DECRYPT_BYTES entschlüsselt und als Klartext angezeigt.

Mit der folgenden Anweisung wird die Tabelle CustomerKeysets erstellt, die eine Spalte mit eindeutigen IDs, eine Spalte mit Keysets DETERMINISTIC_AEAD_AES_SIV_CMAC_256 und eine Spalte mit Lieblingstieren enthält.

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

Die folgende Anweisung erstellt die Tabelle EncryptedCustomerData, die eine Spalte mit eindeutigen IDs und eine Spalte mit Geheimtext enthält. Mit der Anweisung wird der Klartext favorite_animal mit dem Keyset-Wert aus CustomerKeysets verschlüsselt, der jeder eindeutigen ID entspricht.

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

Die folgende Abfrage verwendet die Keysets aus der Tabelle CustomerKeysets, um Daten in der Tabelle EncryptedCustomerData zu entschlüsseln.

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

DETERMINISTIC_DECRYPT_STRING

DETERMINISTIC_DECRYPT_STRING(keyset, ciphertext, additional_data)

Beschreibung

Wie DETERMINISTIC_DECRYPT_BYTES, wobei plaintext jedoch vom Typ STRING ist.

Rückgabedatentyp

STRING

DETERMINISTIC_ENCRYPT

DETERMINISTIC_ENCRYPT(keyset, plaintext, additional_data)

Beschreibung

Verschlüsselt plaintext mit dem primären kryptografischen Schlüssel in keyset mithilfe des deterministischen AEAD. Der Algorithmus des Primärschlüssels muss DETERMINISTIC_AEAD_AES_SIV_CMAC_256 sein. Fügt additional_data in den zurückgegebenen Geheimtext ein. Gibt NULL zurück, wenn eine beliebige Eingabe NULL ist.

keyset ist ein serialisierter BYTES-Wert oder ein STRUCT-Wert, der von einer der KEYS-Funktionen zurückgegeben wird.

plaintext ist der zu verschlüsselnde STRING- oder BYTES-Wert.

additional_data ist ein Wert vom Typ STRING oder BYTES, der in den zurückgegebenen Geheimtext aufgenommen werden soll. plaintext und additional_data müssen vom selben Typ sein. DETERMINISTIC_ENCRYPT(keyset, string1, string2) entspricht DETERMINISTIC_ENCRYPT(keyset, CAST(string1 AS BYTES), CAST(string2 AS BYTES)).

Die Ausgabe ist Geheimtext vom Typ BYTES. Der Geheimtext enthält ein Tink-spezifisches Präfix, das den für die Verschlüsselung verwendeten Schlüssel angibt. Bei identischem keyset und plaintext gibt diese Funktion bei jedem Aufruf denselben Geheimtext zurück (einschließlich über Abfragen hinweg).

Rückgabedatentyp

BYTES

Beispiel

Die folgende Abfrage verwendet die Keysets jeder customer_id in der Tabelle CustomerKeysets, um den Klartextwert favorite_animal in der Tabelle PlaintextCustomerData für die jeweils entsprechende customer_id zu verschlüsseln. Die Ausgabe enthält eine Spalte mit Werten vom Typ customer_id und eine Spalte mit der entsprechenden Geheimtextausgabe als BYTES.

WITH CustomerKeysets AS (
  SELECT 1 AS customer_id,
  KEYS.NEW_KEYSET('DETERMINISTIC_AEAD_AES_SIV_CMAC_256') AS keyset UNION ALL
  SELECT 2, KEYS.NEW_KEYSET('DETERMINISTIC_AEAD_AES_SIV_CMAC_256') UNION ALL
  SELECT 3, KEYS.NEW_KEYSET('DETERMINISTIC_AEAD_AES_SIV_CMAC_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,
  DETERMINISTIC_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)

Beschreibung

Kann anstelle des Arguments keyset an die AEAD- und deterministischen Verschlüsselungsfunktionen verwendet werden, um ein Keyset zu übergeben, das mit einem Cloud KMS-Schlüssel verschlüsselt ist. So können Sie AEAD-Funktionen verwenden, ohne Klartextschlüssel in eine Abfrage aufzunehmen.

kms_resource_name ist ein STRING-Wert, der den Ressourcenpfad zum Cloud KMS-Schlüssel enthält, der zum Entschlüsseln von first_level_keyset verwendet wird. Der vollständige String muss mit gcp-kms:// beginnen und das folgende Format haben: gcp-kms://projects/{id}/locations/{location}/keyRings/{id}/cryptoKeys/{id}. Der Cloud KMS-Schlüssel muss sich in derselben Cloudregion wie die Abfrage befinden.

first_level_keyset ist ein BYTES-Wert mit dem Geheimtext, der durch die Verschlüsselung eines serialisierten Tink-Keysets mit dem angegebenen KMS-Schlüssel generiert wird.

Sowohl kms_resource_name als auch first_level_keyset müssen konstante Werte sein.

Rückgabedatentyp

STRUCT

Beispiel

In diesem Beispiel wird eine Tabelle mit Beispieldaten erstellt. Anschließend wird gezeigt, wie Sie diese Daten mit einem verpackten (verschlüsselten) Keyset verschlüsseln. Schließlich wird gezeigt, wie die verschlüsselte Version der Daten abgefragt wird.

Mit der folgenden Anweisung wird die Tabelle RawCustomerData erstellt, die eine Spalte mit Kundennummern und eine Spalte mit Lieblingstieren enthält.

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;

Die folgende Anweisung erstellt die Tabelle EncryptedCustomerData, die eine Spalte mit eindeutigen IDs und eine Spalte mit Geheimtext enthält. Mit der Anweisung wird der Klartext favorite_animal mit dem angegebenen first_level_keyset verschlüsselt.

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;

Die folgende Abfrage verwendet das first_level_keyset, um Daten in der Tabelle EncryptedCustomerData zu entschlüsseln.

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;

Die vorherigen beiden Schritte funktionieren auch mit den Funktionen DETERMINISTIC_ENCRYPT und DETERMINISTIC_DECRYPT_BYTES. Das verpackte Keyset muss mit dem Typ DETERMINISTIC_AEAD_AES_SIV_CMAC_256 erstellt werden.

Die folgende Anweisung erstellt die Tabelle EncryptedCustomerData, die eine Spalte mit eindeutigen IDs und eine Spalte mit Geheimtext enthält. Mit der Anweisung wird der Klartext favorite_animal mit dem angegebenen first_level_keyset verschlüsselt. Sie sehen, dass der Geheimtext für favorite_animal für die Kunden 2 und 3 identisch ist, da ihr Klartext favorite_animal identisch ist.

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 daead.EncryptedCustomerData AS
SELECT
  customer_id,
  DETERMINISTC_ENCRYPT(
    KEYS.KEYSET_CHAIN(kms_resource_name, first_level_keyset),
    favorite_animal,
    CAST(CAST(customer_id AS STRING) AS BYTES)
  ) AS encrypted_animal
FROM
  daead.RawCustomerData;

Die folgende Abfrage verwendet das first_level_keyset, um Daten in der Tabelle EncryptedCustomerData zu entschlüsseln.

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,
  DETERMINISTIC_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 dead.EncryptedCustomerData;

KEYS.KEYSET_FROM_JSON

KEYS.KEYSET_FROM_JSON(json_keyset)

Beschreibung

Gibt die Eingabe json_keyset STRING als serialisierten BYTES-Wert zurück, der eine gültige Eingabe für andere KEYS- und AEAD-Funktionen ist. Der JSON-STRING muss mit der Definition der Protokollpuffernachricht google.crypto.tink.Keyset kompatibel sein: Das JSON-Keyset sollte ein JSON-Objekt sein, das Objekte und Name/Wert-Paare enthält, die denen in der "keyset"-Nachricht der google.crypto.tink.Keyset-Definition entsprechen. Sie können die ausgegebene serialisierte BYTES-Darstellung mithilfe von KEYS.KEYSET_TO_JSON wieder in einen JSON-STRING umwandeln.

Rückgabedatentyp

BYTES

Beispiel

KEYS.KEYSET_FROM_JSON übernimmt JSON-formatierte STRING-Werte wie die folgenden:

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

Mit der folgenden Abfrage wird aus einem JSON-formatierten STRING json_keyset ein neues Keyset erstellt:

SELECT KEYS.KEYSET_FROM_JSON(json_keyset);

Dadurch wird das json_keyset serialisiert als BYTES so zurückgegeben:

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

Beschreibung

Gibt eine JSON STRING-Darstellung vom Eingabe-keyset zurück. Der zurückgegebene JSON-STRING ist mit der Definition der Protokollpuffernachricht google.crypto.tink.Keyset kompatibel. Sie können die Darstellung als JSON-STRING mithilfe von KEYS.KEYSET_FROM_JSON wieder in BYTES umwandeln.

Rückgabedatentyp

STRING

Beispiel

Die folgende Abfrage gibt ein neues 'AEAD_AES_GCM_256'-Keyset als JSON-formatierten STRING zurück.

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

Das Ergebnis ist ein STRING wie der folgende.

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

Beschreibung

Fügt dem keyset einen neuen Schlüssel basierend auf key_type hinzu. Dieser neue Schlüssel wird zum primären kryptografischen Schlüssel des neuen Keysets. Das neue Keyset wird serialisiert als BYTES zurückgegeben.

Der alte primäre kryptografische Schlüssel aus dem Eingabe-keyset bleibt als zusätzlicher Schlüssel im zurückgegebenen Keyset erhalten.

Der neue key_type muss mit dem Schlüsseltyp der vorhandenen Schlüssel im keyset übereinstimmen.

Rückgabedatentyp

BYTES

Beispiel

Mit der folgenden Anweisung wird eine Tabelle erstellt, die eine Spalte mit eindeutigen customer_id-Werten und Keysets vom Typ 'AEAD_AES_GCM_256' enthält. Anschließend wird mit KEYS.ROTATE_KEYSET in jedem Keyset der Quelltabelle ein neuer primärer kryptografischer Schlüssel erstellt. Jede Zeile in der Ausgabe enthält eine customer_id und ein Keyset vom Typ '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)

Beschreibung

Gibt die Anzahl der Schlüssel im angegebenen Keyset zurück.

Rückgabedatentyp

INT64

Beispiel

In diesem Beispiel wird auf einen JSON-formatierten STRING namens json_keyset verwiesen, der zwei Schlüssel enthält:

{
   "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"
      }
   ]
}

Die folgende Abfrage konvertiert json_keyset in ein Keyset und gibt dann die Anzahl der Schlüssel im Keyset zurück:

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

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