AEAD-Verschlüsselungsfunktionen in Standard-SQL

In den folgenden Abschnitten werden die von BigQuery unterstützten AEAD-Verschlüsselungsfunktionen erläutert. Eine Beschreibung der Funktionalität der AEAD-Verschlüsselungsfunktionen finden Sie unter Konzepte der AEAD-Verschlüsselung in Standard-SQL.

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 ohne 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 STRING-Darstellung vom Typ des Schlüssels, der erstellt werden soll. 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 für jede Zeile in CustomerIds ein Keyset, 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. In jeder Zeile der Ausgabe sind Schlüssel vom Typ customer_id und 'AEAD_AES_GCM_256' in BYTES enthalten.

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 keyset auf der Grundlage von key_type und raw_key_bytes zurück.

Der primäre kryptografische Schlüssel bleibt der gleiche 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 bei Verwendung von Cipher Block Chaining (CBC) oder PKCS-Padding. raw_key_bytes sollte der BYTES-Wert eines Rohschlüssels in 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 Verschlüsselungstypen werden von BigQuery AEAD-Funktionen nicht unterstützt. Es sollten daher Schlüssel vom Typ 'AEAD_AES_GCM_256' oder 'AES_GCM' verwendet werden.
• 'AES_GCM': Erstellt einen Schlüssel für die AES-Entschlüsselung oder -Verschlüsselung im Galois/Counter Mode. raw_key_bytes muss der BYTES-Wert eines Rohschlüssels in 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 für 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 und Rohschlüsselbyte namens CustomerRawKeys sowie eine Tabelle eindeutiger IDs mit der Bezeichnung CustomerIds erstellt. Für jede customer_id-Funktion wird ein neues Keyset vom Typ 'AEAD_AES_GCM_256' angelegt. Anschließend wird unter Verwendung des Wertes von raw_key_bytes, der dieser customer_id-Funktion 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, nutzt 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 sich daraus ergebenden 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 prüft die Integrität der Daten mithilfe von additional_data. Wenn die Entschlüsselung oder Prü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. Dieser Schlüssel muss sich im Status 'ENABLED' befinden, andernfalls gibt die Funktion einen Fehler zurück. AEAD.DECRYPT_BYTES ermittelt den passenden Schlüssel im keyset über die Schlüssel-ID, die mit der ID im verschlüsselten ciphertext übereinstimmt.

ciphertext ist ein BYTES-Wert als Ergebnis eines Aufrufs von AEAD.ENCRYPT, wenn die plaintext-Funktion 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 Wert 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 AEAD_AES_GCM_256-Keysets 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,
      '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;
    

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

Beschreibung

Entspricht AEAD.DECRYPT_BYTES, wobei jedoch ciphertext die BYTES-Ausgabe von AEAD.ENCRYPT ist und die plaintext-Eingabe in AEAD.ENCRYPT vom Typ STRING und nicht vom Typ BYTES 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 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 ein 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 sowie 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 den Eingabe-STRING json_keyset 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 zurückgegeben, etwa wie im Folgenden dargestellt:

\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 etwa 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 anhand von 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-Funktion 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;