TinkStreamingAead 1.0.1

TinkStreamingAead

Open-source .NET port of Google Tink's AES256-GCM-HKDF Streaming AEAD.

Fully interoperable with Google Tink (Java, C++, Go, Python) — encrypt in .NET, decrypt in any Tink language, and vice versa.

Features

• Tink wire-format compatible — Uses the exact AES256-GCM-HKDF-1MB streaming format.
• Streaming — Encrypt/decrypt multi-gigabyte files without loading them into memory.
• Three API styles:
  • Static convenience (Encrypt / Decrypt) — straightforward sync/async calls
  • Lazy streams (CreateEncryptStream / CreateDecryptStream) — compose with GZipStream, CryptoStream, etc.
  • Simplified facade (TinkCrypto) — set the key once, one-liner file operations
• Associated Data (AAD) — Authenticate metadata alongside the ciphertext.
• Cross-framework — Targets netstandard2.0 (.NET Framework 4.8+) and net6.0.
• Zero dependencies on modern .NET — Uses Portable.BouncyCastle on netstandard2.0 where AesGcm isn't available; native AesGcm on net6.0+.

Installation

dotnet add package TinkStreamingAead

Or via Package Manager:

Install-Package TinkStreamingAead

Quick Start

Encrypt and decrypt a file (one-liner with TinkCrypto)

using TinkStreamingAead;

// Generate a key (save this securely!)
byte[] key = TinkCrypto.GenerateKey();

// Create a crypto instance
var crypto = new TinkCrypto(key);

// Encrypt a file
crypto.EncryptFile("document.pdf", "document.pdf.enc");

// Decrypt it back
crypto.DecryptFile("document.pdf.enc", "document_decrypted.pdf");

// For multi-threaded scenarios, create one instance per thread
var workerCrypto = new TinkCrypto(key);

Async with progress reporting

var progress = new Progress<long>(bytes => Console.WriteLine($"Processed: {bytes} bytes"));

await Aes256GcmHkdf1MB.EncryptAsync(
    key,
    inputStream,
    outputStream,
    aad: null,
    progress: progress,
    cancellationToken: ct);

Lazy streaming (compose with other streams)

using var encryptor = Aes256GcmHkdf1MB.CreateEncryptStream(key, fileStream);
using var gzip = new System.IO.Compression.GZipStream(encryptor, CompressionMode.Compress);
// Write to gzip → automatically encrypted to fileStream

In-memory encryption

var crypto = new TinkCrypto(key);
byte[] ciphertext = crypto.EncryptBytes(Encoding.UTF8.GetBytes("Hello, World!"));
byte[] plaintext = crypto.DecryptBytes(ciphertext);

With associated data (AAD)

byte[] aad = Encoding.UTF8.GetBytes("session-12345");

// Encrypt with AAD
Aes256GcmHkdf1MB.Encrypt(key, plaintextStream, ciphertextStream, aad);

// Decrypt must use the same AAD, or it fails
Aes256GcmHkdf1MB.Decrypt(key, ciphertextStream, plaintextStream, aad);

Predict ciphertext size

long plainLen = new FileInfo("large_file.dat").Length;
long cipherLen = Aes256GcmHkdf1MB.GetCiphertextLength(plainLen);
Console.WriteLine($"Ciphertext will be {cipherLen} bytes");

Extract key from Tink JSON keyset

string keysetJson = File.ReadAllText("tink-keyset.json");
byte[] key = TinkCrypto.ExtractKeyFromJsonKeyset(keysetJson);
var crypto = new TinkCrypto(key);
crypto.DecryptFile("encrypted.bin", "decrypted.bin");

Lazy file streaming

var crypto = new TinkCrypto(key);

// Encrypt directly to a file without buffering everything
using var encryptor = crypto.CreateEncryptFileStream("output.enc");
encryptor.Write(plaintextBytes, 0, plaintextBytes.Length);
// File is finalized on Dispose

// Decrypt directly from a file
using var decryptor = crypto.CreateDecryptFileStream("output.enc");
using var ms = new MemoryStream();
decryptor.CopyTo(ms);
byte[] result = ms.ToArray();

API Reference

Aes256GcmHkdf1MB (core static class)

TinkCrypto (instance-based wrapper, implements IDisposable)

Constructor: new TinkCrypto(key, associatedData?) — creates an instance with a 32-byte key.

Static utilities:

Note: TinkCrypto instances are not thread-safe — use one instance per thread. For stateless multi-threaded use, call Aes256GcmHkdf1MB methods directly with per-call keys.

Cryptographic Details

The implementation follows the Google Tink Streaming AEAD specification exactly.

Interoperability

Ciphertexts produced by this library can be decrypted by:

• Google Tink (Java, C++, Go, Python)
• Tinkey CLI tool
• The test suite verifies interoperability against ciphertexts generated by Google Tink (Python).

Testing

The test project (tests/TinkStreamingAead.Tests/) targets net8.0 and net48 and includes:

# Run all tests
dotnet test

# Run a specific category
dotnet test --filter "FullyQualifiedName~GoldenVectorTests"
dotnet test --filter "FullyQualifiedName~TinkInteropTests"

Test Categories

Building from Source

# Clone the repository
git clone https://github.com/salehalakhras/TinkStreamingAead.git
cd TinkStreamingAead

# Build
dotnet build

# Run tests
dotnet test

# Create NuGet package
dotnet pack src/TinkStreamingAead/TinkStreamingAead.csproj -c Release

License

MIT License

Copyright (c) 2026 Saleh Alakhras

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.