표준 SQL의 AEAD 암호화 함수

다음 섹션에서는 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_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         |
+-----------+