@andrewheberle/serverless-ssh-ca 0.21.0 → 0.23.0

package/src/ssh/certificate.ts

@@ -0,0 +1,236 @@
+import * as P from "micro-packed"
+import {
+	decodePublicKey,
+	PublicKeyFieldCounts,
+	SSHBytes,
+	SSHOptions,
+	SSHText,
+	SSHTextList,
+} from "./encoding.js"
+import { base64 } from "@scure/base"
+import { KeyParseError, PublicKey } from "./keys.js"
+import { verify, type Signer } from "./signer.js"
+
+/**
+ * Encoding, decoding and signing of OpenSSH certificates as described in
+ * PROTOCOL.certkeys from OpenSSH
+ */
+
+/** Whether a certificate is for a user or a host */
+export type CertificateKind = "user" | "host"
+
+const CertificateKinds: Readonly<Record<CertificateKind, number>> = {
+	user: 1,
+	host: 2,
+}
+
+/** The fields of a certificate that are set by the CA */
+export type CertificateFields = {
+	/** Whether the certificate is for a user or a host */
+	kind: CertificateKind
+	/** The public key being certified */
+	publicKey: PublicKey
+	/** The serial number of the certificate */
+	serial: bigint
+	/** The key ID of the certificate, which is logged by sshd when it is used */
+	keyId: string
+	/** The users or hosts the certificate is valid for */
+	principals: string[]
+	/** The time from which the certificate is valid, to the second */
+	validAfter: Date
+	/** The time until which the certificate is valid, to the second */
+	validBefore: Date
+	/** The names of the extensions to include, which have no data */
+	extensions: string[]
+}
+
+// the fields of a certificate that follow its type, which are given the
+// number of fields in the public key of the certificate
+const fields = (keyFields: number) => ({
+	nonce: SSHBytes,
+	key: P.array(keyFields, SSHBytes),
+	serial: P.U64BE,
+	kind: P.U32BE,
+	keyId: SSHText,
+	principals: SSHTextList,
+	validAfter: P.U64BE,
+	validBefore: P.U64BE,
+	criticalOptions: SSHOptions,
+	extensions: SSHOptions,
+	reserved: SSHBytes,
+	signatureKey: SSHBytes,
+})
+
+const certificateType = (keyType: string): string => `${keyType}-cert-v01@openssh.com`
+
+// a certificate without and with its signature, tagged by the certificate type
+const ToBeSigned = P.tag(SSHText, Object.fromEntries(
+	Object.entries(PublicKeyFieldCounts).map(([keyType, count]) => [certificateType(keyType), P.struct(fields(count))]),
+))
+const Certificate = P.tag(SSHText, Object.fromEntries(
+	Object.entries(PublicKeyFieldCounts).map(([keyType, count]) => [certificateType(keyType), P.struct({ ...fields(count), signature: SSHBytes })]),
+))
+
+const toSeconds = (date: Date): bigint => BigInt(Math.floor(date.getTime() / 1000))
+
+/**
+ * Thrown when a certificate cannot be parsed
+ */
+export class CertificateParseError extends Error {
+	constructor(message: string, cause?: unknown) {
+		super(message)
+		this.name = "CertificateParseError"
+		this.cause = cause
+
+		Object.setPrototypeOf(this, CertificateParseError.prototype)
+	}
+}
+
+/**
+ * A signed OpenSSH certificate
+ */
+export class SshCertificate {
+	/** The wire encoding of the certificate */
+	readonly bytes: Uint8Array
+	/** The certificate type, for example "ssh-ed25519-cert-v01@openssh.com" */
+	readonly type: string
+	readonly kind: CertificateKind
+	/** The public key being certified */
+	readonly publicKey: PublicKey
+	readonly serial: bigint
+	readonly keyId: string
+	readonly principals: string[]
+	readonly validAfter: Date
+	readonly validBefore: Date
+	/** The names of the extensions on the certificate */
+	readonly extensions: string[]
+	/** The wire encoding of the public key of the CA that signed the certificate */
+	readonly signatureKey: Uint8Array
+	/** The signature of the CA in the SSH wire format */
+	readonly signature: Uint8Array
+
+	/**
+	 * Decodes a certificate from its wire encoding. This does not verify the
+	 * signature on the certificate.
+	 *
+	 * @param bytes The wire encoding of the certificate
+	 * @throws {@link CertificateParseError} when the certificate cannot be decoded or its type is not supported
+	 */
+	constructor(bytes: Uint8Array) {
+		let decoded: P.UnwrapCoder<typeof Certificate>
+		try {
+			decoded = Certificate.decode(bytes)
+		} catch (err) {
+			throw new CertificateParseError("certificate could not be decoded", err)
+		}
+		const { TAG, data } = decoded
+		const kind = (Object.keys(CertificateKinds) as CertificateKind[]).find((k) => CertificateKinds[k] === data.kind)
+		if (kind === undefined) {
+			throw new CertificateParseError(`unknown certificate kind: ${data.kind}`)
+		}
+
+		const publicKeyType = TAG.replace(/-cert-v01@openssh\.com$/, "")
+		try {
+			this.publicKey = new PublicKey(P.struct({ type: SSHText, key: P.array(data.key.length, SSHBytes) }).encode({ type: publicKeyType, key: data.key }))
+		} catch (err) {
+			throw new CertificateParseError(err instanceof KeyParseError ? err.message : "certificate public key could not be decoded", err)
+		}
+
+		this.bytes = bytes
+		this.type = TAG
+		this.kind = kind
+		this.serial = data.serial
+		this.keyId = data.keyId
+		this.principals = data.principals
+		this.validAfter = new Date(Number(data.validAfter) * 1000)
+		this.validBefore = new Date(Number(data.validBefore) * 1000)
+		this.extensions = data.extensions.map((e) => e.name)
+		this.signatureKey = data.signatureKey
+		this.signature = data.signature
+	}
+
+	/**
+	 * Parses a certificate in OpenSSH format, `${type} ${base64}[ ${comment}]`,
+	 * as found in `-cert.pub` files. This does not verify the signature on the
+	 * certificate.
+	 *
+	 * @param text The certificate
+	 * @throws {@link CertificateParseError} when the certificate cannot be parsed or its type is not supported
+	 */
+	static parse(text: string): SshCertificate {
+		const [type, data] = text.trim().split(/\s+/)
+		if (type === undefined || type === "" || data === undefined) {
+			throw new CertificateParseError("certificate was not in OpenSSH format")
+		}
+
+		let bytes: Uint8Array
+		try {
+			bytes = base64.decode(data)
+		} catch (err) {
+			throw new CertificateParseError("certificate was not valid base64", err)
+		}
+
+		const certificate = new SshCertificate(bytes)
+		if (certificate.type !== type) {
+			throw new CertificateParseError(`certificate type ${type} did not match encoded type ${certificate.type}`)
+		}
+
+		return certificate
+	}
+
+	/**
+	 * Returns whether the certificate was signed by a CA key
+	 *
+	 * @param ca The public key of the CA
+	 */
+	async isSignedBy(ca: PublicKey): Promise<boolean> {
+		if (!ca.equals(new PublicKey(this.signatureKey))) {
+			return false
+		}
+
+		// the signature is the last field, so everything before it is signed
+		const signed = this.bytes.subarray(0, this.bytes.length - 4 - this.signature.length)
+
+		return await verify(ca, this.signature, new Uint8Array(signed))
+	}
+
+	/**
+	 * Returns the certificate in OpenSSH format, as used for `-cert.pub` files
+	 */
+	toString(): string {
+		return `${this.type} ${base64.encode(this.bytes)}`
+	}
+}
+
+/**
+ * Creates and signs an OpenSSH certificate
+ *
+ * @param fields The fields of the certificate
+ * @param signer The CA key to sign the certificate with
+ * @returns The signed certificate
+ * @throws Error when the type of the public key being certified is not supported
+ */
+export const signCertificate = async (fields: CertificateFields, signer: Signer): Promise<SshCertificate> => {
+	const { type, fields: key } = decodePublicKey(fields.publicKey.blob)
+
+	const value = {
+		nonce: crypto.getRandomValues(new Uint8Array(32)),
+		key,
+		serial: fields.serial,
+		kind: CertificateKinds[fields.kind],
+		keyId: fields.keyId,
+		principals: fields.principals,
+		validAfter: toSeconds(fields.validAfter),
+		validBefore: toSeconds(fields.validBefore),
+		criticalOptions: [],
+		// options must be in lexical order and may each appear only once
+		extensions: [...new Set(fields.extensions)].sort().map((name) => ({ name, data: new Uint8Array(0) })),
+		reserved: new Uint8Array(0),
+		signatureKey: signer.publicKey,
+	}
+
+	const tbs = ToBeSigned.encode({ TAG: certificateType(type), data: value })
+	const signature = await signer.sign(new Uint8Array(tbs))
+
+	return new SshCertificate(Certificate.encode({ TAG: certificateType(type), data: { ...value, signature } }))
+}

