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/Universal-Health-Chain/aries-framework-go/pkg/crypto/tinkcrypto/primitive/composite"
     "github.com/Universal-Health-Chain/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
		kt := ecdh.NISTPECDHAES256GCMKeyTemplateWithCEK(cek)

		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)
		kt = ecdh.NISTPECDHAES256GCMKeyTemplateWithCEK(cek)

		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

• func NISTP256ECDHKWKeyTemplate() *tinkpb.KeyTemplate
• func NISTP384ECDHKWKeyTemplate() *tinkpb.KeyTemplate
• func NISTP521ECDHKWKeyTemplate() *tinkpb.KeyTemplate
• func NISTPECDHAES256GCMKeyTemplateWithCEK(cek []byte) *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
• func X25519ECDHXChachaKeyTemplateWithCEK(cek []byte) *tinkpb.KeyTemplate

Functions

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.

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

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

func NISTPECDHAES256GCMKeyTemplateWithCEK

func NISTPECDHAES256GCMKeyTemplateWithCEK(cek []byte) *tinkpb.KeyTemplate

NISTPECDHAES256GCMKeyTemplateWithCEK 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 algorithm:

• AES256-GCM

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

func X25519ECDHXChachaKeyTemplateWithCEK

func X25519ECDHXChachaKeyTemplateWithCEK(cek []byte) *tinkpb.KeyTemplate

X25519ECDHXChachaKeyTemplateWithCEK is similar to X25519ECDHKWKeyTemplate but adding the cek to execute the CompositeEncrypt primitive for encrypting a message targeted to one ore more recipients. 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 algorithm:

• XChacha20Poly1305