Chcę zaszyfrować dane

W większości przypadków szyfrowania danych zalecamy używanie elementu podstawowego AEAD z typem klucza AES128_GCM.

Szyfrowanie uwierzytelnione z danymi powiązanymi (AEAD) to najprostszy i najbardziej odpowiedni element podstawowy w przypadku większości zastosowań. AEAD zapewnia poufność i autentyczność oraz gwarantuje, że wiadomości zawsze mają różne teksty szyfrowane (zaszyfrowane dane wyjściowe), nawet jeśli teksty jawne (dane wejściowe do szyfrowania) są takie same. Jest to algorytm symetryczny, który używa jednego klucza do szyfrowania i odszyfrowywania.

Te przykłady pomogą Ci zacząć korzystać z elementu podstawowego 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;
}
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://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
}
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

INSTRUKCJE

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

Element podstawowy szyfrowania uwierzytelnionego z danymi powiązanymi (AEAD) jest najczęstszym elementem podstawowym do szyfrowania danych i jest odpowiedni do większości potrzeb.

AEAD ma te właściwości:

• Secrecy o tekście jawnym nie wiadomo nic oprócz jego długości.
• Autentyczność: nie można zmienić zaszyfrowanego tekstu jawnego, który stanowi podstawę tekstu szyfrowanego, bez wykrycia tej zmiany.
• Symetryczne: szyfrowanie tekstu jawnego i odszyfrowywanie tekstu szyfrowanego odbywa się za pomocą tego samego klucza.
• Randomization (Randomizacja): szyfrowanie jest losowe. Dwie wiadomości z tym samym tekstem jawnym dają różne teksty szyfrowane. Osoby przeprowadzające atak nie mogą wiedzieć, który tekst szyfrowany odpowiada danemu tekstowi jawnemu. Jeśli chcesz tego uniknąć, użyj deterministycznego AEAD.

Powiązane dane

Uwaga: powiązane dane są uwierzytelniane, ale NIE są szyfrowane.

Szyfrowanie AEAD może służyć do powiązania tekstu szyfrowanego z określonymi powiązanymi danymi. Załóżmy, że masz bazę danych z polami user-id i encrypted-medical-history. W tym scenariuszu user-id może być używany jako powiązane dane podczas szyfrowania encrypted-medical-history. Dzięki temu atakujący nie może przenieść historii medycznej od jednego użytkownika do drugiego.

Powiązane dane są opcjonalne. Jeśli zostanie określona, odszyfrowywanie powiedzie się tylko wtedy, gdy te same powiązane dane zostaną przekazane zarówno do wywołania szyfrowania, jak i odszyfrowywania.

Wybierz typ klucza

W większości przypadków zalecamy AES128_GCM, ale dostępne są różne typy kluczy do różnych potrzeb. AES128 zapewnia 128-bitowe zabezpieczenia, a AES256 – 256-bitowe.

Podczas wybierania trybu należy wziąć pod uwagę 2 istotne ograniczenia dotyczące bezpieczeństwa:

1. QPS: ile wiadomości jest zaszyfrowanych tym samym kluczem?
2. Rozmiar wiadomości: jak duże są wiadomości?

Obsługiwane typy kluczy:

• AES-CTR-HMAC (AES128_CTR_HMAC_SHA256, AES256_CTR_HMAC_SHA256) z 16-bajtowym wektorem inicjującym (IV) to najbardziej konserwatywny tryb z dobrymi granicami.
  • Zatwierdzanie klucza.
• AES-EAX (AES128_EAX, AES256_EAX) jest nieco mniej konserwatywny i nieco szybszy niż AES128_CTR_HMAC_SHA256.
  • Nie jest to klucz zatwierdzający MLGR.
• AES-GCM (AES128_GCM, AES256_GCM) to zwykle najszybszy tryb z najbardziej rygorystycznymi limitami liczby wiadomości (2³²) i rozmiaru wiadomości (~64 GB na wiadomość). Po przekroczeniu tych limitów AES-GCM ulega awarii, co powoduje wyciek zwykłego tekstu i części uwierzytelniającej klucza wewnętrznego AES-GCM.
  • Algorytm AES-GCM nie jest odporny [ABN] ani nie zapewnia wiązania klucza [GLR]. Można wygenerować tekst szyfrowany, który można odszyfrować za pomocą 2 różnych kluczy. Może to prowadzić do ataków [DGRW]. Jeśli klucz zostanie wybrany przez przeciwnika, dokładnie sprawdź model zagrożeń.
• AES-GCM-SIV (AES128_GCM_SIV, AES256_GCM_SIV) [RFC8452] jest odporny na przypadkowe nadużycie liczby jednorazowej i jest prawie tak samo wydajny jak AES-GCM. Limity liczby wiadomości i rozmiaru wiadomości dla AES-GCM-SIV z losowymi wektorami IV są znacznie wyższe niż limity AES-GCM. Po przekroczeniu tych limitów AES-GCM-SIV nie zawodzi całkowicie: ujawnia tylko, że 2 wiadomości są takie same. AES-GCM-SIV jest bezpieczniejszy, ale rzadziej używany w praktyce.
  • Granice losowych liczb jednorazowych:
    • 2³² wiadomości, gdzie każdy tekst jawny ma maksymalnie 8 GiB.
    • 2⁴⁸ wiadomości, gdzie każdy zwykły tekst ma maksymalnie 32 MiB.
    • 2⁶⁴ wiadomości, w których każdy tekst jawny ma maksymalnie 128 KiB.
  • Aby używać go w języku Java, zainstaluj Conscrypt.
  • Niepowiązany z kluczem ADGKLS.
• XChaCha20-Poly1305 (XCHACHA20_POLY1305) ma znacznie większy limit liczby wiadomości i rozmiaru wiadomości niż AES-GCM, ale w przypadku niepowodzenia (bardzo mało prawdopodobnego) również ujawnia materiał klucza. Nie jest przyspieszany sprzętowo, więc może być wolniejszy niż tryby AES w sytuacjach, gdy dostępna jest akceleracja sprzętowa.
  • LGR bez klucza.

Uwaga: wszystkie wymienione algorytmy obsługują minimalną długość 2³² bajtów w przypadku zwykłego tekstu i powiązanych danych.

Dowiedz się więcej o formacie przesyłania tekstu szyfrowanego AEAD.

Gwarancje bezpieczeństwa

Implementacje AEAD zapewniają:

• Zabezpieczenia CCA2.
• Siła uwierzytelniania co najmniej 80 bitów.
• Możliwość zaszyfrowania co najmniej 2³² wiadomości o łącznym rozmiarze 2⁵⁰ bajtów. Żaden atak z użyciem maksymalnie 2³² wybranych tekstów jawnych lub wybranych tekstów zaszyfrowanych nie ma prawdopodobieństwa powodzenia większego niż 2^-32.

Uwaga: AEAD nie gwarantuje poufności powiązanych danych.