hybrid

Documentation

Overview

Package hybrid provides implementations of the Hybrid Encryption primitive.

The functionality of Hybrid Encryption is represented as a pair of interfaces:

• HybridEncrypt for encryption of data
• HybridDecrypt for decryption of data

Implementations of these interfaces are secure against adaptive chosen ciphertext attacks. In addition to plaintext the encryption takes an extra parameter contextInfo, which usually is public data implicit from the context, but should be bound to the resulting ciphertext, i.e. the ciphertext allows for checking the integrity of contextInfo (but there are no guarantees wrt. the secrecy or authenticity of contextInfo).

Example

package main

import (
	"encoding/base64"
	"fmt"
	"log"

	"github.com/google/tink/go/hybrid"
	"github.com/google/tink/go/keyset"
)

func main() {
	khPriv, err := keyset.NewHandle(hybrid.ECIESHKDFAES128CTRHMACSHA256KeyTemplate())
	if err != nil {
		log.Fatal(err)
	}

	// TODO: save the private keyset to a safe location. DO NOT hardcode it in source code.
	// 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.

	khPub, err := khPriv.Public()
	if err != nil {
		log.Fatal(err)
	}

	// TODO: share the public keyset with the sender.

	enc, err := hybrid.NewHybridEncrypt(khPub)
	if err != nil {
		log.Fatal(err)
	}

	msg := []byte("this data needs to be encrypted")
	encryptionContext := []byte("encryption context")
	ct, err := enc.Encrypt(msg, encryptionContext)
	if err != nil {
		log.Fatal(err)
	}

	dec, err := hybrid.NewHybridDecrypt(khPriv)
	if err != nil {
		log.Fatal(err)
	}

	pt, err := dec.Decrypt(ct, encryptionContext)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Ciphertext: %s\n", base64.StdEncoding.EncodeToString(ct))
	fmt.Printf("Original  plaintext: %s\n", msg)
	fmt.Printf("Decrypted Plaintext: %s\n", pt)
}

Index

• func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_128_GCM_Key_Template() *tinkpb.KeyTemplate
• func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_128_GCM_Raw_Key_Template() *tinkpb.KeyTemplate
• func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM_Key_Template() *tinkpb.KeyTemplate
• func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM_Raw_Key_Template() *tinkpb.KeyTemplate
• func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_CHACHA20_POLY1305_Key_Template() *tinkpb.KeyTemplate
• func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_CHACHA20_POLY1305_Raw_Key_Template() *tinkpb.KeyTemplate
• func ECIESHKDFAES128CTRHMACSHA256KeyTemplate() *tinkpb.KeyTemplate
• func ECIESHKDFAES128GCMKeyTemplate() *tinkpb.KeyTemplate
• func NewHybridDecrypt(h *keyset.Handle) (tink.HybridDecrypt, error)
• func NewHybridDecryptWithKeyManager(h *keyset.Handle, km registry.KeyManager) (tink.HybridDecrypt, error)
• func NewHybridEncrypt(h *keyset.Handle) (tink.HybridEncrypt, error)
• func NewHybridEncryptWithKeyManager(h *keyset.Handle, km registry.KeyManager) (tink.HybridEncrypt, error)

Examples

• Package

Functions

func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_128_GCM_Key_Template

func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_128_GCM_Key_Template() *tinkpb.KeyTemplate

DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_128_GCM_Key_Template creates a HPKE key template with

• KEM: DHKEM_X25519_HKDF_SHA256,
• KDF: HKDF_SHA256, and
• AEAD: AES_128_GCM.

It adds the 5-byte Tink prefix to ciphertexts.

func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_128_GCM_Raw_Key_Template

func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_128_GCM_Raw_Key_Template() *tinkpb.KeyTemplate

DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_128_GCM_Raw_Key_Template creates a HPKE key template with

• KEM: DHKEM_X25519_HKDF_SHA256,
• KDF: HKDF_SHA256, and
• AEAD: AES_128_GCM.

