ניהול המפתחות

ב-Tink יש פתרונות למניעת ניהול לא תקין של מפתחות, שהוא מקור לסיכון משמעותי.

סקירה

אחרי שבוחרים סוג מפתח וסוג מפתח לתרחיש לדוגמה הקודם (בקטע I want to...) מנהלים את המפתחות באמצעות מערכת ניהול המפתחות (KMS) החיצונית שבחרתם:

1. יצירת מפתח להצפנת מפתחות הצפנה (KEK) ב-KMS כדי להגן על המפתחות.

2. מאחזרים URI של מפתח ופרטי כניסה של מפתח מ-KMS כדי להעביר ל-Tink.

3. משתמשים ב-API של Tink או ב-Tinkey כדי ליצור קבוצת מפתחות מוצפנת. אחרי שהמפתחות מוצפנים, אפשר לאחסן אותם בכל מקום.

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 דורש מזהה משאב אחיד (URI) כדי לעבוד עם מפתחות KMS.

כדי ליצור את ה-URI הזה, משתמשים במזהה הייחודי ש-KMS מקצה למפתח בזמן יצירתו. מוסיפים את הקידומת המתאימה הספציפית ל-KMS ופועלים לפי הפורמט של מזהי URI נתמכים של מפתחות, כפי שמתואר בטבלה הזו:

KMS	קידומת של מזהה KMS	פורמט ה-URI של המפתח
AWS KMS	aws-kms://	aws-kms://arn:aws:kms:[region]:[account-id]:key/[key-id]
KMS KMS	gcp-kms://	gcp-kms://projects/*/locations/*/keyRings/*/cryptoKeys/*
הכספת של HashiCorp	hcvault://	hcvault://[key-id]

הערה: HashhiCorp Vault נתמך רק על ידי tink-go. מערכות KMS אחרות נתמכות בכל ההטמעות של Tink ובאמצעות Tinkey.

קבלת פרטי הכניסה של המפתח

מכינים את פרטי הכניסה הנחוצים כדי ש-Tink יוכל לבצע אימות ל-KMS החיצוני.

פרטי הכניסה מופיעים בתבנית ספציפית ל-KMS:

• Google Cloud KMS – ל-Tink נדרשים פרטי כניסה לחשבונות שירות. זהו קובץ JSON שאפשר ליצור ולהוריד דרך Google Cloud Console.
• AWS KMS – Tink דורש קובץ פרטי כניסה שמכיל
  • מזהה מפתח הגישה בנכס accessKey
  • מפתח הגישה הסודי בנכס secretKey.
• HashiCorp Vault – Tink דורש אסימוני שירות שאפשר ליצור באמצעות פקודת היצירה של אסימון Vault.

אם לא תספקו את פרטי הכניסה, Tink ינסה לטעון את פרטי הכניסה שמוגדרים כברירת מחדל. מידע נוסף זמין במשאבי עזרה ספציפיים ל-KMS:

• Google Cloud KMS
• AWS KMS

שלב 3: יצירה ואחסון של קבוצת מפתחות מוצפנת

אפשר להשתמש בממשקי API של Tink (ל-Google Cloud KMS, AWS KMS או HashiCorp Vault) או ב-Tinkey כדי ליצור קבוצת מפתחות, להצפין אותו באמצעות ה-KMS החיצוני ולאחסן אותו במקום כלשהו.

אזהרה: אפשר להשתמש ב-Tink כדי ליצור ערכות מפתחות לא מוצפנות בטקסט ללא הצפנה, אבל לא מומלץ לעשות זאת כי הרבה פעמים מפתחות דולפים כשהם מאוחסנים בטקסט ללא הצפנה.

טינקי

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:

• Google Cloud KMS
• Amazon KMS
• HashiCorp Vault

נקודת מפתח: רוטציית מפתחות היא שיטה מומלצת חיונית שמונעת שימוש נרחב במפתחות. רוטציית מפתחות רגילה מגבילה את מספר ההודעות שמוצפנות באמצעות אותה גרסת מפתח, מצמצמת את מספר ההודעות שעלולות להיות פגיעות ומבטיחה שהמערכת שלך עמידה.