จัดการคีย์

Tink มีโซลูชันเพื่อหลีกเลี่ยงการจัดการคีย์ที่ไม่เหมาะสม ซึ่งเป็นแหล่งที่มาความเสี่ยงหลัก

สร้างและหมุนเวียนคีย์

หลังจากเลือกประเภทข้อมูลพื้นฐานและคีย์สำหรับกรณีการใช้งาน (ในส่วนฉันต้องการ...ก่อนหน้านี้) ให้จัดการคีย์ด้วยระบบจัดการคีย์ (KMS) ภายนอกที่คุณเลือก ดังนี้

1. สร้างคีย์การเข้ารหัสคีย์ (KEK) ใน KMS เพื่อปกป้องคีย์ของคุณ

2. เรียกดู URI และคีย์เข้าสู่ระบบของคีย์จาก KMS เพื่อส่งให้ Tink

3. ใช้ API หรือ Tinkey ของ Tink เพื่อสร้างชุดคีย์ที่เข้ารหัส หลังจากเข้ารหัสแล้ว คุณจะจัดเก็บคีย์ไว้ที่ใดก็ได้

4. หมุนเวียนคีย์เพื่อหลีกเลี่ยงการใช้คีย์ซ้ำมากเกินไปและเพื่อกู้คืนจากการใช้คีย์ที่ประมาท

หากต้องการส่งออกคีย์ โปรดดูรายละเอียดเกี่ยวกับการส่งออกอย่างปลอดภัยที่หัวข้อส่งออกข้อมูลคีย์ด้วยโปรแกรม

ขั้นตอนที่ 1: สร้าง KEK ใน KMS ภายนอก

สร้างคีย์การเข้ารหัสคีย์ (KEK) ใน KMS ภายนอก KEK จะปกป้องคีย์ของคุณด้วยการเข้ารหัส ซึ่งจะเพิ่มความปลอดภัยอีกชั้น

โปรดดูเอกสารสำหรับ KMS โดยเฉพาะเพื่อสร้าง KEK ดังนี้

• Google Cloud KMS
• Amazon KMS
• HashiCorp Vault (ปัจจุบันมีให้บริการเป็นภาษา Go เท่านั้น)

หมายเหตุ: หากคุณใช้การติดตั้งใช้งาน Java ของ Tink กับ KMS ภายนอก โปรดตรวจสอบว่าได้เพิ่มไลบรารีที่เกี่ยวข้องลงในการกำหนดค่า Java

ขั้นตอนที่ 2: รับ URI และคีย์เข้าสู่ระบบ

คุณสามารถเรียกข้อมูลทั้ง URI และคีย์เข้าสู่ระบบของคีย์จาก KMS ได้

รับ URI ของคีย์

Tink ต้องใช้ Uniform Resource Identifier (URI) จึงจะทำงานร่วมกับคีย์ KMS ได้

หากต้องการสร้าง URI นี้ ให้ใช้ตัวระบุที่ไม่ซ้ำกันซึ่ง KMS กำหนดให้กับคีย์เมื่อสร้าง เพิ่มคำนำหน้าเฉพาะ KMS ที่เหมาะสมและปฏิบัติตามรูปแบบของ URI ของคีย์ที่รองรับตามที่อธิบายไว้ในตารางนี้

KMS	คำนำหน้าตัวระบุ KMS	รูปแบบ URI ของคีย์
AWS KMS	aws-kms://	aws-kms://arn:aws:kms:[region]:[account-id]:key/[key-id]
GCP KMS	gcp-kms://	gcp-kms://projects/*/locations/*/keyRings/*/cryptoKeys/*
HashiCorp ห้องนิรภัย	hcvault://	hcvault://[key-id]

หมายเหตุ: tink-go รองรับ HashiCorp Vault เท่านั้น ส่วน KMS อื่นๆ จะใช้ได้กับการติดตั้งใช้งาน Tink ทั้งหมดและ Tinkey

รับข้อมูลเข้าสู่ระบบที่สำคัญ

