데이터를 암호화하고 싶습니다.

대부분의 데이터 암호화 사용 사례에는AEAD 키 유형이 있는 AES128_GCM 기본을 사용하는 것이 좋습니다.

연관 데이터로 암호화 인증 (AEAD)은 대부분의 사용 사례에 가장 간단하고 적합한 기본입니다. AEAD는 비밀성과 신뢰성을 제공하며 일반 텍스트(암호화의 입력)가 동일하더라도 메시지에 항상 다른 암호문 (암호화된 출력)이 있도록 합니다. 대칭이며 암호화와 복호화 모두에 단일 키를 사용합니다.

다음 예시를 통해 AEAD 기본 사용을 시작할 수 있습니다.

C++

// A command-line utility for testing Tink AEAD.
#include <iostream>
#include <memory>
#include <string>

#include "absl/flags/flag.h"
#include "absl/flags/parse.h"
#include "absl/log/absl_check.h"
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include "absl/strings/string_view.h"
#include "tink/aead.h"
#include "tink/aead/config_v0.h"
#include "util/util.h"
#include "tink/keyset_handle.h"

ABSL_FLAG(std::string, keyset_filename, "", "Keyset file in JSON format");
ABSL_FLAG(std::string, mode, "", "Mode of operation {encrypt|decrypt}");
ABSL_FLAG(std::string, input_filename, "", "Filename to operate on");
ABSL_FLAG(std::string, output_filename, "", "Output file name");
ABSL_FLAG(std::string, associated_data, "",
          "Associated data for AEAD (default: empty");

namespace {

using ::crypto::tink::Aead;
using ::crypto::tink::KeysetHandle;

constexpr absl::string_view kEncrypt = "encrypt";
constexpr absl::string_view kDecrypt = "decrypt";

void ValidateParams() {
  // ...
}

}  // namespace

namespace tink_cc_examples {

// AEAD example CLI implementation.
absl::Status AeadCli(absl::string_view mode, const std::string& keyset_filename,
                     const std::string& input_filename,
                     const std::string& output_filename,
                     absl::string_view associated_data) {
  // Read the keyset from file.
  absl::StatusOr<std::unique_ptr<KeysetHandle>> keyset_handle =
      ReadJsonCleartextKeyset(keyset_filename);
  if (!keyset_handle.ok()) return keyset_handle.status();

  // Get the primitive.
  absl::StatusOr<std::unique_ptr<Aead>> aead =
      (*keyset_handle)
          ->GetPrimitive<crypto::tink::Aead>(crypto::tink::ConfigAeadV0());
  if (!aead.ok()) return aead.status();

  // Read the input.
  absl::StatusOr<std::string> input_file_content = ReadFile(input_filename);
  if (!input_file_content.ok()) return input_file_content.status();

  // Compute the output.
  std::string output;
  if (mode == kEncrypt) {
    absl::StatusOr<std::string> encrypt_result =
        (*aead)->Encrypt(*input_file_content, associated_data);
    if (!encrypt_result.ok()) return encrypt_result.status();
    output = encrypt_result.value();
  } else {  // operation == kDecrypt.
    absl::StatusOr<std::string> decrypt_result =
        (*aead)->Decrypt(*input_file_content, associated_data);
    if (!decrypt_result.ok()) return decrypt_result.status();
    output = decrypt_result.value();
  }

  // Write the output to the output file.
  return WriteToFile(output, output_filename);
}

}  // namespace tink_cc_examples

int main(int argc, char** argv) {
  absl::ParseCommandLine(argc, argv);

  ValidateParams();

  std::string mode = absl::GetFlag(FLAGS_mode);
  std::string keyset_filename = absl::GetFlag(FLAGS_keyset_filename);
  std::string input_filename = absl::GetFlag(FLAGS_input_filename);
  std::string output_filename = absl::GetFlag(FLAGS_output_filename);
  std::string associated_data = absl::GetFlag(FLAGS_associated_data);

  std::clog << "Using keyset from file " << keyset_filename << " to AEAD-"
            << mode << " file " << input_filename << " with associated data '"
            << associated_data << "'." << '\n';
  std::clog << "The resulting output will be written to " << output_filename
            << '\n';

  ABSL_CHECK_OK(tink_cc_examples::AeadCli(mode, keyset_filename, input_filename,
                                          output_filename, associated_data));
  return 0;
}

Go

import (
	"bytes"
	"fmt"
	"log"

	"github.com/tink-crypto/tink-go/v2/aead"
	"github.com/tink-crypto/tink-go/v2/insecurecleartextkeyset"
	"github.com/tink-crypto/tink-go/v2/keyset"
)

func Example() {
	// A keyset created with "tinkey create-keyset --key-template=AES256_GCM". Note
	// that this keyset has the secret key information in cleartext.
	jsonKeyset := `{
			"key": [{
					"keyData": {
							"keyMaterialType":
									"SYMMETRIC",
							"typeUrl":
									"type.googleapis.com/google.crypto.tink.AesGcmKey",
							"value":
									"GiBWyUfGgYk3RTRhj/LIUzSudIWlyjCftCOypTr0jCNSLg=="
					},
					"keyId": 294406504,
					"outputPrefixType": "TINK",
					"status": "ENABLED"
			}],
			"primaryKeyId": 294406504
	}`

	// Create a keyset handle from the cleartext keyset in the previous
	// step. The keyset handle provides abstract access to the underlying keyset to
	// limit the exposure of accessing the raw key material. WARNING: In practice,
	// it is unlikely you will want to use a insecurecleartextkeyset, as it implies
	// that your key material is passed in cleartext, which is a security risk.
	// Consider encrypting it with a remote key in Cloud KMS, AWS KMS or HashiCorp Vault.
	// See https://github.com/google/tink/blob/master/docs/GOLANG-HOWTO.md#storing-and-loading-existing-keysets.
	keysetHandle, err := insecurecleartextkeyset.Read(
		keyset.NewJSONReader(bytes.NewBufferString(jsonKeyset)))
	if err != nil {
		log.Fatal(err)
	}

	// Retrieve the AEAD primitive we want to use from the keyset handle.
	primitive, err := aead.New(keysetHandle)
	if err != nil {
		log.Fatal(err)
	}

	// Use the primitive to encrypt a message. In this case the primary key of the
	// keyset will be used (which is also the only key in this example).
	plaintext := []byte("message")
	associatedData := []byte("associated data")
	ciphertext, err := primitive.Encrypt(plaintext, associatedData)
	if err != nil {
		log.Fatal(err)
	}

	// Use the primitive to decrypt the message. Decrypt finds the correct key in
	// the keyset and decrypts the ciphertext. If no key is found or decryption
	// fails, it returns an error.
	decrypted, err := primitive.Decrypt(ciphertext, associatedData)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(decrypted))
	// Output: message
}

자바

package aead;

import static java.nio.charset.StandardCharsets.UTF_8;

import com.google.crypto.tink.Aead;
import com.google.crypto.tink.InsecureSecretKeyAccess;
import com.google.crypto.tink.KeysetHandle;
import com.google.crypto.tink.RegistryConfiguration;
import com.google.crypto.tink.TinkJsonProtoKeysetFormat;
import com.google.crypto.tink.aead.AeadConfig;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;

/**
 * A command-line utility for encrypting small files with AEAD.
 *
 * <p>It loads cleartext keys from disk - this is not recommended!
 *
 * <p>It requires the following arguments:
 *
 * <ul>
 *   <li>mode: Can be "encrypt" or "decrypt" to encrypt/decrypt the input to the output.
 *   <li>key-file: Read the key material from this file.
 *   <li>input-file: Read the input from this file.
 *   <li>output-file: Write the result to this file.
 *   <li>[optional] associated-data: Associated data used for the encryption or decryption.
 */
public final class AeadExample {
  private static final String MODE_ENCRYPT = "encrypt";
  private static final String MODE_DECRYPT = "decrypt";

