go-pki-cmp

module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: Apache-2.0

README

go-pki-cmp

GitHub Release Go Reference License Tests Integration Supply chain OpenSSF Scorecard

Go library for the Certificate Management Protocol (CMP). Its core encodes, parses, protects and verifies CMP and CRMF messages. On top of it, the client package enrolls, updates and revokes certificates and the server package serves the same operations to CMP clients as an http.Handler in front of a CA. cmp-issuer, a cert-manager external issuer, is built on this library. The library implements:

  • RFC 9810 (obsoletes RFC 4210 and RFC 9480): Certificate Management Protocol (CMP), CMPv2 and CMPv3
  • RFC 9483: Lightweight CMP Profile
  • RFC 4211: Certificate Request Message Format (CRMF)
  • RFC 9811 (obsoletes RFC 6712): HTTP Transfer for the Certificate Management Protocol (CMP)

Supported messages are ir, cr, kur, p10cr, rr, certConf, pollReq and nested with their responses. Key recovery, cross-certification, proof-of-possession challenges, announcements and general messages (genm) are not implemented.

Interoperability and testing

CI runs the library against independent CMP implementations:

  • EJBCA: the client enrolls and updates certificates.
  • OpenSSL: the client enrolls, updates and revokes against the mock server. OpenSSL as a client revokes at the server.
  • Nokia NCM: the client enrolls, re-enrolls, updates and revokes certificates against a hosted instance on every push to dev and main and once a week.
  • Siemens CMP test suite: runs its conformance tests against the server.

Local tests also run the Insta Certifier 10 cmpclient and the Nokia ssh-cmpclient against the server. Both clients are proprietary, so CI does not run them. See test/integration/certifier.

Install

go get github.com/misiektoja/go-pki-cmp

Requires Go 1.27.2 or newer. Releases up to v0.3.2 use the module path github.com/misiektoja/go-pkicmp-ng.

  • ML-DSA-44, ML-DSA-65 and ML-DSA-87 cover certificate keys, CRMF proof of possession and message signatures. Under CMPv3 the client confirms an ML-DSA-signed certificate with an explicit SHA-512 hash. Build a manual confirmation with pkicmp.NewCertStatus, because pkicmp.CertHash cannot carry that hash identifier. Older Dilithium encodings are not supported.
  • Composite ML-DSA keys from go-composite-mldsa sign CMP messages and issued certificates and can be the key a device enrolls. ir, cr, kur and p10cr carry a composite key with a composite proof of possession, and rr revokes its certificate. The client confirms a certificate signed by a composite CA with the hash the composite algorithm uses and an explicit hash identifier. A composite issuer is trusted only when its certificate arrives in extraCerts or caPubs and no certificate in the path has name constraints.
  • RFC 4210 peers are supported. The server accepts their requests without a transactionID or with a short senderNonce. server.WithStrictProfileValidation rejects them as RFC 9483 requires. SHA-1 is off by default. pkicmp.WithPBMAlgorithms(crypto.SHA1, crypto.SHA1) selects the RFC 4210 PasswordBasedMac profile and WithSHA1Signatures in client and server accepts SHA-1 signatures.
  • Device compatibility options in server: WithRawSubject issues the subject exactly as requested, WithOptionalCertConfRecipNonce accepts a certConf without recipNonce and WithMACIterationLimits sets the accepted MAC iteration counts. client.WithMACIterationLimits sets the range for responses.
  • Request rule options in server accept requests that break an RFC 9483 rule: WithPoposkInputVariants for the proof of possession of the Insta Certifier 10 cmpclient, WithOptionalSubject for a template without a subject field that names its identity in subjectAltName and WithSignatureProtectionPOP for a key update that keeps its key and is signed with it. WithOptionalRevocationReason, WithOptionalRevocationIssuer and WithMACRevocation accept revocation requests without a reason code, without an issuer or protected with a shared secret. WithStrictProfileValidation turns all of these off, as well as WithOptionalCertConfRecipNonce.

Package structure

  • pkicmp: CMP and CRMF ASN.1 types with parsing, serialization and MAC or signature protection.
  • client: IR, CR, KUR, P10CR and RR flows with polling, response verification and certificate confirmation.
  • server: an http.Handler that authenticates clients, tracks transactions, supports deferred issuance and revocation, accepts requests a registration authority forwards in nested messages and applies policy middleware such as the lightweight profile.

Usage

Client

Initialization Request (IR) with a shared secret:

key, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
creds, _ := pkicmp.NewMACCredentials([]byte("my-shared-secret"))

// A bootstrapping device has no trust anchor yet. Add client.WithTrustedCAs when
// one is available, so that a signed rejection can be verified.
c := client.NewClient("http://localhost:8080/cmp")
result, err := c.SendIR(context.Background(), key, creds,
	client.WithSenderKID([]byte("my-device")),
	client.WithTemplateSubject(pkix.Name{CommonName: "my-device"}),
)

Key Update Request (KUR) with signature protection:

creds, _ := pkicmp.NewSignatureCredentials(existingKey, existingCert)
c := client.NewClient("http://localhost:8080/cmp", client.WithTrustedCAs(trustedCAs))

// SignatureCredentials lets SendKUR name existingCert in the CRMF oldCertID control.
// The sender and template subject repeat existingCert's subject with its original encoding.
result, err := c.SendKUR(context.Background(), newKey, creds)

Revocation Request (RR):

// RFC 9483 expects the request to be signed with the certificate being revoked.
creds, _ := pkicmp.NewSignatureCredentials(certKey, cert)

