다음 섹션에서는 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
의 각 행에 키 세트를 만들며, 이 키 세트는 나중에 데이터를 암호화하는 데 사용됩니다. 각 키 세트에는 단일 암호화 키와 임의로 생성된 키 데이터가 있습니다. 출력의 각 행에는 BYTES
형식의 customer_id
및 '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)
설명
BYTES
형식의 직렬화된 키 세트와 함께 key_type
및 raw_key_bytes
를 기반으로 한 keyset
에 대한 키를 반환합니다.
기본 암호화 키는 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
라는 원시 키 바이트 및 CustomerIds
라는 고유 ID 테이블과 함께 고객 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;
각 출력 키 세트에는 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
함수 중 한 개가 반환되는 직렬화된 BYTES
값입니다. keyset
에는 ciphertext
를 암호화하는 데 사용된 키가 있어야 하고 키 상태는 'ENABLED'
여야 합니다. 그렇지 않으면 함수에서 오류가 반환됩니다. AEAD.DECRYPT_BYTES
는 ciphertext
에 암호화된 키와 키 ID가 일치하는 키를 찾아 keyset
에서 일치하는 키를 식별합니다.
ciphertext
는 AEAD.ENCRYPT
에 호출한 결과인 BYTES
값입니다. 이 때 입력 plaintext
의 유형은 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
함수 중 한 개가 반환되는 직렬화된 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
입니다. 키가 'AES_GCM'
키인 경우를 제외하고 암호문에는 암호화를 수행하는 데 사용된 키를 나타내는 Tink 관련 프리픽스가 포함됩니다.
반환 데이터 유형
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 객체여야 합니다. 출력 직렬화된 BYTES
표현을 KEYS.KEYSET_TO_JSON
을 사용하여 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
예시
이 예시에서는 두 개의 키가 포함된 json_keyset
라는 JSON 형식의 STRING을 참조합니다.
{
"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 |
+-----------+