  public static void main(String[] args) throws Exception {
    if (args.length != 4 && args.length != 5) {
      System.err.printf("Expected 4 or 5 parameters, got %d\n", args.length);
      System.err.println(
          "Usage: java AeadExample encrypt/decrypt key-file input-file output-file"
              + " [associated-data]");
      System.exit(1);
    }
    String mode = args[0];
    Path keyFile = Paths.get(args[1]);
    Path inputFile = Paths.get(args[2]);
    Path outputFile = Paths.get(args[3]);
    byte[] associatedData = new byte[0];
    if (args.length == 5) {
      associatedData = args[4].getBytes(UTF_8);
    }
    // Register all AEAD key types with the Tink runtime.
    AeadConfig.register();

    // Read the keyset into a KeysetHandle.
    KeysetHandle handle =
        TinkJsonProtoKeysetFormat.parseKeyset(
            new String(Files.readAllBytes(keyFile), UTF_8), InsecureSecretKeyAccess.get());

    // Get the primitive.
    Aead aead = handle.getPrimitive(RegistryConfiguration.get(), Aead.class);

    // Use the primitive to encrypt/decrypt files.
    if (MODE_ENCRYPT.equals(mode)) {
      byte[] plaintext = Files.readAllBytes(inputFile);
      byte[] ciphertext = aead.encrypt(plaintext, associatedData);
      Files.write(outputFile, ciphertext);
    } else if (MODE_DECRYPT.equals(mode)) {
      byte[] ciphertext = Files.readAllBytes(inputFile);
      byte[] plaintext = aead.decrypt(ciphertext, associatedData);
      Files.write(outputFile, plaintext);
    } else {
      System.err.println("The first argument must be either encrypt or decrypt, got: " + mode);
      System.exit(1);
    }
  }

  private AeadExample() {}
}

Obj-C

사용 안내

Python

import tink
from tink import aead
from tink import secret_key_access


def example():
  """Encrypt and decrypt using AEAD."""
  # Register the AEAD key managers. This is needed to create an Aead primitive
  # later.
  aead.register()

  # A keyset created with "tinkey create-keyset --key-template=AES256_GCM". Note
  # that this keyset has the secret key information in cleartext.
  keyset = r"""{
      "key": [{
          "keyData": {
              "keyMaterialType":
                  "SYMMETRIC",
              "typeUrl":
                  "type.googleapis.com/google.crypto.tink.AesGcmKey",
              "value":
                  "GiBWyUfGgYk3RTRhj/LIUzSudIWlyjCftCOypTr0jCNSLg=="
          },
          "keyId": 294406504,
          "outputPrefixType": "TINK",
          "status": "ENABLED"
      }],
      "primaryKeyId": 294406504
  }"""

  # Create a keyset handle from the cleartext keyset in the previous
  # step. The keyset handle provides abstract access to the underlying keyset to
  # limit access of the raw key material. WARNING: In practice, it is unlikely
  # you will want to use a cleartext_keyset_handle, as it implies that your key
  # material is passed in cleartext, which is a security risk.
  keyset_handle = tink.json_proto_keyset_format.parse(
      keyset, secret_key_access.TOKEN
  )

  # Retrieve the Aead primitive we want to use from the keyset handle.
  primitive = keyset_handle.primitive(aead.Aead)

  # Use the primitive to encrypt a message. In this case the primary key of the
  # keyset will be used (which is also the only key in this example).
  ciphertext = primitive.encrypt(b'msg', b'associated_data')

  # Use the primitive to decrypt the message. Decrypt finds the correct key in
  # the keyset and decrypts the ciphertext. If no key is found or decryption
  # fails, it raises an error.
  output = primitive.decrypt(ciphertext, b'associated_data')

AEAD

연관 데이터로 암호화 인증 (AEAD) 기본은 데이터 암호화에 가장 일반적인 기본이며 대부분의 요구사항에 적합합니다.

AEAD에는 다음과 같은 속성이 있습니다.

  • Secrecy: 일반 텍스트의 길이를 제외하고는 일반 텍스트에 관해 알려진 것이 없습니다.
  • 신뢰성: 암호문 아래에 있는 암호화된 일반 텍스트를 감지되지 않고 변경할 수 없습니다.
  • 대칭: 일반 텍스트 암호화 및 암호문 복호화는 동일한 키로 실행됩니다.
  • 랜덤화: 암호화는 랜덤화됩니다. 일반 텍스트가 동일한 두 메시지는 서로 다른 암호문을 생성합니다. 공격자는 특정 일반 텍스트에 해당하는 암호문을 알 수 없습니다. 이를 방지하려면 결정적 AEAD를 대신 사용하세요.

