מומלץ להשתמש בפרימיטיב של AEAD עם סוג המפתח AES128_GCM ברוב התרחישים לדוגמה של הצפנת נתונים.
הצפנה מאומתת עם נתונים משויכים (AEAD) היא הפרימיטיבית הפשוטה והמתאימה ביותר ברוב תרחישי השימוש. קובץ AEAD מספק סודיות ואותנטיות ומבטיח שלהודעות תמיד יהיו מידע מוצפן (ciphertext) (פלט מוצפן) שונה, גם אם הטקסט ללא הצפנה (הקלט של ההצפנה) זהה. השיטה סימטרית, באמצעות מפתח אחד גם להצפנה וגם לפענוח.
הדוגמאות הבאות מראות איך אפשר להשתמש בפרימיטיב של AEAD:
C++
// A command-line utility for testing Tink AEAD.
#include <iostream>
#include <memory>
#include <ostream>
#include <string>
#include "absl/flags/flag.h"
#include "absl/flags/parse.h"
#include "absl/log/check.h"
#include "absl/strings/string_view.h"
#include "tink/aead.h"
#include "tink/aead/aead_config.h"
#include "tink/config/global_registry.h"
#include "util/util.h"
#include "tink/keyset_handle.h"
#include "tink/util/status.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::AeadConfig;
using ::crypto::tink::KeysetHandle;
using ::crypto::tink::util::Status;
using ::crypto::tink::util::StatusOr;
constexpr absl::string_view kEncrypt = "encrypt";
constexpr absl::string_view kDecrypt = "decrypt";
void ValidateParams() {
// ...
}
} // namespace
namespace tink_cc_examples {
// AEAD example CLI implementation.
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) {
Status result = AeadConfig::Register();
if (!result.ok()) return result;
// Read the keyset from file.
StatusOr<std::unique_ptr<KeysetHandle>> keyset_handle =
ReadJsonCleartextKeyset(keyset_filename);
if (!keyset_handle.ok()) return keyset_handle.status();
// Get the primitive.
StatusOr<std::unique_ptr<Aead>> aead =
(*keyset_handle)
->GetPrimitive<crypto::tink::Aead>(
crypto::tink::ConfigGlobalRegistry());
if (!aead.ok()) return aead.status();
// Read the input.
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) {
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.
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';
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
}
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.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(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 יש את המאפיינים הבאים:
- סודיות: מידע על הטקסט ללא הצפנה לא ידוע, מלבד האורך שלו.
- אותנטיות: אי אפשר לשנות את הטקסט ללא הצפנה המוצפן שבבסיס הטקסט המוצפן בלי לזהות אותו.
- סימטרי: הצפנת הטקסט ללא הצפנה והפענוח של המידע המוצפן מתבצעים באמצעות אותו המפתח.
- רנדומיזציה: ההצפנה אקראית. שתי הודעות עם אותו טקסט ללא הצפנה מניבות מידע מוצפן (ciphertext) שונה. תוקפים לא יכולים לדעת איזה מידע מוצפן (ciphertext) תואם לטקסט נתון ללא הצפנה. אם אתם רוצים למנוע את זה, צריך להשתמש במקום זאת ב-Determinism AEAD.
נתונים משויכים
אפשר להשתמש ב-AEAD כדי לקשור טקסט מוצפן (ciphertext) לנתונים משויכים ספציפיים. נניח שיש מסד נתונים עם השדות user-id ו-encrypted-medical-history. בתרחיש הזה, אפשר להשתמש ב-user-id כנתונים משויכים במהלך הצפנת encrypted-medical-history. כך תוקפים לא יכולים להעביר את ההיסטוריה הרפואית ממשתמש אחד לאחר.
בחירת סוג מפתח
אנחנו ממליצים על AES128_GCM לרוב השימושים, אבל יש סוגי מפתחות שונים לצרכים שונים (לאבטחת 256 ביט, מחליפים את AES128 ב-AES256 שבהמשך). באופן כללי:
- AES128_CTR_HMAC_SHA256 עם וקטור אתחול (IV) של 16 בייטים (IV) הוא המצב השמרני ביותר עם גבולות טובים.
- AES128_EAX קצת פחות שמרני וקצת מהיר יותר מ-AES128_CTR_HMAC_SHA256.
- AES128_GCM הוא בדרך כלל המצב המהיר ביותר עם המגבלות המחמירות ביותר על מספר ההודעות וגודל ההודעות. כשיש חריגה מהמגבלות על טקסטים ללא הצפנה ואורך הנתונים המשויכים (בהמשך), השירות AES128_GCM נכשל ודליפה של חומר מפתח.
- AES128_GCM_SIV מהיר כמעט כמו AES128_GCM, עם גבולות טובים מאוד לכמות גדולה של הודעות, אבל הוא קצת פחות מבוסס. כדי להשתמש בו ב-Java, תצטרכו להתקין את Conscrypt.
- ל-XChaCha20Poly1305 יש מגבלה הרבה יותר גדולה על מספר ההודעות וגודל ההודעות מאשר AES128_GCM, אבל כשהיא נכשלת (נדיר מאוד) היא גם דולפת חומר מפתח. המהירות לא פועלת עם שיפור מהירות באמצעות חומרה, כך שהיא יכולה להיות איטית יותר ממצבי AES במצבים שבהם יש שיפור מהירות באמצעות חומרה.
התחייבויות אבטחה
הטמעות של AEAD מציעות:
- אבטחת CCA2.
- חוזק אימות של 80 ביט לפחות.
- יכולת להצפין לפחות 232 הודעות, ובסך הכול 250 בייטים. לכל מתקפה עם עד 232 טקסטים ללא הצפנה או מידע מוצפן (ciphertext) שנבחרו יש סבירות גבוהה מ-232.