@blamejs/pki 0.8.7 → 0.8.10

package/lib/schema-all.js

@@ -38,6 +38,8 @@ var c509 = require("./schema-c509");
 var crl = require("./schema-crl");
 var csr = require("./schema-csr");
 var pkcs8 = require("./schema-pkcs8");
+var pkcs1 = require("./schema-pkcs1");
+var sec1 = require("./schema-sec1");
 var pkcs12 = require("./schema-pkcs12");
 var cms = require("./schema-cms");
 var ocsp = require("./schema-ocsp");
@@ -230,6 +232,117 @@ function detectFormat(input) {
   return null;
 }
 
+/** @internal What a bundle row's bytes are, given the label the file put on them. An
+ * `EncryptedPrivateKeyInfo` is `SEQUENCE { AlgorithmIdentifier, OCTET STRING }`, which a PKCS#1
+ * `DigestInfo` also is, so structure alone cannot classify it and `detectFormat` deliberately
+ * does not. In a bundle the label is evidence the bare bytes do not carry, and RFC 7468 sec. 11
+ * gives the encrypted structure a label of its own, so the label is what makes the question
+ * answerable here and nowhere else. */
+var LABEL_ONLY_FORMATS = [
+  { label: "ENCRYPTED PRIVATE KEY", name: "pkcs8-encrypted", detect: pkcs8.matchesEncrypted },
+  { label: "RSA PRIVATE KEY", name: "pkcs1", detect: pkcs1.matches },
+  { label: "RSA PUBLIC KEY", name: "pkcs1-public", detect: pkcs1.matchesPublic },
+  { label: "EC PRIVATE KEY", name: "sec1", detect: sec1.matches },
+];
+
+function detectFormatForLabel(input, label) {
+  var der = pkix.coerceToDer(input, ENTRY);
+  var root = pkix.decodeRoot(der, ENTRY);
+  for (var j = 0; j < LABEL_ONLY_FORMATS.length; j++) {
+    if (LABEL_ONLY_FORMATS[j].label === label) {
+      return LABEL_ONLY_FORMATS[j].detect(root) ? LABEL_ONLY_FORMATS[j].name : null;
+    }
+  }
+  for (var i = 0; i < FORMATS.length; i++) {
+    if (FORMATS[i].detect(root)) return FORMATS[i].name;
+  }
+  return null;
+}
+
+/**
+ * @primitive  pki.schema.pem.decodeBundle
+ * @signature  pki.schema.pem.decodeBundle(text, opts) -> [{ index, offset, label, der }]
+ * @since      0.8.8
+ * @status     stable
+ * @spec       RFC 7468
+ * @related    pki.schema.detectFormat, pki.schema.pem.encodeBundle
+ *
+ * Read every object in a PEM file: a `fullchain.pem` of a leaf and its intermediates, a
+ * `ca-certificates.crt` of hundreds of anchors, a file holding a key beside its certificate.
+ * Each row carries the label that named the object, the DER it decoded to, its position in
+ * the file and the offset into the text its boundary started at, so a fault in a file of hundreds
+ * names the one object it is about. `offset` counts into the text this verb read: a
+ * `BufferSource` is read as latin1, so one character is one byte and the offset is the byte
+ * offset into the file, while a string a caller decoded itself is counted in that string's own
+ * characters.
+ *
+ * Explanatory text before, between and after the blocks is text, which is what a bundle
+ * written by a real tool carries. A label the toolkit has no parser for is a row like any
+ * other: the label is data, not a filter.
+ *
+ * This is the verb for a file of several objects. Every other door reads one: a parse door,
+ * a `pemDecode`, and a verb taking a certificate or a message as PEM each refuse a file
+ * holding more than one with `pem/multiple-blocks`, naming how many it holds.
+ *
+ * Fail-closed on the file rather than on the object: a boundary opened and never closed, a
+ * block closed under a different label, a body carrying RFC 1421 encryption headers, a body
+ * outside the base64 alphabet, more objects than `opts.maxBlocks`, and objects decoding to
+ * more than `opts.maxDecodedBytes` are each refused with their own `pem/*` code. Either cap
+ * may be tightened by a caller and neither may be raised above the toolkit's own.
+ *
+ * @opts
+ *   route            check each label's claim against the structure its bytes carry, and add
+ *                    `format` to every row (`null` when the label names no parser). A label
+ *                    whose claim the bytes do not support is `pem/label-structure-mismatch`.
+ *   maxBlocks        how many objects the file may hold. Default `C.LIMITS.PEM_MAX_BLOCKS`.
+ *   maxDecodedBytes  how many bytes those objects may decode to in total, across the file
+ *                    rather than per object. Default `C.LIMITS.PEM_MAX_DECODED_BYTES`.
+ *
+ * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var cert = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
+ *   var text = "Some Root CA\n============\n" + pki.schema.x509.pemEncode(cert, "CERTIFICATE");
+ *   var rows = pki.schema.pem.decodeBundle(text);
+ *   rows.length;           // 1, the two prose lines being text
+ *   rows[0].label;         // "CERTIFICATE"
+ *   rows[0].offset;        // 26, where its boundary starts
+ *   pki.schema.x509.parse(rows[0].der);
+ */
+
+/**
+ * @primitive  pki.schema.pem.encodeBundle
+ * @signature  pki.schema.pem.encodeBundle(objects) -> string
+ * @since      0.8.8
+ * @status     stable
+ * @spec       RFC 7468
+ * @related    pki.schema.pem.decodeBundle
+ *
+ * Write an ordered list of `{ label, der }` objects to one PEM text, each block wrapped at 64
+ * characters and closed under the label it was opened with. What `decodeBundle` reads back is
+ * the list that went in, and writing that list again produces the same text.
+ *
+ * A label is held to the uppercase form this toolkit writes, so a label carrying a boundary
+ * cannot put a block into the file that the caller never named. The reader is wider than the
+ * writer: it takes every label RFC 7468 sec. 3 admits, including lowercase and the empty one.
+ *
+ * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var cert = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
+ *   var text = pki.schema.pem.encodeBundle([{ label: "CERTIFICATE", der: cert }, { label: "CERTIFICATE", der: cert }]);
+ *   pki.schema.pem.decodeBundle(text).length;   // 2
+ */
+
+/** @internal What a block's bytes are, for the label-versus-structure comparison. Bytes the
+ * detector cannot place are not a fault here: the label may name something this toolkit has no
+ * parser for, and the reader answers that with a row rather than a refusal. */
+function _detectOrNull(der, label) {
+  try { return detectFormatForLabel(der, label); } catch (_e) { /* allow:swallow-unverified unreadable bytes are "no structure", which the caller is told */ return null; }
+}
+
 module.exports = {
   engine: engine,
   x509: { parse: x509.parse, pemDecode: x509.pemDecode, pemEncode: x509.pemEncode },
@@ -237,6 +350,13 @@ module.exports = {
   crl:  { parse: crl.parse,  pemDecode: crl.pemDecode, pemEncode: crl.pemEncode },
   csr:  { parse: csr.parse,  pemDecode: csr.pemDecode, pemEncode: csr.pemEncode },
   pkcs8: { parse: pkcs8.parse, parseEncrypted: pkcs8.parseEncrypted, pemDecode: pkcs8.pemDecode, pemEncode: pkcs8.pemEncode },
+  pkcs1: {
+    parse: pkcs1.parse, parsePublic: pkcs1.parsePublic,
+    encode: pkcs1.encode, encodePublic: pkcs1.encodePublic,
+    pemDecode: pkcs1.pemDecode, pemEncode: pkcs1.pemEncode,
+    pemDecodePublic: pkcs1.pemDecodePublic, pemEncodePublic: pkcs1.pemEncodePublic,
+  },
+  sec1: { parse: sec1.parse, encode: sec1.encode, pemDecode: sec1.pemDecode, pemEncode: sec1.pemEncode },
   pkcs12: { parse: pkcs12.parse, pemDecode: pkcs12.pemDecode, pemEncode: pkcs12.pemEncode },
   cms:  { parse: cms.parse, pemDecode: cms.pemDecode, pemEncode: cms.pemEncode },
   ocsp: { parseRequest: ocsp.parseRequest, parseResponse: ocsp.parseResponse, pemDecode: ocsp.pemDecode, pemEncode: ocsp.pemEncode },
@@ -247,6 +367,10 @@ module.exports = {
   attrcert: { parse: attrcert.parse, pemDecode: attrcert.pemDecode, pemEncode: attrcert.pemEncode },
   smime: { parseSigningCertificate: smime.parseSigningCertificate, parseSigningCertificateV2: smime.parseSigningCertificateV2, parseSmimeCapabilities: smime.parseSmimeCapabilities, decodeAttribute: smime.decodeAttribute },
   cmc: { parse: cmc.parse, parsePkiData: cmc.parsePkiData, parsePkiResponse: cmc.parsePkiResponse },
+  pem: {
+    decodeBundle: function (text, opts) { return pkix.pemDecodeBundle(text, opts, PemError, _detectOrNull); },
+    encodeBundle: function (objects) { return pkix.pemEncodeBundle(objects, PemError); },
+  },
   all: all,
   parse: parse,
   detectFormat: detectFormat,

package/lib/schema-attrcert.js

@@ -318,8 +318,10 @@ function parseV1(input, callerOpts) {
  * Extract the DER bytes from a PEM block (default label
  * `ATTRIBUTE CERTIFICATE`, the OpenSSL armor and the canonical-label default
  * every sibling format applies). Pass a `label` to enforce a different block
- * type, or an explicit `null` to take the first block of any type. Throws
- * `PemError` on a missing / mismatched envelope or a non-base64 body.
+ * type, or an explicit `null` to accept a block of any type. The text holds one
+ * object: a file of several is refused with `pem/multiple-blocks` and read with
+ * `pki.schema.pem.decodeBundle`. Throws `PemError` on a missing / mismatched
+ * envelope or a non-base64 body.
  *
  * @example
  *   var pair = await pki.key.generate("Ed25519");

package/lib/schema-crmf.js

@@ -368,8 +368,10 @@ var parse = pkix.makeRecordingParser({
  * @related    pki.schema.crmf.parse
  *
  * Extract the DER bytes from a PEM block (RFC 4211 registers no RFC 7468 label, so
- * the first block is taken unless `label` is given; CRMF rides inside CMP / EST as
- * DER in practice). Throws `PemError` on a missing envelope or a non-base64 body.
+ * a block of any label is accepted unless `label` is given; CRMF rides inside CMP /
+ * EST as DER in practice). The text holds one object: a file of several is refused
+ * with `pem/multiple-blocks` and read with `pki.schema.pem.decodeBundle`. Throws
+ * `PemError` on a missing envelope or a non-base64 body.
  *
  * @example
  *   var pair = await pki.key.generate("Ed25519");

package/lib/schema-pkcs1.js

@@ -0,0 +1,335 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.schema.pkcs1
+ * @nav        Schema
+ * @title      PKCS#1
+ * @fullname   PKCS#1 RSA keys, the RSA PRIVATE KEY and RSA PUBLIC KEY encodings
+ * @order      145
+ * @slug       pkcs1
+ *
+ * @intro
+ *   The RSA key encodings of RFC 8017 Appendix A.1: `RSAPrivateKey` and
+ *   `RSAPublicKey`, the `RSA PRIVATE KEY` and `RSA PUBLIC KEY` PEM blocks OpenSSL
+ *   wrote by default for years and appliances still emit. `parse` and
+ *   `parsePublic` read them into their components, and `encode` and `encodePublic`
+ *   write them back.
+ *
+ *   Neither structure carries an algorithm identifier, which is what separates
+ *   them from PKCS#8 and SubjectPublicKeyInfo. So what the key is used under is
+ *   the caller's decision, never a default this module supplies, and nothing here
+ *   routes through `pki.schema.parse`: a SEQUENCE of INTEGERs is a shape other
+ *   structures take, and detecting by shape alone would be a guess.
+ *
+ *   Every relation the specification states between the components is checked, in
+ *   the same pass that reads them. Appendix A.1 fixes the field order and the
+ *   two-or-more-primes rule, sec. 3.1 requires the public exponent to be odd and
+ *   between 3 and the modulus, and sec. 3.2 places the private exponent, the two
+ *   CRT exponents and the coefficient below the modulus or their own prime. A
+ *   component outside those describes no key, and the structure alone cannot say
+ *   so.
+ *
+ * @card
+ *   Read and write the RFC 8017 App. A.1 `RSAPrivateKey` and `RSAPublicKey`, DER
+ *   or PEM, with every component relation the specification states checked and no
+ *   algorithm inferred.
+ */
+
+var asn1 = require("./asn1-der");
+var schema = require("./schema-engine");
+var pkix = require("./schema-pkix");
+var oid = require("./oid");
+var frameworkError = require("./framework-error");
+var intrinsic = require("./guard-intrinsic");
+
+var Pkcs1Error = frameworkError.Pkcs1Error;
+var PemError = frameworkError.PemError;
+
+var NS = pkix.makeNS("pkcs1", Pkcs1Error, oid);
+
+var PRIVATE_LABEL = "RSA PRIVATE KEY";
+var PUBLIC_LABEL = "RSA PUBLIC KEY";
+
+/** @internal RFC 8017 sec. 3.1 and sec. 3.2 state every component as a positive integer. A DER
+ * INTEGER whose first content octet has its high bit set reads as a negative BigInt, and a
+ * negative or zero component describes no key, so it is refused at the leaf rather than carried. */
+function _positive(value, what) {
+  if (typeof value !== "bigint" || value <= 0n) {
+    throw NS.E("pkcs1/bad-component", what + " must be a positive integer (RFC 8017 sec. 3.1, sec. 3.2)");
+  }
+  return value;
+}
+
+/** @internal sec. 3.2: `d < n`, `dP < p`, `dQ < q` and `qInv < p`. Each is an equality the key's
+ * own arithmetic depends on, and a value at or above its bound is not the value the specification
+ * names. */
+function _below(value, bound, what, boundName) {
+  if (value >= bound) {
+    throw NS.E("pkcs1/bad-component", what + " must be smaller than " + boundName + " (RFC 8017 sec. 3.2)");
+  }
+}
+
+var OTHER_PRIME_INFO = schema.seq([
+  schema.field("prime", schema.integerLeaf()),
+  schema.field("exponent", schema.integerLeaf()),
+  schema.field("coefficient", schema.integerLeaf()),
+], {
+  assert: "sequence", arity: { min: 3, max: 3 }, code: "pkcs1/bad-other-prime-infos", what: "OtherPrimeInfo",
+  build: function (m) {
+    /** @internal RFC 8017 sec. 3.2 derives an additional prime's exponent modulo `r_i - 1` and its
+     * coefficient modulo `r_i`, so both are smaller than that prime, the same relation the first
+     * two primes are held to. Checking positivity alone here would read a key the specification
+     * does not describe. */
+    var prime = _positive(m.fields.prime.value, "an other prime info's prime");
+    var exponent = _positive(m.fields.exponent.value, "an other prime info's exponent");
+    var coefficient = _positive(m.fields.coefficient.value, "an other prime info's coefficient");
+    _below(exponent, prime, "an other prime info's exponent", "its prime");
+    _below(coefficient, prime, "an other prime info's coefficient", "its prime");
+    return { prime: prime, exponent: exponent, coefficient: coefficient };
+  },
+});
+
+var RSA_PRIVATE_KEY = schema.seq([
+  schema.field("version", schema.integerLeaf()),
+  schema.field("modulus", schema.integerLeaf()),
+  schema.field("publicExponent", schema.integerLeaf()),
+  schema.field("privateExponent", schema.integerLeaf()),
+  schema.field("prime1", schema.integerLeaf()),
+  schema.field("prime2", schema.integerLeaf()),
+  schema.field("exponent1", schema.integerLeaf()),
+  schema.field("exponent2", schema.integerLeaf()),
+  schema.field("coefficient", schema.integerLeaf()),
+  /** @internal App. A.1.2 puts `otherPrimeInfos` last and untagged, so it is recognized by being
+   * a universal SEQUENCE rather than by a context tag, and it is a SEQUENCE OF: the order is the
+   * key's own and carries no DER SET ordering. */
+  schema.optional("otherPrimeInfos", schema.seqOf(OTHER_PRIME_INFO, { min: 0, code: "pkcs1/bad-other-prime-infos", what: "otherPrimeInfos" }),
+    { whenUniversal: [asn1.TAGS.SEQUENCE] }),
+], {
+  assert: "sequence", arity: { min: 9, max: 10 }, code: "pkcs1/not-an-rsa-private-key", what: "RSAPrivateKey",
+  build: function (m) {
+    var version = m.fields.version.value;
+    if (version !== 0n && version !== 1n) {
+      throw NS.E("pkcs1/bad-version", "an RSAPrivateKey is version 0 or 1 (RFC 8017 App. A.1.2), got " + version);
+    }
+    var multi = m.fields.otherPrimeInfos.present;
+    var infos = multi
+      ? intrinsic.map(m.fields.otherPrimeInfos.value.items, function (it) { return it.value.result; })
+      : [];
+    /** @internal App. A.1.2 ties the version to the prime count: "otherPrimeInfos ... shall be
+     * omitted if version is 0 and shall contain at least one instance of OtherPrimeInfo if version
+     * is 1". A key stating one and carrying the other states two different keys. */
+    if (version === 0n && multi) {
+      throw NS.E("pkcs1/bad-other-prime-infos", "a version-0 RSAPrivateKey carries no otherPrimeInfos (RFC 8017 App. A.1.2)");
+    }
+    if (version === 1n && !multi) {
+      throw NS.E("pkcs1/bad-other-prime-infos", "a version-1 RSAPrivateKey carries at least one OtherPrimeInfo (RFC 8017 App. A.1.2)");
+    }
+    if (version === 1n && infos.length === 0) {
+      throw NS.E("pkcs1/bad-other-prime-infos", "otherPrimeInfos is SIZE(1..MAX), so an empty one is refused (RFC 8017 App. A.1.2)");
+    }
+
+    var modulus = _positive(m.fields.modulus.value, "the modulus");
+    var publicExponent = _positive(m.fields.publicExponent.value, "the public exponent");
+    var privateExponent = _positive(m.fields.privateExponent.value, "the private exponent");
+    var prime1 = _positive(m.fields.prime1.value, "prime1");
+    var prime2 = _positive(m.fields.prime2.value, "prime2");
+    var exponent1 = _positive(m.fields.exponent1.value, "exponent1");
+    var exponent2 = _positive(m.fields.exponent2.value, "exponent2");
+    var coefficient = _positive(m.fields.coefficient.value, "the coefficient");
+    _assertExponent(publicExponent, modulus);
+    _below(privateExponent, modulus, "the private exponent", "the modulus");
+    _below(exponent1, prime1, "exponent1", "prime1");
+    _below(exponent2, prime2, "exponent2", "prime2");
+    _below(coefficient, prime1, "the coefficient", "prime1");
+    return {
+      version: intrinsic.Number(version), modulus: modulus, publicExponent: publicExponent,
+      privateExponent: privateExponent, prime1: prime1, prime2: prime2,
+      exponent1: exponent1, exponent2: exponent2, coefficient: coefficient,
+      otherPrimeInfos: infos,
+    };
+  },
+});
+
+/** @internal sec. 3.1: "the RSA public exponent e ... 3 <= e < n". An even exponent has no
+ * multiplicative inverse modulo a product of odd primes, so it names no key either. */
+function _assertExponent(e, n) {
+  if (e < 3n || e >= n) {
+    throw NS.E("pkcs1/bad-exponent", "the public exponent must satisfy 3 <= e < n (RFC 8017 sec. 3.1)");
+  }
+  if ((e & 1n) === 0n) {
+    throw NS.E("pkcs1/bad-exponent", "the public exponent must be odd (RFC 8017 sec. 3.1)");
+  }
+}
+
+var RSA_PUBLIC_KEY = schema.seq([
+  schema.field("modulus", schema.integerLeaf()),
+  schema.field("publicExponent", schema.integerLeaf()),
+], {
+  assert: "sequence", arity: { min: 2, max: 2 }, code: "pkcs1/not-an-rsa-public-key", what: "RSAPublicKey",
+  build: function (m) {
+    var modulus = _positive(m.fields.modulus.value, "the modulus");
+    var publicExponent = _positive(m.fields.publicExponent.value, "the public exponent");
+    _assertExponent(publicExponent, modulus);
+    return { modulus: modulus, publicExponent: publicExponent };
+  },
+});
+
+var PRIVATE_OPTS = intrinsic.assign(intrinsic.create(null), {
+  pemLabel: PRIVATE_LABEL, PemError: PemError, ErrorClass: Pkcs1Error, prefix: "pkcs1",
+  what: "RSA private key", topSchema: RSA_PRIVATE_KEY, ns: NS,
+});
+var PUBLIC_OPTS = intrinsic.assign(intrinsic.create(null), {
+  pemLabel: PUBLIC_LABEL, PemError: PemError, ErrorClass: Pkcs1Error, prefix: "pkcs1",
+  what: "RSA public key", topSchema: RSA_PUBLIC_KEY, ns: NS,
+});
+
+/**
+ * @primitive  pki.schema.pkcs1.parse
+ * @signature  pki.schema.pkcs1.parse(input, opts) -> key
+ * @since      0.8.8
+ * @status     stable
+ * @spec       RFC 8017
+ * @related    pki.schema.pkcs1.parsePublic, pki.schema.pkcs8.parse
+ *
+ * Read an RFC 8017 Appendix A.1.2 `RSAPrivateKey`, as DER bytes or an
+ * `RSA PRIVATE KEY` PEM block, into `{ version, modulus, publicExponent,
+ * privateExponent, prime1, prime2, exponent1, exponent2, coefficient,
+ * otherPrimeInfos }`. Every component is a `BigInt`.
+ *
+ * The structure names no algorithm, so nothing here decides what the key is used
+ * under. Read it and hand the components to the verb that does.
+ *
+ * Fail-closed on the specification's own relations: a version other than 0 or 1, a
+ * version disagreeing with whether other prime infos are present, an
+ * `OtherPrimeInfo` that is not three integers, a component that is not a positive
+ * integer, a public exponent outside `3 <= e < n` or an even one, and a private
+ * exponent, CRT exponent or coefficient at or above its bound are each refused
+ * with their own `pkcs1/*` code.
+ *
+ * @example
+ *   // requires: der -- an RSAPrivateKey, from `openssl genrsa` or an appliance that emits one
+ *   var key = pki.schema.pkcs1.parse(der);
+ *   key.version;          // 0
+ *   key.publicExponent;   // 65537n
+ */
+var parse = pkix.makeParser(PRIVATE_OPTS);
+
+/**
+ * @primitive  pki.schema.pkcs1.parsePublic
+ * @signature  pki.schema.pkcs1.parsePublic(input, opts) -> key
+ * @since      0.8.8
+ * @status     stable
+ * @spec       RFC 8017
+ * @related    pki.schema.pkcs1.parse
+ *
+ * Read an RFC 8017 Appendix A.1.1 `RSAPublicKey`, as DER bytes or an
+ * `RSA PUBLIC KEY` PEM block, into `{ modulus, publicExponent }`. A structure
+ * carrying anything else, including a private key, is refused: the two encodings
+ * are told apart by their shape and neither door reads the other's.
+ *
+ * @example
+ *   // requires: der -- an RSAPrivateKey, from `openssl genrsa` or an appliance that emits one
+ *   var priv = pki.schema.pkcs1.parse(der);
+ *   var pubDer = pki.schema.pkcs1.encodePublic({ modulus: priv.modulus, publicExponent: priv.publicExponent });
+ *   pki.schema.pkcs1.parsePublic(pubDer).publicExponent;   // 65537n
+ */
+var parsePublic = pkix.makeParser(PUBLIC_OPTS);
+
+/**
+ * @primitive  pki.schema.pkcs1.encode
+ * @signature  pki.schema.pkcs1.encode(key) -> Buffer
+ * @since      0.8.8
+ * @status     stable
+ * @spec       RFC 8017
+ * @related    pki.schema.pkcs1.parse
+ *
+ * Write an `RSAPrivateKey` back to DER from the shape `parse` returns. What `parse`
+ * read is what this writes: a key read and written again produces the bytes it came
+ * from.
+ *
+ * @example
+ *   // requires: der -- an RSAPrivateKey, from `openssl genrsa` or an appliance that emits one
+ *   pki.schema.pkcs1.encode(pki.schema.pkcs1.parse(der)).equals(der);   // true
+ */
+function encode(key) {
+  if (key === null || typeof key !== "object") {
+    throw NS.E("pkcs1/bad-input", "encode takes the object parse returns");
+  }
+  var kids = [asn1.build.integer(intrinsic.BigInt(key.version)), asn1.build.integer(key.modulus),
+    asn1.build.integer(key.publicExponent), asn1.build.integer(key.privateExponent),
+    asn1.build.integer(key.prime1), asn1.build.integer(key.prime2),
+    asn1.build.integer(key.exponent1), asn1.build.integer(key.exponent2),
+    asn1.build.integer(key.coefficient)];
+  var infos = key.otherPrimeInfos;
+  if (intrinsic.isArray(infos) && infos.length > 0) {
+    var rows = [];
+    for (var i = 0; i < infos.length; i++) {
+      rows[i] = asn1.build.sequence([asn1.build.integer(infos[i].prime),
+        asn1.build.integer(infos[i].exponent), asn1.build.integer(infos[i].coefficient)]);
+    }
+    kids[9] = asn1.build.sequence(rows);
+  }
+  return asn1.build.sequence(kids);
+}
+
+/**
+ * @primitive  pki.schema.pkcs1.encodePublic
+ * @signature  pki.schema.pkcs1.encodePublic(key) -> Buffer
+ * @since      0.8.8
+ * @status     stable
+ * @spec       RFC 8017
+ * @related    pki.schema.pkcs1.parsePublic
+ *
+ * Write an `RSAPublicKey` back to DER from the shape `parsePublic` returns.
+ *
+ * @example
+ *   // requires: der -- an RSAPrivateKey, from `openssl genrsa` or an appliance that emits one
+ *   var priv = pki.schema.pkcs1.parse(der);
+ *   var pubDer = pki.schema.pkcs1.encodePublic({ modulus: priv.modulus, publicExponent: priv.publicExponent });
+ *   pki.schema.pkcs1.encodePublic(pki.schema.pkcs1.parsePublic(pubDer)).equals(pubDer);   // true
+ */
+function encodePublic(key) {
+  if (key === null || typeof key !== "object") {
+    throw NS.E("pkcs1/bad-input", "encodePublic takes the object parsePublic returns");
+  }
+  return asn1.build.sequence([asn1.build.integer(key.modulus), asn1.build.integer(key.publicExponent)]);
+}
+
+function pemDecode(text) { return pkix.pemDecode(text, PRIVATE_LABEL, PemError); }
+function pemEncode(der) { return pkix.pemEncode(der, PRIVATE_LABEL, PemError); }
+function pemDecodePublic(text) { return pkix.pemDecode(text, PUBLIC_LABEL, PemError); }
+function pemEncodePublic(der) { return pkix.pemEncode(der, PUBLIC_LABEL, PemError); }
+
+/** @internal RFC 8017 App. A.1.2: `RSAPrivateKey ::= SEQUENCE { version, modulus, publicExponent,
+ * privateExponent, prime1, prime2, exponent1, exponent2, coefficient, otherPrimeInfos OPTIONAL }`,
+ * so nine INTEGERs and an optional SEQUENCE. Structure alone does not separate this from every
+ * other SEQUENCE of INTEGERs, which is why nothing routes to it from bare bytes; it answers for a
+ * caller that already has the armor label saying what the bytes are meant to be. */
+function matches(root) {
+  var k = pkix.rootSequenceChildren(root, 9, 10);
+  if (!k) return false;
+  for (var i = 0; i < 9; i++) {
+    if (!schema.isUniversal(k[i], asn1.TAGS.INTEGER)) return false;
+  }
+  return k.length === 9 || schema.isUniversal(k[9], asn1.TAGS.SEQUENCE);
+}
+
+/** @internal RFC 8017 App. A.1.1: `RSAPublicKey ::= SEQUENCE { modulus, publicExponent }`. */
+function matchesPublic(root) {
+  var k = pkix.rootSequenceChildren(root, 2, 2);
+  return !!k && schema.isUniversal(k[0], asn1.TAGS.INTEGER) && schema.isUniversal(k[1], asn1.TAGS.INTEGER);
+}
+
+module.exports = {
+  parse: parse,
+  parsePublic: parsePublic,
+  matches: matches,
+  matchesPublic: matchesPublic,
+  encode: encode,
+  encodePublic: encodePublic,
+  pemDecode: pemDecode,
+  pemEncode: pemEncode,
+  pemDecodePublic: pemDecodePublic,
+  pemEncodePublic: pemEncodePublic,
+};

package/lib/schema-pkcs8.js

@@ -193,6 +193,20 @@ function matches(root) {
 }
 
 
+/** @internal RFC 5958 sec. 3: `EncryptedPrivateKeyInfo ::= SEQUENCE { encryptionAlgorithm
+ * AlgorithmIdentifier, encryptedData OCTET STRING }`. Exactly two children where a
+ * `PrivateKeyInfo` has three or more, and an `AlgorithmIdentifier` where that one has an INTEGER
+ * version, so the two are told apart by their first child and neither is read as the other. */
+function matchesEncrypted(root) {
+  var TAGS = asn1.TAGS;
+  var k = pkix.rootSequenceChildren(root, 2, 2);
+  if (!k) return false;
+  if (!schema.isUniversal(k[0], TAGS.SEQUENCE) || !k[0].children || k[0].children.length < 1) return false;
+  if (!schema.isUniversal(k[0].children[0], TAGS.OBJECT_IDENTIFIER)) return false;
+  return schema.isUniversal(k[1], TAGS.OCTET_STRING) && !k[1].constructed;
+}
+
+
 /** @internal `ctx` is the walk context of the parse that reached this key, when another format
  *  carries it. Only its caps and budget cross over: the key is still read in this namespace, so a
  *  fault in it keeps the PKCS#8 error class and code. */
@@ -209,6 +223,7 @@ module.exports = {
   pemDecode: pemDecode,
   pemEncode: pemEncode,
   matches: matches,
+  matchesEncrypted: matchesEncrypted,
   walkPrivateKeyInfo: walkPrivateKeyInfo,
   walkEncryptedPrivateKeyInfo: walkEncryptedPrivateKeyInfo,
 };