nish/crypto/x509-random

The private key and the serial number nish/crypto/x509's x509MintSelfSigned needs, drawn from the operating system's CSPRNG, and the mint that draws its own serial.

import {
  x509DrawP256Key,
  x509DrawSerial,
  x509MintSelfSignedDrawn,
} from "nish/crypto/x509-random";
import { Secret, wipe } from "nish:secret";
import { x509DrawP256Key, x509MintSelfSignedDrawn } from "nish/crypto/x509-random";

const priv: Secret<u8[]> = x509DrawP256Key();
const der: u8[] | null = x509MintSelfSignedDrawn(priv, "localhost", toI64(Date.now()), 14);
// ... present `der` and sign the handshake with `priv` ...
wipe(priv);
Native only

Every function here reaches crypto.getRandomValues, so a program that imports this module does not compile for wasm32, which has no entropy to reach. That is why it is a module of its own: nish/crypto/x509 takes the key and the serial as arguments and imports nothing from here, so a wasm32 program can still parse, verify and mint with bytes it was handed (X509-6, docs/security/crypto-x509.md).

Functions

x509DrawP256Key

A fresh P-256 private key: P256_SCALAR_SIZE bytes from crypto.getRandomValues, drawn again until they hold a scalar in [1, n), which p256PublicKey is the test of. Rejection rather than reduction mod n, so every key is equally likely; a draw is refused with odds below 2^-32. A refused draw is wiped before the next, and the caller wipes the one returned.

const x509DrawP256Key: () => Secret<u8[]>
returnsSecret<u8[]>

The 32-byte scalar, big-endian, in a new Secret the caller owns and wipes.

x509DrawSerial

A fresh serial number for x509MintSelfSigned: X509_MAX_SERIAL (20) bytes from crypto.getRandomValues with the first one's top two bits set to 01, so the INTEGER is positive, never zero, and always twenty octets long — 158 random bits, past the 64 the CA/Browser Forum asks of a serial. A serial is public, written into the certificate, so it is a plain array.

const x509DrawSerial: () => u8[]
returnsu8[]

The 20 serial octets, big-endian, in a fresh array.

x509MintSelfSignedDrawn

x509MintSelfSigned(priv, commonName, notBeforeMs, days, x509DrawSerial()): the self-signed certificate with a serial drawn here, null for everything the mint answers null for. The key stays the caller's, since the server that presents the certificate signs its handshakes with it; draw one with x509DrawP256Key.

const x509MintSelfSignedDrawn: (
  priv: Secret<u8[]>,
  commonName: string,
  notBeforeMs: i64,
  days: i32,
) => u8[] | null
privSecret<u8[]>required

The 32-byte P-256 private scalar; read, and left for the caller to wipe.

commonNamestringrequired

The subject's and issuer's common name, 1 to 64 bytes of UTF-8 without a NUL.

notBeforeMsi64required

When validity starts, in milliseconds since 1970-01-01 UTC.

daysi32required

How long it is valid, 1 to X509_MAX_DAYS.

returnsu8[] | null

The certificate's DER, a fresh array, or null.