npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@andrewheberle/serverless-ssh-ca

v1.0.1

Published

A serverless SSH CA built for Cloudflare Workers that can also run on Node.js

Readme

@andrewheberle/serverless-ssh-ca

This is the package that implements the SSH CA functionality which can be deployed to Cloudflare as a working solution using the "Deploy to Cloudflare" button below:

Deploy to Cloudflare

To use the package in your own Worker manually (assuming you have the required bindings in place), the following code in src/index.ts (your Worker's main file) will work:

import app from "@andrewheberle/serverless-ssh-ca"

export default app

This package is built for Cloudflare Workers and can also run on Node.js 24 (see Running on Node.js). These are the only runtimes it is tested on, see Supported Platforms for the versions supported and what is best effort.

The package doesn't use any Workers-specific APIs and doesn't depend on @cloudflare/workers-types. It needs:

  • Web standard APIs (Request, Response and WebCrypto)
  • Node.js compatibility (nodejs_compat on Workers), because sshpk uses Node APIs
  • A database binding compatible with Cloudflare D1
  • A secret binding with an async get() method that returns the CA private key

Its exported types describe only these needs, so the Env generated by wrangler types (with DB as a D1Database and PRIVATE_KEY as a SecretsStoreSecret) can be passed directly as SshCaBindings.

Upgrading from a 0.x release? See Upgrading to 1.0 before you do: API v3 is removed, and some configurations 0.x accepted are refused.

Running on Node.js

Node.js 24 or later is required. Helpers for Node.js are imported from @andrewheberle/serverless-ssh-ca/node:

| Helper | Purpose | |---|---| | fromNodeSqlite(db) | Uses a built-in node:sqlite database as the DB binding | | secretFromFile(path) | Reads the CA private key from a file (re-read each time it is needed) | | secretFromString(value) | Uses a string as the CA private key | | cacheInMemory() | Uses an in-memory cache as the optional CACHE binding (see KRL Caching) | | bindingsFromEnv({ DB, PRIVATE_KEY }) | Reads and validates the remaining configuration from process.env |

createSshCa(bindings) returns a fetch(request) handler that takes a standard Request and returns a Response, and a cleanup() task that replaces the Workers cron trigger.

The handler can be served by any server that works with Request and Response. For example, with @hono/node-server (installed separately with npm install @hono/node-server):

import { DatabaseSync } from "node:sqlite"
import { serve } from "@hono/node-server"
import { createSshCa } from "@andrewheberle/serverless-ssh-ca"
import { bindingsFromEnv, fromNodeSqlite, secretFromFile } from "@andrewheberle/serverless-ssh-ca/node"

const ca = createSshCa(bindingsFromEnv({
    DB: fromNodeSqlite(new DatabaseSync("/var/lib/ssh-ca/ssh-ca.sqlite")),
    PRIVATE_KEY: secretFromFile("/etc/ssh-ca/ca_key"),
}))

// remove expired certificates once a day
setInterval(() => void ca.cleanup(), 24 * 60 * 60 * 1000)

serve({ fetch: (req) => ca.fetch(req), port: 8787 })

Notes:

  • The configuration environment variables have the same names and formats as the vars in the Workers wrangler.jsonc. bindingsFromEnv validates them at start up with the same rules as createSshCa and the Workers default export (see Validation), and throws an InvalidConfigurationError that lists every missing or invalid variable. It returns only the variables the CA reads, unchanged.
  • The database schema is created and migrated automatically on first use, as on Workers (see Database). Use a file path for DatabaseSync (not :memory:) so issued and revoked certificates survive restarts.
  • Only SQLite databases are supported. Other SQLite-compatible databases can be used by implementing the CaDatabase interface.
  • The CA private key has the same requirements as on Workers (see CA Private Key). Keep the key file readable only by the user running the CA.
  • cleanup() can also be run on a schedule outside the process (for example from a systemd timer or cron job) instead of using setInterval.
  • Put the CA behind a reverse proxy that terminates TLS, as clients send identity tokens to it.

See the following repositories for additional information:

| Repository | Details | |---|---| | https://github.com/andrewheberle/ssh-ca-client | Contains client code for issuing user and host certificates | | template/ | The Worker the "Deploy to Cloudflare" button deploys, which pins the CA to the latest release |

Architecture

The solution comprises of the CA running as a Worker, a Go based client (found here) and a third party OIDC IdP.

The IdP may be any OIDC compatible service that issues identity tokens as JWTs, and access tokens that are either JWTs with an email claim or accepted by its userinfo endpoint (see Opaque Access Tokens). At this time only Cloudflare Access has been tested.

User Certificates

The flow to obtain a User SSH certificate using the CLI version is as follows:

  1. The user initiates ssh-ca-client-cli login
  2. If required a new SSH key is generated and a browser is opened to visit http://localhost:3000/auth/login
  3. The client redirects the user to the configured IdP
  4. The IdP returns the user to the callback URL (default http://localhost:3000/auth/callback)
  5. The client sends the access token from the IdP as Authorization: Bearer <TOKEN> in a POST request to the CA's /api/v4/user/certificates endpoint, with the user's SSH public key, the identity token, and a proof of possession of the key in the Proof-Of-Possession header
  6. The CA verifies both tokens and the proof of possession and, if they are valid, responds with a signed certificate for the provided public key
  7. The client saves the certificate and adds the SSH private key and certificate to the local SSH Agent.

This flow is shown below once the user executes ssh-ca-client-cli login:

sequenceDiagram
    User->>Client: GET /auth/login
    activate Client
    Client-->>User: Redirect to IdP
    deactivate Client
    activate User
    User->>IdP: OIDC authentication flow
    deactivate User
    activate IdP
    IdP-->>User: Redirect to Client
    deactivate IdP
    activate User
    User->>Client: Completes OIDC redirect
    deactivate User
    activate Client
    activate Client
    Client-->>User: Auth flow completed
    deactivate Client
    Client->>CA: POST /api/v4/user/certificates
    deactivate Client
    activate CA
    CA-->>Client: Signed certificate
    deactivate CA
    activate Client
    Client->>SSH Agent: Add key and certificate to Agent
    deactivate Client

If a refresh token is available, the process looks like this when running ssh-ca-client-cli login:

sequenceDiagram
    Client->>IdP: Request access and identity tokens
    activate IdP
    IdP-->>Client: Token returned
    deactivate IdP
    activate Client
    Client->>CA: POST /api/v4/user/certificates
    deactivate Client
    activate CA
    CA-->>Client: Signed certificate
    deactivate CA
    activate Client
    Client->>SSH Agent: Add key and certificate to Agent
    deactivate Client

If refreshing the tokens with the refresh token fails, the standard authentication process is followed which requires user interaction.

The principals of a user certificate come from the identity token's JWT_SSH_CERTIFICATE_PRINCIPALS_CLAIM (with spaces replaced by underscores), SSH_CERTIFICATE_PRINCIPALS and the SSH_CERTIFICATE_INCLUDE_SELF* settings. A request is refused with a 422 error if there are none, or if any of them is empty or contains a comma, whitespace, a control character or an OpenSSH pattern character (*, ? or !). A server that restricts certificates with the principals="..." option in authorized_keys reads that option as a comma separated list, so, depending on how it matches them, a principal such as alice,root might otherwise be accepted for an account it was not meant for.

Host Certificates

Initial Request

The process to request an initial Host certificate is similar to obtaining a User certificate once ssh-ca-client-cli host is run, however instead of adding the obtained certificate to a SSH Agent, it is written to <KEYPATH>-cert.pub instead:

sequenceDiagram
    User->>Client: GET /auth/login
    activate Client
    Client-->>User: Redirect to IdP
    deactivate Client
    activate User
    User->>IdP: OIDC authentication flow
    deactivate User
    activate IdP
    IdP-->>User: Redirect to Client
    deactivate IdP
    activate User
    User->>Client: Completes OIDC redirect
    deactivate User
    activate Client
    activate Client
    Client-->>User: Auth flow completed
    deactivate Client
    Client->>CA: POST /api/v4/host/certificates
    deactivate Client
    activate CA
    CA-->>Client: Signed certificate
    deactivate CA
    activate Client
    Client->>Writes Certificate: Certificate written to disk
    deactivate Client

Host certificate principals may be IP addresses, bare host names or fully qualified domain names. As OpenSSH matches the principals of a host certificate as patterns, principals containing wildcard or pattern characters (*, ?, ! or ,), whitespace or control characters are refused, as a principal such as * would make the certificate valid for every host.

Renewals

Renewals are done using the existing certificate and will succeed if:

  1. The certificate is not expired
  2. It was issued by the CA
  3. The public key used to obtain the certificate is the same as the one currently presented
  4. It has not been revoked, or already renewed

The certificate that was renewed is revoked and added to the host KRL, so it cannot be used to renew again, and SSH clients that check the host KRL will no longer accept it. From OpenSSH 9.8, sshd only reads host certificates when it starts or is reloaded, so it must be reloaded to present the renewed certificate once it has been written to disk; until then it keeps presenting the revoked one. OpenSSH 9.7 and earlier read the certificate for each connection, so present the renewed certificate without a reload. The client's host --renew --reload-command option reloads sshd only when a certificate was renewed.

This means the OIDC authentication flow is not required in this case as shown below when ssh-ca-client-cli host --renew is run:

sequenceDiagram
    Client->>CA: POST /api/v4/host/certificates/{serial}/renew
    activate CA
    CA-->>Client: Signed certificate
    deactivate CA
    activate Client
    Client->>Writes Certificate: Certificate written to disk
    deactivate Client

API

The CA's API is documented in OpenAPI format at /docs and in openapi.json:

| Action | Endpoint | |--------------------------|-------------------------------------------------| | Get the CA public key | GET /api/v4/ca | | Request user certificate | POST /api/v4/user/certificates | | Revoke user certificate | DELETE /api/v4/user/certificates/{serial} | | Get user KRL | GET /api/v4/user/krl | | Request host certificate | POST /api/v4/host/certificates | | Renew host certificate | POST /api/v4/host/certificates/{serial}/renew | | Revoke host certificate | DELETE /api/v4/host/certificates/{serial} | | Get host KRL | GET /api/v4/host/krl |

API v3 was removed in 1.0.0, because its proofs of possession were not bound to the request they were sent with (see ADR 0006). Every request under /api/v3 is answered with 410 Gone, so clients must be ssh-ca-client 0.24.0 or later.

Certificates are issued for Ed25519, ECDSA and RSA keys. RSA keys must be at least 2048 bits; a request for a smaller key is refused with a 400 error, and a certificate for a smaller key cannot be renewed. Certificates for smaller keys can still be revoked.

Proof of Possession

Requests that use an SSH key prove possession of its private key by including a proof of the form ${timestamp}.${fingerprint}.${signature}, where timestamp is the time in milliseconds since the Unix epoch, fingerprint is the SHA256 fingerprint of the public key (for example SHA256:79mq0wtpQMTvS4+Of8VzLN0qmYWNUyTXYmqKwhEgSLs) and signature is the BASE64 encoded armored SSHSIG signature (as produced by ssh-keygen -Y sign) of the signed data. The proof is rejected if the timestamp is outside of CERTIFICATE_REQUEST_TIME_SKEW_MAX of the time on the CA.

The proof is sent in the Proof-Of-Possession header and is bound to the request it is made for. The signed data is ${timestamp}.${fingerprint}.${METHOD} ${path} using the request-proof-of-possession@com.github.serverless-ssh-ca.andrewheberle namespace, where ${METHOD} ${path} is the request as documented in the OpenAPI schema with any parameters filled in, for example:

1765696780805.SHA256:79mq0wtpQMTvS4+Of8VzLN0qmYWNUyTXYmqKwhEgSLs.DELETE /api/v4/user/certificates/12345678901234567890

Only ${timestamp}.${fingerprint}.${signature} is sent, as the CA rebuilds the request part from the request it receives. The path does not change if the CA is served behind a proxy under another path, and serials in the path are written in decimal without leading zeros.

The timestamp is written in decimal without a sign or leading zeros, and the signature is standard base64 with padding. A proof in any other form is refused.

The public key for a revocation or renewal is taken from the proof and the certificate respectively, so it is not sent separately.

Configuration

Validation

The configuration is validated on every runtime before the CA serves anything with it:

| Setting | Accepted values | |---|---| | CERTIFICATE_REQUEST_TIME_SKEW_MAX | A positive duration of at most 5 minutes, such as "90 seconds". A proof of possession is accepted this long either side of the CA's clock | | SSH_CERTIFICATE_LIFETIME | A duration of at least 5 minutes, in whole seconds, such as "24 hours". The longest lifetime of a user certificate | | SSH_HOST_CERTIFICATE_LIFETIME | A duration of at least 24 hours, in whole seconds, such as "30 days". The longest lifetime of a host certificate | | DB_CERTIFICATE_RETENTION | "infinite", or a positive period such as "1 year" or "90 days" | | JWT_ISSUER, ISSUER_DN, JWT_SSH_CERTIFICATE_PRINCIPALS_CLAIM | Must be set | | JWT_AUD | A list with at least one audience. Must be set | | JWT_ALGORITHMS | A list with at least one of RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, EdDSA or Ed25519. Symmetric algorithms and none are refused, as the keys come from a public JWKS | | JWT_JWKS_URL | An https URL, or an http URL for localhost, 127.0.0.0/8 or [::1] (such as a test identity provider) | | OIDC_USERINFO_URL | As JWT_JWKS_URL, or unset (an empty string is treated as unset) | | JWT_ACCESS_TOKEN_AUD, SSH_HOST_CERTIFICATE_ALLOWED_EMAILS, SSH_HOST_CERTIFICATE_ALLOWED_ROLES | A list, or unset (an empty string is an empty list) | | SSH_CERTIFICATE_EXTENSIONS | A list of extension names, each without whitespace, or unset. These are the extensions user certificates get by default and the only ones a requester may ask for; when unset, user certificates have no extensions (so no permit-pty) | | SSH_CERTIFICATE_PRINCIPALS | A list of principals, each of which contains no whitespace, control characters or *, ?, !, or unset | | SSH_CERTIFICATE_INCLUDE_SELF, SSH_CERTIFICATE_INCLUDE_SELF_EMAIL | "true" or "false" (or a boolean), or unset | | LOG_LEVEL | none, error, warning, info or debug, or unset | | LANDING_PAGE | "true" or "false" (or a boolean), or unset. See Landing Page | | ADMIN_* | See Admin UI. Each may be unset, but must be valid when set |

A list is a comma separated string, or an array of strings where bindings can be arrays. Each entry is trimmed, so "a, b" is the same as "a,b", and an empty entry, such as in "a,,b" or "a,", is refused.

SSH_HOST_CERTIFICATE_ALLOWED_EMAILS is compared with the requester's email address case-insensitively. SSH_HOST_CERTIFICATE_ALLOWED_ROLES is compared exactly with the values of the JWT_SSH_CERTIFICATE_PRINCIPALS_CLAIM claim of the identity token. Spaces are replaced with underscores in both, so a group ops team is allowed by the role ops team or ops_team.

A duration is a number and one of the units second, minute, hour, day, week, month or year (singular or plural), separated by a space. A unit is required, so a bare number or an abbreviation such as "90 secs" is refused. A retention period uses the same format without week, as it is passed to SQLite as a date modifier.

How an invalid configuration is reported depends on the runtime:

  • On Cloudflare Workers the default export logs the problems once, at error level, and then answers every request with a 500 error whose body does not describe the configuration. The scheduled database cleanup is skipped until the configuration is fixed.
  • createSshCa throws an InvalidConfigurationError listing every missing or invalid setting, as does bindingsFromEnv on Node.js. The error is exported from both @andrewheberle/serverless-ssh-ca and @andrewheberle/serverless-ssh-ca/node.

The scheduled cleanup removes certificates that expired longer ago than DB_CERTIFICATE_RETENTION. A revoked certificate stays in the KRL until 24 hours after it expires, so it is not removed before then, however short the retention period is.

Database

The CA keeps the certificates it has issued, and the version of each KRL, in a SQLite database: D1 on Cloudflare Workers, or node:sqlite (or another CaDatabase) on Node.js. The CA's tables are created in the database on first use, and after an upgrade any new migrations are applied automatically the first time the database is used. Upgrading from any earlier release migrates the database, as migrations are never removed.

The schema is internal to the CA and can change in any release, including a minor or patch release, so it is not part of what semver covers. Reading the tables, writing to them or adding your own tables, indexes or views is not supported, and may break on any upgrade. Use the admin UI and the API instead.

Running an older release against a database that a newer release has migrated is not supported. To roll back after an upgrade, restore a backup of the database taken before it, such as a D1 Time Travel restore point or a copy of the SQLite file, along with the older release.

CA Private Key

The CA private key is read from the PRIVATE_KEY Secrets Store binding and must be an unencrypted Ed25519 or ECDSA (nistp256, nistp384 or nistp521) key in OpenSSH format, which is what ssh-keygen creates by default:

ssh-keygen -t ed25519 -N "" -C "" -f ssh-ca

Unencrypted keys in PKCS#8 format (starting with -----BEGIN PRIVATE KEY-----), such as those created by ssh-keygen -m PKCS8 or openssl genpkey, are also accepted.

RSA CA keys are not supported. With an RSA CA key configured, every request that uses the CA key (including /api/v4/ca and the KRL endpoints) returns a 500 error, and the reason is logged:

CA key type rsa is not supported, the CA key must be Ed25519 or ECDSA

Identity Provider

This example shows the configuration in Cloudflare Access, however other OIDC IdP's should be generally equivalent:

Basic OIDC Settings

The Redirect URL must match the configured value in the client.

Transfer the IdP settings as follows:

IdP Settings

Copy the Client ID to JWT_AUD on the CA and to client_id in the client, the Issuer to JWT_ISSUER on the CA and to issuer in the client, and the Key endpoint to JWT_JWKS_URL on the CA.

The openid and email scopes are required, with enabling of refresh tokens (the offline_access scope) being optional, but recommended.

JWT_AUD must be set to the audience the IdP issues tokens for this application with (for Cloudflare Access, the application's client ID). Both the access token and the identity token must be issued for this audience, so tokens the IdP issues for other applications are not accepted. If the IdP issues access tokens with a different audience to identity tokens, set JWT_ACCESS_TOKEN_AUD to the audience of the access token. Either value may be a comma separated list. JWT_AUD must be set (see Validation).

When JWT_ACCESS_TOKEN_AUD is not set, both tokens are checked against the same audience, issuer and keys, so the access token adds little beyond the identity token. The CA refuses a request whose access token is the identity token itself, so a single leaked identity token is not enough, but where the IdP can issue access tokens with their own audience, setting JWT_ACCESS_TOKEN_AUD keeps the two tokens apart.

Cloudflare Access issues access tokens for the client's redirect URL (for example http://localhost:3000/auth/callback), so set JWT_ACCESS_TOKEN_AUD to it. This is safe because the issuer of an Access application includes its client ID, so tokens for other applications fail the JWT_ISSUER check. With IdPs where every application shares an issuer, JWT_ACCESS_TOKEN_AUD must be an audience that only tokens for this application are issued for.

Opaque Access Tokens

Some IdPs (such as Google) issue access tokens that are not JWTs, so they cannot be verified by the CA itself. For these IdPs set OIDC_USERINFO_URL to the IdP's OIDC userinfo endpoint (the userinfo_endpoint of its /.well-known/openid-configuration). Every access token is then sent to this endpoint, which returns the claims of the user the token was issued to, instead of being verified as a JWT, and JWT_ACCESS_TOKEN_AUD is not used.

The userinfo endpoint does not say which application an access token was issued to, so with this method an access token is bound to the CA only by its sub claim matching that of the identity token, which is still verified as a JWT issued for JWT_AUD. Each certificate request makes a request to the userinfo endpoint. A token the endpoint does not accept is refused with a 400 error, and if the endpoint cannot be reached or does not respond with a JSON object the request fails with a 500 error and the cause is logged.

The email claim of the access token (or of the userinfo response) must be an email address. It is used as the key ID of user certificates, and with SSH_CERTIFICATE_INCLUDE_SELF its local part (before the @) is added as a principal. If the IdP includes the email_verified claim it must be true, so tokens for an address the IdP has not verified are refused.

As the local part does not include the domain, [email protected] and [email protected] are given the same principal with SSH_CERTIFICATE_INCLUDE_SELF. Only enable it when the IdP only allows users from domains you control.

Rate Limiting

Requests to issue, renew and revoke certificates can be rate limited by adding a rate limit binding named RATE_LIMITER to wrangler.jsonc:

"ratelimits": [
	{
		"name": "RATE_LIMITER",
		"namespace_id": "1001",
		"simple": { "limit": 10, "period": 60 }
	}
]

On Workers, requests are counted by the client IP address in the CF-Connecting-IP header, which Cloudflare sets, and requests over the limit receive a 429 response. Requests to get the CA public key and the KRLs are not limited, as many hosts may fetch them from the same address. When no RATE_LIMITER binding is configured, requests are not limited. If the rate limiter fails, the request is allowed and the error is logged, so certificates can still be issued and revoked.

With createSshCa, for example on Node.js, pass any limiter with the same shape (a limit({ key }) method returning { success }, see CaRateLimiter) as RATE_LIMITER. The rateLimitKey option, which chooses the key requests are counted by, must then be set too, and createSshCa throws an InvalidConfigurationError without it. Choose a value the client cannot set itself: a client can send any CF-Connecting-IP, X-Real-IP or X-Forwarded-For header it likes, so a header can only be trusted when a proxy you control overwrites or appends to it. Behind a single trusted reverse proxy that appends the client address to X-Forwarded-For, use the last entry, as any earlier ones came from the client:

const ca = createSshCa(bindingsFromEnv({
    DB: fromNodeSqlite(new DatabaseSync("/var/lib/ssh-ca/ssh-ca.sqlite")),
    PRIVATE_KEY: secretFromFile("/etc/ssh-ca/ca_key"),
    RATE_LIMITER: myLimiter,
}), {
    // the address appended by the one trusted proxy in front of the CA
    rateLimitKey: (req) => req.headers.get("X-Forwarded-For")?.split(",").at(-1)?.trim() || undefined,
})

When createSshCa runs behind Cloudflare, pass rateLimitKey: cloudflareClientIp (exported by this package) to count requests as the Workers default export does.

Requests for which rateLimitKey returns undefined are not limited, and the first such request is logged as a warning.

Client Addresses

The CA records the client address (the IP address a request came from) of each request that issues or renews a certificate, and of each request a key holder revokes a certificate with. A renewal records the same address as the request address of the new certificate and the revocation address of the certificate it renewed. Revocations by an admin record no address, as the admin is recorded by their email. The addresses are shown on the certificate's page in the admin UI, included as client_address in the log lines for issuing and revoking certificates, and kept for as long as the certificate is (see DB_CERTIFICATE_RETENTION).

On Workers, the address is read from the CF-Connecting-IP header, which Cloudflare sets.

With createSshCa, no address is recorded unless the clientAddress option is set. It is a function from the request to its address, and the same warning applies as for rateLimitKey: a client can send any header it likes, so only read a header that a proxy you control overwrites or appends to. Behind the single trusted reverse proxy from the example above:

const ca = createSshCa(bindings, {
    // the address appended by the one trusted proxy in front of the CA
    clientAddress: (req) => req.headers.get("X-Forwarded-For")?.split(",").at(-1)?.trim() || undefined,
})

When createSshCa runs behind Cloudflare, pass clientAddress: cloudflareClientIp to record addresses as the Workers default export does.

Only IPv4 and IPv6 addresses are recorded. A value that is not one is left out, and the first such value is logged as a warning, but the certificate is still issued, renewed or revoked.

KRL Caching

Generating and signing a KRL reads every revoked certificate from the database, so the KRLs can be cached by adding an optional CACHE binding. On Workers this is a KV namespace:

"kv_namespaces": [
    {
        "binding": "CACHE",
        "id": "<kv namespace id>"
    }
]

On Node.js an in-memory cache can be passed to bindingsFromEnv, or any other cache that implements the CaCache interface:

const ca = createSshCa(bindingsFromEnv({
    DB: fromNodeSqlite(new DatabaseSync("/var/lib/ssh-ca/ssh-ca.sqlite")),
    PRIVATE_KEY: secretFromFile("/etc/ssh-ca/ca_key"),
    CACHE: cacheInMemory(),
}))

A cached KRL is never served after it is out of date. Each certificate type has a revision in the database that is incremented whenever a certificate of that type is revoked (including the previous certificate on a host renewal), or when expired certificates are removed. The cache key includes this revision and the fingerprint of the CA key, so a revocation or a new CA key immediately uses a new key rather than relying on cache entries being deleted or the cache being consistent. Entries are left to expire after 7 days.

A KRL keeps the same version and generation date until its contents change, so a regenerated KRL is identical to the one that was cached. If the cache cannot be read or written the KRL is generated as it is without a cache.

Landing Page

The CA can serve a landing page at /, on Workers and with createSshCa, that shows public information about the CA. It is off unless LANDING_PAGE is set to "true"; while it is off, / answers with 404. Like the admin UI, it is not part of the OpenAPI schema.

The page shows:

  • the CA public key, its SHA256 fingerprint and a link to /api/v4/ca;
  • generic instructions for trusting user certificates on a host (TrustedUserCAKeys), trusting host certificates in SSH clients (@cert-authority), and refusing revoked certificates with the KRLs (RevokedKeys and RevokedHostKeys), with the CA's URL and public key filled in;
  • a pointer to ssh-ca-client for requesting certificates;
  • links to the API documentation (/docs), the user and host KRLs, ssh-ca-client and its releases, and the admin UI.

It shows only what the CA already publishes. In particular it does not show a configuration for ssh-ca-client: the CA cannot know the client ID or the redirect URL for certain (JWT_AUD may be a list, or an audience that is not the client ID), and a page that shows a wrong value is worse than none, so users are told to get the client's settings from their administrator. It never shows the identity provider's settings, certificate lifetimes, the version of the CA or any allowlist.

The link to the admin UI is only shown while the admin UI is turned on (see Admin UI). It is to /admin, or to https://<ADMIN_HOSTNAME>/admin when ADMIN_HOSTNAME is set, as the landing page answers on every host name. Every visitor sees the link, as the CA cannot tell who is an admin outside /admin.

The page has no client-side JavaScript or forms and loads only its own stylesheet, and is sent with the same security headers as the admin UI, except that its Content-Security-Policy allows no scripts. The stylesheet is served at /style-<hash>.css, named after its content as described in Stylesheet and script, and as the page is public it is sent with Cache-Control: public, max-age=31536000, immutable.

The CA's URL in the instructions is the origin the page was requested on. On Workers this is always the public URL. On Node.js, behind a reverse proxy that terminates TLS, it is only the public URL if the server builds the Request from the public URL, otherwise the instructions show http:// and the internal host name. Links on the page are relative, so they work either way.

Admin UI

The CA can serve an admin UI under /admin, on Workers and with createSshCa, where admins can see every certificate the CA has issued and revoke any that are still valid. It is not part of the OpenAPI schema.

Pages

| Path | Page | |---|---| | /admin | Redirects to /admin/user/certificates | | /admin/user/certificates, /admin/host/certificates | The user or host certificates, newest first, 50 at a time | | /admin/user/certificates/<serial>, /admin/host/certificates/<serial> | Everything recorded about one certificate, and a form to revoke it while it is valid | | POST /admin/user/certificates/<serial>/revoke, POST /admin/host/certificates/<serial>/revoke | Revokes the certificate, sent by the revoke form | | /admin/user/certificates/revoke, /admin/host/certificates/revoke | Confirms revoking the valid certificates that match a list's filters, see Revoking several certificates | | POST /admin/user/certificates/revoke, POST /admin/host/certificates/revoke | Revokes the certificates ticked on that page |

The lists are filtered by query parameters, which the filter form on the page sets, so a filtered view can be bookmarked:

| Parameter | Filter | |---|---| | status | valid (the default), expired, revoked or all. A revoked certificate is revoked even once it has expired, and expired only lists certificates that were not revoked | | principal | Certificates with this principal, matched exactly and case-sensitively against each principal, so root does not find rootless | | key_id | Certificates whose key ID contains this, case-insensitively, so alice finds [email protected]. % and _ are matched literally | | serial | The certificate with this serial, in decimal | | before | Set by the "Next page" link, which keeps the other filters. Pages follow on from the last certificate shown, so they neither skip nor repeat certificates issued while paging |

An invalid parameter gets a 400 page. A serial that does not exist, or is for the other certificate type, gets a 404 page.

The detail page shows the serial, type, key ID, principals, extensions, validity, status, the SHA256 fingerprint of the certificate's public key, who requested it and the client address it was requested from. For a revoked certificate it also shows when, by whom and why it was revoked, and for a revocation by the key holder the client address it was revoked from. Values that were not recorded, such as the requester of a certificate issued before they were recorded, or the reason for a revocation by the key holder, are shown as "unknown".

Times

Times are recorded in UTC, and the server always renders them in UTC, such as 2026-11-04 21:10 UTC, to the minute in the lists and to the second on the detail page.

The admin UI's script then shows them in the browser's time zone, in the same layout with the UTC offset of each time in place of UTC, such as 2026-11-05 05:10 UTC+8, UTC+5:30, UTC-3:30 or UTC+0. Each time has its own offset, so the two ends of a certificate's validity can show different offsets either side of a change to or from daylight saving time. Hovering over a time shows it the other way.

The header has a Times: Local | UTC switch to show times in UTC instead. The choice is remembered by the browser (in localStorage, under admin-time-zone), and times are shown in local time until a choice is made, or when the browser does not allow it to be remembered.

The script only changes how times are displayed. Without it, times are shown in UTC, the switch is hidden, and everything else works the same. See ADR-0004.

Revoking certificates

The detail page of a valid certificate has a form to revoke it. The admin must give a reason, of 1 to 500 characters once surrounding whitespace is trimmed, and tick a box to confirm. A revoked certificate is added to the KRL for its type, just as when its key holder revokes it, and the detail page then shows when, by whom and why it was revoked. The admin's email is recorded exactly as the proxy's JWT gives it, and the revocation is logged at info level with the serial, type, email and reason.

Revocations are permanent. Nobody can undo one, including an admin. Access is restored by issuing a new certificate.

| Response | When | |---|---| | 303 to the detail page | The certificate was revoked | | 422 with the form again | The reason is missing, empty or too long, or the box was not ticked. Nothing is revoked | | 422 | The certificate has expired. Expired certificates are no longer trusted, so they are read-only and have no revoke form. A key holder can still revoke one through the API | | 409 | The certificate was already revoked | | 404 | There is no certificate of that type with the serial |

Revocations are POST requests, so they must come from the admin UI itself and are rate limited, as described in the security model. Whether a certificate has expired or was already revoked is checked again as it is revoked, so concurrent revocations revoke it once, keeping the first, and a revocation cannot race with the certificate expiring.

Revoking several certificates

To revoke every valid certificate of a person, such as when they leave, filter the user certificates by their email as the key ID (user certificates are issued with the requester's email as their key ID) or by their principal. A list filtered to Valid certificates by principal or key ID has a Revoke these certificates… button, which opens a page listing the matching certificates, newest first, each with a ticked box. The key ID filter matches any key ID that contains it, so [email protected] also finds [email protected]: check the list, and untick any certificate that should not be revoked. A list that is unfiltered, filtered by serial alone, or shows other statuses has no button, and its filters are refused by the page with a 400.

At most 50 certificates are listed. When more match, the page says so; revoke those shown, then open the page again for the rest.

Only the ticked certificates are sent, with one reason for them all and the confirmation box, so what is revoked is what the admin saw, not whatever matches the filters by then. Each certificate is recorded and logged as if it had been revoked on its own, with the same reason. They are revoked in one transaction, and the KRL revision for the type is incremented once.

| Response | When | |---|---| | 200 with what happened to each certificate | The request was valid. Each certificate is shown as revoked, or as already revoked, expired or not found when it changed since the page was shown, and the others are still revoked | | 422 with the page again | The reason is missing, empty or too long, the box was not ticked, no certificates were ticked, a serial is not valid, or more than 50 were sent. The page lists only the certificates that were sent, and nothing is revoked |

Reloading the result page may send the form again, which revokes nothing more and shows each certificate as already revoked. See ADR-0005.

Security model

The CA has no login of its own for admins. Instead an identity-aware proxy, such as Cloudflare Access, sits in front of /admin, signs in the admin, and adds a signed JWT to every request it passes on. The CA verifies that JWT on every request against the proxy's JWKS, issuer and audience, and decides who is an admin from an allowlist of emails or roles. See ADR-0002 for why.

  • A request without a JWT, or with one that does not verify, gets 401.
  • A request with a valid JWT that has no email claim, or whose email and roles are not in the allowlist, gets 403.
  • Requests that change state (anything other than GET, HEAD or OPTIONS) must come from the admin UI itself: their Origin must be the admin UI's origin (https://<ADMIN_HOSTNAME> when it is set) and their Sec-Fetch-Site header must be same-origin, or they get 403. The proxy keeps the admin's session in a cookie, so does not protect against cross-site requests itself. A refused request is logged at warning level with the Origin and Sec-Fetch-Site it had and the origin that was expected.
  • When a RATE_LIMITER is configured, requests that change state are rate limited with the key admin:<email>, using the verified email, so they never share a key with the client API. The rateLimitKey option is not used for them. GET requests are not limited.
  • Every response has a strict Content-Security-Policy, Cache-Control: no-store, Referrer-Policy: same-origin and X-Content-Type-Options: nosniff. The policy allows scripts and styles from the admin UI itself only, and no inline scripts. The only script is the one that shows times in the browser's time zone, and pages work without it. The stylesheet and script are the only responses that may be cached, see Stylesheet and script. Other sites are never sent a referrer. no-referrer is not used because browsers then send Origin: null on the admin UI's own forms, which would be refused.
  • Every request is logged at info level with the admin's email, the method, the path and the response status. The JWT is never logged.

Make sure the proxy protects every hostname the CA answers on, or set ADMIN_HOSTNAME to the one it protects. On Workers this includes the workers.dev hostname unless workers_dev is false.

When ADMIN_HOSTNAME is not set, the admin UI's origin is the origin of the URL the CA receives. On Node.js behind a reverse proxy that terminates TLS, that is usually http:// and an internal host name, while the browser sends Origin: https://<public host>, so every revocation gets 403. Set ADMIN_HOSTNAME to the public host name in that case. The origin it gives is https://<ADMIN_HOSTNAME> on the default port, so the admin UI must be reached on port 443.

Stylesheet and script

The admin UI's stylesheet and script are served at /admin/style-<hash>.css and /admin/time-<hash>.js, where <hash> is the first 8 hex characters of the SHA-256 of the file's content. The name changes whenever the content does, so browsers can keep them for a year (Cache-Control: private, max-age=31536000, immutable) and are never given an old copy after the CA is updated. They are private as they are only served to admins, behind the proxy.

Only the current name of each file is served. Any other name, such as /admin/style.css or the name of an earlier version, gets a 404 that is not cached. Pages are never cached, so they always link the current names.

Settings

| Setting | Meaning | |---|---| | ADMIN_JWT_HEADER | The request header holding the proxy's JWT | | ADMIN_JWKS_URL | The https URL of the proxy's JWKS | | ADMIN_JWT_ISSUER | The issuer (iss) the JWT must have | | ADMIN_JWT_AUD | The audience (aud) the JWT must be issued for, or a comma separated list of them | | ADMIN_JWT_ALGORITHMS | Optional. A comma separated list of the algorithms the JWT may be signed with, from RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, EdDSA and Ed25519. RS256 when unset | | ADMIN_ALLOWED_EMAILS | A comma separated list of the emails of admins, compared case-insensitively with the JWT's email claim | | ADMIN_ALLOWED_ROLES | A comma separated list of roles that make someone an admin, compared exactly | | ADMIN_JWT_ROLES_CLAIM | The claim of the JWT holding the roles, as a string or an array of strings. A claim of any other type is ignored with a warning | | ADMIN_HOSTNAME | Optional. The only host name the admin UI answers on, such as ssh-ca.example.com. Every other host name gets 404 for /admin |

The admin UI is turned on when ADMIN_JWT_HEADER, ADMIN_JWKS_URL, ADMIN_JWT_ISSUER and ADMIN_JWT_AUD are set, along with ADMIN_ALLOWED_EMAILS or both ADMIN_ALLOWED_ROLES and ADMIN_JWT_ROLES_CLAIM. Roles are only used when both are set.

  • When none of the ADMIN_* settings are set, the admin UI is off and every /admin path gets 404.
  • When only some are set, the admin UI is also off, and a warning naming the missing settings is logged once. The rest of the CA keeps working.
  • A setting that is set but not valid, such as an http JWKS URL or an audience list with an empty entry, makes the whole configuration invalid, as described under Validation.

An empty string counts as not set. List entries are trimmed, so "[email protected], [email protected]" is accepted, but an empty entry is refused.

Cloudflare Access example

Create a self-hosted Access application for ssh-ca.example.com/admin with a policy that allows your admins, then set:

"vars": {
	"ADMIN_JWT_HEADER": "Cf-Access-Jwt-Assertion",
	"ADMIN_JWKS_URL": "https://<team>.cloudflareaccess.com/cdn-cgi/access/certs",
	"ADMIN_JWT_ISSUER": "https://<team>.cloudflareaccess.com",
	"ADMIN_JWT_AUD": "<the Access application's AUD tag>",
	"ADMIN_ALLOWED_EMAILS": "[email protected]",
	"ADMIN_HOSTNAME": "ssh-ca.example.com"
}

<team> is your Zero Trust team name. The AUD tag is shown in the Access application's settings.

Client

Please visit the ssh-ca-client repository for further information:

https://github.com/andrewheberle/ssh-ca-client

SSH Endpoints

Host Configuration

For systems to allow SSH login using certificates the following configuration changes must be made:

PubkeyAuthentication yes
TrustedUserCAKeys /etc/ssh/ca.pub
AuthorizedPrincipalsFile /etc/ssh/principals.d/%u
# Uncomment the following lines to enable host certificates
# HostCertificate /etc/ssh/ssh_host_rsa_key-cert.pub
# HostCertificate /etc/ssh/ssh_host_ecdsa_key-cert.pub
# HostCertificate /etc/ssh/ssh_host_ed25519_key-cert.pub

The contents of /etc/ssh/ca.pub is the public key of the SSH CA, which can be retrieved as follows:

curl https://ssh-ca.example.com/api/v4/ca | sudo tee /etc/ssh/ca.pub

The /etc/ssh/principals.d directory should contain a file corresponding to a local user that contains a list of principals that should be allowed login.

For example, with SSH_CERTIFICATE_PRINCIPALS set to ssh-admin (as in the example wrangler.jsonc), the following file named /etc/ssh/principals.d/admin would allow login as the SSH user admin for the bearer of an issued (and valid) certificate:

ssh-admin

To refuse revoked user certificates, sshd also needs the user KRL. ssh-ca-client downloads it from /api/v4/user/krl, checks its signature with the CA public key and writes it where OpenSSH can read it:

sudo ssh-ca-client-cli krl --out /etc/ssh/revocation_list

Then add RevokedKeys /etc/ssh/revocation_list to sshd_config. Write the KRL before setting RevokedKeys, as sshd refuses all public key authentication when it cannot read the file, and refresh it regularly, as certificates can be revoked at any time.

Client Configuration

In order for a client to trust a certificate presented by a host the following configuration must be added to /etc/ssh/ssh_known_hosts (system wide) or ~/.ssh/known_hosts (user specific):

@cert-authority *.example.com ecdsa-sha2-nistp256 ....

The format of the above file is documented in the ssh(1) man page however the important item of note is that the *.example.com above tells ssh that the CA public key (ie ecdsa-sha2-nistp256 ....) is trusted for all hosts, that match *.example.com.

This will need adjusting depending on your environment along with the actual SSH CA public key which can be retrieved as follows:

curl https://ssh-ca.example.com/api/v4/ca

Once the above configuration is completed and host certificates are in place clients will not require "trust on first use" (TOFU) as the certificate will be verified as being signed by the configured SSH CA.

SSH clients refuse revoked host certificates with the host KRL: run ssh-ca-client-cli krl --host --out ~/.ssh/revocation_list and add RevokedHostKeys ~/.ssh/revocation_list to ~/.ssh/config.