est

README

EST Server

The project is an open source implementation of the Enrollment over Secure Transport (EST) protocol as defined in RFC 7030 with added notes from RFC 8951 and RFC 8996. The primary use for this server is to allow Linux microPlatform devices to renew their certificates after they've been deployed to production.

Key Features from RFC 7030

• 4.1 Distribution of CA Certificates /cacerts
• 4.2.1 Client certificate enrollement /simpleenroll
• 4.2.2 Client certificate renewal /simplereenroll

Deviations from RFC 7030

As this project's primary aim is handling device certificate renewal, optional features of the RFC have been omitted including:

• 4.3 - CMC
• 4.4 - Server side key generation
• 4.5 - CSR attributes

Contributing

Pull requests are welcome. Run make check to verify changes will pass CI.

Building

The simple "standalone" server can be built with:

make bin/estserver

Using

First you must create a TLS certificate for this server that your factory devices will trust. This can be generated using the helper script contrib/mk-tls-keypair.sh.

Next you need to create an intermediate "device CA" this service can use to sign certificates with. There is a Fioctl helper for this:

fioctl keys ca add-device-ca <path to your PKI dir> --local-ca --local-ca-filename est-ca.pem

Finally, the this server needs a list of intermediate CAs to trust. This can be obtained with:

fioctl keys ca show --just-device-cas > client-cas.pem

If you have devices that were registered before you configured your Factory's PKI, then you'll also need to get a copy of the Foundries default "online CA" that was used to sign certificates for those devices. You can download this certificate by running:

fioctl get https://api.foundries.io/ota/default-online-ca.pem >> client-cas.pem

You can tell if a device was registered with the default online CA by looking at it's certificate under /var/sota/client.pem:

openssl x509 -in ./client.pem -issuer -noout

If the output looks something like:

issuer=CN=ota-devices-CA

Then the device was created using the default online CA.

Now the server can be run with:

```bash
$ ./bin/estserver \
    -root-cert <pkidir>/factory_ca.pem \
    -tls-cert <pkidir>/local-tls.pem  # cert from mk-tls-keypair above \
    -tls-key <pkidir>/local-tls.key   # key from mk-tls-keypair above \
    -ca-cert <pkidir>/est-ca.pem      # cert from fioctl keys ca add-device-ca \
    -ca-key <pkidir>/est-ca.key       # key from fioctl keys ca add-device-ca \
    -client-cas  client-cas.pem

fioconfig can then be pointed at this service to rotate certificates with:

$ fioconfig renew-cert https://<SERVER_NAME>/.well-known/est

Documentation

Index

• Constants
• Variables
• func ApplyTlsCertHandler(tlsConfig *tls.Config, handler TlsCertHandler) error
• func CtxGetLog(ctx context.Context) zerolog.Logger
• func CtxWithLog(ctx context.Context, log zerolog.Logger) context.Context
• func InitLogger(level string) zerolog.Logger
• func RegisterEchoHandlers(svcHandler ServiceHandler, e *echo.Echo)
• func RunGracefully(ctx context.Context, server *http.Server, e *echo.Echo) error
• type EstErrorType
  • func (e EstErrorType) Error() string
  • func (e EstErrorType) Unwrap() error
• type Service
  • func NewService(rootCa *x509.Certificate, ca *x509.Certificate, key crypto.Signer, ...) Service
  • func (s Service) CaCerts(ctx context.Context) ([]byte, error)
  • func (s Service) Enroll(ctx context.Context, csrBytes []byte) ([]byte, error)
  • func (s Service) ReEnroll(ctx context.Context, csrBytes []byte, curCert *x509.Certificate) ([]byte, error)
• type ServiceHandler
  • func NewStaticServiceHandler(svc Service) ServiceHandler
• type TlsCertHandler
  • func NewStaticTlsCertHandler(certs *TlsCerts) (TlsCertHandler, error)
• type TlsCerts

Constants

const MAX_CONTENT_LEN = 4096

Variables

var (
	ErrEst = errors.New("base EstError")
)

Functions

func ApplyTlsCertHandler

func ApplyTlsCertHandler(tlsConfig *tls.Config, handler TlsCertHandler) error

Apply the TlsCertHandler logic to the tlsConfig

func CtxGetLog

func CtxGetLog(ctx context.Context) zerolog.Logger

func CtxWithLog

func CtxWithLog(ctx context.Context, log zerolog.Logger) context.Context

func InitLogger

func InitLogger(level string) zerolog.Logger

func RegisterEchoHandlers

func RegisterEchoHandlers(svcHandler ServiceHandler, e *echo.Echo)

func RunGracefully

func RunGracefully(ctx context.Context, server *http.Server, e *echo.Echo) error

Types

type EstErrorType

type EstErrorType int

const (
	ErrInvalidSignatureAlgorithm EstErrorType = iota
	ErrSubjectMismatch
	ErrSubjectAltNameMismatch
	ErrInvalidBase64
	ErrInvalidCsr
	ErrInvalidCsrSignature
)

func (EstErrorType) Error

func (e EstErrorType) Error() string

func (EstErrorType) Unwrap

func (e EstErrorType) Unwrap() error

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service represents a thin API to handle required operations of EST7030. This service implements the required parts of EST. Specifically:

"cas" - Section 4.1
"enroll" and "reenroll" - Section 4.2

Optional APIs are not implemented including:

4.3 - cmc
4.4 - server side key generation
4.5 - CSR attributes

func NewService

func NewService(rootCa *x509.Certificate, ca *x509.Certificate, key crypto.Signer, certDuration time.Duration) Service

NewService creates an EST7030 API for a Factory

func (Service) CaCerts

func (s Service) CaCerts(ctx context.Context) ([]byte, error)

CaCerts return the CA certificate as per: https://www.rfc-editor.org/rfc/rfc7030.html#section-4.1.2

func (Service) Enroll

func (s Service) Enroll(ctx context.Context, csrBytes []byte) ([]byte, error)

Enroll perform EST7030 enrollment operation as per https://www.rfc-editor.org/rfc/rfc7030.html#section-4.2.1 Errors can be generic errors or of the type EstError

func (Service) ReEnroll

func (s Service) ReEnroll(ctx context.Context, csrBytes []byte, curCert *x509.Certificate) ([]byte, error)

ReEnroll perform EST7030 enrollment operation as per https://www.rfc-editor.org/rfc/rfc7030.html#section-4.2.2 Errors can be generic errors or of the type EstError

type ServiceHandler

type ServiceHandler interface {
	GetService(ctx context.Context, serverName string) (Service, error)
}

func NewStaticServiceHandler

func NewStaticServiceHandler(svc Service) ServiceHandler

type TlsCertHandler

type TlsCertHandler interface {
	Init(ctx context.Context) error
	Get(ctx context.Context, serverName string) (*TlsCerts, error)
	VerifyConnection(ctx context.Context, certs *TlsCerts, conn tls.ConnectionState) error
}

TLSCertHandler provides a way to hook into Go's HTTPS implementation to support different TLS Certs based on the incoming SNI server name.

func NewStaticTlsCertHandler

func NewStaticTlsCertHandler(certs *TlsCerts) (TlsCertHandler, error)

Createa a TlsCertHandler based on a static keyfile and certificate

type TlsCerts

type TlsCerts struct {
	Server *tls.Certificate
	Roots  *x509.CertPool
}

TlsCerts represents the Server TLS keypair to advertise and CA roots we trust for client authentication.