Saya ingin mengenkripsi data

Sebaiknya gunakan primitif AEAD dengan jenis kunci AES128_GCM untuk sebagian besar kasus penggunaan enkripsi data.

Authenticated Encryption with Associated Data (AEAD) adalah primitif yang paling sederhana dan paling sesuai untuk sebagian besar kasus penggunaan. AEAD memberikan kerahasiaan dan keaslian serta memastikan bahwa pesan selalu memiliki ciphertext (output terenkripsi) yang berbeda meskipun teks biasa (input untuk enkripsi) sama. Algoritma ini bersifat simetris, menggunakan satu kunci untuk enkripsi dan dekripsi.

Contoh berikut akan membantu Anda mulai menggunakan primitif 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;
}
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://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
}
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

PETUNJUK

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

Primitif Authenticated Encryption with Associated Data (AEAD) adalah primitif yang paling umum untuk enkripsi data dan cocok untuk sebagian besar kebutuhan.

AEAD memiliki properti berikut:

• Secrecy: Tidak ada yang diketahui tentang teks biasa, kecuali panjangnya.
• Keaslian: Tidak mungkin mengubah teks biasa terenkripsi yang mendasari ciphertext tanpa terdeteksi.
• Simetris: Mengenkripsi teks biasa dan mendekripsi ciphertext dilakukan dengan kunci yang sama.
• Pengacakan: Enkripsi diacak. Dua pesan dengan teks biasa yang sama menghasilkan ciphertext yang berbeda. Penyerang tidak dapat mengetahui ciphertext mana yang sesuai dengan teks biasa tertentu. Jika Anda ingin menghindari hal ini, gunakan AEAD Deterministik.

Data terkait

Perhatian: Data terkait diautentikasi, tetapi TIDAK dienkripsi.

AEAD dapat digunakan untuk mengaitkan ciphertext ke data terkait tertentu. Misalkan Anda memiliki database dengan kolom user-id dan encrypted-medical-history. Dalam skenario ini, user-id dapat digunakan sebagai data terkait saat mengenkripsi encrypted-medical-history. Hal ini mencegah penyerang memindahkan histori medis dari satu pengguna ke pengguna lain.

Data terkait bersifat opsional. Jika ditentukan, dekripsi hanya akan berhasil jika data terkait yang sama diteruskan ke panggilan enkripsi dan dekripsi.

Pilih jenis kunci

Meskipun kami merekomendasikan AES128_GCM untuk sebagian besar penggunaan, ada berbagai jenis kunci untuk kebutuhan yang berbeda. AES128 menawarkan keamanan 128-bit, dan AES256 menawarkan keamanan 256-bit.

Dua batasan keamanan yang perlu diperhatikan saat memilih mode adalah:

1. QPS: Berapa banyak pesan yang dienkripsi dengan kunci yang sama?
2. Ukuran pesan: Seberapa besar pesannya?

Jenis kunci yang didukung:

• AES-CTR-HMAC (AES128_CTR_HMAC_SHA256, AES256_CTR_HMAC_SHA256) dengan Vektor Inisialisasi (IV) 16 byte adalah mode paling konservatif dengan batas yang baik.
  • Key-committing.
• AES-EAX (AES128_EAX, AES256_EAX) sedikit kurang konservatif dan sedikit lebih cepat daripada AES128_CTR_HMAC_SHA256.
  • MLGR tanpa key-committing.
• AES-GCM (AES128_GCM, AES256_GCM) biasanya merupakan mode tercepat dengan batasan paling ketat pada jumlah pesan (2³²) dan ukuran pesan (~64 GB per pesan). Jika batas ini terlampaui, AES-GCM akan gagal total dengan membocorkan teks biasa dan bagian autentikasi kunci internal AES-GCM.
  • AES-GCM tidak tangguh [ABN] atau key-committing [GLR]. Anda dapat membuat ciphertext yang dapat didekripsi dengan dua kunci berbeda. Hal ini dapat menyebabkan serangan praktis [DGRW]. Tinjau model ancaman Anda dengan cermat jika kunci dipilih oleh musuh.
• AES-GCM-SIV (AES128_GCM_SIV, AES256_GCM_SIV) [RFC8452] tahan terhadap penyalahgunaan nonce yang tidak disengaja dan memiliki performa yang hampir sama dengan AES-GCM. Batas jumlah pesan dan ukuran pesan untuk AES-GCM-SIV dengan IV acak jauh lebih tinggi daripada batas AES-GCM. Jika batas ini terlampaui, AES-GCM-SIV akan gagal dengan dampak yang lebih kecil: AES-GCM-SIV hanya akan membocorkan bahwa dua pesan sama. AES-GCM-SIV lebih aman digunakan, tetapi jarang digunakan dalam praktik.
  • Batas untuk nonce acak:
    • 2³² pesan, dengan setiap teks biasa berukuran maksimal 8 GiB
    • 2⁴⁸ pesan, dengan setiap teks biasa berukuran maksimal 32 MiB
    • 2⁶⁴ pesan, dengan setiap teks biasa berukuran maksimal 128 KiB
  • Untuk menggunakannya di Java, instal Conscrypt.
  • ADGKLS yang tidak mengikat kunci.
• XChaCha20-Poly1305 (XCHACHA20_POLY1305) memiliki batas jumlah pesan dan ukuran pesan yang jauh lebih besar daripada AES-GCM, tetapi jika gagal (sangat tidak mungkin), algoritma ini juga akan membocorkan materi kunci. Mode ini tidak menggunakan akselerasi hardware, sehingga dapat lebih lambat daripada mode AES dalam situasi saat akselerasi hardware tersedia.
  • LGR tanpa key-committing.

Catatan: Semua algoritma yang tercantum mendukung panjang minimum 2³² byte untuk teks biasa dan data terkait.

Pelajari lebih lanjut format kabel ciphertext AEAD.

Jaminan keamanan

Implementasi AEAD menawarkan:

• Keamanan CCA2.
• Kekuatan autentikasi minimal 80 bit.
• Kemampuan untuk mengenkripsi setidaknya 2³² pesan dengan total 2⁵⁰ byte. Tidak ada serangan dengan hingga 2³² teks biasa yang dipilih atau ciphertext yang dipilih memiliki probabilitas keberhasilan lebih besar dari 2^-32.

Perhatian: AEAD tidak menawarkan jaminan kerahasiaan untuk data terkait.