It does not add a prefix to ciphertexts.

func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM_Key_Template

func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM_Key_Template() *tinkpb.KeyTemplate

DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM_Key_Template creates a HPKE key template with

• KEM: DHKEM_X25519_HKDF_SHA256,
• KDF: HKDF_SHA256, and
• AEAD: AES_256_GCM.

It adds the 5-byte Tink prefix to ciphertexts.

func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM_Raw_Key_Template

func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM_Raw_Key_Template() *tinkpb.KeyTemplate

DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM_Raw_Key_Template creates a HPKE key template with

• KEM: DHKEM_X25519_HKDF_SHA256,
• KDF: HKDF_SHA256, and
• AEAD: AES_256_GCM.

It does not add a prefix to ciphertexts.

func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_CHACHA20_POLY1305_Key_Template

func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_CHACHA20_POLY1305_Key_Template() *tinkpb.KeyTemplate

DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_CHACHA20_POLY1305_Key_Template creates a HPKE key template with

• KEM: DHKEM_X25519_HKDF_SHA256,
• KDF: HKDF_SHA256, and
• AEAD: CHACHA20_POLY1305.

It adds the 5-byte Tink prefix to ciphertexts.

func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_CHACHA20_POLY1305_Raw_Key_Template

func DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_CHACHA20_POLY1305_Raw_Key_Template() *tinkpb.KeyTemplate

DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_CHACHA20_POLY1305_Raw_Key_Template creates a HPKE key template with

• KEM: DHKEM_X25519_HKDF_SHA256,
• KDF: HKDF_SHA256, and
• AEAD: CHACHA20_POLY1305.

It does not add a prefix to ciphertexts.

func ECIESHKDFAES128CTRHMACSHA256KeyTemplate

func ECIESHKDFAES128CTRHMACSHA256KeyTemplate() *tinkpb.KeyTemplate

ECIESHKDFAES128CTRHMACSHA256KeyTemplate is a KeyTemplate that generates an ECDH P-256 and decapsulation key AES128-CTR-HMAC-SHA256 with the following parameters:

• KEM: ECDH over NIST P-256
• DEM: AES128-CTR-HMAC-SHA256 with the following parameters
• AES key size: 16 bytes
• AES CTR IV size: 16 bytes
• HMAC key size: 32 bytes
• HMAC tag size: 16 bytes
• KDF: HKDF-HMAC-SHA256 with an empty salt

func ECIESHKDFAES128GCMKeyTemplate

func ECIESHKDFAES128GCMKeyTemplate() *tinkpb.KeyTemplate

ECIESHKDFAES128GCMKeyTemplate is a KeyTemplate that generates an ECDH P-256 and decapsulation key AES128-GCM key with the following parameters:

• KEM: ECDH over NIST P-256
• DEM: AES128-GCM
• KDF: HKDF-HMAC-SHA256 with an empty salt

func NewHybridDecrypt

func NewHybridDecrypt(h *keyset.Handle) (tink.HybridDecrypt, error)

NewHybridDecrypt returns an HybridDecrypt primitive from the given keyset handle.

func NewHybridDecryptWithKeyManager

func NewHybridDecryptWithKeyManager(h *keyset.Handle, km registry.KeyManager) (tink.HybridDecrypt, error)

NewHybridDecryptWithKeyManager returns an HybridDecrypt primitive from the given keyset handle and custom key manager.

Deprecated: Use NewHybridDecrypt.

func NewHybridEncrypt

func NewHybridEncrypt(h *keyset.Handle) (tink.HybridEncrypt, error)

NewHybridEncrypt returns an HybridEncrypt primitive from the given keyset handle.

func NewHybridEncryptWithKeyManager

func NewHybridEncryptWithKeyManager(h *keyset.Handle, km registry.KeyManager) (tink.HybridEncrypt, error)

NewHybridEncryptWithKeyManager returns an HybridEncrypt primitive from the given keyset handle and custom key manager.

Deprecated: Use NewHybridEncrypt.