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 (
	"bytes"
	"fmt"
	"log"

	"github.com/tink-crypto/tink-go/v2/hybrid"
	"github.com/tink-crypto/tink-go/v2/insecurecleartextkeyset"
	"github.com/tink-crypto/tink-go/v2/keyset"
)

func main() {
	// A private keyset created with
	// "tinkey create-keyset --key-template=DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM --out private_keyset.cfg".
	// Note that this keyset has the secret key information in cleartext.
	privateJSONKeyset := `{
		"key": [{
				"keyData": {
						"keyMaterialType":
								"ASYMMETRIC_PRIVATE",
						"typeUrl":
								"type.googleapis.com/google.crypto.tink.HpkePrivateKey",
						"value":
								"EioSBggBEAEYAhogVWQpmQoz74jcAp5WOD36KiBQ71MVCpn2iWfOzWLtKV4aINfn8qlMbyijNJcCzrafjsgJ493ZZGN256KTfKw0WN+p"
				},
				"keyId": 958452012,
				"outputPrefixType": "TINK",
				"status": "ENABLED"
		}],
		"primaryKeyId": 958452012
  }`

	// The corresponding public keyset created with
	// "tinkey create-public-keyset --in private_keyset.cfg".
	publicJSONKeyset := `{
		"key": [{
				"keyData": {
						"keyMaterialType":
								"ASYMMETRIC_PUBLIC",
						"typeUrl":
								"type.googleapis.com/google.crypto.tink.HpkePublicKey",
						"value":
								"EgYIARABGAIaIFVkKZkKM++I3AKeVjg9+iogUO9TFQqZ9olnzs1i7Sle"
				},
				"keyId": 958452012,
				"outputPrefixType": "TINK",
				"status": "ENABLED"
		}],
		"primaryKeyId": 958452012
  }`

	// Create a keyset handle from the keyset containing the public key. Because the
	// public keyset does not contain any secrets, we can use [keyset.ReadWithNoSecrets].
	publicKeysetHandle, err := keyset.ReadWithNoSecrets(
		keyset.NewJSONReader(bytes.NewBufferString(publicJSONKeyset)))
	if err != nil {
		log.Fatal(err)
	}

	// Retrieve the HybridEncrypt primitive from publicKeysetHandle.
	encPrimitive, err := hybrid.NewHybridEncrypt(publicKeysetHandle)
	if err != nil {
		log.Fatal(err)
	}

	plaintext := []byte("message")
	encryptionContext := []byte("encryption context")
	ciphertext, err := encPrimitive.Encrypt(plaintext, encryptionContext)
	if err != nil {
		log.Fatal(err)
	}

	// Create a keyset handle from the cleartext private keyset in the previous
	// step. The keyset handle provides abstract access to the underlying keyset to
	// limit the access of the raw key material. WARNING: In practice,
	// it is unlikely you will want to use a 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.
	privateKeysetHandle, err := insecurecleartextkeyset.Read(
		keyset.NewJSONReader(bytes.NewBufferString(privateJSONKeyset)))
	if err != nil {
		log.Fatal(err)
	}

	// Retrieve the HybridDecrypt primitive from privateKeysetHandle.
	decPrimitive, err := hybrid.NewHybridDecrypt(privateKeysetHandle)
	if err != nil {
		log.Fatal(err)
	}

	decrypted, err := decPrimitive.Decrypt(ciphertext, encryptionContext)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(decrypted))
}

Output:

message

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(handle *keyset.Handle) (tink.HybridDecrypt, error)
• func NewHybridEncrypt(handle *keyset.Handle) (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 creates an ECIES-AEAD-HKDF key template with:

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

The DEM parameters are:

• AES key size: 16 bytes
• AES CTR IV size: 16 bytes
• HMAC key size: 32 bytes
• HMAC tag size: 16 bytes

func ECIESHKDFAES128GCMKeyTemplate

func ECIESHKDFAES128GCMKeyTemplate() *tinkpb.KeyTemplate

ECIESHKDFAES128GCMKeyTemplate creates an ECIES-AEAD-HKDF key template with:

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

func NewHybridDecrypt

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

NewHybridDecrypt returns an HybridDecrypt primitive from the given keyset handle.

func NewHybridEncrypt

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

NewHybridEncrypt returns an HybridEncrypt primitive from the given keyset handle.