Je souhaite chiffrer des données

Nous recommandons la primitive AEAD avec le type de clé AES128_GCM pour la plupart des cas d'utilisation de chiffrement des données.

Le chiffrement authentifié avec les données associées (AEAD) est la primitive la plus simple et la plus appropriée pour la plupart des cas d'utilisation. AEAD assure la confidentialité et l'authenticité, et garantit que les messages ont toujours des textes chiffrés (sorties chiffrées) différents, même si les textes bruts (entrées pour le chiffrement) sont identiques. Il est symétrique et utilise une seule clé pour le chiffrement et le déchiffrement.

Les exemples suivants vous aident à commencer à utiliser la primitive 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

PROCÉDURE

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

La primitive de chiffrement authentifié avec les données associées (AEAD) est la plus courante pour chiffrer des données. Elle convient à la plupart des besoins.

AEAD présente les propriétés suivantes :

  • Secrecy : aucune information sur le texte brut n'est connue, à l'exception de sa longueur.
  • Authenticité : il est impossible de modifier le texte brut chiffré sous-jacent au texte chiffré sans que la modification ne soit détectable.
  • Symétrie : le chiffrement du texte brut et le déchiffrement du texte chiffré s' effectuent avec la même clé.
  • Randomisation : le chiffrement est aléatoire. Deux messages comportant le même texte brut renvoient des textes chiffrés différents. Les pirates ne peuvent pas savoir quel texte chiffré correspond à un texte brut donné. Si vous souhaitez éviter cela, utilisez AEAD déterministe plutôt.

Données associées

AEAD peut être utilisé pour lier un texte chiffré à des données associées spécifiques. Supposons que vous disposez d'une base de données avec les champs user-id et encrypted-medical-history. Dans ce scénario, user-id peut être utilisé comme données associées lors du chiffrement de encrypted-medical-history. Cela empêche un pirate de transférer l'historique médical d'un utilisateur à un autre.

Les données associées sont facultatives. Si elles sont spécifiées, le déchiffrement ne réussit que si les mêmes données associées sont transmises aux appels de chiffrement et de déchiffrement.

Choisir un type de clé

Bien que nous recommandions AES128_GCM pour la plupart des utilisations, il existe différents types de clés pour différents besoins. AES128 offre une sécurité de 128 bits, tandis qu'AES256 offre une sécurité de 256 bits.

Les deux contraintes de sécurité notables lors du choix d'un mode sont les suivantes :

  1. RPS : combien de messages sont chiffrés avec la même clé ?
  2. Taille du message : quelle est la taille des messages ?

Types de clés compatibles :

  • AES-CTR-HMAC (AES128_CTR_HMAC_SHA256, AES256_CTR_HMAC_SHA256) avec un vecteur d'initialisation (IV) de 16 octets est le mode le plus conservateur avec de bonnes limites.
    • Engagement de la clé.
  • AES-EAX (AES128_EAX, AES256_EAX) est légèrement moins conservateur et légèrement plus rapide qu'AES128_CTR_HMAC_SHA256.
  • AES-GCM (AES128_GCM, AES256_GCM) est généralement le mode le plus rapide avec les limites les plus strictes concernant le nombre de messages et la taille des messages. Lorsque ces limites de longueur du texte brut et des données associées (ci-dessous) sont dépassées, AES-GCM échoue de manière catastrophique en divulguant le texte brut et la partie d'authentification de la clé interne AES-GCM.
    • AES-GCM n'est ni robuste [ABN] ni engagé par la clé [GLR]. Il est possible de générer un texte chiffré qui peut être déchiffré avec deux clés différentes. Cela peut entraîner des attaques pratiques [DGRW]. Examinez attentivement votre modèle de menace si la clé est choisie par l'adversaire.
  • AES-GCM-SIV (AES128_GCM_SIV, AES256_GCM_SIV) est presque aussi rapide qu'AES-GCM. Il présente les mêmes limites qu'AES-GCM concernant le nombre de messages et la taille des messages, mais lorsque ces limites sont dépassées, il échoue de manière moins catastrophique : il ne peut que divulguer le fait que deux messages sont égaux. Il est donc plus sûr à utiliser qu'AES-GCM, mais il est moins utilisé en pratique. Pour l'utiliser en Java, vous devez installer Conscrypt.
  • XChaCha20-Poly1305 (XCHACHA20_POLY1305) présente une limite beaucoup plus élevée concernant le nombre de messages et la taille des messages qu'AES-GCM, mais lorsqu'il échoue (ce qui est très peu probable), il divulgue également le matériel de clé. Il n'est pas accéléré par le matériel. Il peut donc être plus lent que les modes AES dans les situations où l'accélération matérielle est disponible.
    • LGR sans engagement de la clé LGR.

En savoir plus sur le format filaire du texte chiffré AEAD

Garanties de sécurité

Les implémentations AEAD offrent les avantages suivants :

  • Sécurité CCA2.
  • Niveau d'authentification d'au moins 80 bits.
  • Possibilité de chiffrer au moins 232 messages avec un total de 250 octets. Aucune attaque avec jusqu'à 232 textes bruts choisis ou textes chiffrés choisis n'a une probabilité de réussite supérieure à 2-32.