Я хочу зашифровать данные

Для большинства случаев шифрования данных мы рекомендуем использовать примитив 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::ConfigAead2026());
  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;
}

Проложить маршрут

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://developers.google.com/tink/key-management-overview.
	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.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() {}
}

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 (Authenticated Encryption with Associated Data – аутентифицированное шифрование с дополнительными данными) – самый распространенный примитив для шифрования данных, который подходит для большинства задач.

У AEAD есть следующие свойства:

  • Secrecy Об открытом тексте ничего не известно, кроме его длины.
  • Подлинность. Невозможно изменить зашифрованный открытый текст, лежащий в основе шифротекста, без обнаружения.
  • Симметричное. Для шифрования открытого текста и расшифровки зашифрованного текста используется один и тот же ключ.
  • Рандомизация. Шифрование выполняется случайным образом. Два сообщения с одинаковым открытым текстом дают разные зашифрованные тексты. Злоумышленники не могут узнать, какой зашифрованный текст соответствует определенному открытому тексту. Чтобы этого не произошло, используйте детерминированный AEAD.

Связанные данные

Алгоритм AEAD можно использовать, чтобы связывать зашифрованный текст с определенными связанными данными. Предположим, у вас есть база данных с полями user-id и encrypted-medical-history. В этом случае user-id можно использовать в качестве связанных данных при шифровании encrypted-medical-history. Это не позволит злоумышленнику перенести историю болезни одного пользователя другому.

Связанные данные указывать необязательно. Если указано, расшифровка будет выполнена только в том случае, если в вызовах шифрования и расшифровки передаются одни и те же связанные данные.

Выберите тип ключа

Мы рекомендуем использовать AES128_GCM, но для разных задач могут подходить разные типы ключей. AES128 обеспечивает 128-битный уровень безопасности, а AES256 – 256-битный.

При выборе режима следует учитывать два важных ограничения безопасности:

  1. Сколько сообщений зашифровано одним и тем же ключом?
  2. Размер письма.

Поддерживаемые типы ключей:

  • AES-CTR-HMAC (AES128_CTR_HMAC_SHA256, AES256_CTR_HMAC_SHA256) с 16-байтовым вектором инициализации (IV) – наиболее консервативный режим с хорошими границами.
    • Подтверждение ключа.
  • Алгоритм AES-EAX (AES128_EAX, AES256_EAX) немного менее консервативен и немного быстрее, чем AES128_CTR_HMAC_SHA256.
    • Не передает ключ MLGR.
  • AES-GCM (AES128_GCM, AES256_GCM) обычно является самым быстрым режимом с самыми строгими ограничениями на количество сообщений (232) и размер сообщений (~64 ГБ на сообщение). При превышении этих лимитов AES-GCM катастрофически выходит из строя, раскрывая открытый текст и часть ключа аутентификации внутреннего ключа AES-GCM.
    • AES-GCM не является ни надежным [ABN], ни фиксирующим ключ [GLR]. Можно создать зашифрованный текст, который можно расшифровать с помощью двух разных ключей. Это может привести к практическим атакам [DGRW]. Если ключ выбирает злоумышленник, внимательно изучите модель угроз.
  • AES-GCM-SIV (AES128_GCM_SIV, AES256_GCM_SIV) почти так же быстр, как AES-GCM. У него такие же ограничения на количество сообщений и размер сообщений, как и у AES-GCM, но при превышении этих ограничений он работает менее катастрофично: может быть раскрыт только факт того, что два сообщения равны. Это делает его более безопасным, чем AES-GCM, но на практике он используется реже. Чтобы использовать эту функцию в Java, необходимо установить Conscrypt.
    • Не ключевой ADGKLS.
  • XChaCha20-Poly1305 (XCHACHA20_POLY1305) имеет гораздо более высокий лимит на количество сообщений и размер сообщений, чем AES-GCM, но когда он выходит из строя (что очень маловероятно), он также раскрывает ключевой материал. Оно не поддерживает аппаратное ускорение, поэтому может работать медленнее, чем режимы AES, если аппаратное ускорение доступно.
    • Не ключевой LGR.

Подробнее о формате передачи данных зашифрованного текста AEAD…

Гарантии безопасности

Реализации AEAD предлагают:

  • CCA2.
  • Сила аутентификации не менее 80 бит.
  • Возможность зашифровать не менее 232 сообщений общим объемом 250 байт. Ни одна атака с использованием до 232 выбранных открытых текстов или выбранных зашифрованных текстов не имеет вероятности успеха, превышающей 2-32.