streamingaead

Documentation

Overview

Package streamingaead provides implementations of the streaming AEAD primitive.

AEAD encryption assures the confidentiality and authenticity of the data. This primitive is CPA secure.

Example

package main

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 main() {
	// 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

Index

• func AES128CTRHMACSHA256Segment1MBKeyTemplate() *tinkpb.KeyTemplate
• func AES128CTRHMACSHA256Segment4KBKeyTemplate() *tinkpb.KeyTemplate
• func AES128GCMHKDF1MBKeyTemplate() *tinkpb.KeyTemplate
• func AES128GCMHKDF4KBKeyTemplate() *tinkpb.KeyTemplate
• func AES256CTRHMACSHA256Segment1MBKeyTemplate() *tinkpb.KeyTemplate
• func AES256CTRHMACSHA256Segment4KBKeyTemplate() *tinkpb.KeyTemplate
• func AES256GCMHKDF1MBKeyTemplate() *tinkpb.KeyTemplate
• func AES256GCMHKDF4KBKeyTemplate() *tinkpb.KeyTemplate
• func New(handle *keyset.Handle) (tink.StreamingAEAD, error)

Examples

• Package

Functions

func AES128CTRHMACSHA256Segment1MBKeyTemplate

func AES128CTRHMACSHA256Segment1MBKeyTemplate() *tinkpb.KeyTemplate

AES128CTRHMACSHA256Segment1MBKeyTemplate is a KeyTemplate that generates an AES-CTR-HMAC key with the following parameters:

• Main key size: 16 bytes
• HKDF algorthim: HMAC-SHA256
• AES-CTR derived key size: 16 bytes
• Tag algorithm: HMAC-SHA256
• Tag size: 32 bytes
• Ciphertext segment size: 1048576 bytes (1 MB)

func AES128CTRHMACSHA256Segment4KBKeyTemplate

func AES128CTRHMACSHA256Segment4KBKeyTemplate() *tinkpb.KeyTemplate

AES128CTRHMACSHA256Segment4KBKeyTemplate is a KeyTemplate that generates an AES-CTR-HMAC key with the following parameters:

• Main key size: 16 bytes
• HKDF algorthim: HMAC-SHA256
• AES-CTR derived key size: 16 bytes
• Tag algorithm: HMAC-SHA256
• Tag size: 32 bytes
• Ciphertext segment size: 4096 bytes (4 KB)

func AES128GCMHKDF1MBKeyTemplate

func AES128GCMHKDF1MBKeyTemplate() *tinkpb.KeyTemplate

AES128GCMHKDF1MBKeyTemplate is a KeyTemplate that generates an AES-GCM key with the following parameters:

• Main key size: 16 bytes
• HKDF algo: HMAC-SHA256
• Size of AES-GCM derived keys: 16 bytes
• Ciphertext segment size: 1048576 bytes (1 MB)

func AES128GCMHKDF4KBKeyTemplate

func AES128GCMHKDF4KBKeyTemplate() *tinkpb.KeyTemplate

AES128GCMHKDF4KBKeyTemplate is a KeyTemplate that generates an AES-GCM key with the following parameters:

• Main key size: 16 bytes
• HKDF algo: HMAC-SHA256
• Size of AES-GCM derived keys: 16 bytes
• Ciphertext segment size: 4096 bytes

func AES256CTRHMACSHA256Segment1MBKeyTemplate

func AES256CTRHMACSHA256Segment1MBKeyTemplate() *tinkpb.KeyTemplate

AES256CTRHMACSHA256Segment1MBKeyTemplate is a KeyTemplate that generates an AES-CTR-HMAC key with the following parameters:

• Main key size: 32 bytes
• HKDF algorthim: HMAC-SHA256
• AES-CTR derived key size: 32 bytes
• Tag algorithm: HMAC-SHA256
• Tag size: 32 bytes
• Ciphertext segment size: 1048576 bytes (1 MB)

func AES256CTRHMACSHA256Segment4KBKeyTemplate

func AES256CTRHMACSHA256Segment4KBKeyTemplate() *tinkpb.KeyTemplate

AES256CTRHMACSHA256Segment4KBKeyTemplate is a KeyTemplate that generates an AES-CTR-HMAC key with the following parameters:

• Main key size: 32 bytes
• HKDF algorthim: HMAC-SHA256
• AES-CTR derived key size: 32 bytes
• Tag algorithm: HMAC-SHA256
• Tag size: 32 bytes
• Ciphertext segment size: 4096 bytes (4 KB)

func AES256GCMHKDF1MBKeyTemplate

func AES256GCMHKDF1MBKeyTemplate() *tinkpb.KeyTemplate

AES256GCMHKDF1MBKeyTemplate is a KeyTemplate that generates an AES-GCM key with the following parameters:

• Main key size: 32 bytes
• HKDF algo: HMAC-SHA256
• Size of AES-GCM derived keys: 32 bytes
• Ciphertext segment size: 1048576 bytes (1 MB)

func AES256GCMHKDF4KBKeyTemplate

func AES256GCMHKDF4KBKeyTemplate() *tinkpb.KeyTemplate

AES256GCMHKDF4KBKeyTemplate is a KeyTemplate that generates an AES-GCM key with the following parameters:

• Main key size: 32 bytes
• HKDF algo: HMAC-SHA256
• Size of AES-GCM derived keys: 32 bytes
• Ciphertext segment size: 4096 bytes

func New

func New(handle *keyset.Handle) (tink.StreamingAEAD, error)

New returns a StreamingAEAD primitive from the given keyset handle.