@andrewheberle/serverless-ssh-ca 0.22.0 → 0.23.0

package/src/proof.ts

@@ -1,16 +1,34 @@
 import { ms } from "itty-time"
-import sshpk from "sshpk"
-import type { Fingerprint, Key } from "sshpk"
+import { KeyParseError, PublicKey } from "./ssh/keys.js"
 import { verify } from "./sshsig/index.js"
 import { parse } from "./sshsig/sig_parser.js"
 import { Sig } from "./sshsig/sig.js"
 import { group, Logger, LogLevel } from "@andrewheberle/ts-slog"
 
-// sshpk is CommonJS and Node's ESM loader cannot detect most of its named exports, so values are taken from the default import
-const { FingerprintFormatError, parseFingerprint, parseKey } = sshpk
+// a SHA256 fingerprint as shown by ssh-keygen -l, which is unpadded base64
+const FingerprintFormat = /^SHA256:[A-Za-z0-9+/]{43}$/
 
 export const Namespace = "proof-of-possession@com.github.serverless-ssh-ca.andrewheberle"
 
+/**
+ * The namespace used for proofs of possession that are bound to a request,
+ * kept separate from {@link Namespace} so a proof made for one form can never
+ * be accepted as the other.
+ */
+export const RequestNamespace = "request-proof-of-possession@com.github.serverless-ssh-ca.andrewheberle"
+
+/**
+ * Returns the request a proof of possession is bound to, which is appended to
+ * the signed data as `${timestamp}.${fingerprint}.${binding}`.
+ *
+ * @param method The HTTP method of the request, for example "DELETE"
+ * @param path The path of the request with any parameters filled in, for example "/api/v4/user/certificates/123"
+ * @returns The request binding, for example "DELETE /api/v4/user/certificates/123"
+ */
+export const requestBinding = (method: string, path: string): string => {
+	return `${method.toUpperCase()} ${path}`
+}
+
 export class PossessionParseError extends Error {
 	constructor(message: string, cause?: unknown) {
 		super(message)
@@ -38,9 +56,10 @@ export class PossessionParseError extends Error {
  */
 export class ProofOfPossession {
 	readonly timestamp: number
-	readonly fingerprint: Fingerprint
+	/** The SHA256 fingerprint of the key, for example "SHA256:79mq0wtpQMTvS4+Of8VzLN0qmYWNUyTXYmqKwhEgSLs" */
+	readonly fingerprint: string
 	readonly signature: Sig
-	readonly signaturePubkey: Key
+	readonly signaturePubkey: PublicKey
 	readonly logger: Logger
 	private readonly data: string
 
@@ -69,10 +88,9 @@ constructor(proof: string, options?: { from?: number, logger?: Logger, skew?: nu
 			throw new PossessionParseError("timestamp was from the future")
 		}
 		try {
-			// parse fingerprint
-			const fingerprint = parseFingerprint(fingerprintString!)
-			if (fingerprint === undefined) {
-				throw new PossessionParseError("fingerprint did not parse")
+			// check fingerprint
+			if (!FingerprintFormat.test(fingerprintString!)) {
+				throw new PossessionParseError("proof of possession fingerprint was an invalid format")
 			}
 
 			// convert siganture from base64
@@ -86,26 +104,26 @@ constructor(proof: string, options?: { from?: number, logger?: Logger, skew?: nu
 				throw new PossessionParseError("proof of possession signature could not be parsed", err)
 			}
 
-			this.fingerprint = fingerprint
+			this.fingerprint = fingerprintString!
 			this.data = `${timestamp}.${fingerprintString}`
-			this.signaturePubkey = parseKey(this.signature.publickey.toString())
+			this.signaturePubkey = PublicKey.parse(this.signature.publickey.toString())
 
 			// ensure the provided fingerprint matches the signature public key
-			if (!this.fingerprint.matches(this.signaturePubkey)) {
+			if (this.fingerprint !== this.signaturePubkey.fingerprint()) {
 				throw new PossessionParseError("proof of possession fingerprint does not match signature public key")
 			}
 
 			this.logger.debug("constructor completed",
 				...group("this",
 					"timestamp", this.timestamp,
-					"fingerprint", this.fingerprint.toString("base64"),
-					"signaturePubkey.fingerprint()", this.signaturePubkey.fingerprint().toString("base64"),
+					"fingerprint", this.fingerprint,
+					"signaturePubkey.fingerprint()", this.signaturePubkey.fingerprint(),
 				),
 			)
 		} catch (err) {
 			switch (true) {
-				case (err instanceof FingerprintFormatError):
-					throw new PossessionParseError("proof of possession fingerprint was an invalid format", err)
+				case (err instanceof KeyParseError):
+					throw new PossessionParseError(`proof of possession signature key could not be used: ${err.message}`, err)
 				default:
 					throw err
 			}
@@ -120,26 +138,42 @@ constructor(proof: string, options?: { from?: number, logger?: Logger, skew?: nu
 		return await verify(this.signature, this.data, { namespace: namespace || Namespace })
 	}
 
+	/**
+	 * Verifies the proof was made for a specific request, so it cannot be
+	 * replayed against another endpoint or with other path parameters (such
+	 * as a different certificate serial).
+	 *
+	 * The signed data is `${timestamp}.${fingerprint}.${METHOD} ${path}` using
+	 * the {@link RequestNamespace} namespace.
+	 *
+	 * @param method The HTTP method of the request
+	 * @param path The path of the request with any parameters filled in
+	 * @returns true if signature is valid for the request, false otherwise
+	 */
+	async verifyRequest(method: string, path: string): Promise<boolean> {
+		return await verify(this.signature, `${this.data}.${requestBinding(method, path)}`, { namespace: RequestNamespace })
+	}
+
 	/**
 	 *
 	 * @param keys array of keys to verify finterprint against
 	 * @returns true if the proof of possession fingerprint matches any of the provided keys, false otherwise
 	 */
-	matches(key: Key): boolean
-	matches(...keys: Key[]): boolean
+	matches(key: PublicKey): boolean
+	matches(...keys: PublicKey[]): boolean
 
-	matches(...keys: Key[]): boolean {
+	matches(...keys: PublicKey[]): boolean {
 		this.logger.debug("matches() called", "in", "ProofOfPossession", "keys", keys.length)
 		try {
 			for (const key of keys) {
 				// confirm proof of possession fingerprint matches keys
-				this.logger.debug("this.fingerprint.matches()", "in", "ProofOfPossession", "fingerprint", this.fingerprint.toString("base64"), "key", key.toString("ssh"))
-				if (!this.fingerprint.matches(key))
+				this.logger.debug("comparing fingerprint", "in", "ProofOfPossession", "fingerprint", this.fingerprint, "key", key.toString())
+				if (this.fingerprint !== key.fingerprint())
 					return false
 
 				// also confirm key used to sign proof of possession matches
-				this.logger.debug("this.signaturePubkey.fingerprint().matches()", "in", "ProofOfPossession", "signaturePubkey", this.signaturePubkey.fingerprint().toString("base64"), "key", key.toString("ssh"))
-				if (!this.signaturePubkey.fingerprint().matches(key))
+				this.logger.debug("comparing signature public key", "in", "ProofOfPossession", "signaturePubkey", this.signaturePubkey.fingerprint(), "key", key.toString())
+				if (!this.signaturePubkey.equals(key))
 					return false
 			}
 			this.logger.debug("matches() completed", "in", "ProofOfPossession", "keys", keys.length)
@@ -163,10 +197,10 @@ export class PossessionMatchError extends Error {
 }
 
 export class RenewalProofOfPossession extends ProofOfPossession {
-	override matches(key: Key): never
-	override matches(...keys: Key[]): boolean
+	override matches(key: PublicKey): never
+	override matches(...keys: PublicKey[]): boolean
 
-	override matches(...keys: Key[]): boolean {
+	override matches(...keys: PublicKey[]): boolean {
 		this.logger.debug("matches() called", "in", "RenewalProofOfPossession", "keys", keys.length)
 		if (keys.length === 1) {
 			throw new PossessionMatchError("must verify both public key and certificate")
@@ -174,11 +208,11 @@ export class RenewalProofOfPossession extends ProofOfPossession {
 
 		try {
 			for (const key of keys) {
-				this.logger.debug("this.fingerprint.matches()", "in", "RenewalProofOfPossession", "fingerprint", this.fingerprint.toString("base64"), "key", key.toString("ssh"))
-				if (!this.fingerprint.matches(key))
+				this.logger.debug("comparing fingerprint", "in", "RenewalProofOfPossession", "fingerprint", this.fingerprint, "key", key.toString())
+				if (this.fingerprint !== key.fingerprint())
 					return false
-				this.logger.debug("this.signaturePubkey.fingerprint().matches()", "in", "RenewalProofOfPossession", "signaturePubkey", this.signaturePubkey.fingerprint().toString("base64"), "key", key.toString("ssh"))
-				if (!this.signaturePubkey.fingerprint().matches(key))
+				this.logger.debug("comparing signature public key", "in", "RenewalProofOfPossession", "signaturePubkey", this.signaturePubkey.fingerprint(), "key", key.toString())
+				if (!this.signaturePubkey.equals(key))
 					return false
 			}
 			this.logger.debug("matches() completed", "in", "RenewalProofOfPossession", "keys", keys.length)

package/src/router.ts

@@ -1,6 +1,7 @@
 import { fromHono } from "chanfana"
 import { Hono, type Context } from "hono"
 import { createApi as apiv3 } from "./api/v3/index.js"
+import { BasePath as v4BasePath, createApi as apiv4 } from "./api/v4/index.js"
 import { HTTPException } from "hono/http-exception"
 import { logger } from "./logger.js"
 import type { SshCaBindings } from "./types.js"
@@ -24,7 +25,7 @@ export const createApp = (env: SshCaBindings) => {
 		schema: {
 			info: {
 				title: "Serverless SSH CA API",
-				version: "3.0.0"
+				version: "4.0.0"
 			},
 		}
 	})
@@ -36,6 +37,7 @@ export const createApp = (env: SshCaBindings) => {
     })
 
     app.route("/api/v3", apiv3(env))
+    app.route(v4BasePath, apiv4(env))
 
     return app
 }

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 }
+}