Gerenciar chaves

A Tink oferece soluções para evitar o gerenciamento inadequado de chaves, que é uma das principais fontes de risco.

Criar e rotacionar chaves

Depois de selecionar um tipo de chave e primitivo para seu caso de uso (na seção Quero... anterior), gerencie as chaves com o sistema de gerenciamento de chaves (KMS, na sigla em inglês) externo escolhido:

1. Crie uma chave de criptografia de chaves (KEK, na sigla em inglês) no KMS para proteger as suas chaves.

2. Recupere um URI de chave e credenciais de chave do KMS para transmitir à Tink.

3. Use as APIs da Tink ou o Tinkey para gerar um conjunto de chaves criptografado. Depois que as chaves forem criptografadas, você poderá armazená-las onde quiser.

4. Rotacione as chaves para evitar o uso excessivo delas e se recuperar de uma violação.

Se você precisar exportar chaves, consulte Exportar material de chave de maneira programática para mais detalhes sobre como fazer isso com segurança.

Etapa 1: criar uma KEK no KMS externo

Crie uma chave de criptografia de chaves (KEK, na sigla em inglês) no KMS externo. A KEK protege as chaves criptografando-as, adicionando uma camada extra de segurança.

Consulte a documentação específica do KMS para criar uma KEK:

• Cloud KMS do Google Cloud
• KMS da Amazon
• HashiCorp Vault (atualmente disponível apenas na linguagem Go)

Observação: se você estiver usando a implementação Java da Tink com um KMS externo, adicione a dependência apropriada à configuração do Java.

Etapa 2: receber um URI de chave e credenciais

É possível recuperar um URI de chave e credenciais de chave do KMS.

Receber o URI da chave

A Tink exige um identificador uniforme de recursos (URI, na sigla em inglês) para trabalhar com chaves do KMS.

Para criar esse URI, use o identificador exclusivo que o KMS atribui à chave quando ela é criada. Adicione o prefixo específico do KMS apropriado e siga o formato dos URIs de chave compatíveis, conforme descrito nesta tabela:

KMS	Prefixo do identificador do KMS	Formato do URI da chave
KMS da AWS	aws-kms://	aws-kms://arn:aws:kms:[region]:[account-id]:key/[key-id]
KMS do GCP	gcp-kms://	gcp-kms://projects/*/locations/*/keyRings/*/cryptoKeys/*
HashiCorp Vault	hcvault://	hcvault://[key-id]

**Observação**: o HashiCorp Vault é compatível apenas com o tink-go. Outros KMSs são compatíveis com todas as implementações da Tink e com o o Tinkey.

Receber as credenciais da chave

Prepare as credenciais necessárias para que a Tink possa se autenticar no KMS externo.

O formato exato da credencial é específico do KMS:

• Cloud KMS do Google Cloud: a Tink exige credenciais de contas de serviço. Elas são um arquivo JSON que pode ser criado e baixado no Google Cloud Console.
• KMS da AWS: a Tink exige um arquivo de credenciais que contenha
  • o ID da chave de acesso na accessKey propriedade e
  • a chave de acesso secreta na secretKey propriedade.
• HashiCorp Vault: a Tink exige tokens de serviço que podem ser criados pelo comando vault token create.

Se você não fornecer credenciais, a Tink tentará carregar as credenciais padrão. Para mais informações, consulte a documentação específica do KMS:

• Cloud KMS do Google Cloud
• KMS da AWS

Etapa 3: criar e armazenar um conjunto de chaves criptografado

Use as APIs da Tink (para o Cloud KMS do Google Cloud, o KMS da AWS ou o HashiCorp Vault) ou Tinkey para gerar um conjunto de chaves, criptografá-lo usando o KMS externo e armazená-lo em algum lugar.

Aviso: embora seja possível usar a Tink para gerar conjuntos de chaves não criptografados de texto simples, não recomendamos fazer isso, já que as chaves costumam ser vazadas quando armazenadas em texto simples.

Tinkey

tinkey create-keyset --key-template AES128_GCM \
  --out-format json --out encrypted_aead_keyset.json \
  --master-key-uri gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar \
  --credential gcp_credentials.json

