Chcę zaszyfrować dane

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

Szyfrowanie uwierzytelnione z danymi powiązanymi (AEAD) to najprostszy i najbardziej odpowiedni element pierwotny w większości przypadków użycia. AEAD zapewnia poufność i autentyczność oraz gwarantuje, że wiadomości zawsze mają różne teksty zaszyfrowane (zaszyfrowane dane wyjściowe), nawet jeśli teksty jawne (dane wejściowe do szyfrowania) są takie same. Jest to szyfrowanie symetryczne, które wykorzystuje jeden klucz do szyfrowania i odszyfrowywania.

Poniższe przykłady pomogą Ci zacząć korzystać z prymitywu 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

Przeczytaj

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

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

Podstawowa funkcja szyfrowania uwierzytelnionego z danymi powiązanymi (AEAD) jest najczęściej używaną podstawową funkcją szyfrowania danych i spełnia większość potrzeb.

Szyfrowanie AEAD ma te właściwości:

• Secrecy o tekście jawnym nie wiadomo nic poza jego długością.
• Autentyczność: nie można zmienić zaszyfrowanego tekstu jawnego, który jest podstawą tekstu zaszyfrowanego, bez wykrycia.
• Symetryczne: szyfrowanie tekstu jawnego i odszyfrowywanie tekstu zaszyfrowanego odbywa się za pomocą tego samego klucza.
• Randomizacja: szyfrowanie jest randomizowane. Dwie wiadomości z tym samym tekstem jawny generują różne teksty zaszyfrowane. Hakerzy nie mogą wiedzieć, który szyfrogram odpowiada danemu tekstowi jawnemu. Jeśli chcesz tego uniknąć, użyj deterministycznego AEAD.

Powiązane dane

Ostrzeżenie: powiązane dane są uwierzytelnione, ale NIE są szyfrowane.

Algorytm AEAD może służyć do powiązania tekstu zaszyfrowanego z określonymi danymi powiązanymi. Załóżmy, że masz bazę danych z polami user-id i encrypted-medical-history. W tym scenariuszu user-id może być używane jako dane powiązane podczas szyfrowania encrypted-medical-history. Zapobiega to przenoszeniu historii medycznej przez atakującego z jednego konta użytkownika na inne.

Dane powiązane są opcjonalne. Jeśli podano dane powiązane, odszyfrowanie się powiedzie tylko wtedy, gdy te same dane powiązane zostaną przekazane do wywołań funkcji szyfrujących i odszyfrowujących.

Wybierz typ klucza

Większości użytkowników zalecamy używanie klucza AES128_GCM, ale w zależności od potrzeb dostępne są różne typy kluczy (aby uzyskać 256-bitowe zabezpieczenia, zastąp poniżej AES128 kluczem AES256). Ogólnie:

• AES128_CTR_HMAC_SHA256 z 16-bajtowym wektorem inicjującym (IV) to najbardziej konserwatywny tryb z dobrymi ograniczeniami.
• AES128_EAX jest nieco mniej konserwatywny i nieco szybszy niż AES128_CTR_HMAC_SHA256.
• AES128_GCM jest zwykle najszybszym trybem, który ma najsurowsze ograniczenia dotyczące liczby wiadomości i ich rozmiaru. Jeśli te limity długości tekstu jawnego i powiązanych danych (poniżej) zostaną przekroczone, AES128_GCM nie działa i ujawnia klucz.
• AES128_GCM_SIV jest prawie tak samo szybki jak AES128_GCM. Ma takie same limity jak AES128_GCM w zakresie liczby wiadomości i rozmiaru wiadomości, ale po przekroczeniu tych limitów działa w mniej katastrofalny sposób: może ujawnić tylko fakt, że dwie wiadomości są identyczne. Dzięki temu jest bezpieczniejszy niż AES128_GCM, ale w praktyce jest rzadziej używany. Aby używać tej funkcji w Javie, musisz zainstalować Conscrypt.
• XChaCha20Poly1305 ma znacznie większy limit liczby wiadomości i rozmiaru wiadomości niż AES128_GCM, ale gdy zawiedzie (co jest bardzo mało prawdopodobne), ujawnia też materiał klucza. Nie jest akcelerowany sprzętowo, więc w sytuacjach, w których akceleracja sprzętowa jest dostępna, może działać wolniej niż tryby AES.

Uwaga: tekst jawny i powiązane z nim dane mogą mieć dowolną długość w zakresie od 0 do 2³² bajtów.

Gwarancje bezpieczeństwa

Implementacje AEAD oferują:

• zabezpieczenia CCA2,
• Siła uwierzytelniania musi wynosić co najmniej 80 bitów.
• Możliwość zaszyfrowania co najmniej 2³² wiadomości o łącznym rozmiarze 2⁵⁰ bajtów. Żaden atak z wybranymi tekstami jawnymi lub szyfrogramami (maksymalnie 2³²) nie ma prawdopodobieństwa powodzenia większego niż 2^-32.

Ostrzeżenie: AEAD nie gwarantuje poufności danych powiązanych.