Trust anchors

RFC 5914 trust anchors. A trust anchor as a structure rather than as a certificate, carrying the constraints a root program otherwise states out of band: the namespace the root is trusted for, the policies it may assert, and how far below it a path may run. parse reads a TrustAnchorList and parseInfo a bare TrustAnchorInfo; pki.trust.parseTrustAnchorList turns either into the anchors pki.path.validate consumes, and RFC 5937 section 3.2 says how each constraint reaches the validation state.

pki.schema.trustanchor.parse

since 0.8.13 stable
pki.schema.trustanchor.parse(input, caps?) -> trustAnchorList

Parse a DER Buffer or a PEM (TRUST ANCHOR LIST) string into { anchors }, one entry per TrustAnchorChoice. Each entry names the arm it came from in kind, one of "certificate", "tbsCert" or "taInfo", and carries that arm's decoded value with the other two null.

A taInfo entry is { version, pubKey, keyId, taTitle, certPath, exts, excludedExtensions, taTitleLangTag }. certPath is the RFC 5914 section 2 CertPathControls, carrying the name the anchor is known by and the constraints a relying party applies: policySet, policyFlags, nameConstr and pathLenConstraint. excludedExtensions lists the identifiers of any extensions the RFC excludes from exts that the anchor carried anyway; those are left out of exts, because the RFC ignores them rather than refusing the anchor.

Every rule RFC 5914 states is enforced: an empty taName is refused, a policySet carrying policy qualifiers is refused, a negative pathLenConstraint is refused, requireExplicitPolicy with no policySet is refused, and where certPath carries a certificate its subject, its public key and its subjectKeyIdentifier must match taName, pubKey and keyId.

Options

- `maxBytes` / `maxDepth` / `maxItems` (number) -- decode caps for this parse. Each
  defaults to the matching `pki.C.LIMITS` figure and may only be set lower.

Example

async function example() {
  var pair = await pki.key.generate("Ed25519");
  var spki = await pki.key.export(pair.publicKey);
  var der = pki.trustanchor.build({ anchors: [{ taInfo: {
    pubKey: spki, keyId: Buffer.alloc(20, 1), certPath: { taName: "CN=Example Root" } } }] });
  pki.schema.trustanchor.parse(der).anchors[0].kind;   // -> "taInfo"
}
example();

See also: pki.schema.trustanchor.parseInfo, pki.trust.parseTrustAnchorList, pki.trustanchor.build

References

pki.schema.trustanchor.parseInfo

since 0.8.13 stable
pki.schema.trustanchor.parseInfo(input, caps?) -> trustAnchorInfo

Parse a bare TrustAnchorInfo, the structure the [2] arm of a TrustAnchorChoice wraps, for a caller holding one on its own rather than inside a list. The result is the same record parse().anchors[i].taInfo carries.

Options

- `maxBytes` / `maxDepth` / `maxItems` (number) -- decode caps for this parse.

Example

async function example() {
  var pair = await pki.key.generate("Ed25519");
  var spki = await pki.key.export(pair.publicKey);
  var list = pki.schema.trustanchor.parse(pki.trustanchor.build({ anchors: [{ taInfo: {
    pubKey: spki, keyId: Buffer.alloc(20, 1), certPath: { taName: "CN=Example Root" } } }] }));
  list.anchors[0].taInfo.certPath.taName.dn;   // -> "CN=Example Root"
}
example();

See also: pki.schema.trustanchor.parse

References

pki.schema.trustanchor.pemDecode

since 0.8.13 stable
pki.schema.trustanchor.pemDecode(text, label?) -> Buffer

Extract the DER bytes from a PEM trust anchor list (default label TRUST ANCHOR LIST).

Example

async function example() {
  var pair = await pki.key.generate("Ed25519");
  var der = pki.trustanchor.build({ anchors: [{ taInfo: {
    pubKey: await pki.key.export(pair.publicKey), keyId: Buffer.alloc(20, 1),
    certPath: { taName: "CN=Example Root" } } }] });
  pki.schema.trustanchor.pemDecode(pki.schema.trustanchor.pemEncode(der)).equals(der);  // -> true
}
example();

See also: pki.schema.trustanchor.pemEncode

References

pki.schema.trustanchor.pemEncode

since 0.8.13 stable
pki.schema.trustanchor.pemEncode(der, label?) -> string

Wrap DER bytes in a PEM trust anchor list envelope (default label TRUST ANCHOR LIST).

Example

async function example() {
  var pair = await pki.key.generate("Ed25519");
  var der = pki.trustanchor.build({ anchors: [{ taInfo: {
    pubKey: await pki.key.export(pair.publicKey), keyId: Buffer.alloc(20, 1),
    certPath: { taName: "CN=Example Root" } } }] });
  pki.schema.trustanchor.pemEncode(der).indexOf("-----BEGIN TRUST ANCHOR LIST-----");  // -> 0
}
example();

See also: pki.schema.trustanchor.pemDecode

References