go-pki-scep is a Go implementation of the Simple Certificate Enrollment Protocol (SCEP, RFC 8894). Routers, VPN gateways, mobile device managers and other network devices use SCEP to request certificates from a CA. The module has three packages:
scepbuilds and parses SCEP messages and answers requests without any transport.scepserveris anhttp.Handlerthat serves SCEP for a CA you implement.scepclientenrolls, renews, polls and queries a SCEP server over HTTP.
The library handles message signatures and encryption, nonces, transaction IDs and the HTTP operations. Your code decides who may enroll, issues the certificates and keeps the state of the CA. The CMS layer comes from go-pkcs7.
go get github.com/misiektoja/go-pki-scepThe module needs Go 1.27.3 or newer. Its only dependency is go-pkcs7.
| Operation | Server handler | Client |
|---|---|---|
| GetCACaps and GetCACert | Yes | Yes |
| PKCSReq and RenewalReq | Passed to the CA, which issues, keeps the request pending or refuses it | Enroll and EnrollAndWait |
| UpdateReq | Passed to the CA | Message layer only |
| CertPoll | Passed to the CA | Poll |
| GetCert and GetCRL | When the CA implements them | GetCert and GetCRL |
| GetNextCACert and GetCACertChain | When the CA implements them | GetNextCACert and GetCACertChain |
The scep package builds, parses and answers every RFC 8894 message type. sscep, the micromdm/scep
client and server and EJBCA run against the module in CI, see
Tested implementations.
The API may still change before v1.0.0 as described in the
Compatibility policy.
A server implements scepserver.CA and mounts the handler. The CA decides who may enroll, for
example by checking the challenge password of a PKCSReq:
handler, err := scepserver.NewHandler(myCA, scepserver.Options{Logger: slog.Default()})
if err != nil {
log.Fatal(err)
}
http.Handle("/scep", handler)A device fetches the CA certificates with GetCACert, checks them against a fingerprint it trusts
and enrolls with EnrollAndWait from scepclient.
Getting started builds a local server
and client in one file, enrolls and renews a certificate and names what to replace before
production. That program is in examples/quickstart and runs with
go run ./examples/quickstart. The package example in example_test.go shows the message layer
without HTTP.
Full documentation is at misiektoja.github.io/go-pki-scep.
- Getting started
- Support matrix
- Architecture
- Implementing a CA
- Pending requests and throttling
- Optional operations
- Refusals and logging
- CA certificates and trust
- Enrollment and renewal
- Capabilities, answers and retries
- Message layer
- Server options and Client options
- Troubleshooting
- Security model
The package documentation on pkg.go.dev describes every exported type and option. Repository files:
- SUPPORT.md explains where to ask and what to include.
- CONTRIBUTING.md lists the development checks.
- SECURITY.md explains how to report a vulnerability.
- DEPENDENCIES.md lists the dependency and the copied code with their licenses.
- CHANGELOG.md records user-visible changes per release.
- Requests and answers use RSA key transport, so a requester signs with an RSA key and a CA without an RSA key needs an RSA RA certificate. A CSR may still carry an ECDSA key. Password-based encryption of answers (PasswordRecipientInfo) is not supported.
- No storage. The CA keeps pending requests, issued certificates and CRLs.
- The client makes no trust decision about the GetCACert answer. The caller checks it, for example against a pinned fingerprint.
- No automatic CA rollover, AES-GCM or AuthEnvelopedData.
Known limitations explains each gap.
go-pki-scep continues the work of these projects and their contributors:
- micromdm/scep, the original implementation by Victor Vrantchan and the MicroMDM contributors.
- smallstep/scep, the Smallstep fork of the message layer this repository started from.
Both are MIT licensed. NOTICE records the origins of the code, including the Go standard
library code in x509util.
SUPPORT.md directs usage questions, bug reports, feature requests and security reports. Check Troubleshooting and gather the versions, the failInfo or HTTP status and the server log before posting.
Licensed under the MIT License. The Go code in x509util keeps the Go BSD-style license
in its file header, as NOTICE describes.