다음 섹션에서는 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 함수 중 하나 또는 KEYS.KEYSET_CHAIN에서 반환한 STRUCT로 직렬화된 BYTES 값입니다. keyset에는 ciphertext를 암호화하는 데 사용된 키가 있어야 하고 키 상태는 'ENABLED'여야 합니다. 그렇지 않으면 함수에서 오류가 반환됩니다. AEAD.DECRYPT_BYTES는 ciphertext에 암호화된 키와 키 ID가 일치하는 키를 찾아 keyset에서 일치하는 키를 식별합니다.
ciphertext는 AEAD.ENCRYPT에 호출한 결과인 BYTES 값입니다. 이 때 입력 plaintext의 유형은 BYTES이었습니다.
ciphertext에 초기화 벡터(IV)가 포함된 경우 ciphertext의 첫 번째 바이트여야 합니다. ciphertext에 인증 태그가 포함된 경우 ciphertext의 마지막 바이트여야 합니다. IV 및 인증 태그가 1(SIV)인 경우 ciphertext의 첫 번째 바이트여야 합니다. IV 및 인증 태그에는 일반적으로 16바이트가 필요하지만 크기는 다를 수 있습니다.
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(CAST(customer_id AS STRING) AS BYTES))
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(CAST(customer_id AS STRING) AS BYTES)
) 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 함수 중 하나 또는 KEYS.KEYSET_CHAIN에서 반환한 STRUCT로 직렬화된 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_CHAIN
KEYS.KEYSET_CHAIN(kms_resource_name, first_level_keyset)
설명
AEAD 함수에 대한 keyset 인수 대신 Cloud KMS 키로 암호화된 키 세트를 전달할 수 있습니다. 이렇게 하면 쿼리에 일반 텍스트 키를 포함하지 않고도 AEAD 함수를 사용할 수 있습니다.
kms_resource_name은 first_level_keyset를 복호화하는 데 사용되는 Cloud KMS 키에 대한 리소스 경로를 포함하는 STRING 값입니다. 전체 문자열은 gcp-kms://로 시작해야 하며 gcp-kms://projects/{id}/locations/{location}/keyRings/{id}/cryptoKeys/{id} 형식이어야 합니다.
Cloud KMS 키는 쿼리와 동일한 Cloud 리전에 있어야 합니다.
first_level_keyset는 지정된 KMS 키로 직렬화된 Tink 키 세트를 암호화하여 생성된 암호문을 포함하는 BYTES 값입니다.
kms_resource_name 및 first_level_keyset 모두 상수 값이어야 합니다.
반환 데이터 유형
STRUCT
예시
이 예시에서는 예시 데이터 테이블을 만든 다음 래핑된(암호화된) 키 세트를 사용하여 데이터를 암호화하는 방법을 보여줍니다. 마지막으로 암호화된 버전의 데이터를 쿼리하는 방법을 보여줍니다.
다음 문은 고객 ID 열과 좋아하는 동물 열이 포함된 RawCustomerData 테이블을 만듭니다.
CREATE TABLE aead.RawCustomerData AS
SELECT
1 AS customer_id,
b'jaguar' AS favorite_animal
UNION ALL
SELECT
2 AS customer_id,
b'zebra' AS favorite_animal
UNION ALL
SELECT
3 AS customer_id,
b'nautilus' AS favorite_animal;
다음 문은 고유 ID 열과 암호문 열이 포함된 EncryptedCustomerData 테이블을 만듭니다. 이 문은 제공된 first_level_keyset를 사용하여 일반 텍스트 favorite_animal을 암호화합니다.
SET kms_resource_name = 'gcp-kms://projects/my-project/locations/us/keyRings/my-key-ring/cryptoKeys/my-crypto-key';
SET first_level_keyset = b'\012\044\000\107\275\360\176\264\206\332\235\215\304...';
CREATE TABLE aead.EncryptedCustomerData AS
SELECT
customer_id,
AEAD.ENCRYPT(
KEYS.KEYSET_CHAIN(kms_resource_name, first_level_keyset),
favorite_animal,
CAST(CAST(customer_id AS STRING) AS BYTES)
) AS encrypted_animal
FROM
aead.RawCustomerData;
다음 쿼리는 first_level_keyset를 사용하여 EncryptedCustomerData 테이블의 데이터를 복호화합니다.
SET kms_resource_name = 'gcp-kms://projects/my-project/locations/us/keyRings/my-key-ring/cryptoKeys/my-crypto-key';
SET first_level_keyset = b'\012\044\000\107\275\360\176\264\206\332\235\215\304...';
SELECT
customer_id,
AEAD.DECRYPT_BYTES(
KEYS.KEYSET_CHAIN(kms_resource_name, first_level_keyset)
encrypted_animal,
CAST(CAST(customer_id AS STRING) AS BYTES)
) AS favorite_animal
FROM EncryptedCustomerData;
KEYS.KEYSET_FROM_JSON
KEYS.KEYSET_FROM_JSON(json_keyset)
설명
입력 json_keysetSTRING을 직렬화된 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 |
+-----------+