Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Cloud KMS에서 클라이언트 측 암호화를 사용하고 싶습니다.

Tink를 사용하면 일부 데이터를 클라이언트 측 암호화하고 클라우드 KMS를 사용하여 키를 보호할 수 있습니다. 작동 방식은 다음과 같습니다.

클라이언트가 데이터 암호화 키 (DEK)를 생성합니다.
클라이언트가 DEK를 사용하여 데이터를 암호화합니다.
DEK는 클라우드 KMS에 저장된 키 암호화 키 (KEK)로 암호화됩니다.

Cloud KMS를 사용하면 KEK가 클라우드에 안전하게 저장되므로 필요에 따라 KEK를 순환하거나 비활성화하거나 폐기할 수 있습니다.

Tink가 클라우드 KMS와 상호작용하는 데 필요한 사항에 관한 자세한 내용은 키 관리 개요 섹션을 참고하세요.

Tink를 사용하면 다음과 같은 두 가지 방법으로 클라우드 KMS를 사용하여 클라이언트 측 암호화를 실행할 수 있습니다.

KMS 봉투 AEAD 기본 요소 (KmsEnvelopeAead) 사용: 모든 암호화에 대해 Tink는 새 AEAD DEK를 만들고, Cloud KMS KEK로 암호화하고, 암호문의 일부로 저장하므로 DEK를 직접 처리할 필요가 없습니다. 따라서 암호화된 DEK가 포함되어 있으므로 암호문이 약간 더 깁니다. 또한 암호화하거나 복호화할 때마다 Tink는 KMS에 RPC를 실행합니다 (데이터의 실제 복호화 또는 암호화는 로컬에서 실행됨).
다른 기본 요소를 사용하고 클라우드 KMS로 키 세트 암호화: AEAD 이외의 다른 기본 요소를 사용할 수 있고 클라우드 KMS에 대한 호출을 제한할 수 있어 더 유연합니다.

KMS 봉투 AEAD

KmsEnvelopeAead 기본 요소로 데이터를 암호화하면 Tink에서 다음 작업을 실행합니다.

무작위 DEK를 생성하고 이를 사용하여 데이터를 로컬로 암호화합니다.
KMS KEK로 DEK를 암호화하도록 KMS에 요청합니다.
KEK로 암호화된 암호화 DEK를 암호화된 데이터와 연결합니다.

DEK 유형과 KEK URI는 모두 KmsEnvelopeAead 키에 지정됩니다. 복호화할 때 Tink는 역 작업을 실행합니다.

KEK로 암호화된 DEK 키를 추출합니다.
KMS에 KEK로 암호화된 DEK를 복호화하도록 요청합니다.
DEK를 사용하여 로컬에서 암호문을 복호화합니다.

다음 예에서는 KmsEnvelopeAead 기본 요소를 사용하는 방법을 보여줍니다.

C++

이 예시에는 Google Cloud KMS 확장 프로그램 tink-cc-gcpkms이 필요합니다.

// A command-line utility for testing Tink Envelope AEAD with Google Cloud KMS.
#include <fstream>
#include <iostream>
#include <memory>
#include <ostream>
#include <sstream>
#include <string>
#include <utility>

#include "absl/flags/parse.h"
#include "absl/flags/flag.h"
#include "absl/log/check.h"
#include "absl/log/log.h"
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include "absl/strings/str_cat.h"
#include "absl/strings/string_view.h"
#include "tink/aead.h"
#include "tink/aead/aead_config.h"
#include "tink/aead/aead_key_templates.h"
#include "tink/aead/kms_envelope_aead.h"
#include "tink/integration/gcpkms/gcp_kms_client.h"
#include "proto/tink.pb.h"

ABSL_FLAG(std::string, mode, "", "Mode of operation {encrypt|decrypt}");
ABSL_FLAG(std::string, kek_uri, "", "URI of the KMS Key Encryption Key to use");
ABSL_FLAG(std::string, input_filename, "", "Input file name");
ABSL_FLAG(std::string, output_filename, "", "Output file name");
ABSL_FLAG(std::string, credentials, "",
          "Optional Google Cloud KMS credentials file path; if not specified, "
          "use the default credentials");
ABSL_FLAG(std::string, associated_data, "", "Optional associated data");

namespace {

using ::crypto::tink::Aead;
using ::crypto::tink::AeadKeyTemplates;
using ::crypto::tink::integration::gcpkms::GcpKmsClient;
using ::google::crypto::tink::KeyTemplate;

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

void ValidateParams() {
  // ...
}

absl::StatusOr<std::string> ReadFile(absl::string_view filename) {
  // ...
}

absl::Status WriteToFile(absl::string_view data_to_write,
                         absl::string_view filename) {
  // ...
}

}  // namespace