เตรียมข้อมูลเข้าสู่ระบบที่จำเป็นเพื่อให้ Tink ตรวจสอบสิทธิ์กับ KMS ภายนอกได้

รูปแบบที่แน่นอนของเอกสารรับรองมีไว้สำหรับ KMS โดยเฉพาะ ดังนี้

• Google Cloud KMS – Tink ต้องใช้ข้อมูลเข้าสู่ระบบของบัญชีบริการ ไฟล์เหล่านี้เป็นไฟล์ JSON ที่สร้างและดาวน์โหลดได้จากคอนโซล Google Cloud
• AWS KMS – Tink ต้องใช้ไฟล์ข้อมูลเข้าสู่ระบบที่มี
  • รหัสคีย์การเข้าถึงในพร็อพเพอร์ตี้ accessKey และ
  • คีย์การเข้าถึงข้อมูลลับในพร็อพเพอร์ตี้ secretKey
• HashiCorp Vault – Tink ต้องใช้โทเค็นบริการที่สร้างได้จากคําสั่ง vault token create

หากคุณไม่ได้ระบุข้อมูลเข้าสู่ระบบ Tink จะพยายามโหลดข้อมูลเข้าสู่ระบบเริ่มต้น ดูข้อมูลเพิ่มเติมได้ในเอกสารประกอบเฉพาะของ KMS

• Google Cloud KMS
• AWS KMS

ขั้นตอนที่ 3: สร้างและจัดเก็บชุดคีย์ที่เข้ารหัส

ใช้ API ของ Tink (สำหรับ Google Cloud KMS, AWS KMS หรือ HashiCorp Vault) หรือ Tinkey เพื่อสร้างชุดคีย์ เข้ารหัสโดยใช้ KMS ภายนอก และจัดเก็บไว้ที่ใดที่หนึ่ง

คำเตือน: แม้ว่าคุณจะใช้ Tink เพื่อสร้างชุดคีย์แบบข้อความธรรมดาที่ไม่ได้เข้ารหัสได้ แต่เราไม่แนะนำให้ทำเช่นนั้น เนื่องจากคีย์มักจะรั่วไหลเมื่อจัดเก็บในรูปแบบข้อความธรรมดา

Tinkey

tinkey create-keyset --key-template AES128_GCM \
  --out-format json --out encrypted_aead_keyset.json \
  --master-key-uri gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar \
  --credential gcp_credentials.json

Java

สําหรับตัวอย่างนี้ คุณต้องมีส่วนขยาย Google Cloud KMS tink-java-gcpkms

package encryptedkeyset;

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

import com.google.crypto.tink.Aead;
import com.google.crypto.tink.KeysetHandle;
import com.google.crypto.tink.TinkJsonProtoKeysetFormat;
import com.google.crypto.tink.aead.AeadConfig;
import com.google.crypto.tink.aead.PredefinedAeadParameters;
import com.google.crypto.tink.integration.gcpkms.GcpKmsClient;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;

/**
 * A command-line utility for working with encrypted keysets.
 *
 * <p>It requires the following arguments:
 *
 * <ul>
 *   <li>mode: Can be "generate", "encrypt" or "decrypt". If mode is "generate", it will generate a
 *       keyset, encrypt it and store it in the key-file argument. If mode is "encrypt" or
 *       "decrypt", it will read and decrypt an keyset from the key-file argument, and use it to
 *       encrypt or decrypt the input-file argument.
 *   <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: If mode is "encrypt" or "decrypt", read the input from this file.
 *   <li>output-file: If mode is "encrypt" or "decrypt", write the result to this file.
 */
public final class EncryptedKeysetExample {
  private static final String MODE_ENCRYPT = "encrypt";
  private static final String MODE_DECRYPT = "decrypt";
  private static final String MODE_GENERATE = "generate";
  private static final byte[] EMPTY_ASSOCIATED_DATA = new byte[0];