package/src/ssh/encoding.ts

@@ -0,0 +1,81 @@
+import * as P from "micro-packed"
+
+/**
+ * Coders for the SSH wire format (RFC 4251 section 5)
+ */
+
+/** A string of bytes, prefixed by its length as a uint32 */
+export const SSHBytes = P.bytes(P.U32BE)
+
+/** A UTF-8 string, prefixed by its length as a uint32 */
+export const SSHText = P.string(P.U32BE)
+
+/** A list of strings packed into a string, as used for certificate principals */
+export const SSHTextList = P.prefix(P.U32BE, P.array(null, SSHText))
+
+/**
+ * A list of named options packed into a string, as used for certificate
+ * critical options and extensions
+ */
+export const SSHOptions = P.prefix(P.U32BE, P.array(null, P.struct({
+	name: SSHText,
+	data: SSHBytes,
+})))
+
+/**
+ * An mpint holding an unsigned integer, decoded to and encoded from its
+ * big-endian bytes without leading zeros.
+ *
+ * An mpint has no leading zero bytes, other than one to keep the value
+ * positive when the high bit of the first byte is set.
+ */
+export const SSHUnsignedMpint = P.apply(SSHBytes, {
+	encode: (mpint: Uint8Array): Uint8Array => {
+		let start = 0
+		while (start < mpint.length && mpint[start] === 0) {
+			start++
+		}
+
+		return mpint.subarray(start)
+	},
+	decode: (value: Uint8Array): Uint8Array => {
+		let start = 0
+		while (start < value.length && value[start] === 0) {
+			start++
+		}
+		const trimmed = value.subarray(start)
+
+		return trimmed.length > 0 && trimmed[0]! & 0x80
+			? P.utils.concatBytes(new Uint8Array([0]), trimmed)
+			: trimmed
+	},
+})
+
+/** The number of fields that follow the type in the wire encoding of a public key of each type */
+export const PublicKeyFieldCounts: Readonly<Record<string, number>> = {
+	"ssh-ed25519": 1, // public key
+	"ecdsa-sha2-nistp256": 2, // curve, public key
+	"ecdsa-sha2-nistp384": 2,
+	"ecdsa-sha2-nistp521": 2,
+	"ssh-rsa": 2, // e, n
+}
+
+/**
+ * Splits the wire encoding of a public key into its type and the encoded
+ * fields that follow it
+ *
+ * @param blob The wire encoding of the public key
+ * @returns The key type and its fields
+ * @throws Error when the key type is not supported or the encoding is invalid
+ */
+export const decodePublicKey = (blob: Uint8Array): { type: string, fields: Uint8Array[] } => {
+	const type = SSHText.decode(blob, { allowUnreadBytes: true })
+	const count = PublicKeyFieldCounts[type]
+	if (count === undefined) {
+		throw new Error(`unsupported public key type: ${type}`)
+	}
+
+	const { fields } = P.struct({ type: SSHText, fields: P.array(count, SSHBytes) }).decode(blob)
+
+	return { type, fields }
+}