namespace tink_cc_gcpkms_examples {

void KmsEnvelopAeadCli(absl::string_view mode, absl::string_view kek_uri,
                       absl::string_view input_filename,
                       absl::string_view output_filename,
                       absl::string_view credentials,
                       absl::string_view associated_data) {
  CHECK_OK(crypto::tink::AeadConfig::Register());
  // Obtain a remote Aead that can use the KEK.
  absl::StatusOr<std::unique_ptr<GcpKmsClient>> gcp_kms_client =
      GcpKmsClient::New(kek_uri, credentials);
  CHECK_OK(gcp_kms_client.status());
  absl::StatusOr<std::unique_ptr<Aead>> remote_aead =
      (*gcp_kms_client)->GetAead(kek_uri);
  CHECK_OK(remote_aead.status());
  // Define the DEK template.
  KeyTemplate dek_key_template = AeadKeyTemplates::Aes256Gcm();
  // Create a KmsEnvelopeAead instance.
  absl::StatusOr<std::unique_ptr<Aead>> aead =
      crypto::tink::KmsEnvelopeAead::New(dek_key_template,
                                         *std::move(remote_aead));
  CHECK_OK(aead.status());

  absl::StatusOr<std::string> input_file_content = ReadFile(input_filename);
  CHECK_OK(input_file_content.status());
  if (mode == kEncrypt) {
    // Generate the ciphertext.
    absl::StatusOr<std::string> encrypt_result =
        (*aead)->Encrypt(*input_file_content, associated_data);
    CHECK_OK(encrypt_result.status());
    CHECK_OK(WriteToFile(encrypt_result.value(), output_filename));
  } else {  // mode == kDecrypt.
    // Recover the plaintext.
    absl::StatusOr<std::string> decrypt_result =
        (*aead)->Decrypt(*input_file_content, associated_data);
    CHECK_OK(decrypt_result.status());
    CHECK_OK(WriteToFile(decrypt_result.value(), output_filename));
  }
}

}  // namespace tink_cc_gcpkms_examples

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

  ValidateParams();

  std::string mode = absl::GetFlag(FLAGS_mode);
  std::string kek_uri = absl::GetFlag(FLAGS_kek_uri);
  std::string input_filename = absl::GetFlag(FLAGS_input_filename);
  std::string output_filename = absl::GetFlag(FLAGS_output_filename);
  std::string credentials = absl::GetFlag(FLAGS_credentials);
  std::string associated_data = absl::GetFlag(FLAGS_associated_data);

  LOG(INFO) << "Using kek-uri " << kek_uri << " with "
            << (credentials.empty()
                    ? "default credentials"
                    : absl::StrCat("credentials file ", credentials))
            << " to envelope " << mode << " file " << input_filename
            << " with associated data '" << associated_data << "'." << '\n';
  LOG(INFO) << "The resulting output will be written to " << output_filename
            << '\n';

  tink_cc_gcpkms_examples::KmsEnvelopAeadCli(mode, kek_uri, input_filename,
                                             output_filename, credentials,
                                             associated_data);
  return 0;
}envelopeaead_cli.cc

Go

import (
	"fmt"
	"log"

	"github.com/tink-crypto/tink-go/v2/aead"
	"github.com/tink-crypto/tink-go/v2/testing/fakekms"
)

// The fake KMS should only be used in tests. It is not secure.
const keyURI = "fake-kms://CM2b3_MDElQKSAowdHlwZS5nb29nbGVhcGlzLmNvbS9nb29nbGUuY3J5cHRvLnRpbmsuQWVzR2NtS2V5EhIaEIK75t5L-adlUwVhWvRuWUwYARABGM2b3_MDIAE"

func Example_kmsEnvelopeAEAD() {
	// Get a KEK (key encryption key) AEAD. This is usually a remote AEAD to a KMS. In this example,
	// we use a fake KMS to avoid making RPCs.
	client, err := fakekms.NewClient(keyURI)
	if err != nil {
		log.Fatal(err)
	}
	kekAEAD, err := client.GetAEAD(keyURI)
	if err != nil {
		log.Fatal(err)
	}

	// Get the KMS envelope AEAD primitive.
	primitive := aead.NewKMSEnvelopeAEAD2(aead.AES256GCMKeyTemplate(), kekAEAD)

	// Use the primitive.
	plaintext := []byte("message")
	associatedData := []byte("example KMS envelope AEAD encryption")

	ciphertext, err := primitive.Encrypt(plaintext, associatedData)
	if err != nil {
		log.Fatal(err)
	}

	decrypted, err := primitive.Decrypt(ciphertext, associatedData)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(decrypted))
	// Output: message
}
kms_envelope_aead_example_test.go

자바

이 예시에는 Google Cloud KMS 확장 프로그램 tink-java-gcpkms이 필요합니다.

package envelopeaead;

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

import com.google.crypto.tink.Aead;
import com.google.crypto.tink.KmsClient;
import com.google.crypto.tink.aead.AeadConfig;
import com.google.crypto.tink.aead.KmsEnvelopeAead;
import com.google.crypto.tink.aead.PredefinedAeadParameters;
import com.google.crypto.tink.integration.gcpkms.GcpKmsClient;
import java.io.File;
import java.io.FileOutputStream;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.GeneralSecurityException;

