Quiero encriptar datos

Recomendamos la primitiva AEAD con el AES128_GCM para la mayoría de los casos de uso de encriptación de datos.

La encriptación autenticada con datos asociados (AEAD) es la primitiva más simple y adecuada para la mayoría de los casos de uso. AEAD proporciona secreto y autenticidad, y garantiza que los mensajes siempre tengan textos cifrados diferentes (salidas encriptadas), incluso si los textos sin formato (las entradas para la encriptación) son los mismos. Es simétrica y usa una sola clave para la encriptación y la desencriptación.

En los siguientes ejemplos, se muestra cómo comenzar a usar la primitiva 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;
}

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
}

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

INSTRUCTIVO

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 primitiva de encriptación autenticada con datos asociados (AEAD) es la más común para la encriptación de datos y es adecuada para la mayoría de las necesidades.

AEAD tiene las siguientes propiedades:

  • Secrecy: No se sabe nada sobre el texto sin formato, excepto su longitud.
  • Autenticidad: Es imposible cambiar el texto sin formato encriptado subyacente al texto cifrado sin que se detecte.
  • Simétrico: La encriptación del texto sin formato y la desencriptación del texto cifrado se realizan con la misma clave.
  • Aleatorización: La encriptación se aleatoriza. Dos mensajes con el mismo texto sin formato producen textos cifrados diferentes. Los atacantes no pueden saber qué texto cifrado corresponde a un texto sin formato determinado. Si quieres evitar esto, usa AEAD determinista en su lugar.

Datos asociados

AEAD se puede usar para vincular el texto cifrado a datos asociados específicos datos. Supongamos que tienes una base de datos con los campos user-id y encrypted-medical-history. En este caso, user-id se puede usar como datos asociados cuando se encripta encrypted-medical-history. Esto evita que un atacante mueva el historial médico de un usuario a otro.

Los datos asociados son opcionales. Si se especifican, la desencriptación solo se realiza correctamente si se pasan los mismos datos asociados a las llamadas de encriptación y desencriptación.

Elige un tipo de clave

Si bien recomendamos AES128_GCM para la mayoría de los usos, existen varios tipos de claves para diferentes necesidades. AES128 ofrece seguridad de 128 bits y AES256 ofrece seguridad de 256 bits.

Las dos restricciones de seguridad notables cuando se elige un modo son las siguientes:

  1. QPS: ¿Cuántos mensajes se encriptan con la misma clave?
  2. Tamaño del mensaje: ¿Qué tan grandes son los mensajes?

Tipos de claves compatibles:

  • AES-CTR-HMAC (AES128_CTR_HMAC_SHA256, AES256_CTR_HMAC_SHA256) con un vector de inicialización (IV) de 16 bytes es el modo más conservador con buenos límites.
    • Compromiso de clave.
  • AES-EAX (AES128_EAX, AES256_EAX) es un poco menos conservador y un poco más rápido que AES128_CTR_HMAC_SHA256.
    • No se compromete la clave MLGR.
  • AES-GCM (AES128_GCM, AES256_GCM) suele ser el modo más rápido con los límites más estrictos en la cantidad de mensajes (232) y el tamaño del mensaje (~64 GB por mensaje). Cuando se superan estos límites, AES-GCM falla de forma catastrófica, ya que filtra el texto sin formato y la parte de autenticación de la clave interna de AES-GCM.
    • AES-GCM no es robusto [ABN] ni se compromete la clave [GLR]. Es posible generar un texto cifrado que se pueda desencriptar con dos claves diferentes. Esto puede generar ataques prácticos [DGRW]. Revisa cuidadosamente tu modelo de amenazas si el adversario elige la clave.
  • AES-GCM-SIV (AES128_GCM_SIV, AES256_GCM_SIV) [RFC8452] es resistente al uso indebido accidental de nonce y tiene un rendimiento casi tan bueno como AES-GCM. Los límites en la cantidad de mensajes y el tamaño del mensaje para AES-GCM-SIV con IV aleatorios son mucho más altos que los límites de AES-GCM. Cuando se superan estos límites, AES-GCM-SIV falla de forma menos catastrófica: solo filtra que dos mensajes son iguales. AES-GCM-SIV es más seguro de usar, pero se usa menos en la práctica.
    • Límites para nonces aleatorios:
      • 232 mensajes, en los que cada texto sin formato es de 8 GiB como máximo
      • 248 mensajes, en los que cada texto sin formato es de 32 MiB como máximo
      • 264 mensajes, en los que cada texto sin formato es de 128 KiB como máximo
    • Para usar en Java, instala Conscrypt.
    • No se compromete la clave ADGKLS.
  • XChaCha20-Poly1305 (XCHACHA20_POLY1305) tiene un límite mucho mayor en la cantidad de mensajes y el tamaño del mensaje que AES-GCM, pero cuando falla (muy poco probable), también filtra el material de la clave. No tiene aceleración de hardware, por lo que puede ser más lento que los modos AES en situaciones en las que la aceleración de hardware está disponible.
    • No se compromete la clave LGR.

Obtén más información sobre el formato de transmisión del texto cifrado AEAD.

Garantías de seguridad

Las implementaciones de AEAD ofrecen lo siguiente:

  • Seguridad CCA2
  • Al menos 80 bits de intensidad de autenticación
  • La capacidad de encriptar al menos 232 mensajes con un total de 250 bytes. Ningún ataque con hasta 232 textos sin formato elegidos o textos cifrados elegidos tiene una probabilidad de éxito mayor que 2-32.