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)
  • func (suite CipherSuite) ID() []byte
• type KDFID
• type KDFScheme
• type KEMID
• type KEMPrivateKey
• type KEMPublicKey
• type KEMScheme
• type Mode
• type ReceiverContext
  • func SetupAuthPSKR(suite CipherSuite, skR KEMPrivateKey, pkS KEMPublicKey, ...) (*ReceiverContext, error)
  • func SetupAuthR(suite CipherSuite, skR KEMPrivateKey, pkS KEMPublicKey, enc, info []byte) (*ReceiverContext, error)
  • func SetupBaseR(suite CipherSuite, skR KEMPrivateKey, enc, info []byte) (*ReceiverContext, error)
  • func SetupPSKR(suite CipherSuite, skR KEMPrivateKey, enc, psk, pskID, info []byte) (*ReceiverContext, error)
  • func UnmarshalReceiverContext(opaque []byte) (*ReceiverContext, error)
  • func (ctx *ReceiverContext) Export(context []byte, L int) []byte
  • func (ctx *ReceiverContext) Marshal() ([]byte, error)
  • func (ctx *ReceiverContext) Open(aad, ct []byte) ([]byte, error)
• type SenderContext
  • func SetupAuthPSKS(suite CipherSuite, rand io.Reader, pkR KEMPublicKey, skS KEMPrivateKey, ...) ([]byte, *SenderContext, error)
  • func SetupAuthS(suite CipherSuite, rand io.Reader, pkR KEMPublicKey, skS KEMPrivateKey, ...) ([]byte, *SenderContext, error)
  • func SetupBaseS(suite CipherSuite, rand io.Reader, pkR KEMPublicKey, info []byte) ([]byte, *SenderContext, error)
  • func SetupPSKS(suite CipherSuite, rand io.Reader, pkR KEMPublicKey, psk, pskID, info []byte) ([]byte, *SenderContext, error)
  • func UnmarshalSenderContext(opaque []byte) (*SenderContext, error)
  • func (ctx *SenderContext) Export(context []byte, L int) []byte
  • func (ctx *SenderContext) Marshal() ([]byte, error)
  • func (ctx *SenderContext) Seal(aad, pt []byte) []byte

Types

type AEADID

type AEADID uint16

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

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)

func (CipherSuite) ID

func (suite CipherSuite) ID() []byte

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, suiteID []byte, label string, ikm []byte) []byte
	LabeledExpand(prk []byte, suiteID []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
)

type KEMPrivateKey

type KEMPrivateKey interface {
	PublicKey() KEMPublicKey
}

type KEMPublicKey

type KEMPublicKey interface{}

type KEMScheme

type KEMScheme interface {
	ID() KEMID
	DeriveKeyPair(ikm []byte) (KEMPrivateKey, KEMPublicKey, error)
	SerializePublicKey(pkX KEMPublicKey) []byte
	DeserializePublicKey(pkXm []byte) (KEMPublicKey, error)
	Encap(rand io.Reader, pkR KEMPublicKey) ([]byte, []byte, error)
	Decap(enc []byte, skR KEMPrivateKey) ([]byte, error)
	PublicKeySize() int
	PrivateKeySize() int

	SerializePrivateKey(skX KEMPrivateKey) []byte
	DeserializePrivateKey(skXm []byte) (KEMPrivateKey, error)
	// contains filtered or unexported methods
}

type Mode

type Mode uint8

type ReceiverContext

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

func SetupAuthPSKR

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

func SetupAuthR

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

func SetupBaseR

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

func SetupPSKR

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

func UnmarshalReceiverContext

func UnmarshalReceiverContext(opaque []byte) (*ReceiverContext, error)

func (*ReceiverContext) Export

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

func (*ReceiverContext) Marshal

func (ctx *ReceiverContext) Marshal() ([]byte, error)

func (*ReceiverContext) Open

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

type SenderContext

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

func SetupAuthPSKS

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

func SetupAuthS

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

func SetupBaseS

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

func SetupPSKS

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

func UnmarshalSenderContext

func UnmarshalSenderContext(opaque []byte) (*SenderContext, error)

func (*SenderContext) Export

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

func (*SenderContext) Marshal

func (ctx *SenderContext) Marshal() ([]byte, error)

func (*SenderContext) Seal

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