/**
 * A command-line utility for encrypting small files with envelope encryption.
 *
 * <p>It requires the following arguments:
 *
 * <ul>
 *   <li>mode: Can be "encrypt" or "decrypt" to encrypt/decrypt the input to the output.
 *   <li>kek-uri: Use this Cloud KMS' key as the key-encrypting-key for envelope encryption.
 *   <li>gcp-credential-file: Use this JSON credential file to connect to Cloud KMS.
 *   <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 EnvelopeAeadExample {
  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 != 5 && args.length != 6) {
      System.err.printf("Expected 5 or 6 parameters, got %d\n", args.length);
      System.err.println(
          "Usage: java EnvelopeAeadExample encrypt/decrypt kek-uri gcp-credential-file"
              + " input-file output-file [associated-data]");
      System.exit(1);
    }
    String mode = args[0];
    String kekUri = args[1];
    String gcpCredentialFilename = args[2];
    byte[] input = Files.readAllBytes(Paths.get(args[3]));
    File outputFile = new File(args[4]);
    byte[] associatedData = new byte[0];
    if (args.length == 6) {
      System.out.println("Associated data!");
      associatedData = args[5].getBytes(UTF_8);
    }
    // Initialise Tink: register all AEAD key types with the Tink runtime
    AeadConfig.register();

    // Read the GCP credentials and create a remote AEAD object.
    Aead remoteAead = null;
    try {
      KmsClient kmsClient = new GcpKmsClient().withCredentials(gcpCredentialFilename);
      remoteAead = kmsClient.getAead(kekUri);
    } catch (GeneralSecurityException ex) {
      System.err.println("Error initializing GCP client: " + ex);
      System.exit(1);
    }

    // Create envelope AEAD primitive using AES256 GCM for encrypting the data
    Aead aead = KmsEnvelopeAead.create(PredefinedAeadParameters.AES256_GCM, remoteAead);

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

    System.exit(0);
  }

  private EnvelopeAeadExample() {}
}EnvelopeAeadExample.java

Python

"""A command-line utility for encrypting small files using envelope encryption with GCP."""

from absl import app
from absl import flags
from absl import logging
import tink
from tink import aead
from tink.integration import gcpkms


FLAGS = flags.FLAGS

flags.DEFINE_enum(
    'mode', None, ['encrypt', 'decrypt'], 'The operation to perform.'
)
flags.DEFINE_string(
    'kek_uri', None, 'The Cloud KMS URI of the key encryption key.'
)
flags.DEFINE_string(
    'gcp_credential_path', None, 'Path to the GCP credentials JSON file.'
)
flags.DEFINE_string('input_path', None, 'Path to the input file.')
flags.DEFINE_string('output_path', None, 'Path to the output file.')
flags.DEFINE_string(
    'associated_data', None, 'Optional associated data used for the encryption.'
)


def main(argv):
  del argv  # Unused.

  associated_data = (
      b''
      if not FLAGS.associated_data
      else bytes(FLAGS.associated_data, 'utf-8')
  )

  # Initialise Tink
  aead.register()

  try:
    # Read the GCP credentials and setup client
    client = gcpkms.GcpKmsClient(FLAGS.kek_uri, FLAGS.gcp_credential_path)
  except tink.TinkError as e:
    logging.exception('Error creating GCP KMS client: %s', e)
    return 1

  # Create envelope AEAD primitive using AES256 GCM for encrypting the data
  try:
    remote_aead = client.get_aead(FLAGS.kek_uri)
    env_aead = aead.KmsEnvelopeAead(
        aead.aead_key_templates.AES256_GCM, remote_aead
    )
  except tink.TinkError as e:
    logging.exception('Error creating primitive: %s', e)
    return 1

  with open(FLAGS.input_path, 'rb') as input_file:
    input_data = input_file.read()
    if FLAGS.mode == 'decrypt':
      output_data = env_aead.decrypt(input_data, associated_data)
    elif FLAGS.mode == 'encrypt':
      output_data = env_aead.encrypt(input_data, associated_data)
    else:
      logging.error(
          'Unsupported mode %s. Please choose "encrypt" or "decrypt".',
          FLAGS.mode,
      )
      return 1

    with open(FLAGS.output_path, 'wb') as output_file:
      output_file.write(output_data)


if __name__ == '__main__':
  flags.mark_flags_as_required(
      ['mode', 'kek_uri', 'gcp_credential_path', 'input_path', 'output_path']
  )
  app.run(main)envelope_cli.py

다음 단계

클라이언트 측 암호화를 사용하여 Cloud SQL 데이터베이스에 데이터를 추가하기 전에 데이터를 암호화할 수 있습니다.
Tink 및 Cloud KMS를 사용한 클라이언트 측 암호화를 사용하여 데이터를 암호화한 후 Google Cloud Storage에 업로드하는 방법을 자세히 알아보세요.

Cloud KMS에서 클라이언트 측 암호화를 사용하고 싶습니다. 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

KMS 봉투 AEAD

C++

Go

자바

Python

다음 단계

Cloud KMS에서 클라이언트 측 암호화를 사용하고 싶습니다.