Java

Para este exemplo, você precisa da extensão do Google Cloud KMS tink-java-gcpkms.

package encryptedkeyset;

import static java.nio.charset.StandardCharsets.UTF_8;

import com.google.crypto.tink.Aead;
import com.google.crypto.tink.KeysetHandle;
import com.google.crypto.tink.TinkJsonProtoKeysetFormat;
import com.google.crypto.tink.aead.AeadConfig;
import com.google.crypto.tink.aead.PredefinedAeadParameters;
import com.google.crypto.tink.integration.gcpkms.GcpKmsClient;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;

/**
 * A command-line utility for working with encrypted keysets.
 *
 * <p>It requires the following arguments:
 *
 * <ul>
 *   <li>mode: Can be "generate", "encrypt" or "decrypt". If mode is "generate", it will generate a
 *       keyset, encrypt it and store it in the key-file argument. If mode is "encrypt" or
 *       "decrypt", it will read and decrypt an keyset from the key-file argument, and use it to
 *       encrypt or decrypt the input-file argument.
 *   <li>kek-uri: Use this Cloud KMS' key as the key-encrypting-key for envelope encryption.
 *   <li>gcp-credential-file: Use this JSON credential file to connect to Cloud KMS.
 *   <li>input-file: If mode is "encrypt" or "decrypt", read the input from this file.
 *   <li>output-file: If mode is "encrypt" or "decrypt", write the result to this file.
 */
public final class EncryptedKeysetExample {
  private static final String MODE_ENCRYPT = "encrypt";
  private static final String MODE_DECRYPT = "decrypt";
  private static final String MODE_GENERATE = "generate";
  private static final byte[] EMPTY_ASSOCIATED_DATA = new byte[0];

  public static void main(String[] args) throws Exception {
    if (args.length != 4 && args.length != 6) {
      System.err.printf("Expected 4 or 6 parameters, got %d\n", args.length);
      System.err.println(
          "Usage: java EncryptedKeysetExample generate/encrypt/decrypt key-file kek-uri"
              + " gcp-credential-file input-file output-file");
      System.exit(1);
    }
    String mode = args[0];
    if (!mode.equals(MODE_ENCRYPT) && !mode.equals(MODE_DECRYPT) && !mode.equals(MODE_GENERATE)) {
      System.err.print("The first argument should be either encrypt, decrypt or generate");
      System.exit(1);
    }
    Path keyFile = Paths.get(args[1]);
    String kekUri = args[2];
    String gcpCredentialFilename = args[3];

    // Initialise Tink: register all AEAD key types with the Tink runtime
    AeadConfig.register();

    // From the key-encryption key (KEK) URI, create a remote AEAD primitive for encrypting Tink
    // keysets.
    Aead kekAead = new GcpKmsClient().withCredentials(gcpCredentialFilename).getAead(kekUri);

    if (mode.equals(MODE_GENERATE)) {
      KeysetHandle handle = KeysetHandle.generateNew(PredefinedAeadParameters.AES128_GCM);

      String serializedEncryptedKeyset =
          TinkJsonProtoKeysetFormat.serializeEncryptedKeyset(
              handle, kekAead, EMPTY_ASSOCIATED_DATA);
      Files.write(keyFile, serializedEncryptedKeyset.getBytes(UTF_8));
      return;
    }

    // Use the primitive to encrypt/decrypt files

    // Read the encrypted keyset
    KeysetHandle handle =
        TinkJsonProtoKeysetFormat.parseEncryptedKeyset(
            new String(Files.readAllBytes(keyFile), UTF_8), kekAead, EMPTY_ASSOCIATED_DATA);

    // Get the primitive
    Aead aead = handle.getPrimitive(Aead.class);

    Path inputFile = Paths.get(args[4]);
    Path outputFile = Paths.get(args[5]);

    if (mode.equals(MODE_ENCRYPT)) {
      byte[] plaintext = Files.readAllBytes(inputFile);
      byte[] ciphertext = aead.encrypt(plaintext, EMPTY_ASSOCIATED_DATA);
      Files.write(outputFile, ciphertext);
    } else if (mode.equals(MODE_DECRYPT)) {
      byte[] ciphertext = Files.readAllBytes(inputFile);
      byte[] plaintext = aead.decrypt(ciphertext, EMPTY_ASSOCIATED_DATA);
      Files.write(outputFile, plaintext);
    }
  }

