x25519

Documentation

Overview

Package x25519 implements chainbind.KeyWrapper: ECDH-ES key agreement over X25519 followed by A256KW (RFC 3394 AES Key Wrap with a 256-bit KEK) to wrap a segment's data-encryption key to a recipient's public key, and to unwrap it with the recipient's private key. It also computes the RFC 7638 JWK thumbprint of an X25519 public key, the value that goes into manifest.cnf[a].jkt.

Index

• Variables
• func Thumbprint(pub []byte) (string, error)
• type Wrapper
  • func (Wrapper) PublicKey(priv []byte) ([]byte, error)
  • func (Wrapper) Thumbprint(recipientPub []byte) (string, error)
  • func (Wrapper) Unwrap(_ context.Context, priv, epk, wrapped []byte) (dek []byte, err error)
  • func (Wrapper) Wrap(_ context.Context, recipientPub, dek []byte) (wrapped, epk []byte, err error)

Variables

var ErrUnwrapFailed = errors.New("keywrap/x25519: unwrap failed")

ErrUnwrapFailed is returned when Unwrap cannot recover a DEK: the wrong private key, a tampered epk, or a tampered wrapped key are all indistinguishable failures, and none of them may be described in more detail (architecture invariant 10 — no error carries secret-derived bytes).

var ErrWrapFailed = errors.New("keywrap/x25519: wrap failed")

ErrWrapFailed is the Wrap-side counterpart. It exists because the obvious error messages on this path name the length of the data-encryption key or of the ECDH-derived key-encryption key. A length is a fact about secret material, and invariant 10 admits no exceptions for facts that feel harmless: key lengths distinguish algorithms, and an oracle that reveals why a wrap failed is an oracle.

Functions

func Thumbprint

func Thumbprint(pub []byte) (string, error)

Thumbprint computes the RFC 7638 JWK thumbprint of an X25519 public key, represented per RFC 8037 as an OKP JWK with crv "X25519". The three required members are already in lexicographic order (crv, kty, x) and none of their values needs JSON escaping: kty and crv are fixed literals, and x is base64url, whose alphabet contains no character JSON escapes.

Types

type Wrapper

type Wrapper struct{}

Wrapper implements chainbind.KeyWrapper.

func (Wrapper) PublicKey

func (Wrapper) PublicKey(priv []byte) ([]byte, error)

PublicKey satisfies chainbind.KeyWrapper: it derives the public half of an X25519 private key. Its error names nothing about priv, not even its length (architecture invariant 10).

func (Wrapper) Thumbprint

func (Wrapper) Thumbprint(recipientPub []byte) (string, error)

Thumbprint satisfies chainbind.KeyWrapper. The value is derived from the same public key Wrap seals the data key to, which is what makes cnf[a].jkt a confirmation rather than an issuer's claim.

func (Wrapper) Unwrap

func (Wrapper) Unwrap(_ context.Context, priv, epk, wrapped []byte) (dek []byte, err error)

Unwrap redoes the ECDH-ES agreement between priv and the ephemeral public key epk, rederives the KEK, and unwraps wrapped to recover the DEK. Any failure — wrong priv, tampered epk, tampered wrapped — collapses to the single static ErrUnwrapFailed sentinel.

func (Wrapper) Wrap

func (Wrapper) Wrap(_ context.Context, recipientPub, dek []byte) (wrapped, epk []byte, err error)

Wrap agrees on a shared secret with recipientPub via a fresh ephemeral X25519 keypair (ECDH-ES), derives a 256-bit KEK from it with the Concat KDF, and wraps dek under that KEK with RFC 3394 AES Key Wrap. epk is the ephemeral public key, recorded alongside the wrapped key so Unwrap can redo the agreement.