go-pki-cmp

module
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Oct 12, 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, genm and nested with their responses. General messages carry the RFC 9483 support requests for CA certificates, a root CA update, a certificate request template and CRL updates. Key recovery, cross-certification, proof-of-possession challenges and announcements 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, revokes and sends support messages against the mock server. OpenSSL as a client revokes at the server and sends support messages to it.
  • 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.

Package structure

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

Compatibility

  • Post-quantum keys: ML-DSA-44, ML-DSA-65, ML-DSA-87 and composite ML-DSA support enrollment and CMP signatures. Older Dilithium encodings are not supported.
  • RFC 4210 peers are supported by default. SHA-1 signatures and additional device compatibility options are opt-in. Server options describe these exceptions and the stricter WithStrictProfileValidation checks.

For manual certificate confirmation, use pkicmp.NewCertStatus. Composite certificate chains have additional verification limits and client trust requirements.

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)

Root CA update (RFC 9483 §4.3.2):

update, err := c.GetRootCAUpdate(context.Background(), currentRoot, creds)
switch {
case errors.Is(err, client.ErrInfoTypeNotSupported):
	// The CA does not offer root updates. RFC 4210 CAs often ignore the request.
case err != nil:
	return err
case update != nil:
	// update.NewWithNew is the new root. The client has checked that currentRoot
	// signed update.NewWithOld.
}

GetCACertificates, GetCertReqTemplate, GetCRLUpdate and GetCurrentCRL follow the same pattern.

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

Support messages are answered by optional interfaces: server.CACertificatesProvider, server.RootCAUpdateProvider, server.CertReqTemplateProvider and server.CRLProvider. The server lists a requested type without a provider as unsupported.

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 Tero Saarni (@tsaarni). Its package layout, ASN.1 types and client and server design come from that project.

Early hardening changes were submitted in tsaarni/go-pkicmp#3. This fork is maintained separately. See the release notes for changes and NOTICE for attribution.

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