algorithm

Documentation

Overview

Package algorithm holds the OpenPGP algorithm identifiers and the sizes they imply, shared by the packages that read and write them.

Internal on purpose. These are wire-format numbers, and a consumer who needs to name one should be reading RFC 9580 rather than depending on a constant here that we would then have to keep.

Every lookup reports success as a bool rather than an error, so this package needs no sentinels of its own — and therefore cannot form an import cycle with the packages that define them.

Index

• Constants
• func CurveCoordinateBytes(oid string) (int, bool)
• func DefinedHash(id byte) bool
• func DefinedPublicKeyAlgo(id byte) bool
• func Hash(id byte) (crypto.Hash, bool)
• func HashID(h crypto.Hash) (byte, bool)
• func KEKKeySize(id byte) (int, bool)
• func LengthPrefixed(oid string) (string, bool)
• func RevocationHash(id byte) (crypto.Hash, bool)
• func SessionKeySize(id byte) (int, bool)

Constants

const (
	RSA  = 1
	ECDH = 18
)

Public-key algorithm identifiers, RFC 9580 §9.1.

const (
	SHA1   = 2
	SHA256 = 8
	SHA384 = 9
	SHA512 = 10
)

Hash algorithm identifiers, RFC 9580 §9.5. Only those usable here are named.

const (
	IDEA        = 1
	TripleDES   = 2
	CAST5       = 3
	Blowfish    = 4
	AES128      = 7
	AES192      = 8
	AES256      = 9
	Twofish256  = 10
	Camellia128 = 11
	Camellia192 = 12
	Camellia256 = 13
)

Symmetric-key algorithm identifiers, RFC 9580 §9.3.

const (
	KeySize128 = 16
	KeySize192 = 24
	KeySize256 = 32
)

Key sizes in octets.

const (
	OIDP256 = "\x2a\x86\x48\xce\x3d\x03\x01\x07"
	OIDP384 = "\x2b\x81\x04\x00\x22"
	OIDP521 = "\x2b\x81\x04\x00\x23"
)

Bare OIDs, as they appear once the length octet is stripped.

const (
	CoordinateBytesP256 = 32
	CoordinateBytesP384 = 48
	CoordinateBytesP521 = 66
)

CoordinateBytes for each curve: the width of one coordinate, which is also the width the KDF pads the shared secret to.

const (
	OIDP256Packet = "\x08" + OIDP256
	OIDP384Packet = "\x05" + OIDP384
	OIDP521Packet = "\x05" + OIDP521
)

The same OIDs as they appear in a key packet, where a single octet giving the length comes first.

Constants, so they stay immutable wire values rather than package-level slices any code could reach into — which is why they are concatenated here rather than computed by a function returning a var.

The length octet is the one thing written twice, and TestEveryCurveIsCross Checkable asserts it matches. That is a far smaller thing to keep in step than three OIDs in two files, which is what this replaced.

Functions

func CurveCoordinateBytes

func CurveCoordinateBytes(oid string) (int, bool)

CurveCoordinateBytes maps a bare curve OID to its coordinate width.

A switch rather than a package-level map, for the reason the algorithm tables use one: this is fixed specification data, and a map is mutable state.

An OID that is not listed is not rejected — nothing here restricts which curve a caller uses — it simply cannot be cross-checked.

func DefinedHash

func DefinedHash(id byte) bool

DefinedHash reports whether a hash identifier is one any OpenPGP specification assigns a meaning, whether or not this package implements it.

Distinct from Hash, and the distinction is load-bearing where a reader has to tell "an algorithm I do not implement" from "a number naming nothing". The first is a real signature made by a real holder; the second is noise, and treating the two alike let appended garbage look like a revocation.

RFC 9580 §9.5, carrying forward RFC 4880. Reserved identifiers count as defined: they name something a future specification may assign, which is still not arbitrary.

func DefinedPublicKeyAlgo

func DefinedPublicKeyAlgo(id byte) bool

DefinedPublicKeyAlgo reports whether a public-key algorithm identifier names an interoperable algorithm some OpenPGP specification assigns.

RFC 9580 §9.1, and deliberately narrower than "assigned". Two assigned ranges are excluded on purpose:

• 24 is Reserved (AEDSA). Reserved means no implementation may emit it.
• 100 to 110 are Private or Experimental. By definition nothing interoperable uses them, so a correspondent cannot expect us to act on one.

The distinction matters because this gates whether a revocation-shaped packet is treated as a revocation at all. A packet naming a reserved or private algorithm is not a withdrawal anyone could have expected this to honour, so it is not reported as one — whereas a packet naming, say, an assigned signature algorithm this module cannot verify IS a real revocation it cannot evaluate, and is surfaced as [encryption.ErrUnverifiableRevocation].

The previous wording claimed the gaps between the ranges were unassigned. They are not: it is the narrowing that is deliberate, not the specification that is sparse.

func Hash

func Hash(id byte) (crypto.Hash, bool)

Hash maps an OpenPGP hash identifier to its Go counterpart.

func HashID

func HashID(h crypto.Hash) (byte, bool)

HashID maps a Go hash back to its OpenPGP identifier.

func KEKKeySize

func KEKKeySize(id byte) (int, bool)

KEKKeySize reports the key length a key-encryption algorithm implies, and whether it is one RFC 6637 permits for that role.

Deliberately narrower than SessionKeySize. RFC 6637 §8 defines the KEK as AES only, whereas the identifier inside the payload names the cipher the message *body* uses, which may be anything §9.3 defines. Judging one by the other's table refuses messages whose key can be recovered perfectly well.

func LengthPrefixed

func LengthPrefixed(oid string) (string, bool)

LengthPrefixed returns an OID with its length octet in front, reporting whether the OID is short enough to have one.

Used by the test that holds the packet-form constants above to their bare counterparts; the constants themselves are what production code reads. The bound is real rather than ceremonial — the octet is one byte, so an OID of 256 or more could not be described by it, and narrowing without checking is the defect class this module already built internal/num to prevent.

func RevocationHash

func RevocationHash(id byte) (crypto.Hash, bool)

RevocationHash maps a hash identifier to its Go counterpart for verifying a revocation, which accepts more than Hash does.

Deliberately wider, and only here. A revocation is the holder saying "stop using this key", and the cost of being unable to check one is that a withdrawn key stays in service. gpg 1.x and 2.0 signed revocations with SHA-1, and a certificate carrying one is not hypothetical.

Not widened for bindings. Accepting a SHA-1 binding would let a weaker signature authorise a key, where accepting a SHA-1 revocation only ever takes one out of service — the risks point in opposite directions, so the answers do too.

func SessionKeySize

func SessionKeySize(id byte) (int, bool)

SessionKeySize reports the key length a message's symmetric algorithm implies, and whether the identifier is one RFC 9580 §9.3 defines.

A switch rather than a map: the data is a fixed specification table, and a package-level map is mutable state that any code in the module could reach into. Algorithm 0 (unencrypted) is absent on purpose — a session key for no cipher is not something a well-formed message carries.