  private EncryptedKeysetExample() {}
}
EncryptedKeysetExample.java

Go

import (
	"bytes"
	"fmt"
	"log"

	"github.com/tink-crypto/tink-go/v2/aead"
	"github.com/tink-crypto/tink-go/v2/keyset"
	"github.com/tink-crypto/tink-go/v2/testing/fakekms"
)

// The fake KMS should only be used in tests. It is not secure.
const keyURI = "fake-kms://CM2b3_MDElQKSAowdHlwZS5nb29nbGVhcGlzLmNvbS9nb29nbGUuY3J5cHRvLnRpbmsuQWVzR2NtS2V5EhIaEIK75t5L-adlUwVhWvRuWUwYARABGM2b3_MDIAE"

func Example_encryptedKeyset() {
	// Get a KEK (key encryption key) AEAD. This is usually a remote AEAD to a KMS. In this example,
	// we use a fake KMS to avoid making RPCs.
	client, err := fakekms.NewClient(keyURI)
	if err != nil {
		log.Fatal(err)
	}
	kekAEAD, err := client.GetAEAD(keyURI)
	if err != nil {
		log.Fatal(err)
	}

	// Generate a new keyset handle for the primitive we want to use.
	newHandle, err := keyset.NewHandle(aead.AES256GCMKeyTemplate())
	if err != nil {
		log.Fatal(err)
	}

	// Choose some associated data. This is the context in which the keyset will be used.
	keysetAssociatedData := []byte("keyset encryption example")

	// Encrypt the keyset with the KEK AEAD and the associated data.
	buf := new(bytes.Buffer)
	writer := keyset.NewBinaryWriter(buf)
	err = newHandle.WriteWithAssociatedData(writer, kekAEAD, keysetAssociatedData)
	if err != nil {
		log.Fatal(err)
	}
	encryptedKeyset := buf.Bytes()

	// The encrypted keyset can now be stored.

	// To use the primitive, we first need to decrypt the keyset. We use the same
	// KEK AEAD and the same associated data that we used to encrypt it.
	reader := keyset.NewBinaryReader(bytes.NewReader(encryptedKeyset))
	handle, err := keyset.ReadWithAssociatedData(reader, kekAEAD, keysetAssociatedData)
	if err != nil {
		log.Fatal(err)
	}

	// Get the primitive.
	primitive, err := aead.New(handle)
	if err != nil {
		log.Fatal(err)
	}

	// Use the primitive.
	plaintext := []byte("message")
	associatedData := []byte("example encryption")
	ciphertext, err := primitive.Encrypt(plaintext, associatedData)
	if err != nil {
		log.Fatal(err)
	}
	decrypted, err := primitive.Decrypt(ciphertext, associatedData)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(decrypted))
	// Output: message
}
keyset_test.go

Python

"""A command-line utility for generating, encrypting and storing keysets."""

from absl import app
from absl import flags
from absl import logging

import tink
from tink import aead
from tink.integration import gcpkms


FLAGS = flags.FLAGS

flags.DEFINE_enum('mode', None, ['generate', 'encrypt', 'decrypt'],
                  'The operation to perform.')
flags.DEFINE_string('keyset_path', None,
                    'Path to the keyset used for encryption.')
flags.DEFINE_string('kek_uri', None,
                    'The Cloud KMS URI of the key encryption key.')
flags.DEFINE_string('gcp_credential_path', None,
                    'Path to the GCP credentials JSON file.')
flags.DEFINE_string('input_path', None, 'Path to the input file.')
flags.DEFINE_string('output_path', None, 'Path to the output file.')
flags.DEFINE_string('associated_data', None,
                    'Optional associated data to use with the '
                    'encryption operation.')


