go-pki-cmp

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.

• Install
• Scope
• Getting started
• Interoperability
• Documentation
• Credits
• Support and contributing
• License

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

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

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.

Post-quantum keys: ML-DSA-44, ML-DSA-65, ML-DSA-87, the twelve SLH-DSA parameter sets and composite ML-DSA keys can enroll and sign CMP messages. ML-KEM-768 and ML-KEM-1024 keys, which cannot sign, prove possession by decryption.

RFC 4210 peers work with the defaults. Options accept deployed clients that break RFC 9483 rules.

Key recovery, central key generation, cross-certification and announcements are not implemented.

The support matrix and known limitations give the details.

Enroll a certificate with a shared secret:

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

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"}),
)

Serve CMP in front of your CA, which implements server.CA and the credential lookups:

srv := server.NewCAServer(myCA,
	server.LightweightPolicy(),
	server.WithSigner(caKey, caCert),
	server.WithSecretLookup(myCA),
	server.WithCertificateLookup(myCA),
)
if err := srv.Err(); err != nil {
	log.Fatal(err)
}
http.Handle("/cmp", srv)

examples holds a mock CA and a client that enrolls, updates and revokes a certificate against it. Run them in two terminals:

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

Getting started walks through both programs and names what to replace before production.

CI runs the library against EJBCA, OpenSSL 3.5 and 4.0 in both directions, a hosted Nokia NCM instance and the Siemens CMP test suite. Local tests also run the Insta Certifier 10 cmpclient and the Insta Certifier 7 ssh-cmpclient against the server. Both clients are proprietary, so CI does not run them.

Tested implementations lists the scenarios and the server options each client needs.

Full documentation is at misiektoja.github.io/go-pki-cmp.

• Getting started
• Support matrix
• Architecture
• Client: Enrollment, Response verification, Revocation and Keys that cannot sign
• Server: Implementing a CA, Authentication, Policy and client compatibility and Transactions and recovery
• Client options and Server options
• Troubleshooting
• Security model

The package documentation on pkg.go.dev describes every exported type and option. RELEASE_NOTES.md records the changes in each release.

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. NOTICE records the attribution.

SUPPORT.md says where to ask a question or report a bug. Report vulnerabilities privately as SECURITY.md describes. The Contributing Guide lists the development checks.

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