  public static void main(String[] args) throws Exception {
    if (args.length != 4 && args.length != 6) {
      System.err.printf("Expected 4 or 6 parameters, got %d\n", args.length);
      System.err.println(
          "Usage: java EncryptedKeysetExample generate/encrypt/decrypt key-file kek-uri"
              + " gcp-credential-file input-file output-file");
      System.exit(1);
    }
    String mode = args[0];
    if (!mode.equals(MODE_ENCRYPT) && !mode.equals(MODE_DECRYPT) && !mode.equals(MODE_GENERATE)) {
      System.err.print("The first argument should be either encrypt, decrypt or generate");
      System.exit(1);
    }
    Path keyFile = Paths.get(args[1]);
    String kekUri = args[2];
    String gcpCredentialFilename = args[3];

    // Initialise Tink: register all AEAD key types with the Tink runtime
    AeadConfig.register();

    // From the key-encryption key (KEK) URI, create a remote AEAD primitive for encrypting Tink
    // keysets.
    Aead kekAead = new GcpKmsClient().withCredentials(gcpCredentialFilename).getAead(kekUri);

    if (mode.equals(MODE_GENERATE)) {
      KeysetHandle handle = KeysetHandle.generateNew(PredefinedAeadParameters.AES128_GCM);

      String serializedEncryptedKeyset =
          TinkJsonProtoKeysetFormat.serializeEncryptedKeyset(
              handle, kekAead, EMPTY_ASSOCIATED_DATA);
      Files.write(keyFile, serializedEncryptedKeyset.getBytes(UTF_8));
      return;
    }

    // Use the primitive to encrypt/decrypt files

    // Read the encrypted keyset
    KeysetHandle handle =
        TinkJsonProtoKeysetFormat.parseEncryptedKeyset(
            new String(Files.readAllBytes(keyFile), UTF_8), kekAead, EMPTY_ASSOCIATED_DATA);

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

    Path inputFile = Paths.get(args[4]);
    Path outputFile = Paths.get(args[5]);

    if (mode.equals(MODE_ENCRYPT)) {
      byte[] plaintext = Files.readAllBytes(inputFile);
      byte[] ciphertext = aead.encrypt(plaintext, EMPTY_ASSOCIATED_DATA);
      Files.write(outputFile, ciphertext);
    } else if (mode.equals(MODE_DECRYPT)) {
      byte[] ciphertext = Files.readAllBytes(inputFile);
      byte[] plaintext = aead.decrypt(ciphertext, EMPTY_ASSOCIATED_DATA);
      Files.write(outputFile, plaintext);
    }
  }

  private EncryptedKeysetExample() {}
}
EncryptedKeysetExample.java

Go

import (
	"bytes"
	"fmt"
	"log"

	"github.com/tink-crypto/tink-go/v2/aead"
	"github.com/tink-crypto/tink-go/v2/keyset"
	"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_encryptedKeyset() {
	// 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)
	}

	// Generate a new keyset handle for the primitive we want to use.
	newHandle, err := keyset.NewHandle(aead.AES256GCMKeyTemplate())
	if err != nil {
		log.Fatal(err)
	}

	// Choose some associated data. This is the context in which the keyset will be used.
	keysetAssociatedData := []byte("keyset encryption example")

	// Encrypt the keyset with the KEK AEAD and the associated data.
	buf := new(bytes.Buffer)
	writer := keyset.NewBinaryWriter(buf)
	err = newHandle.WriteWithAssociatedData(writer, kekAEAD, keysetAssociatedData)
	if err != nil {
		log.Fatal(err)
	}
	encryptedKeyset := buf.Bytes()

	// The encrypted keyset can now be stored.

	// To use the primitive, we first need to decrypt the keyset. We use the same
	// KEK AEAD and the same associated data that we used to encrypt it.
	reader := keyset.NewBinaryReader(bytes.NewReader(encryptedKeyset))
	handle, err := keyset.ReadWithAssociatedData(reader, kekAEAD, keysetAssociatedData)
	if err != nil {
		log.Fatal(err)
	}

	// Get the primitive.
	primitive, err := aead.New(handle)
	if err != nil {
		log.Fatal(err)
	}

	// Use the primitive.
	plaintext := []byte("message")
	associatedData := []byte("example 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
}
keyset_test.go

