Chcę zaszyfrować dane

W większości przypadków szyfrowania danych zalecamy używanie typu klucza AES128_GCM z pierwotną funkcją AEAD.

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 <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::ConfigAeadV0());
  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://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.

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 tej zmiany.
• Symetryczne: szyfrowanie tekstu jawnego i odszyfrowywanie tekstu zaszyfrowanego odbywa się przy użyciu 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 zamiast tego 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 zostanie określony, odszyfrowywanie powiedzie się tylko wtedy, gdy te same dane powiązane zostaną przekazane do wywołań szyfrowania i odszyfrowywania.

Wybierz typ klucza

W większości przypadków zalecamy używanie klucza AES128_GCM, ale w zależności od potrzeb możesz wybrać inny typ klucza. AES128 zapewnia 128-bitowe bezpieczeństwo, a AES256 – 256-bitowe.

Wybierając tryb, należy wziąć pod uwagę 2 główne 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?

Ogólnie:

• AES-CTR-HMAC (AES128_CTR_HMAC_SHA256, AES256_CTR_HMAC_SHA256) z 16-bajtowym wektorem inicjującym (IV) to najbardziej konserwatywny tryb o dobrych granicach.
• AES-EAX (AES128_EAX, AES256_EAX) jest nieco mniej konserwatywny i nieco szybszy niż AES128_CTR_HMAC_SHA256.
• AES-GCM (AES128_GCM, AES256_GCM) jest zwykle najszybszym trybem z najbardziej rygorystycznymi limitami liczby wiadomości i ich rozmiaru. Jeśli te limity długości tekstu jawnego i powiązanych danych (poniżej) zostaną przekroczone, AES-GCM ulegnie awarii i ujawni materiał klucza.
• AES-GCM-SIV (AES128_GCM_SIV, AES256_GCM_SIV) jest prawie tak szybki jak AES-GCM. Ma takie same limity liczby wiadomości i rozmiaru wiadomości jak AES-GCM, ale gdy te limity zostaną przekroczone, błąd jest mniej poważny: może ujawnić tylko fakt, że 2 wiadomości są identyczne. Dzięki temu jest bezpieczniejszy w użyciu niż AES-GCM, ale w praktyce jest rzadziej stosowany. Aby używać tej funkcji w Javie, musisz zainstalować Conscrypt.
• Algorytm XChaCha20-Poly1305 (XCHACHA20_POLY1305) ma znacznie większy limit liczby wiadomości i rozmiaru wiadomości niż AES-GCM, ale gdy zawodzi (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.