// Some CAs sign the response without attaching their certificate. WithServerCerts
// supplies it, and it must still chain to trustedCAs and match the response sender.
c := client.NewClient("http://localhost:8080/cmp",
	client.WithTrustedCAs(trustedCAs),
	client.WithServerCerts([]*x509.Certificate{issuingCA}),
)

// A nil error means the CA revoked the certificate. A rejection such as
// certRevoked is returned as *pkicmp.PKIStatusError.
err := c.SendRR(context.Background(), cert, pkicmp.CRLReasonKeyCompromise, creds)
Server

Implement the server.CA interface and the credential lookups:

type MyCA struct{}

func (ca *MyCA) IssueCertificate(ctx, reqType, template, sender) {
	// Called on enrollment requests (IR/CR/KUR). Signs template with CA private key.
}
func (ca *MyCA) LookupSecret(sender, senderKID) {
	// Called to verify MAC-protected requests. Finds pre-shared secret by DN or key ID.
}
func (ca *MyCA) LookupCertificate(issuer, subject, senderKID) {
	// Called to verify signature-protected requests. Finds existing cert by DN or Subject Key ID.
}
func (ca *MyCA) RevokeCertificate(ctx, req, sender) {
	// Optional. Called on revocation requests (RR) signed with the certificate being revoked.
	// Implement server.RevocationAuthorizer to also accept requests from other signers.
}

Then serve it:

myCA := &MyCA{}
srv := server.NewCAServer(myCA,
	server.LightweightPolicy(),
	server.WithSigner(caKey, caCert),
	server.WithSecretLookup(myCA),
	server.WithCertificateLookup(myCA),
	// A present messageTime outside this local tolerance is rejected as badTime.
	server.WithMessageTimeTolerance(5*time.Minute),
)
// Reports a misconfiguration such as a signer key that does not match its cert.
if err := srv.Err(); err != nil {
	log.Fatal(err)
}

http.Handle("/cmp", srv)
http.ListenAndServe(":8080", nil)

Runnable examples

examples holds a mock CA server and a client that runs a MAC-protected IR, a signature-protected KUR and an RR against it. Run them in two terminals:

go run ./examples/mockserver/cmd
go run ./examples/mockclient/cmd

Credits and relationship to go-pkicmp

This project began as a fork of tsaarni/go-pkicmp by @tsaarni. Its package layout, ASN.1 types and client and server design are still the base of this library and made everything here possible. The credit for that foundation belongs to its author.

Development continued here because the changes are security relevant and needed a faster cycle than upstream review allowed. The early hardening work is offered upstream in tsaarni/go-pkicmp#3, which is still open. This fork adds:

  • Stricter verification. Signatures are bound to the sender they claim. Issued certificates must certify the requested key and carry the request's certReqId. PBKDF2 parameters and poll intervals from peers are bounded.
  • Post-quantum signatures: ML-DSA with SHA-512 certificate confirmation plus composite ML-DSA keys for both CAs and enrolling devices.
  • Revocation in the client and the server, plus nested requests from a registration authority.
  • Certificate confirmation checks on both sides, with SnapshotTransactions and RestoreTransactions to keep server transactions across a restart.
  • Support for RFC 4210 peers, with the SHA-1 options off by default.
  • Server hardening: required proof of possession, an optional messageTime tolerance, no handler error text on the wire, MAC-protected errors for shared-secret clients and Server.Err for a misconfigured signer.
  • Interoperability fixes for EJBCA, OpenSSL, Nokia NCM and vendor CMP clients. Key update names the replaced certificate in oldCertID, enrollment works with Ed25519-signing CAs and client.WithServerCerts verifies responses from CAs that do not attach their certificate.

The release notes list every change.

Contributing and support

The Contributing Guide describes the development checks, the integration tests and the release process. SUPPORT.md says where to ask a question or report a bug. Report vulnerabilities privately as SECURITY.md describes.

License

Apache License 2.0. See LICENSE and NOTICE. DEPENDENCIES.md lists third-party dependencies and their licenses.

Directories

Path Synopsis
Package client provides a Certificate Management Protocol (CMP) client for requesting X.509 certificates from a CA over HTTP.
Package client provides a Certificate Management Protocol (CMP) client for requesting X.509 certificates from a CA over HTTP.
examples
mockclient
Package mockclient provides reusable enrollment and revocation helpers built on top of the client and pkicmp packages.
Package mockclient provides reusable enrollment and revocation helpers built on top of the client and pkicmp packages.
mockclient/cmd command
Command mockclient is a minimal CMP client for testing.
Command mockclient is a minimal CMP client for testing.
mockserver
Package mockserver demonstrates how to implement the server.CA interface to build a CMP certificate authority server.
Package mockserver demonstrates how to implement the server.CA interface to build a CMP certificate authority server.
mockserver/cmd command
Command mockserver is a minimal CMP server for testing.
Command mockserver is a minimal CMP server for testing.
internal
certpath
Package certpath verifies certification paths that contain composite ML-DSA signatures, which crypto/x509 cannot check.
Package certpath verifies certification paths that contain composite ML-DSA signatures, which crypto/x509 cannot check.
Package pkicmp implements the Certificate Management Protocol (CMP) as defined in RFC 9810, with CRMF support per RFC 4211.
Package pkicmp implements the Certificate Management Protocol (CMP) as defined in RFC 9810, with CRMF support per RFC 4211.
Package server implements a CMP server framework that can be embedded in a CA to add CMP support.
Package server implements a CMP server framework that can be embedded in a CA to add CMP support.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL