openpgp

Documentation

Index

• Variables
• func Decrypt(ctx context.Context, deriver SecretDeriver, recipient Recipient, ...) error
• func ReadRecipient(r io.Reader) (Recipient, Findings, error)
• type Findings
• type Recipient
• type SecretDeriver

Variables

var (
	// ErrNotAddressed means the message is not addressed to the certificate
	// supplied — a different recipient, or a different subkey of the same
	// identity after a rotation.
	ErrNotAddressed = errors.New("message is not addressed to this certificate")

	// ErrMalformedMessage means the message could not be read as OpenPGP.
	ErrMalformedMessage = errors.New("malformed message")

	// ErrIntegrity means the message did not survive the journey intact: its
	// modification detection code does not match what was decrypted.
	//
	// Treat it as tampering rather than corruption. The plaintext is
	// deliberately not written out, because a report an attacker has edited is
	// worse than no report at all.
	ErrIntegrity = errors.New("message integrity check failed; it may have been altered")

	// ErrTooLarge means the message, or what it decompresses to, is beyond
	// what this will hold in memory. A compressed packet expands without
	// limit, and the certificate is public.
	ErrTooLarge = errors.New("message is larger than this will decrypt")

	// ErrCostCeiling means the run stopped because it reached the limit on
	// billed key-service derivations, with candidates left untried.
	//
	// Deliberately NOT ErrNotAddressed, which this used to be. Hitting the
	// ceiling establishes nothing about who the message is for — the candidates
	// never tried might have been ours — so reporting it as "addressed
	// elsewhere" sends the operator to find a certificate that may not exist,
	// which is the misdiagnosis this package has produced three separate ways.
	ErrCostCeiling = errors.New("stopped before trying every recipient: too many key-service derivations")

	// ErrUnprotected means the message uses the legacy encrypted-data packet,
	// which carries no integrity protection and is refused for that reason.
	ErrUnprotected = errors.New("message has no integrity protection and will not be decrypted")
)

Errors reported by this package.

Functions

func Decrypt

func Decrypt(
	ctx context.Context,
	deriver SecretDeriver,
	recipient Recipient,
	message io.Reader,
	out io.Writer,
) error

Decrypt recovers the plaintext of a message addressed to recipient.

The only secret operation is the deriver's: everything else — the KDF, the key unwrap, the body decryption — happens locally with public data and the recovered session key.

func ReadRecipient

func ReadRecipient(r io.Reader) (Recipient, Findings, error)

ReadRecipient extracts the encryption subkey's parameters from a certificate.

The certificate is the source of truth rather than a set of flags: the key derivation binds the subkey's fingerprint, so parameters that did not come from the certificate the sender used cannot recover anything, and inviting a caller to supply them by hand invites exactly that mistake.

Armoured and binary certificates are both accepted — a certificate published on a page is armoured, one fetched from WKD is not, and a caller should not have to know which they have. Findings come back on every path, including the error paths, so a caller can surface what the parser noticed even when no usable subkey was found — which is exactly the case where an unevaluable revocation matters most.

Types

type Findings

type Findings = certificate.Findings

Findings is re-exported alongside Recipient: the certificate parser reports things it noticed but had no standing to decide — a revocation it could not evaluate, a certificate read only part-way — and a caller surfaces them.

type Recipient

type Recipient = certificate.Recipient

Recipient is re-exported so callers need only this package. It is the core's type: parsing a certificate is packet work, and the core does it with the binding signature verified.

type SecretDeriver

type SecretDeriver interface {
	DeriveSharedSecret(ctx context.Context, peerPoint []byte) ([]byte, error)
	CoordinateBytes() int
}

SecretDeriver is the key service the decrypt command needs.

One method plus the curve's coordinate length, which is what the core's KDF parameters require. gitlab.com/phpboyscout/go/encryption-aws-kms's Deriver satisfies it, and so would an HSM or a software key held elsewhere — the command has no opinion about which.