أريد تشفير البيانات

ننصح باستخدام دالة AEAD الأساسية مع نوع مفتاح AES128_GCM لمعظم حالات استخدام تشفير البيانات.

التشفير المُعتمَد بالبيانات المرتبطة (AEAD) هو أبسط وأنسب أسلوب تشفير لأغلب حالات الاستخدام. يقدّم "التشفير التام مع إثبات الهوية" السرية والأصالة ويضمن أن تتضمّن الرسائل دائمًا نصوصًا مشفّرة مختلفة (نتائج مشفّرة) حتى إذا كانت النصوص الواضحة (مدخلات التشفير) متطابقة. وهو متماثل، ويستخدم مفتاحًا واحدًا لكلٍّ من التشفير و فك التشفير.

تساعدك الأمثلة التالية في بدء استخدام دالة 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;
}
aead_cli.cc

انتقال

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

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

AEAD

التشفير المُعتمَد بالبيانات المرتبطة (AEAD) هو الإجراء الأساسي الأكثر رواجًا لتشفير البيانات وهو مناسب لمعظم الاحتياجات.

تتسم ميزة "التشفير من جهة العميل" بالخصائص التالية:

• Secrecy: لا يمكن معرفة أي معلومات عن النص العادي، باستثناء طوله.
• الأصالة: من المستحيل تغيير النص العادي المشفَّر الذي يشكّل النص المشفَّر بدون أن يتم رصد ذلك.
• التشفير المتماثل: يتم تشفير النص العادي وفك تشفيره باستخدام المفتاح نفسه.
• التوزيع العشوائي: يتم توزيع التشفير بشكل عشوائي. تؤدي رسالتان تتضمّنان النص العادي نفسه إلى نصّين مشفَّرين مختلفَين. لا يمكن للمهاجمين معرفة ملف التشفير الذي يتوافق مع نص عادي معيّن. إذا أردت تجنُّب ذلك، استخدِم التشفير المحدد مسبقًا للتشفير وفك التشفير والتوقيع بدلاً من ذلك.

البيانات المرتبطة

ملاحظة: تتم مصادقة البيانات المرتبطة ولكن لا يتم تشفيرها.

يمكن استخدام التشفير التام الامتثال للخصوصية لربط النص المشفَّر ببيانات مرتبطة محدّدة. لنفترض أنّ لديك قاعدة بيانات تحتوي على الحقلين user-id وencrypted-medical-history. في هذا السيناريو، يمكن استخدام user-id كข้อมูล مرتبطة عند تشفير encrypted-medical-history. ويمنع ذلك المهاجم من نقل السجلّ الطبي من مستخدم إلى آخر.

اختيار نوع المفتاح

على الرغم من أنّنا ننصح باستخدام AES128_GCM لمعظم الاستخدامات، هناك أنواع مختلفة من المفاتيح لمختلف الاحتياجات (للحصول على أمان بسعة 256 بت، استبدِل AES128 بـ AES256 أدناه). بشكل عام:

• إنّ AES128_CTR_HMAC_SHA256 مع 16 بايت من "متجه الإعداد" (IV) هو الوضع الأكثر تحفظًا مع حدود جيدة.
• إنّ AES128_EAX أقل أمانًا قليلاً وأسرع قليلاً من AES128_CTR_HMAC_SHA256.
• يكون تنسيق AES128_GCM عادةً هو الأسرع، مع وضع حدود صارمة على عدد الرسائل وحجمها. عند تجاوز هذه الحدود المفروضة على طول النص العادي وطول البيانات المرتبطة به (أدناه)، يتعذّر تنفيذ AES128_GCM ويتسرّب محتوى المفتاح.
• إنّ AES128_GCM_SIV سريع تقريبًا مثل AES128_GCM. تفرض هذه الطريقة الحدود نفسها التي يفرضها أسلوب AES128_GCM في ما يتعلق بعدد الرسائل وحجمها، ولكن عند تجاوز هذه الحدود ، لا يؤدي ذلك إلى حدوث خطأ كبير، بل قد يؤدي فقط إلى الكشف عن حقيقة تطابق رسالتَين. وهذا يجعله أكثر أمانًا من AES128_GCM، ولكن يتم استخدامه على نطاق أقل في الممارسة العملية. لاستخدام هذا الإجراء في Java، عليك تثبيت Conscrypt.
• يفرض XChaCha20Poly1305 حدًا أقصى أكبر بكثير لعدد الرسائل و حجم الرسالة مقارنةً بـ AES128_GCM، ولكن عند حدوث خطأ (من غير المرجّح حدوثه)، يؤدي ذلك أيضًا إلى تسرُّب مادة المفتاح. ولا يتم تسريعه باستخدام الأجهزة، لذا يمكن أن يكون أبطأ من وضعات AES في الحالات التي تتوفّر فيها ميزة تسريع الأجهزة.

ملاحظة: يمكن أن يكون طول النص العادي والبيانات المرتبطة به ضمن 0..2³² بايت.

ضمانات الأمان

تقدّم عمليات تنفيذ AEAD ما يلي:

• أمان CCA2
• قوة مصادقة تبلغ 80 بت على الأقل
• إمكانية تشفير ³² رسالة على الأقل بإجمالي 2⁵⁰ بايت لا يمكن لأي هجوم باستخدام ما يصل إلى 2³² نصًا عاديًا أو نصًا مشفَّرًا مختارًا أن يكون احتمال نجاحه أكبر من 2^-32.

تحذير: لا تقدّم ميزة "التشفير من جهة العميل" أي ضمانات بالسرية للبيانات المرتبطة.