ecdh

Documentation

Overview

Package ecdh provides implementations of payload encryption using ECDH-ES/1PU KW key wrapping with AEAD primitives.

The functionality of ecdh Encryption is represented as a pair of primitives (interfaces):

- ECDHEncrypt for encryption of data and aad for a given cek (recipients cek wrapping is not done in this primitive)

- ECDHDecrypt for decryption of data for a given cek and returning decrypted plaintext

Example:

 package main

 import (
     "bytes"

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

     "github.com/hyperledger/aries-framework-go/pkg/crypto/tinkcrypto/primitive/composite"
     "github.com/hyperledger/aries-framework-go/pkg/crypto/tinkcrypto/primitive/composite/ecdh"
 )

 func main() {
     // create recipient side keyset handle
     recKH, err := keyset.NewHandle(ecdh.NISTP256ECDHKWKeyTemplate())
     if err != nil {
         //handle error
     }

     // extract recipient public keyset handle and key
     recPubKH, err := recKH.Public()
     if err != nil {
         //handle error
     }

     buf := new(bytes.Buffer)
     pubKeyWriter := ecdh.NewWriter(buf)
     err = recPubKH.WriteWithNoSecrets(pubKeyWriter)
     if err != nil {
         //handle error
     }
     // ecPubKey represents a recipient public key that can be used to wrap cek
     ecPubKey := new(composite.VerificationMethod)
     err := json.Unmarshal(buf.Bytes(), ecPubKey)

		// see pkg/crypto/tinkcrypto to see how you can wrap a shared secret (cek)

		// once a cek is created create an ECDH KH that can be used to encrypt plaintext as follows
		// for AES256GCM content encryption using a NIST P key for cek wrapping as an example
		kt := ecdh.KeyTemplateForECDHPrimitiveWithCEK(cek, true, ecdh.AES256GCM)

		kh, err := keyset.NewHandle(kt)
		if err != nil {
			// handle error
		}

		pubKH, err := kh.Public()
		if err != nil {
			// handle error
		}

		// finally get the encryption primitive from the public key handle created above
		e:= ecdh.NewECDHEncrypt(pubKH)

		// and now encrypt using e
     ct, err = e.Encrypt([]byte("secret message"), []byte("some aad"))
     if err != nil {
         // handle error
     }

     // to decrypt, recreate kh for the cek (once unwrapped from pkg/crypto)
		// for AES256GCM content encryption using a NIST P key for cek wrapping to match the encryption template above
		kt = ecdh.KeyTemplateForECDHPrimitiveWithCEK(cek, true, ecdh.AES256GCM)

		kh, err = keyset.NewHandle(kt)
		if err != nil {
			// handle error
		}

		// get the decryption primtive for kh
     d := ecdh.NewECDHDecrypt(kh)

		// and decrypt
     pt, err := d.Decrypt(ct)
     if err != nil {
         // handle error
     }
 }

Index

• Constants
• Variables
• func KeyTemplateForECDHPrimitiveWithCEK(cek []byte, nistpKW bool, encAlg AEADAlg) *tinkpb.KeyTemplate
• func NISTP256ECDHKWKeyTemplate() *tinkpb.KeyTemplate
• func NISTP384ECDHKWKeyTemplate() *tinkpb.KeyTemplate
• func NISTP521ECDHKWKeyTemplate() *tinkpb.KeyTemplate
• func NewECDHDecrypt(h *keyset.Handle) (api.CompositeDecrypt, error)
• func NewECDHDecryptWithKeyManager(h *keyset.Handle, km registry.KeyManager) (api.CompositeDecrypt, error)
• func NewECDHEncrypt(h *keyset.Handle) (api.CompositeEncrypt, error)
• func NewECDHEncryptWithKeyManager(h *keyset.Handle, km registry.KeyManager) (api.CompositeEncrypt, error)
• func X25519ECDHKWKeyTemplate() *tinkpb.KeyTemplate
• type AEADAlg

Constants

const (
	// AES256GCM AEAD.
	AES256GCM = iota + 1
	// XC20P AEAD.
	XC20P
	// AES128CBCHMACSHA256 AEAD.
	AES128CBCHMACSHA256
	// AES192CBCHMACSHA384 AEAD.
	AES192CBCHMACSHA384
	// AES256CBCHMACSHA384 AEAD.
	AES256CBCHMACSHA384
	// AES256CBCHMACSHA512 AEAD.
	AES256CBCHMACSHA512
)

Variables

var EncryptionAlgLabel = ecdh.EncryptionAlgLabel // nolint: gochecknoglobals

EncryptionAlgLabel maps AEADAlg to its label.

Functions

func KeyTemplateForECDHPrimitiveWithCEK

