Wir empfehlen für die meisten Anwendungsfälle der Dateiverschlüsselung das Streaming AEAD-Primitive mit dem Schlüsseltyp AES128_GCM_HKDF_1MB.
Das Primitive „Streaming Authenticated Encryption with Associated Data“ (Streaming AEAD) eignet sich zum Verschlüsseln von Live-Datenstreams oder großen Dateien, die nicht in den Arbeitsspeicher passen. Ähnlich wie AEAD ist sie symmetrisch und verwendet einen einzigen Schlüssel für die Ver- und Entschlüsselung.
In den folgenden Beispielen erfahren Sie, wie Sie die Streaming-AEAD-Primitive verwenden:
Ok
import ( "bytes" "fmt" "io" "log" "os" "path/filepath" "github.com/tink-crypto/tink-go/v2/insecurecleartextkeyset" "github.com/tink-crypto/tink-go/v2/keyset" "github.com/tink-crypto/tink-go/v2/streamingaead" ) func Example() { // A keyset created with "tinkey create-keyset --key-template=AES256_CTR_HMAC_SHA256_1MB". Note // that this keyset has the secret key information in cleartext. jsonKeyset := `{ "primaryKeyId": 1720777699, "key": [{ "keyData": { "typeUrl": "type.googleapis.com/google.crypto.tink.AesCtrHmacStreamingKey", "keyMaterialType": "SYMMETRIC", "value": "Eg0IgCAQIBgDIgQIAxAgGiDtesd/4gCnQdTrh+AXodwpm2b6BFJkp043n+8mqx0YGw==" }, "outputPrefixType": "RAW", "keyId": 1720777699, "status": "ENABLED" }] }` // 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 an 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 StreamingAEAD primitive we want to use from the keyset handle. primitive, err := streamingaead.New(keysetHandle) if err != nil { log.Fatal(err) } // Create a file with the plaintext. dir, err := os.MkdirTemp("", "streamingaead") if err != nil { log.Fatal(err) } defer os.RemoveAll(dir) plaintextPath := filepath.Join(dir, "plaintext") if err := os.WriteFile(plaintextPath, []byte("this data needs to be encrypted"), 0666); err != nil { log.Fatal(err) } plaintextFile, err := os.Open(plaintextPath) if err != nil { log.Fatal(err) } // associatedData defines the context of the encryption. Here, we include the path of the // plaintext file. associatedData := []byte("associatedData for " + plaintextPath) // Encrypt the plaintext file and write the output to the ciphertext file. In this case the // primary key of the keyset will be used (which is also the only key in this example). ciphertextPath := filepath.Join(dir, "ciphertext") ciphertextFile, err := os.Create(ciphertextPath) if err != nil { log.Fatal(err) } w, err := primitive.NewEncryptingWriter(ciphertextFile, associatedData) if err != nil { log.Fatal(err) } if _, err := io.Copy(w, plaintextFile); err != nil { log.Fatal(err) } if err := w.Close(); err != nil { log.Fatal(err) } if err := ciphertextFile.Close(); err != nil { log.Fatal(err) } if err := plaintextFile.Close(); err != nil { log.Fatal(err) } // Decrypt the ciphertext file and write the output to the decrypted file. The // decryption finds the correct key in the keyset and decrypts the ciphertext. // If no key is found or decryption fails, it returns an error. ciphertextFile, err = os.Open(ciphertextPath) if err != nil { log.Fatal(err) } decryptedPath := filepath.Join(dir, "decrypted") decryptedFile, err := os.Create(decryptedPath) if err != nil { log.Fatal(err) } r, err := primitive.NewDecryptingReader(ciphertextFile, associatedData) if err != nil { log.Fatal(err) } if _, err := io.Copy(decryptedFile, r); err != nil { log.Fatal(err) } if err := decryptedFile.Close(); err != nil { log.Fatal(err) } if err := ciphertextFile.Close(); err != nil { log.Fatal(err) } // Print the content of the decrypted file. b, err := os.ReadFile(decryptedPath) if err != nil { log.Fatal(err) } fmt.Println(string(b)) // Output: this data needs to be encrypted }
Java
package streamingaead; import static java.nio.charset.StandardCharsets.UTF_8; import com.google.crypto.tink.InsecureSecretKeyAccess; import com.google.crypto.tink.KeysetHandle; import com.google.crypto.tink.RegistryConfiguration; import com.google.crypto.tink.StreamingAead; import com.google.crypto.tink.TinkJsonProtoKeysetFormat; import com.google.crypto.tink.streamingaead.StreamingAeadConfig; import java.io.IOException; import java.nio.ByteBuffer; import java.nio.channels.FileChannel; import java.nio.channels.ReadableByteChannel; import java.nio.channels.WritableByteChannel; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.nio.file.StandardOpenOption; import java.security.GeneralSecurityException; /** * A command-line utility for encrypting files with Streaming 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 StreamingAeadExample { private static final String MODE_ENCRYPT = "encrypt"; private static final String MODE_DECRYPT = "decrypt"; private static final int BLOCK_SIZE_IN_BYTES = 8 * 1024; 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 StreamingAeadExample 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); } // Initialize Tink: register all Streaming AEAD key types with the Tink runtime StreamingAeadConfig.register(); // Read the keyset into a KeysetHandle KeysetHandle handle = TinkJsonProtoKeysetFormat.parseKeyset( new String(Files.readAllBytes(keyFile), UTF_8), InsecureSecretKeyAccess.get()); // Get the primitive StreamingAead streamingAead = handle.getPrimitive(RegistryConfiguration.get(), StreamingAead.class); // Use the primitive to encrypt/decrypt files if (mode.equals(MODE_ENCRYPT)) { encryptFile(streamingAead, inputFile, outputFile, associatedData); } else if (mode.equals(MODE_DECRYPT)) { decryptFile(streamingAead, inputFile, outputFile, associatedData); } else { System.err.println( "The first argument must be either " + MODE_ENCRYPT + " or " + MODE_DECRYPT + ", got: " + mode); System.exit(1); } } private static void encryptFile( StreamingAead streamingAead, Path inputFile, Path outputFile, byte[] associatedData) throws GeneralSecurityException, IOException { try (WritableByteChannel encryptingChannel = streamingAead.newEncryptingChannel( FileChannel.open(outputFile, StandardOpenOption.WRITE, StandardOpenOption.CREATE), associatedData); FileChannel inputChannel = FileChannel.open(inputFile, StandardOpenOption.READ)) { ByteBuffer byteBuffer = ByteBuffer.allocate(BLOCK_SIZE_IN_BYTES); while (true) { int read = inputChannel.read(byteBuffer); if (read <= 0) { return; } byteBuffer.flip(); while (byteBuffer.hasRemaining()) { encryptingChannel.write(byteBuffer); } byteBuffer.clear(); } } } private static void decryptFile( StreamingAead streamingAead, Path inputFile, Path outputFile, byte[] associatedData) throws GeneralSecurityException, IOException { try (ReadableByteChannel decryptingChannel = streamingAead.newDecryptingChannel( FileChannel.open(inputFile, StandardOpenOption.READ), associatedData); FileChannel outputChannel = FileChannel.open(outputFile, StandardOpenOption.WRITE, StandardOpenOption.CREATE)) { ByteBuffer byteBuffer = ByteBuffer.allocate(BLOCK_SIZE_IN_BYTES); while (true) { int read = decryptingChannel.read(byteBuffer); if (read <= 0) { return; } byteBuffer.flip(); while (byteBuffer.hasRemaining()) { outputChannel.write(byteBuffer); } byteBuffer.clear(); } } } private StreamingAeadExample() {} }
Python
"""A command-line utility for using streaming AEAD for a file. It loads cleartext keys from disk - this is not recommended! It requires 4 arguments (and one optional one): mode: either 'encrypt' or 'decrypt' keyset_path: name of the file with the keyset to be used for encryption or decryption input_path: name of the file with the input data to be encrypted or decrypted output_path: name of the file to write the ciphertext respectively plaintext to [optional] associated_data: the associated data used for encryption/decryption provided as a string. """ from typing import BinaryIO from absl import app from absl import flags from absl import logging import tink from tink import secret_key_access from tink import streaming_aead FLAGS = flags.FLAGS BLOCK_SIZE = 1024 * 1024 # The CLI tool will read/write at most 1 MB at once. flags.DEFINE_enum('mode', None, ['encrypt', 'decrypt'], 'Selects if the file should be encrypted or decrypted.') flags.DEFINE_string('keyset_path', None, 'Path to the keyset used for encryption or decryption.') 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, 'Associated data used for the encryption or decryption.') def read_as_blocks(file: BinaryIO): """Generator function to read from a file BLOCK_SIZE bytes. Args: file: The file object to read from. Yields: Returns up to BLOCK_SIZE bytes from the file. """ while True: data = file.read(BLOCK_SIZE) # If file was opened in rawIO, EOF is only reached when b'' is returned. # pylint: disable=g-explicit-bool-comparison if data == b'': break # pylint: enable=g-explicit-bool-comparison yield data def encrypt_file(input_file: BinaryIO, output_file: BinaryIO, associated_data: bytes, primitive: streaming_aead.StreamingAead): """Encrypts a file with the given streaming AEAD primitive. Args: input_file: File to read from. output_file: File to write to. associated_data: Associated data provided for the AEAD. primitive: The streaming AEAD primitive used for encryption. """ with primitive.new_encrypting_stream(output_file, associated_data) as enc_stream: for data_block in read_as_blocks(input_file): enc_stream.write(data_block) def decrypt_file(input_file: BinaryIO, output_file: BinaryIO, associated_data: bytes, primitive: streaming_aead.StreamingAead): """Decrypts a file with the given streaming AEAD primitive. This function will cause the program to exit with 1 if the decryption fails. Args: input_file: File to read from. output_file: File to write to. associated_data: Associated data provided for the AEAD. primitive: The streaming AEAD primitive used for decryption. """ try: with primitive.new_decrypting_stream(input_file, associated_data) as dec_stream: for data_block in read_as_blocks(dec_stream): output_file.write(data_block) except tink.TinkError as e: logging.exception('Error decrypting ciphertext: %s', e) exit(1) def main(argv): del argv associated_data = b'' if not FLAGS.associated_data else bytes( FLAGS.associated_data, 'utf-8') # Initialise Tink. try: streaming_aead.register() except tink.TinkError as e: logging.exception('Error initialising Tink: %s', e) return 1 # Read the keyset into a keyset_handle. with open(FLAGS.keyset_path, 'rt') as keyset_file: try: text = keyset_file.read() keyset_handle = tink.json_proto_keyset_format.parse( text, secret_key_access.TOKEN ) except tink.TinkError as e: logging.exception('Error reading key: %s', e) return 1 # Get the primitive. try: streaming_aead_primitive = keyset_handle.primitive( streaming_aead.StreamingAead) except tink.TinkError as e: logging.exception('Error creating streaming AEAD primitive from keyset: %s', e) return 1 # Encrypt or decrypt the file. with open(FLAGS.input_path, 'rb') as input_file: with open(FLAGS.output_path, 'wb') as output_file: if FLAGS.mode == 'encrypt': encrypt_file(input_file, output_file, associated_data, streaming_aead_primitive) elif FLAGS.mode == 'decrypt': decrypt_file(input_file, output_file, associated_data, streaming_aead_primitive) if __name__ == '__main__': flags.mark_flag_as_required('mode') flags.mark_flag_as_required('keyset_path') flags.mark_flag_as_required('input_path') flags.mark_flag_as_required('output_path') app.run(main)
Streaming AEAD
Das Streaming-AEAD-Primitive bietet eine authentifizierte Verschlüsselung für Streamingdaten. Sie ist nützlich, wenn die zu verschlüsselnden Daten zu groß sind, um in einem einzigen Schritt verarbeitet zu werden. Typische Anwendungsfälle sind die Verschlüsselung großer Dateien oder Live-Datenstreams.
Die Verschlüsselung erfolgt in Segmenten, die an ihren Speicherort innerhalb eines Geheimtexts gebunden sind und nicht entfernt oder neu angeordnet werden können. Segmente aus einem Geheimtext können nicht in einen anderen Geheimtext eingefügt werden. Wenn ein vorhandener Geheimtext geändert werden soll, muss der gesamte Datenstream noch einmal verschlüsselt werden.1
Die Entschlüsselung ist schnell, da jeweils nur ein Teil des Geheimtexts entschlüsselt und authentifiziert wird. Teilweise Klartexte können ohne Verarbeitung des gesamten Geheimtexts abgerufen werden.
Streaming-AEAD-Implementierungen erfüllen die AEAD-Definition und sind nOAE-sicher. Sie haben folgende Eigenschaften:
- Secrecy Außer der Länge ist nichts über den Klartext bekannt.
- Authenticity Es ist nicht möglich, den verschlüsselten Klartext, der dem Geheimtext zugrunde liegt, unbemerkt zu ändern.
- Symmetric Der Klartext wird mit demselben Schlüssel verschlüsselt und der Geheimtext wird mit demselben Schlüssel entschlüsselt.
- Zufälligkeit: Die Verschlüsselung wird zufällig durchgeführt. Zwei Nachrichten mit demselben Klartext liefern unterschiedliche Geheimtexte. Angreifer können nicht wissen, welcher Geheimtext einem bestimmten Klartext entspricht.
Verknüpfte Daten
Mit der Streaming-AEAD-Primitiv kann Geheimtext mit bestimmten zugehörigen Daten verknüpft werden. Angenommen, Sie haben eine Datenbank mit den Feldern user-id
und encrypted-medical-history
. In diesem Fall kann user-id
beim Verschlüsseln von encrypted-medical-history
als verknüpfte Daten verwendet werden. Dadurch wird verhindert, dass ein Angreifer einen medizinischen Verlauf von einem Nutzer zu einem anderen verschieben kann.
Schlüsseltyp auswählen
Wir empfehlen für die meisten Anwendungsfälle AES128_GCM_HKDF_1MB. Allgemein gilt:
- AES-GCM-HKDF
- AES128_GCM_HKDF_1MB (oder AES256_GCM_HKDF_1MB) ist die schnellere Option. Es können 264 Dateien mit jeweils bis zu 264 Byte verschlüsselt werden. Während der Verschlüsselung und Entschlüsselung wird etwa 1 MB Arbeitsspeicher verbraucht.
- AES128_GCM_HKDF_4KB belegt etwa 4 KB Arbeitsspeicher und ist eine gute Wahl, wenn Ihr System nicht viel Arbeitsspeicher hat.
- AES-CTR HMAC
- AES128_CTR_HMAC_SHA256_1MB (oder AES256_CTR_HMAC_SHA256_1MB) ist eine konservativere Option.
Sicherheitsgarantien
Streaming-AEAD-Implementierungen bieten folgende Vorteile:
- CCA2-Sicherheit
- Mindestens 80-Bit-Authentifizierungsstärke.
- Es können mindestens 264 Nachrichten3 mit insgesamt 251 Byte2 verschlüsselt werden . Kein Angriff mit bis zu 232 ausgewählten Klartexten oder ausgewählten Geheimtexten hat eine Erfolgswahrscheinlichkeit, die größer als 2−32 ist.
-
Ein Grund für diese Einschränkung ist die Verwendung der AES-GCM-Chiffre. Das Verschlüsseln eines anderen Klartextsegments am selben Speicherort würde der Wiederverwendung des IV entsprechen, was gegen die Sicherheitsgarantien von AES-GCM verstößt. Außerdem werden so Rollback-Angriffe verhindert, bei denen der Angreifer versucht, eine frühere Version der Datei unbemerkt wiederherzustellen. ↩
-
Es werden 232 Segmente unterstützt, wobei jedes Segment
segment_size - tag_size
Byte Klartext enthält. Bei 1-MB-Segmenten beträgt die Gesamtgröße des Klartexts 232 * (220 – 16) ≈ 251 Byte. ↩ -
Streaming-AEAD wird unsicher, wenn eine Kombination aus abgeleitetem Schlüssel (128 Bit) und Nonce-Prefix (unabhängiger Zufallswert mit 7 Byte) wiederholt wird. Wir haben eine Kollisionsresistenz von 184 Bit, was ungefähr 264 Nachrichten entspricht, wenn die Erfolgswahrscheinlichkeit unter 2−32 liegen soll. ↩