다음 섹션에서는 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,
'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;
다음 문은 고유 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_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)
설명
AEAD.DECRYPT_BYTES와 마찬가지로 ciphertext는 AEAD.ENCRYPT의 BYTES 출력입니다. 이때 AEAD.ENCRYPT에 대한 plaintext 입력은 BYTES 유형이 아닌 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;