hpke

Documentation

Overview

Package hpke provides RFC9180 hybrid public key encryption features.

Example

// Prepare HPKE suite.
s := New(kem.DHKEM_X25519_HDKF_SHA256, kdf.HKDF_SHA256, aead.ChaCha20Poly1305)

// Generate a remote public key matching the key group.
pkR, skR, err := s.KEM().GenerateKeyPair()
if err != nil {
	panic(err)
}

// -------------------------------------------------------------------------

// Prepare a message sealer.
enc, sealer, err := s.Sender(pkR, []byte("sample test purpose")).SetupBase()
if err != nil {
	panic(err)
}

// Seal a plaintext content.
ct, err := sealer.Seal([]byte("my message to secure"), nil)
if err != nil {
	panic(err)
}

// -------------------------------------------------------------------------

// Prepare the message opener.
opener, err := s.Receiver(skR, []byte("sample test purpose")).SetupBase(enc)
if err != nil {
	panic(err)
}

// Open a sealed content.
pt, err := opener.Open(ct, nil)
if err != nil {
	panic(err)
}

// Bidirectional encryption
// https://www.rfc-editor.org/rfc/rfc9180.html#name-bidirectional-encryption

responseKeyR, err := opener.Export([]byte("response key"), aead.ChaCha20Poly1305.KeySize())
if err != nil {
	panic(err)
}
responseNonceR, err := opener.Export([]byte("response nonce"), aead.ChaCha20Poly1305.NonceSize())
if err != nil {
	panic(err)
}

responseCipherR, err := s.AEAD().New(responseKeyR)
if err != nil {
	panic(err)
}

response := responseCipherR.Seal(nil, responseNonceR, pt, enc)

// -------------------------------------------------------------------------

responseKeyS, err := sealer.Export([]byte("response key"), aead.ChaCha20Poly1305.KeySize())
if err != nil {
	panic(err)
}
responseNonceS, err := sealer.Export([]byte("response nonce"), aead.ChaCha20Poly1305.NonceSize())
if err != nil {
	panic(err)
}

responseCipherS, err := s.AEAD().New(responseKeyS)
if err != nil {
	panic(err)
}

got, err := responseCipherS.Open(response[:0], responseNonceS, response, enc)
if err != nil {
	panic(err)
}

Output:

my message to secure

Index

• type Exporter
• type Opener
• type Receiver
• type Sealer
• type Sender
• type Suite
  • func New(kemID kem.KEM, kdfID kdf.KDF, aeadID aead.AEAD) Suite

Examples

• Package

Types

type Exporter

type Exporter interface {
	Export(exporterContext []byte, length uint16) ([]byte, error)
}

Exporter describes key derivation operation.

type Opener

type Opener interface {
	Exporter

	// Open tries to authenticate and decrypt a ciphertext with associated
	// additional data. The nonce is handled internally.
	Open(ct, aad []byte) (pt []byte, err error)
}

Opener decrypts a ciphertext using an AEAD encryption.

type Receiver

type Receiver interface {
	SetupBase(enc []byte) (Opener, error)
	SetupPSK(enc []byte, psk, pskID []byte) (Opener, error)
	SetupAuth(enc []byte, pkS *ecdh.PublicKey) (Opener, error)
	SetupAuthPSK(enc []byte, psk, pskID []byte, pkS *ecdh.PublicKey) (Opener, error)
}

Receiver describes message receiver contract.

type Sealer

type Sealer interface {
	Exporter

	// Seal encrypts a given plaintext a plaintext with associated data.
	// The nonce is managed internally.
	Seal(pt, aad []byte) (ct []byte, err error)
}

Sealer encrypts a plaintext using an AEAD encryption.

type Sender

type Sender interface {
	SetupBase() ([]byte, Sealer, error)
	SetupPSK(psk, pskID []byte) ([]byte, Sealer, error)
	SetupAuth(skS *ecdh.PrivateKey) ([]byte, Sealer, error)
	SetupAuthPSK(psk, pskID []byte, skS *ecdh.PrivateKey) ([]byte, Sealer, error)
}

Sender describes message sender contract.

type Suite

type Suite interface {
	IsValid() bool
	Params() (kem.KEM, kdf.KDF, aead.AEAD)
	KEM() kem.Scheme
	AEAD() aead.AEAD
	Sender(pkR *ecdh.PublicKey, info []byte) Sender
	Receiver(skR *ecdh.PrivateKey, info []byte) Receiver
}

Suite repesents a HPKE cipher suite contract.

func New

func New(kemID kem.KEM, kdfID kdf.KDF, aeadID aead.AEAD) Suite

New initializes a new HPKE suite.