관련 데이터

AEAD를 사용하여 암호문을 특정 관련 데이터에 연결할 수 있습니다. user-idencrypted-medical-history 필드가 있는 데이터베이스가 있다고 가정해 보겠습니다. 이 시나리오에서는 encrypted-medical-history를 암호화할 때 user-id를 관련 데이터로 사용할 수 있습니다. 이렇게 하면 공격자가 한 사용자의 의료 기록을 다른 사용자로 이동할 수 없습니다.

관련 데이터는 선택사항입니다. 지정된 경우 동일한 관련 데이터가 암호화 및 복호화 호출 모두에 전달되는 경우에만 복호화가 성공합니다.

키 유형 선택

대부분의 용도에는 AES128_GCM 이 권장되지만 다양한 요구사항에 맞는 다양한 키 유형이 있습니다. AES128은 128비트 보안을 제공하고 AES256은 256비트 보안을 제공합니다.

모드를 선택할 때 주목할 만한 두 가지 보안 제약조건은 다음과 같습니다.

  1. QPS: 동일한 키로 암호화된 메시지는 몇 개입니까?
  2. 메시지 크기: 메시지 크기는 얼마나 됩니까?

지원되는 키 유형:

  • 16바이트 초기화 벡터 (IV)가 있는 AES-CTR-HMAC (AES128_CTR_HMAC_SHA256, AES256_CTR_HMAC_SHA256)는 경계가 좋은 가장 보수적인 모드입니다.
    • 키 커밋.
  • AES-EAX (AES128_EAX, AES256_EAX)는 AES128_CTR_HMAC_SHA256보다 약간 덜 보수적이고 약간 더 빠릅니다.
    • 키 커밋 MLGR이 아닙니다.
  • AES-GCM (AES128_GCM, AES256_GCM)은 일반적으로 메시지 수와 메시지 크기에 가장 엄격한 제한이 있는 가장 빠른 모드입니다. 일반 텍스트 및 관련 데이터 길이 (아래)에 대한 이러한 제한을 초과하면 AES-GCM은 일반 텍스트와 AES-GCM 내부 키의 인증 부분을 유출하여 치명적으로 실패합니다.
    • AES-GCM은 강력하지 않으며[ABN] 키 커밋[GLR]도 아닙니다. 두 개의 서로 다른 키로 복호화할 수 있는 암호문을 생성할 수 있습니다. 이로 인해 실제 공격 [DGRW]이 발생할 수 있습니다. 상대가 키를 선택하는 경우 위협 모델을 신중하게 검토하세요.
  • AES-GCM-SIV (AES128_GCM_SIV, AES256_GCM_SIV)는 AES-GCM과 거의 동일한 속도입니다. 메시지 수와 메시지 크기에 대한 제한은 AES-GCM과 동일하지만 이러한 제한을 초과하면 덜 치명적인 방식으로 실패합니다. 즉, 두 메시지가 동일하다는 사실만 유출될 수 있습니다. 따라서 AES-GCM보다 안전하게 사용할 수 있지만 실제로는 널리 사용되지 않습니다. 자바에서 이를 사용하려면 Conscrypt를 설치해야 합니다.
    • 키 커밋 ADGKLS가 아닙니다.
  • XChaCha20-Poly1305 (XCHACHA20_POLY1305)는 AES-GCM보다 메시지 수와 메시지 크기에 대한 제한이 훨씬 크지만 실패하는 경우(매우 드물지만) 키 자료도 유출합니다. 하드웨어 가속화되지 않으므로 하드웨어 가속화가 가능한 상황에서는 AES 모드보다 느릴 수 있습니다.
    • 키 커밋 LGR이 아닙니다.

AEAD 암호문의 와이어 형식에 대해 자세히 알아보세요.

보안 보장

AEAD 구현은 다음을 제공합니다.

  • CCA2 보안.
  • 최소 80비트 인증 강도.
  • 총 250바이트로 메시지를 232개 이상 암호화하는 기능. 선택한 일반 텍스트 또는 선택한 암호문이 최대 232개인 공격의 성공 확률은 2-32보다 크지 않습니다.