def main(argv):
  del argv  # Unused.

  associated_data = b'' if not FLAGS.associated_data else bytes(
      FLAGS.associated_data, 'utf-8')

  # Initialise Tink
  aead.register()

  try:
    # Read the GCP credentials and setup client
    client = gcpkms.GcpKmsClient(FLAGS.kek_uri, FLAGS.gcp_credential_path)
  except tink.TinkError as e:
    logging.exception('Error creating GCP KMS client: %s', e)
    return 1

  # Create envelope AEAD primitive using AES128 GCM for encrypting the data
  try:
    remote_aead = client.get_aead(FLAGS.kek_uri)
  except tink.TinkError as e:
    logging.exception('Error creating primitive: %s', e)
    return 1

  if FLAGS.mode == 'generate':
    # Generate a new keyset
    try:
      key_template = aead.aead_key_templates.AES128_GCM
      keyset_handle = tink.new_keyset_handle(key_template)
    except tink.TinkError as e:
      logging.exception('Error creating primitive: %s', e)
      return 1

    # Encrypt the keyset_handle with the remote key-encryption key (KEK)
    with open(FLAGS.keyset_path, 'wt') as keyset_file:
      try:
        keyset_encryption_associated_data = 'encrypted keyset example'
        serialized_encrypted_keyset = (
            tink.json_proto_keyset_format.serialize_encrypted(
                keyset_handle, remote_aead, keyset_encryption_associated_data
            )
        )
        keyset_file.write(serialized_encrypted_keyset)
      except tink.TinkError as e:
        logging.exception('Error writing key: %s', e)
        return 1
    return 0

  # Use the keyset to encrypt/decrypt data

  # Read the encrypted keyset into a keyset_handle
  with open(FLAGS.keyset_path, 'rt') as keyset_file:
    try:
      serialized_encrypted_keyset = keyset_file.read()
      keyset_encryption_associated_data = 'encrypted keyset example'
      keyset_handle = tink.json_proto_keyset_format.parse_encrypted(
          serialized_encrypted_keyset,
          remote_aead,
          keyset_encryption_associated_data,
      )
    except tink.TinkError as e:
      logging.exception('Error reading key: %s', e)
      return 1

  # Get the primitive
  try:
    cipher = keyset_handle.primitive(aead.Aead)
  except tink.TinkError as e:
    logging.exception('Error creating primitive: %s', e)
    return 1

  with open(FLAGS.input_path, 'rb') as input_file:
    input_data = input_file.read()
    if FLAGS.mode == 'decrypt':
      output_data = cipher.decrypt(input_data, associated_data)
    elif FLAGS.mode == 'encrypt':
      output_data = cipher.encrypt(input_data, associated_data)
    else:
      logging.error(
          'Unsupported mode %s. Please choose "encrypt" or "decrypt".',
          FLAGS.mode,
      )
      return 1

    with open(FLAGS.output_path, 'wb') as output_file:
      output_file.write(output_data)


if __name__ == '__main__':
  flags.mark_flags_as_required([
      'mode', 'keyset_path', 'kek_uri', 'gcp_credential_path'])
  app.run(main)
encrypted_keyset_cli.py

Etapa 4: rotacionar chaves

Para garantir a segurança do sistema, é necessário rotacionar as chaves.

1. Ative a rotação de chaves automática no KMS.

2. Determine uma frequência adequada para rotacionar as chaves. Isso depende da sensibilidade dos dados, do número de mensagens que você precisa criptografar e se é necessário coordenar a rotação com parceiros externos.

   • Para criptografia simétrica, use chaves de 30 a 90 dias.
   • Para criptografia assimétrica, a frequência de rotação pode ser menor, mas apenas se você puder revogar chaves com segurança.

Saiba mais sobre a rotação de chaves na documentação específica do KMS:

• Cloud KMS do Google Cloud
• KMS da Amazon
• HashiCorp Vault

Ponto principal:a rotação de chaves é uma prática recomendada essencial que impede que as chaves sejam reutilizadas extensivamente. A rotação regular de chaves limita o número de mensagens criptografadas com a mesma versão de chave, minimiza o número de mensagens potencialmente vulneráveis e garante a resiliência do sistema.