func KeyTemplateForECDHPrimitiveWithCEK(cek []byte, nistpKW bool, encAlg AEADAlg) *tinkpb.KeyTemplate

KeyTemplateForECDHPrimitiveWithCEK is similar to NISTP256ECDHKWKeyTemplate but adding the cek to execute the CompositeEncrypt primitive for encrypting a message targeted to one ore more recipients. KW is not executed by this template, so it is ignored and set to NIST P Curved key by default. Keys from this template offer valid CompositeEncrypt primitive execution only and should not be stored in the KMS. The key created from this template has no recipient key info linked to it. It is exclusively used for primitive execution using content encryption. Available content encryption algorithms:

• AES256GCM, XChacaha20Poly1305, AES128CBC+HMAC256, AES192CBC+HMAC384, AES256CBC+HMAC384, AES256CBC+HMAC512

It works with both key wrapping modes (executed outside of the key primitive created by this template): NIST P kw or XC20P kw cek should be of size: - 32 bytes for AES256GCM, XChacaha20Poly1305, AES128CBC+HMAC256. - 48 bytes for AES192CBC+HMAC384. - 56 bytes for AES256CBC+HMAC384. - 64 bytes for AES256CBC+HMAC512.

func NISTP256ECDHKWKeyTemplate

func NISTP256ECDHKWKeyTemplate() *tinkpb.KeyTemplate

NISTP256ECDHKWKeyTemplate is a KeyTemplate that generates a key that accepts a CEK for JWE content encryption. CEK wrapping is done outside of this Tink key (in the tinkcrypto service). Keys from this template represent a valid recipient public/private key pairs and can be stored in the KMS. The recipient key represented in this key template uses the following key wrapping curve:

• NIST curve P-256.

Keys created with this template are mainly used for key wrapping of a cek. They are independent of the AEAD content encryption algorithm.

func NISTP384ECDHKWKeyTemplate

func NISTP384ECDHKWKeyTemplate() *tinkpb.KeyTemplate

NISTP384ECDHKWKeyTemplate is a KeyTemplate that generates a key that accepts a CEK for JWE content encryption. CEK wrapping is done outside of this Tink key (in the tinkcrypto service). Keys from this template represent a valid recipient public/private key pairs and can be stored in the KMS. The recipient key represented in this key template uses the following key wrapping curve:

• NIST curve P-384

Keys created with this template are mainly used for key wrapping of a cek. They are independent of the AEAD content encryption algorithm.

func NISTP521ECDHKWKeyTemplate

func NISTP521ECDHKWKeyTemplate() *tinkpb.KeyTemplate

NISTP521ECDHKWKeyTemplate is a KeyTemplate that generates a key that accepts a CEK for JWE content encryption. CEK wrapping is done outside of this Tink key (in the tinkcrypto service). Keys from this template represent a valid recipient public/private key pairs and can be stored in the KMS. The recipient key represented in this key template uses the following key wrapping curve:

• NIST curve P-521

Keys created with this template are mainly used for key wrapping of a cek. They are independent of the AEAD content encryption algorithm.

func NewECDHDecrypt

func NewECDHDecrypt(h *keyset.Handle) (api.CompositeDecrypt, error)

NewECDHDecrypt returns an CompositeDecrypt primitive from the given keyset handle.

func NewECDHDecryptWithKeyManager

func NewECDHDecryptWithKeyManager(h *keyset.Handle, km registry.KeyManager) (api.CompositeDecrypt, error)

NewECDHDecryptWithKeyManager returns an CompositeDecrypt primitive from the given keyset handle and custom key manager.

func NewECDHEncrypt

func NewECDHEncrypt(h *keyset.Handle) (api.CompositeEncrypt, error)

NewECDHEncrypt returns an CompositeEncrypt primitive from the given keyset handle.

func NewECDHEncryptWithKeyManager

func NewECDHEncryptWithKeyManager(h *keyset.Handle, km registry.KeyManager) (api.CompositeEncrypt, error)

NewECDHEncryptWithKeyManager returns an CompositeEncrypt primitive from the given h keyset handle and custom km key manager.

func X25519ECDHKWKeyTemplate

func X25519ECDHKWKeyTemplate() *tinkpb.KeyTemplate

X25519ECDHKWKeyTemplate is a KeyTemplate that generates a key that accepts a CEK for JWE content encryption. CEK wrapping is done outside of this Tink key (in the tinkcrypto service). Keys from this template represent a valid recipient public/private key pairs and can be stored in the KMS.The recipient key represented in this key template uses the following key wrapping curve:

• Curve25519

Keys created with this template are mainly used for key wrapping of a cek. They are independent of the AEAD content encryption algorithm.

Types

type AEADAlg

type AEADAlg = ecdh.AEADAlg

AEADAlg represents the AEAD implementation algorithm used by ECDH.