package/src/ssh/keys.ts

@@ -0,0 +1,294 @@
+import { sha256 } from "@noble/hashes/sha2.js"
+import { base64, base64nopad, base64urlnopad } from "@scure/base"
+import * as P from "micro-packed"
+import { toFixedWidth } from "../sshsig/sig_parser.js"
+import { decodePublicKey, SSHBytes, SSHText } from "./encoding.js"
+
+/**
+ * Thrown when a key cannot be parsed
+ */
+export class KeyParseError extends Error {
+	constructor(message: string, cause?: unknown) {
+		super(message)
+		this.name = "KeyParseError"
+		this.cause = cause
+
+		Object.setPrototypeOf(this, KeyParseError.prototype)
+	}
+}
+
+/**
+ * Thrown when a private key is of a type that cannot be used to sign
+ */
+export class UnsupportedKeyError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = "UnsupportedKeyError"
+
+		Object.setPrototypeOf(this, UnsupportedKeyError.prototype)
+	}
+}
+
+const equalBytes = (a: Uint8Array, b: Uint8Array): boolean => {
+	return a.length === b.length && a.every((v, i) => v === b[i])
+}
+
+/**
+ * An SSH public key
+ */
+export class PublicKey {
+	/** The key type, for example "ssh-ed25519" */
+	readonly type: string
+	/** The wire encoding of the key (RFC 4253 section 6.6) */
+	readonly blob: Uint8Array
+	/** The comment of the key, if any */
+	readonly comment: string | undefined
+
+	/**
+	 * @param blob The wire encoding of the key
+	 * @param comment The comment of the key
+	 * @throws {@link KeyParseError} when the key cannot be decoded or its type is not supported
+	 */
+	constructor(blob: Uint8Array, comment?: string) {
+		try {
+			this.type = decodePublicKey(blob).type
+		} catch (err) {
+			throw new KeyParseError(err instanceof Error ? err.message : "public key could not be decoded", err)
+		}
+		this.blob = blob
+		this.comment = comment === "" ? undefined : comment
+	}
+
+	/**
+	 * Parses a public key in OpenSSH format, `${type} ${base64}[ ${comment}]`
+	 *
+	 * @param text The public key
+	 * @throws {@link KeyParseError} when the key cannot be parsed or its type is not supported
+	 */
+	static parse(text: string): PublicKey {
+		const [type, data, ...comment] = text.trim().split(/\s+/)
+		if (type === undefined || type === "" || data === undefined) {
+			throw new KeyParseError("public key was not in OpenSSH format")
+		}
+
+		let blob: Uint8Array
+		try {
+			blob = base64.decode(data)
+		} catch (err) {
+			throw new KeyParseError("public key was not valid base64", err)
+		}
+
+		const key = new PublicKey(blob, comment.join(" "))
+		if (key.type !== type) {
+			throw new KeyParseError(`public key type ${type} did not match encoded type ${key.type}`)
+		}
+
+		return key
+	}
+
+	/**
+	 * Returns the SHA256 fingerprint of the key, as shown by `ssh-keygen -l`,
+	 * for example "SHA256:79mq0wtpQMTvS4+Of8VzLN0qmYWNUyTXYmqKwhEgSLs"
+	 */
+	fingerprint(): string {
+		return `SHA256:${base64nopad.encode(sha256(this.blob))}`
+	}
+
+	/**
+	 * Returns whether this is the same key as another, ignoring comments
+	 */
+	equals(other: PublicKey): boolean {
+		return equalBytes(this.blob, other.blob)
+	}
+
+	/**
+	 * Returns a copy of the key with a different comment
+	 */
+	withComment(comment: string | undefined): PublicKey {
+		return new PublicKey(this.blob, comment)
+	}
+
+	/**
+	 * Returns the key in OpenSSH format, `${type} ${base64}[ ${comment}]`
+	 */
+	toString(): string {
+		const key = `${this.type} ${base64.encode(this.blob)}`
+
+		return this.comment === undefined ? key : `${key} ${this.comment}`
+	}
+}
+
+/** The ECDSA curves that can be used to sign */
+export type EcdsaCurve = "nistp256" | "nistp384" | "nistp521"
+
+const EcdsaCurves: Readonly<Record<EcdsaCurve, { namedCurve: string, size: number }>> = {
+	nistp256: { namedCurve: "P-256", size: 32 },
+	nistp384: { namedCurve: "P-384", size: 48 },
+	nistp521: { namedCurve: "P-521", size: 66 },
+}
+
+/**
+ * A private key that can be used to sign, with its key material as a JWK for
+ * WebCrypto
+ */
+export type PrivateKey = {
+	readonly type: "ed25519"
+	readonly publicKey: PublicKey
+	readonly jwk: JsonWebKey
+} | {
+	readonly type: "ecdsa"
+	readonly curve: EcdsaCurve
+	readonly publicKey: PublicKey
+	readonly jwk: JsonWebKey
+}
+
+// "openssh-key-v1\0"
+const AUTH_MAGIC = new TextEncoder().encode("openssh-key-v1\0")
+
+/** The container of an OpenSSH private key (PROTOCOL.key) */
+const OpenSshPrivateKey = P.struct({
+	magic: P.magicBytes(AUTH_MAGIC),
+	cipherName: SSHText,
+	kdfName: SSHText,
+	kdfOptions: SSHBytes,
+	publicKeys: P.array(P.U32BE, SSHBytes),
+	privateKeys: SSHBytes,
+})
+
+/** The start of the (decrypted) private section of an OpenSSH private key */
+const PrivateSectionStart = P.struct({
+	check1: P.U32BE,
+	check2: P.U32BE,
+	type: SSHText,
+})
+
+const Ed25519PrivateKey = P.struct({
+	check1: P.U32BE,
+	check2: P.U32BE,
+	type: SSHText,
+	publicKey: SSHBytes,
+	// the seed followed by the public key
+	privateKey: SSHBytes,
+	comment: SSHText,
+})
+
+const EcdsaPrivateKey = P.struct({
+	check1: P.U32BE,
+	check2: P.U32BE,
+	type: SSHText,
+	curve: SSHText,
+	publicKey: SSHBytes,
+	// an mpint
+	privateKey: SSHBytes,
+	comment: SSHText,
+})
+
+/**
+ * Returns a short name for the type of a key, for example "rsa" for "ssh-rsa"
+ */
+const keyTypeName = (type: string): string => {
+	return type.replace(/^ssh-/, "").replace(/^ecdsa-sha2-.*$/, "ecdsa")
+}
+
+/**
+ * Parses an unencrypted Ed25519 or ECDSA private key in OpenSSH format, as
+ * created by `ssh-keygen`
+ *
+ * @param text The private key, starting with `-----BEGIN OPENSSH PRIVATE KEY-----`
+ * @returns The private key
+ * @throws {@link KeyParseError} when the key cannot be parsed or is encrypted
+ * @throws {@link UnsupportedKeyError} when the key is not an Ed25519 or ECDSA key
+ */
+export const parsePrivateKey = (text: string): PrivateKey => {
+	const match = /-----BEGIN OPENSSH PRIVATE KEY-----([\s\S]*?)-----END OPENSSH PRIVATE KEY-----/.exec(text)
+	if (match === null) {
+		throw new KeyParseError("private key was not in OpenSSH format, as created by ssh-keygen (starting with -----BEGIN OPENSSH PRIVATE KEY-----)")
+	}
+
+	let container: P.UnwrapCoder<typeof OpenSshPrivateKey>
+	try {
+		container = OpenSshPrivateKey.decode(base64.decode(match[1]!.replace(/\s+/g, "")))
+	} catch (err) {
+		throw new KeyParseError("private key could not be decoded", err)
+	}
+
+	if (container.cipherName !== "none" || container.kdfName !== "none") {
+		throw new KeyParseError("encrypted private keys are not supported")
+	}
+	if (container.publicKeys.length !== 1) {
+		throw new KeyParseError(`private key must contain one key, not ${container.publicKeys.length}`)
+	}
+
+	// the private section is padded to a block size, so may have trailing bytes
+	const options = { allowUnreadBytes: true }
+	let start: P.UnwrapCoder<typeof PrivateSectionStart>
+	try {
+		start = PrivateSectionStart.decode(container.privateKeys, options)
+	} catch (err) {
+		throw new KeyParseError("private key could not be decoded", err)
+	}
+	if (start.check1 !== start.check2) {
+		throw new KeyParseError("private key check values did not match")
+	}
+
+	try {
+		if (start.type === "ssh-ed25519") {
+			const key = Ed25519PrivateKey.decode(container.privateKeys, options)
+			if (key.publicKey.length !== 32 || key.privateKey.length !== 64) {
+				throw new KeyParseError("Ed25519 private key was an unexpected length")
+			}
+			const publicKey = new PublicKey(container.publicKeys[0]!, key.comment)
+			if (!equalBytes(P.struct({ type: SSHText, key: SSHBytes }).encode({ type: start.type, key: key.publicKey }), publicKey.blob)) {
+				throw new KeyParseError("private key did not match its public key")
+			}
+
+			return {
+				type: "ed25519",
+				publicKey,
+				jwk: {
+					kty: "OKP",
+					crv: "Ed25519",
+					d: base64urlnopad.encode(key.privateKey.subarray(0, 32)),
+					x: base64urlnopad.encode(key.publicKey),
+				},
+			}
+		}
+
+		if (start.type.startsWith("ecdsa-sha2-")) {
+			const key = EcdsaPrivateKey.decode(container.privateKeys, options)
+			const curve = EcdsaCurves[key.curve as EcdsaCurve]
+			if (curve === undefined || start.type !== `ecdsa-sha2-${key.curve}`) {
+				throw new UnsupportedKeyError(`ECDSA curve ${key.curve} is not supported`)
+			}
+			if (key.publicKey.length !== 1 + curve.size * 2 || key.publicKey[0] !== 0x04) {
+				throw new KeyParseError(`unexpected ECDSA public key encoding for ${key.curve}`)
+			}
+			const publicKey = new PublicKey(container.publicKeys[0]!, key.comment)
+			if (!equalBytes(P.struct({ type: SSHText, curve: SSHText, key: SSHBytes }).encode({ type: start.type, curve: key.curve, key: key.publicKey }), publicKey.blob)) {
+				throw new KeyParseError("private key did not match its public key")
+			}
+
+			return {
+				type: "ecdsa",
+				curve: key.curve as EcdsaCurve,
+				publicKey,
+				jwk: {
+					kty: "EC",
+					crv: curve.namedCurve,
+					// d is an mpint, so may be short or have a leading sign byte
+					d: base64urlnopad.encode(toFixedWidth(key.privateKey, curve.size)),
+					x: base64urlnopad.encode(key.publicKey.subarray(1, 1 + curve.size)),
+					y: base64urlnopad.encode(key.publicKey.subarray(1 + curve.size)),
+				},
+			}
+		}
+	} catch (err) {
+		if (err instanceof KeyParseError || err instanceof UnsupportedKeyError) {
+			throw err
+		}
+		throw new KeyParseError("private key could not be decoded", err)
+	}
+
+	throw new UnsupportedKeyError(`CA key type ${keyTypeName(start.type)} is not supported, the CA key must be Ed25519 or ECDSA`)
+}
+