Chcę zaszyfrować dane

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

Uwierzytelnione szyfrowanie z powiązanymi danymi (AEAD) to najprostszy i najbardziej odpowiedni prymityw w większości przypadków użycia. AEAD zapewnia poufność i autentyczność oraz gwarantuje, że wiadomości zawsze będą miały różne teksty zaszyfrowane (zaszyfrowane dane wyjściowe), nawet jeśli teksty jawne (dane wejściowe do szyfrowania) będą takie same. Jest to szyfrowanie symetryczne, które do szyfrowania i odszyfrowywania używa jednego klucza.

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;
}

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
}

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

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

Prymityw uwierzytelnionego szyfrowania z powiązanymi danymi (AEAD) jest najczęściej używanym prymitywem do szyfrowania danych i sprawdza się w większości przypadków.

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.
  • Symetryczność: 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 jawnym dają różne teksty zaszyfrowane. Osoby atakujące nie mogą wiedzieć, który tekst zaszyfrowany odpowiada danemu tekstowi jawnemu. Jeśli chcesz tego uniknąć, użyj deterministycznego AEAD zamiast tego.

Powiązane dane

AEAD można używać do powiązania tekstu zaszyfrowanego z określonymi powiązanymi danymi. Załóżmy, że masz bazę danych z polami user-id i encrypted-medical-history. W tym przypadku user-id może być używany jako powiązane dane podczas szyfrowania encrypted-medical-history. Uniemożliwia to osobie atakującej przenoszenie historii medycznej z jednego użytkownika na drugiego.

Powiązane dane są opcjonalne. Jeśli są określone, odszyfrowanie powiedzie się tylko wtedy, gdy te same powiązane dane zostaną przekazane do wywołań szyfrowania i odszyfrowywania.

Wybierz typ klucza

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

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

  1. QPS: ile wiadomości jest szyfrowanych 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 ograniczeniami.
    • Key-committing.
  • AES-EAX (AES128_EAX, AES256_EAX) jest nieco mniej konserwatywny i nieco szybszy niż AES128_CTR_HMAC_SHA256.
    • Nie jest to key-committing MLGR.
  • AES-GCM (AES128_GCM, AES256_GCM) jest zwykle najszybszym trybem z najbardziej rygorystycznymi limitami liczby wiadomości i rozmiaru wiadomości. Gdy te limity długości tekstu jawnego i powiązanych danych (poniżej) zostaną przekroczone, AES-GCM ulegnie katastrofalnemu awarii, ujawniając tekst jawny i część uwierzytelniającą klucza wewnętrznego AES-GCM.
    • AES-GCM nie jest ani odporny [ABN], ani key-committing [GLR]. Można wygenerować tekst zaszyfrowany, który można odszyfrować za pomocą 2 różnych kluczy. Może to prowadzić do praktycznych ataków [DGRW]. Jeśli klucz jest wybierany przez przeciwnika, dokładnie sprawdź model zagrożeń.
  • AES-GCM-SIV (AES128_GCM_SIV, AES256_GCM_SIV) jest prawie tak szybki jak AES-GCM. Ma te same limity co AES-GCM dotyczące liczby wiadomości i rozmiaru wiadomości, ale gdy te limity zostaną przekroczone, ulegnie awarii w mniej katastrofalny sposób: może ujawnić tylko fakt, że 2 wiadomości są równe. Dzięki temu jest bezpieczniejszy w użyciu niż AES-GCM, ale w praktyce jest rzadziej używany. Aby używać go w Javie, musisz zainstalować Conscrypt.
    • Nie jest to key-committing ADGKLS.
  • XChaCha20-Poly1305 (XCHACHA20_POLY1305) ma znacznie większy limit liczby wiadomości i rozmiaru wiadomości niż AES-GCM, ale gdy ulegnie awarii (co jest bardzo mało prawdopodobne), ujawni też materiał klucza. Nie jest akcelerowany sprzętowo, więc w sytuacjach, w których akceleracja sprzętowa jest dostępna, może być wolniejszy niż tryby AES.
    • Nie jest to key-committing LGR.

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

Gwarancje bezpieczeństwa

Implementacje AEAD oferują:

  • bezpieczeństwo CCA2;
  • siłę uwierzytelniania co najmniej 80-bitową;
  • możliwość zaszyfrowania co najmniej 232 wiadomości o łącznej długości 250 bajtów. Żaden atak z maksymalnie 232 wybranymi tekstami jawnymi lub wybranymi tekstami zaszyfrowanymi nie ma prawdopodobieństwa powodzenia większego niż 2-32.