אני רוצה להצפין נתונים

אנחנו ממליצים על הפרימיטיב 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;
}
aead_cli.cc

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
}
aead_test.go

Java

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() {}
}
AeadExample.java

Obj-C

HOW-TO

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_basic.py

AEAD

הפרימיטיב 'הצפנה מאומתת עם נתונים משויכים' (AEAD) הוא הפרימיטיב הנפוץ ביותר להצפנת נתונים, והוא מתאים לרוב הצרכים.

ל-AEAD יש את המאפיינים הבאים:

• Secrecy: לא ידוע דבר על הטקסט הרגיל, מלבד האורך שלו.
• אותנטיות: אי אפשר לשנות את הטקסט הרגיל המוצפן שמהווה את הבסיס לטקסט המוצפן בלי שהשינוי יתגלה.
• סימטרי: הצפנת הטקסט הגלוי ופענוח הטקסט המוצפן מתבצעים באמצעות אותו מפתח.
• אקראיות: ההצפנה היא אקראית. שתי הודעות עם אותו טקסט רגיל יניבו טקסטים מוצפנים שונים. תוקפים לא יכולים לדעת איזה טקסט מוצפן מתאים לטקסט גלוי מסוים. כדי להימנע מכך, מומלץ להשתמש ב-Deterministic AEAD.

נתונים משויכים

שימו לב: הנתונים המשויכים מאומתים אבל לא מוצפנים.

אפשר להשתמש ב-AEAD כדי לקשור טקסט מוצפן לנתונים משויכים ספציפיים. נניח שיש לכם מסד נתונים עם השדות user-id ו-encrypted-medical-history. בתרחיש הזה, אפשר להשתמש ב-user-id כנתונים משויכים כשמצפינים את encrypted-medical-history. כך לא תהיה אפשרות לתוקף להעביר היסטוריה רפואית ממשתמש אחד למשתמש אחר.

הנתונים המשויכים הם אופציונליים. אם מציינים נתונים משויכים, הפענוח יצליח רק אם אותם נתונים משויכים יועברו גם לקריאות ההצפנה וגם לקריאות הפענוח.

בחירת סוג המפתח

מומלץ להשתמש ב-AES128_GCM ברוב המקרים, אבל יש סוגים שונים של מפתחות לצרכים שונים. ‫AES128 מציע אבטחה של 128 ביט, ו-AES256 מציע אבטחה של 256 ביט.

שני אילוצי האבטחה הבולטים כשבוחרים מצב הם:

1. QPS: כמה הודעות מוצפנות באמצעות אותו מפתח?
2. גודל ההודעה: מה גודל ההודעות?

באופן כללי:

• ‫AES-CTR-HMAC (AES128_CTR_HMAC_SHA256, ‏ AES256_CTR_HMAC_SHA256) עם וקטור אתחול (IV) של 16 בייט הוא המצב השמרני ביותר עם גבולות טובים.
• ‫AES-EAX (AES128_EAX, ‏ AES256_EAX) הוא קצת פחות שמרני וקצת יותר מהיר מ-AES128_CTR_HMAC_SHA256.
• בדרך כלל, AES-GCM (AES128_GCM,‏ AES256_GCM) הוא המצב הכי מהיר עם המגבלות הכי מחמירות על מספר ההודעות וגודל ההודעה. אם חורגים מהמגבלות האלה על אורכי הטקסט הגלוי והנתונים המשויכים (בהמשך),‏ AES-GCM נכשל באופן קטסטרופלי וחושף חומרי מפתח.
• ‫AES-GCM-SIV (AES128_GCM_SIV, ‏ AES256_GCM_SIV) מהיר כמעט כמו AES-GCM. יש לו את אותן מגבלות כמו AES-GCM לגבי מספר ההודעות וגודל ההודעה, אבל אם חורגים מהמגבלות האלה, הוא נכשל בצורה פחות קטסטרופלית: יכול להיות שהוא רק יחשוף את העובדה ששתי הודעות שוות. ההצפנה הזו בטוחה יותר לשימוש מ-AES-GCM, אבל בפועל היא פחות נפוצה. כדי להשתמש בזה ב-Java, צריך להתקין את Conscrypt.
• ל-XChaCha20-Poly1305 ‏ (XCHACHA20_POLY1305) יש מגבלה הרבה יותר גדולה על מספר ההודעות ועל גודל ההודעה בהשוואה ל-AES-GCM, אבל אם הוא נכשל (מאוד לא סביר), הוא גם חושף חומר מפתח. הוא לא מואץ על ידי חומרה, ולכן הוא יכול להיות איטי יותר ממצבי AES במצבים שבהם האצת חומרה זמינה.

הערה: האורך של הטקסט הגלוי והנתונים המשויכים יכול להיות כל ערך בין 0 ל-2³² בייטים.

התחייבויות אבטחה

הטמעות של AEAD מציעות:

• אבטחת CCA2.
• חוזק אימות של 80 ביט לפחות.
• היכולת להצפין לפחות 2³² הודעות עם סך של 2⁵⁰ בייטים. לא ניתן לבצע מתקפה עם עד 2³² טקסטים פשוטים או טקסטים מוצפנים שנבחרו, עם הסתברות להצלחה שגבוהה מ-2^-32.

זהירות: אלגוריתם AEAD לא מבטיח סודיות של נתונים משויכים.