xpki

xpki

Go library and CLI tools for building PKI: hardware or cloud backed keys (PKCS#11, AWS KMS, GCP KMS), certificate signing requests, a certificate authority with policy profiles, OCSP and CRL signing, certificate bundling and verification, and JWT/DPoP token issuance and validation.

The module is github.com/effective-security/xpki and targets Go 1.27.

Packages

See Documentation/codemap.md for entry points and invariants per package, FINDINGS.md for known defects, and ROADMAP.md for planned work.

Install

go get github.com/effective-security/xpki
go install github.com/effective-security/xpki/cmd/hsm-tool@latest
go install github.com/effective-security/xpki/cmd/xpki-tool@latest

Configuration

Crypto provider

A provider is described by a small JSON or YAML token config. The Manufacturer selects the registered loader; the remaining fields are provider specific. Import the provider package for its side-effect registration.

SoftHSM / PKCS#11 (crypto11, manufacturer SoftHSM):

{
  "Manufacturer": "SoftHSM",
  "Path": "/usr/lib/softhsm/libsofthsm2.so",
  "TokenLabel": "xpki_unittest",
  "Pin": "file:/home/me/softhsm2/xpki_pin.txt"
}

AWS KMS (awskmscrypto, manufacturer AWSKMS):

{
  "Manufacturer": "AWSKMS",
  "Model": "14555",
  "Attributes": "Endpoint=http://localhost:14555,Region=us-west-2"
}

In-memory (inmemcrypto, manufacturer inmem):

{
  "Manufacturer": "inmem",
  "TokenLabel": "inmem_unittest",
  "Pin": "file:inmem_pin.txt"
}

Pin accepts a literal value, file:<path>, or an environment reference, see cryptoprov.TokenConfig in the code map.

Private keys that live in a provider are referenced by a PKCS#11 style URI and can be used anywhere a PEM key is accepted (issuer config, JWT config):

pkcs11:manufacturer=AWSKMS;id=c98c624e-3609-4d8f-a615-9031b3a811d4;serial=arn:aws:kms:eu-west-2:111122223333:key/c98c624e-3609-4d8f-a615-9031b3a811d4;type=private

Certificate Authority

authority:
  issuers:
    - label: TrustyCA
      type: trusty
      cert: /tmp/xpki/certs/l2_ca.pem
      key: /tmp/xpki/certs/l2_ca.key # PEM file or pkcs11: URI
      ca_bundle: /tmp/xpki/certs/l1_ca.pem
      root_bundle: /tmp/xpki/certs/root_ca.pem
      aia:
        issuer_url: http://localhost:7880/v1/cert/${ISSUER_ID}
        crl_url: http://localhost:7880/v1/crl/${ISSUER_ID}
        ocsp_url: http://localhost:7880/v1/ocsp

profiles:
  server:
    expiry: 168h
    backdate: 30m
    usages: [signing, key encipherment, server auth]
    allowed_extensions:
      - 1.3.6.1.5.5.7.1.1 # AIA
      - 2.5.29.17 # SAN

A profile controls validity, key usages, allowed extensions, name and SAN policies, and path length. Requester CSR fields not permitted by the profile are dropped or rejected at Issuer.Sign.

allowed_extensions governs extensions from two sources. For the trusted SignRequest.Extensions an empty list allows all. For the untrusted CSR an empty list allows none, and key usage, EKU, SAN, basic constraints, key identifiers and OCSP no-check are never taken from a CSR; the SAN is rebuilt from the allowed_fields names. An allow-listed CSR AIA or CRL DP is kept only when the issuer does not generate one. Explicit NotBefore/NotAfter must fit the profile: lifetime no longer than expiry, NotBefore no earlier than now minus backdate. A populated allowed_profiles on an issuer limits it to the listed profiles, issuer-specific and issuer_label: "*" alike.

JWT provider

issuer: trusty-dev.com
token_expiry: 12h
kid: 0
keys:
  - id: 0
    seed: <symmetric seed>

or, for an asymmetric signer:

issuer: trusty-dev.com
private_key: pkcs11:manufacturer=AWSKMS;id=...;type=private

Token verification against an OpenID Connect issuer:

issuer: https://accounts.google.com
jwks_uri: https://www.googleapis.com/oauth2/v3/certs

Usage

Load providers and sign with an HSM key

import (
    "github.com/effective-security/xpki/cryptoprov"
    _ "github.com/effective-security/xpki/crypto11"                 // registers "SoftHSM"
    _ "github.com/effective-security/xpki/cryptoprov/awskmscrypto"  // registers "AWSKMS"
)

crypto, err := cryptoprov.Load("/etc/xpki/softhsm.json", []string{"/etc/xpki/awskms.json"})
if err != nil {
    return err
}
// Load a key by PEM file or by pkcs11: URI, whichever the file holds.
signer, err := crypto.NewSignerFromFromFile("/etc/xpki/ca.key")

Create a key and CSR

prov := csr.NewProvider(crypto.Default())
req := &csr.CertificateRequest{
    CommonName: "localhost",
    SAN:        []string{"localhost", "127.0.0.1", "spiffe://trusty/all"},
    KeyRequest: prov.NewKeyRequest("server", "ECDSA", 256, csr.SigningKey),
    Names:      []csr.X509Name{{Country: "US", Organization: "trusty.com"}},
}
csrPEM, priv, keyID, err := prov.GenerateKeyAndRequest(req)

Run a CA

cfg, err := authority.LoadConfig("/etc/xpki/ca-config.yaml")
if err != nil {
    return err
}
ca, err := authority.NewAuthority(cfg, crypto)
if err != nil {
    return err
}
issuer, err := ca.GetIssuerByProfile("server")
if err != nil {
    return err
}
cert, certPEM, err := issuer.Sign(csr.SignRequest{
    Request: string(csrPEM),
    Profile: "server",
    SAN:     []string{"localhost"},
})

Issuer.SignOCSP and the CRL helpers produce signed OCSP responses and CRLs for the issuer's certificates.

Verify a certificate chain

bundle, status, err := certutil.LoadAndVerifyBundleFromPEM(
    "server.pem", "intermediates.pem", "roots.pem",
    certutil.WithKeyUsages(x509.ExtKeyUsageServerAuth),
)

Without a root file the bundler only checks that each certificate signs the previous one (Force). To verify against the platform trust store, pass certutil.WithSystemRoots(true); system roots are never trusted implicitly.

Issue and verify JWTs

prov, err := jwt.LoadProvider("/etc/xpki/jwtprov.yaml", crypto)
if err != nil {
    return err
}
claims := jwt.CreateClaims("jti-1", "subject", prov.Issuer(), []string{"api"}, time.Hour, nil)
token, err := prov.Sign(ctx, claims)

parsed, err := prov.ParseToken(ctx, token, &jwt.VerifyConfig{
    ExpectedIssuer:   prov.Issuer(),
    ExpectedAudience: []string{"api"},
})

Tokens from a third-party OIDC issuer are verified with jwt.NewParser(cfg), which loads keys from a static JWKS or a jwks_uri. A key is chosen by kid and the token algorithm; a token without kid needs exactly one eligible signing key. Remote sets refetch when no cached key fits, at most once per 10s, with a 10s fetch timeout and a 1 MiB response limit (jwt.NewRemoteKeySet options change these).

CLI tools

• hsm-tool: list, inspect, generate and delete keys in an HSM or KMS; create CSRs and sign certificates with those keys.
• xpki-tool: inspect and validate certificates, CSRs, CRLs and OCSP responses.

hsm-tool --cfg /tmp/xpki/softhsm_unittest.json hsm list
xpki-tool cert info server.pem

Development

Requirements: Go 1.27, a C compiler for PKCS#11/cgo, SoftHSM2 (softhsm2-util and its module), and Docker for the local AWS KMS emulator. Generating a new test PIN also requires openssl.

make hsmconfig builds bin/hsm-tool, initializes the test token using softhsm2-util, then verifies the generated configuration and PIN with bin/hsm-tool --cfg /tmp/xpki/softhsm_unittest.json hsm list. OpenSC (pkcs11-tool) is optional: it is needed only when invoking scripts/config-softhsm.sh directly with --list-slots or --list-object.

make tools            # golangci-lint, cov-report, govulncheck, gomarkdoc (pinned versions)
make hsmconfig        # create the SoftHSM token and /tmp/xpki/softhsm_unittest.json
make start-local-kms  # start two local-kms containers on :14555 and :14556
make test             # full test suite (needs the two steps above)
make test RACE=true   # under the race detector
make covtest coverage # coverage report
make lint             # fmt-check, go vet, govulncheck, golangci-lint (read-only)
make build            # builds bin/hsm-tool and bin/xpki-tool
make docs             # regenerate Documentation/*.md (gomarkdoc) and CLI help dumps
make all              # clean, tools, generate, hsmconfig, start-local-kms, covtest

The AWS emulator does not check credentials, but the SDK requires them:

export AWS_ACCESS_KEY_ID=notusedbyemulator
export AWS_SECRET_ACCESS_KEY=notusedbyemulator
export AWS_DEFAULT_REGION=us-west-2

CI (.github/workflows/unittest.yml) runs make lint and make covtest with SoftHSM and local-kms and requires more than 90% total coverage; documentation-only pull requests skip the job. Merges to main are tagged from .VERSION plus the commit count.

Contributing

Read AGENTS.md for coding, error handling, testing and documentation rules, and keep Documentation/codemap.md current in the same change as the code.

Generated API reference (make docs, gomarkdoc, do not edit): Documentation/api

License

See LICENSE.