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);
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.
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.
x509MintSelfSignedDrawn
x509MintSelfSigned(priv, commonName, notBeforeMs, days, x509DrawSerial()): the self-signed certificate with a serial drawn here, null for everything the mint answers null for.
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[]>requiredThe 32-byte P-256 private scalar; read, and left for the caller to wipe.
commonNamestringrequiredThe subject's and issuer's common name, 1 to 64 bytes of UTF-8 without a NUL.
notBeforeMsi64requiredWhen validity starts, in milliseconds since 1970-01-01 UTC.
daysi32requiredHow long it is valid, 1 to X509_MAX_DAYS.
returnsu8[] | nullThe certificate's DER, a fresh array, or null.

