以下のセクションでは、BigQuery でサポートされている AEAD 暗号化関数について説明します。AEAD 暗号化関数については、AEAD 暗号化のコンセプトをご覧ください。
KEYS.NEW_KEYSET
KEYS.NEW_KEYSET(key_type)
説明
key_type
に基づく新しいキーを含むシリアル化されたキーセットを返します。返されるキーセットは、BYTES
のシリアル化された google.crypto.tink.Keyset 表現で、主暗号鍵を含み、追加のキーは含まれていません。暗号化と復号のための、AEAD.ENCRYPT
、AEAD.DECRYPT_BYTES
、AEAD.DECRYPT_STRING
関数、およびキーセット関連関数の KEYS
グループとともにキーセットを使用できます。
key_type
は、作成するキータイプの STRING
リテラル表現です。key_type
を NULL
にすることはできません。現時点で key_type
をサポートする唯一の値は、AEAD_AES_GCM_256
です。KEYS.NEW_KEYSET(AEAD_AES_GCM_256)
は、OpenSSL が提供する擬似乱数生成を使用して 256 ビットのキーを作成します。キーは、暗号化および復号操作に AES-GCM を使用します。
戻りデータの型
BYTES
例
次のクエリは、CustomerIds
各行のキーセットを作成し、続いてデータの暗号化に使用します。各キーセットには、ランダムに生成されたキーデータを含む単一の暗号鍵が含まれています。出力の各行には、customer_id
が含まれ、BYTES
には 'AEAD_AES_GCM_256'
が含まれています。
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)
説明
key_type
と raw_key_bytes
に基づいて keyset
にキーを追加した、シリアル化されたキーセットを BYTES
として返します。
主暗号キーは keyset
と同じです。予想される raw_key_bytes
の長さは、key_type
の値によって異なります。サポートされている key_types
は次のとおりです。
'AES_CBC_PKCS'
: 暗号化ブロック チェーンと PKCS パディングを使用して AES 復号用のキーを作成します。raw_key_bytes
は、長さ 16、24、32 の未加工のキーBYTES
の値であると予想されています。これらの長さは、それぞれ 128、192、256 ビットサイズです。BigQuery の AEAD 関数は、これらの型の暗号化のキーをサポートしていません。代わりに'AEAD_AES_GCM_256'
または'AES_GCM'
キーを使用します。'AES_GCM'
: Galois / Counter Mode を使用して AES 復号または暗号化用のキーを作成します。raw_key_bytes
は、長さ 16 または 32 の未加工のキーBYTES
値でなければなりません。これらの長さは、それぞれ 128 ビットと 256 ビットのサイズです。このタイプのキーがAEAD.ENCRYPT
への入力である場合、出力暗号テキストには、どのキーが入力として使用されたかを示す Tink 固有の接頭辞がありません。
戻りデータの型
BYTES
例
次のクエリは、CustomerRawKeys
という名前の未加工のキーバイトとともに顧客の ID テーブルを作成します。また、CustomerIds
と呼ばれる固有の顧客 ID のテーブルも作成します。customer_id
ごとに新しい 'AEAD_AES_GCM_256'
キーセットを作成し、次に、その customer_id
に対応する raw_key_bytes
値を使用して、各キーセットに新しいキーを追加します。出力は、各行に customer_id
と BYTES
のキーセットが含まれるテーブルです。このテーブルには、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;
出力キーセットにはそれぞれ、以下の 2 つが含まれています。KEYS.NEW_KEYSET('AEAD_AES_GCM_256')
を使用して作成された主暗号キーと、KEYS.ADD_KEY_FROM_RAW_BYTES
を使用して追加された未加工のキーです。出力内のキーセットが AEAD.ENCRYPT
とともに使用されている場合、BigQuery は KEYS.NEW_KEYSET('AEAD_AES_GCM_256')
を使用して作成された主暗号キーを使用して入力平文を暗号化します。キーセットが AEAD.DECRYPT_STRING
または AEAD.DECRYPT_BYTES
とともに使用されている場合、いずれかのキーで暗号文の復号に成功した場合、BigQuery は結果の平文を返します。
AEAD.DECRYPT_BYTES
AEAD.DECRYPT_BYTES(keyset, ciphertext, additional_data)
説明
keyset
の中の一致するキーを使用して暗号 ciphertext
を復号し、additional_data
を使用してデータの整合性を検証します。復号や検証が失敗した場合はエラーが返されます。
keyset
は、KEYS
関数の 1 つによって返されるシリアル化された BYTES
値です。keyset
は、暗号化 ciphertext
に使用されたキーを含んでいなければならず、そのキーは 'ENABLED'
状態になっていなければなりません。そうでなければ、関数はエラーを返します。AEAD.DECRYPT_BYTES
は、keyset
で暗号化されたキーと一致するキー ID を持つキーを見つけることによって、ciphertext
内の一致するキーを識別します。
ciphertext
は、入力 plaintext
が BYTES
型であった場合の AEAD.ENCRYPT
呼び出しの結果である BYTES
値です。
additional_data
は、暗号化されたデータの信頼性と整合性を保証する STRING
または BYTES
値です。この関数は、任意の STRING
値 を BYTES
にキャストします。これは、タイプを無視して ciphertext
を暗号化するために AEAD.ENCRYPT
に提供された additional_data
と同じでなければなりません。そうでなければ、関数はエラーを返します。
戻りデータの型
BYTES
例
この例では、関連付けられた平文値とキーセットを使用して一意の ID のテーブルを作成します。その後、これらのキーセットを使用して平文値を BYTES
として暗号化し、新しいテーブルに格納します。最後に、AEAD.DECRYPT_BYTES
を使用して暗号化された値を復号し、それらを平文として表示します。
次の構文は、一意の ID の列、AEAD_AES_GCM_256
キーセットの列、お気に入りの動物の列を含むテーブル CustomerKeysets
を作成します。
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;
次の文は、一意の ID の列と暗号文の列を含むテーブル EncryptedCustomerData
を作成します。この構文は、各固有の ID に対応する CustomerKeysets
のキーセット値を使用して、平文の favorite_animal
を暗号化します。
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;
次のクエリでは、CustomerKeysets
テーブルのキーセットを使用して 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(ecd.customer_id AS STRING)
) AS favorite_animal
FROM aead.EncryptedCustomerData AS ecd;
AEAD.DECRYPT_STRING
AEAD.DECRYPT_STRING(keyset, ciphertext, additional_data)
説明
AEAD.DECRYPT_BYTES
と類似していますが、plaintext
は STRING
型です。
戻りデータの型
STRING
AEAD.ENCRYPT
AEAD.ENCRYPT(keyset, plaintext, additional_data)
説明
keyset
内のアルゴリズムと主暗号キーを使用して平文を暗号化します。返された暗号文に additional_data
を組み込みます。いずれかの入力が NULL
の場合は NULL
を返します。
keyset
は、KEYS
関数の 1 つによって返されるシリアル化された BYTES
値です。
plaintext
は、暗号化対象の STRING
または BYTES
値です。
additional_data
は、返された暗号文に組み込む STRING
または BYTES
値です。plaintext
と additional_data
は同じ型でなければなりません。AEAD.ENCRYPT(keyset, string1, string2)
は、AEAD.ENCRYPT(keyset, CAST(string1 AS BYTES), CAST(string2 AS BYTES))
と同等です。
出力は暗号文 BYTES
です。暗号文には、暗号化の実行に使用されたキーを示す Tink 固有の接頭辞が含まれます。ただし、そのキーが 'AES_GCM'
キーである場合は除きます。
戻りデータの型
BYTES
例
次のクエリは、CustomerKeysets
テーブル内の各 customer_id
のキーセットを使用して、その customer_id
に対応する PlaintextCustomerData
テーブル内の平文 favorite_animal
の値を暗号化します。出力には、customer_id
値の列と、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)
説明
入力 json_keyset
STRING
をシリアル化された BYTES
として返します。これは、他の KEYS
や AEAD
関数に対する有効な入力です。JSON STRING
は、google.crypto.tink.Keyset プロトコル バッファ メッセージの定義と互換性が必要です。JSON キーセットは、google.crypto.tink.Keyset 定義における「キーセット」メッセージ内のものと対応するオブジェクトと名前値ペアを含む JSON オブジェクトである必要があります。KEYS.KEYSET_TO_JSON
を使用して、出力がシリアル化された BYTES
表現を JSON STRING
に戻すことができます。
戻りデータの型
BYTES
例
KEYS.KEYSET_FROM_JSON
は、次のような JSON 形式の STRING
値を取ります。
{
"key":[
{
"keyData":{
"keyMaterialType":"SYMMETRIC",
"typeUrl":"type.googleapis.com/google.crypto.tink.AesGcmKey",
"value":"GiD80Z8kL6AP3iSNHhqseZGAIvq7TVQzClT7FQy8YwK3OQ=="
},
"keyId":3101427138,
"outputPrefixType":"TINK",
"status":"ENABLED"
}
],
"primaryKeyId":3101427138
}
次のクエリは、JSON 形式の STRING
json_keyset
から新しいキーセットを作成します。
SELECT KEYS.KEYSET_FROM_JSON(json_keyset);
次のように、BYTES
としてシリアル化された json_keyset
を返します。
\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)
説明
入力 keyset
の JSON STRING
表現を返します。返された JSON STRING
は、 google.crypto.tink.Keyset プロトコル バッファ メッセージの定義と互換性があります。KEYS.KEYSET_FROM_JSON
を使用して JSON STRING
表現を BYTES
に戻すことができます。
戻りデータの型
STRING
例
次のクエリは、新しい 'AEAD_AES_GCM_256'
キーセットを JSON 形式の STRING
として返します。
SELECT KEYS.KEYSET_TO_JSON(KEYS.NEW_KEYSET('AEAD_AES_GCM_256'));
表示される結果は、以下のような STRING
です。
{
"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)
説明
key_type
に基づく新しいキーを keyset
に追加します。この新しいキーが新しいキーセットの主暗号キーになります。BYTES
としてシリアル化された新しいキーセットを返します。
入力 keyset
の古い主暗号キーは、返されたキーセットの追加キーのままです。
戻りデータの型
BYTES
例
次の構文は、一意の customer_id
値と 'AEAD_AES_GCM_256'
キーセットの列を含むテーブルを作成します。次に、KEYS.ROTATE_KEYSET
を使用して、ソーステーブルの各キーセット内に新しい主暗号キーを作成します。出力の各行には、BYTES
内の customer_id
と 'AEAD_AES_GCM_256'
キーセットが含まれています。
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)
説明
指定されたキーセット内のキーの数を返します。
戻りデータの型
INT64
例
この例では、2 つのキーを含む json_keyset
という JSON 形式の文字列を参照しています。
{
"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"
}
]
}
次のクエリは、json_keyset
をキーセットに変換してから、キーセット内のキーの数を返します。
SELECT KEYS.KEYSET_LENGTH(KEYS.KEYSET_FROM_JSON(json_keyset)) as key_count;
+-----------+
| key_count |
+-----------+
| 2 |
+-----------+