AEAD-Verschlüsselungsfunktionen in Standard-SQL

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. Derzeit ist AEAD_AES_GCM_256 der einzige unterstützte Wert für key_type. KEYS.NEW_KEYSET(AEAD_AES_GCM_256) erstellt einen 256-Bit-Schlüssel mit dem von OpenSSL bereitgestellten Pseudozufallszahlengenerator. Der Schlüssel verwendet AES-GCM 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 zurückgegeben wird. keyset muss den Schlüssel enthalten, der zum Verschlüsseln von ciphertext verwendet wurde, und der Schlüssel muss sich in einem 'ENABLED'-Status 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.

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(customer_id AS STRING))
   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(ecd.customer_id AS STRING)
  ) 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 den Klartext mithilfe des Algorithmus und des primären kryptografischen Schlüssels im keyset. 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 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, es sei denn, dieser Schlüssel ist ein 'AES_GCM'-Schlüssel.

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;

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.

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         |
+-----------+