hpke

README

HPKE

This repo provides a Go implementation of the HPKE primitive proposed for discussion at CFRG.

https://tools.ietf.org/html/draft-irtf-cfrg-hpke

Test vector generation

To generate test vectors, run:

$ HPKE_TEST_VECTORS_OUT=test-vectors.json go test -v -run TestVectorGenerate

To check test vectors, run:

$ HPKE_TEST_VECTORS_IN=test-vectors.json go test -v -run TestVectorVerify

Documentation

Index

• type AEADID
• type AEADScheme
• type AuthKEMScheme
• type CipherSuite
  • func AssembleCipherSuite(kemID KEMID, kdfID KDFID, aeadID AEADID) (CipherSuite, error)
• type DecryptContext
  • func SetupAuthPSKR(suite CipherSuite, skR KEMPrivateKey, pkS KEMPublicKey, ...) (*DecryptContext, error)
  • func SetupAuthR(suite CipherSuite, skR KEMPrivateKey, pkS KEMPublicKey, enc, info []byte) (*DecryptContext, error)
  • func SetupBaseR(suite CipherSuite, skR KEMPrivateKey, enc, info []byte) (*DecryptContext, error)
  • func SetupPSKR(suite CipherSuite, skR KEMPrivateKey, enc, psk, pskID, info []byte) (*DecryptContext, error)
  • func (ctx *DecryptContext) Export(context []byte, L int) []byte
  • func (ctx *DecryptContext) Open(aad, ct []byte) ([]byte, error)
• type EncryptContext
  • func SetupAuthPSKS(suite CipherSuite, rand io.Reader, pkR KEMPublicKey, skS KEMPrivateKey, ...) ([]byte, *EncryptContext, error)
  • func SetupAuthS(suite CipherSuite, rand io.Reader, pkR KEMPublicKey, skS KEMPrivateKey, ...) ([]byte, *EncryptContext, error)
  • func SetupBaseS(suite CipherSuite, rand io.Reader, pkR KEMPublicKey, info []byte) ([]byte, *EncryptContext, error)
  • func SetupPSKS(suite CipherSuite, rand io.Reader, pkR KEMPublicKey, psk, pskID, info []byte) ([]byte, *EncryptContext, error)
  • func (ctx *EncryptContext) Export(context []byte, L int) []byte
  • func (ctx *EncryptContext) Seal(aad, pt []byte) []byte
• type HPKEMode
• type KDFID
• type KDFScheme
• type KEMID
• type KEMPrivateKey
• type KEMPublicKey
• type KEMScheme

Types

type AEADID

type AEADID uint16

const (
	AEAD_AESGCM128        AEADID = 0x0001
	AEAD_AESGCM256        AEADID = 0x0002
	AEAD_CHACHA20POLY1305 AEADID = 0x0003
)

type AEADScheme

type AEADScheme interface {
	ID() AEADID
	New(key []byte) (cipher.AEAD, error)
	KeySize() int
	NonceSize() int
}

type AuthKEMScheme

type AuthKEMScheme interface {
	KEMScheme
	AuthEncap(rand io.Reader, pkR KEMPublicKey, skS KEMPrivateKey) ([]byte, []byte, error)
	AuthDecap(enc []byte, skR KEMPrivateKey, pkS KEMPublicKey) ([]byte, error)
}

type CipherSuite

type CipherSuite struct {
	KEM  KEMScheme
	KDF  KDFScheme
	AEAD AEADScheme
}

func AssembleCipherSuite

func AssembleCipherSuite(kemID KEMID, kdfID KDFID, aeadID AEADID) (CipherSuite, error)

type DecryptContext

type DecryptContext struct {
	// contains filtered or unexported fields
}

func SetupAuthPSKR

func SetupAuthPSKR(suite CipherSuite, skR KEMPrivateKey, pkS KEMPublicKey, enc, psk, pskID, info []byte) (*DecryptContext, error)

func SetupAuthR

func SetupAuthR(suite CipherSuite, skR KEMPrivateKey, pkS KEMPublicKey, enc, info []byte) (*DecryptContext, error)

func SetupBaseR

func SetupBaseR(suite CipherSuite, skR KEMPrivateKey, enc, info []byte) (*DecryptContext, error)

func SetupPSKR

func SetupPSKR(suite CipherSuite, skR KEMPrivateKey, enc, psk, pskID, info []byte) (*DecryptContext, error)

func (*DecryptContext) Export

func (ctx *DecryptContext) Export(context []byte, L int) []byte

func (*DecryptContext) Open

func (ctx *DecryptContext) Open(aad, ct []byte) ([]byte, error)

type EncryptContext

type EncryptContext struct {
	// contains filtered or unexported fields
}

func SetupAuthPSKS

func SetupAuthPSKS(suite CipherSuite, rand io.Reader, pkR KEMPublicKey, skS KEMPrivateKey, psk, pskID, info []byte) ([]byte, *EncryptContext, error)

func SetupAuthS

func SetupAuthS(suite CipherSuite, rand io.Reader, pkR KEMPublicKey, skS KEMPrivateKey, info []byte) ([]byte, *EncryptContext, error)

func SetupBaseS

func SetupBaseS(suite CipherSuite, rand io.Reader, pkR KEMPublicKey, info []byte) ([]byte, *EncryptContext, error)

func SetupPSKS

func SetupPSKS(suite CipherSuite, rand io.Reader, pkR KEMPublicKey, psk, pskID, info []byte) ([]byte, *EncryptContext, error)

func (*EncryptContext) Export

func (ctx *EncryptContext) Export(context []byte, L int) []byte

func (*EncryptContext) Seal

func (ctx *EncryptContext) Seal(aad, pt []byte) []byte

type HPKEMode

type HPKEMode uint8

type KDFID

type KDFID uint16

const (
	KDF_HKDF_SHA256 KDFID = 0x0001
	KDF_HKDF_SHA384 KDFID = 0x0002
	KDF_HKDF_SHA512 KDFID = 0x0003
)

type KDFScheme

type KDFScheme interface {
	ID() KDFID
	Hash(message []byte) []byte
	Extract(salt, ikm []byte) []byte
	Expand(prk, info []byte, L int) []byte
	LabeledExtract(salt []byte, label string, ikm []byte) []byte
	LabeledExpand(prk []byte, label string, info []byte, L int) []byte
	OutputSize() int
}

type KEMID

type KEMID uint16

const (
	DHKEM_P256   KEMID = 0x0010
	DHKEM_P521   KEMID = 0x0012
	DHKEM_X25519 KEMID = 0x0020
	DHKEM_X448   KEMID = 0x0021
	KEM_SIKE503  KEMID = 0xFFFE
	KEM_SIKE751  KEMID = 0xFFFF
)

type KEMPrivateKey

type KEMPrivateKey interface {
	PublicKey() KEMPublicKey
}

type KEMPublicKey

type KEMPublicKey interface{}

type KEMScheme

type KEMScheme interface {
	ID() KEMID
	GenerateKeyPair(rand io.Reader) (KEMPrivateKey, KEMPublicKey, error)
	Marshal(pk KEMPublicKey) []byte
	Unmarshal(enc []byte) (KEMPublicKey, error)
	Encap(rand io.Reader, pkR KEMPublicKey) ([]byte, []byte, error)
	Decap(enc []byte, skR KEMPrivateKey) ([]byte, error)
	PublicKeySize() int

	MarshalPrivate(sk KEMPrivateKey) []byte
	UnmarshalPrivate(enc []byte) (KEMPrivateKey, error)
	// contains filtered or unexported methods
}