Object Identifiers

The object-identifier registry: a two-way map between dotted-decimal OID strings and their human names, plus arc conversion and DER encode/decode convenience. Every algorithm, attribute type, and extension in PKI is named by an OID, and resolving them through one registry, instead of scattering magic dotted strings across the codebase, is what lets a new algorithm be a data entry instead of a code change.

The seed set is declared by FAMILY: an OID belongs to a class with a shared base arc (the "starting variable": 2.5.4 for the RFC 5280 attribute types, 2.5.29 for the extensions, 2.16.840.1.101.3.4 for the NIST algorithms), and each member names only its trailing arc. The full OID is derived from base + leaf at load, so the arc hierarchy that IS the OID namespace is modeled directly instead of re-spelled per entry. It covers the RFC 5280 attribute types and extensions, the classical signature / public-key / digest algorithms, and the NIST-assigned post-quantum arcs (ML-DSA, ML-KEM, SLH-DSA). Operators extend it with register (one OID) or registerFamily (a whole arc).

pki.oid.name

since 0.1.0 stable
pki.oid.name(dotted) -> string | undefined

Resolve a dotted OID to its registered name. Returns undefined for an unregistered OID (a caller that needs the raw arc keeps the dotted string); throws OidError only when the argument isn't a dotted OID.

Example

pki.oid.name("1.2.840.113549.1.1.11"); // -> "sha256WithRSAEncryption"

See also: pki.oid.byName, pki.oid.register

References

pki.oid.register

since 0.1.0 stable
pki.oid.register(dotted, name) -> void

Add (or override) an OID -> name mapping so an operator's private or newly-standardized arc resolves through the same registry as the seed set. A later registration of the same OID replaces the forward name; the reverse (name -> OID) keeps the first registration as canonical.

Example

pki.oid.register("1.3.6.1.4.1.99999.1", "acmeWidgetPolicy");

See also: pki.oid.registerFamily, pki.oid.name

References

pki.oid.registerFamily

since 0.1.2 stable
pki.oid.registerFamily(base, members) -> void

Register a whole OID family in one call. base is the shared arc prefix (the starting variable a class of OIDs has in common) and members maps each name to its trailing arc -- a number, or a short arc array for a multi-level leaf. Each full OID is derived as base followed by the leaf, so a family is declared as its hierarchy and no full path is re-spelled. This is the primitive the built-in seed set itself is built from.

Options

base:      number[],           // the shared arc prefix, e.g. [1,3,6,1,4,1,99999]
members:   object,             // name -> number | number[] trailing arc

Example

pki.oid.registerFamily([1, 3, 6, 1, 4, 1, 99999], {
  widgetPolicy: 1,
  gadgetPolicy: [2, 4],
});
pki.oid.name("1.3.6.1.4.1.99999.2.4"); // -> "gadgetPolicy"

See also: pki.oid.register, pki.oid.name

References

pki.oid.paramsMustBeAbsent

since 0.1.21 stable
pki.oid.paramsMustBeAbsent(dotted) -> boolean

True when an AlgorithmIdentifier bearing this OID MUST encode its parameters field as ABSENT (not an explicit NULL, not any bytes): the FIPS 204 ML-DSA and FIPS 205 SLH-DSA signature families and the RFC 8410 Edwards / Montgomery curves. The shared AlgorithmIdentifier decoder consults this and fails closed on a present-parameters violation, so every format inherits the rule.

Example

pki.oid.paramsMustBeAbsent(pki.oid.byName("id-slh-dsa-sha2-128s")); // -> true
pki.oid.paramsMustBeAbsent(pki.oid.byName("rsaEncryption"));        // -> false

See also: pki.oid.name, pki.oid.byName

References