Python

"""A command-line utility for generating, encrypting and storing keysets."""

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, ['generate', 'encrypt', 'decrypt'],
                  'The operation to perform.')
flags.DEFINE_string('keyset_path', None,
                    'Path to the keyset used for encryption.')
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 to use with the '
                    'encryption operation.')


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)
  except tink.TinkError as e:
    logging.exception('Error creating primitive: %s', e)
    return 1

  if FLAGS.mode == 'generate':
    # Generate a new keyset
    try:
      key_template = aead.aead_key_templates.AES128_GCM
      keyset_handle = tink.new_keyset_handle(key_template)
    except tink.TinkError as e:
      logging.exception('Error creating primitive: %s', e)
      return 1

    # Encrypt the keyset_handle with the remote key-encryption key (KEK)
    with open(FLAGS.keyset_path, 'wt') as keyset_file:
      try:
        keyset_encryption_associated_data = 'encrypted keyset example'
        serialized_encrypted_keyset = (
            tink.json_proto_keyset_format.serialize_encrypted(
                keyset_handle, remote_aead, keyset_encryption_associated_data
            )
        )
        keyset_file.write(serialized_encrypted_keyset)
      except tink.TinkError as e:
        logging.exception('Error writing key: %s', e)
        return 1
    return 0

  # Use the keyset to encrypt/decrypt data

  # Read the encrypted keyset into a keyset_handle
  with open(FLAGS.keyset_path, 'rt') as keyset_file:
    try:
      serialized_encrypted_keyset = keyset_file.read()
      keyset_encryption_associated_data = 'encrypted keyset example'
      keyset_handle = tink.json_proto_keyset_format.parse_encrypted(
          serialized_encrypted_keyset,
          remote_aead,
          keyset_encryption_associated_data,
      )
    except tink.TinkError as e:
      logging.exception('Error reading key: %s', e)
      return 1

  # Get the primitive
  try:
    cipher = keyset_handle.primitive(aead.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 = cipher.decrypt(input_data, associated_data)
    elif FLAGS.mode == 'encrypt':
      output_data = cipher.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', 'keyset_path', 'kek_uri', 'gcp_credential_path'])
  app.run(main)
encrypted_keyset_cli.py

ขั้นตอนที่ 4: หมุนเวียนคีย์

คุณต้องหมุนเวียนคีย์เพื่อรักษาความปลอดภัยของระบบ

1. เปิดใช้การหมุนเวียนคีย์อัตโนมัติใน KMS

2. กำหนดความถี่ที่เหมาะสมในการหมุนคีย์ ซึ่งขึ้นอยู่กับความไวของข้อมูล จำนวนข้อความที่ต้องเข้ารหัส และขึ้นอยู่กับว่าต้องประสานงานกับพาร์ทเนอร์ภายนอกหรือไม่

   • สำหรับการเข้ารหัสแบบแบบสมมาตร ให้ใช้คีย์ 30 ถึง 90 วัน
   • สําหรับการเข้ารหัสแบบอสมมาตร ความถี่ในการหมุนเวียนอาจลดลงได้ แต่ต้องสามารถเพิกถอนคีย์ได้อย่างปลอดภัยเท่านั้น

ดูข้อมูลเพิ่มเติมเกี่ยวกับการหมุนเวียนคีย์ในเอกสารประกอบเฉพาะ KMS

• KMS ของ Google Cloud
• Amazon KMS
• HashiCorp ห้องนิรภัย

ประเด็นสำคัญ: การหมุนเวียนคีย์เป็นแนวทางปฏิบัติแนะนำที่สำคัญซึ่งช่วยป้องกันไม่ให้นำคีย์มาใช้ซ้ำอย่างแพร่หลาย การเปลี่ยนคีย์เป็นประจำจะจำกัดจำนวนข้อความที่เข้ารหัสด้วยเวอร์ชันคีย์เดียวกัน ลดจำนวนข้อความที่อาจมีช่องโหว่ และช่วยให้ระบบมีความยืดหยุ่น