est

README

EST

go build -o ./cmd/example ./cmd/example
./cmd/example

Documentation

Overview

Package est provides an EST client and server as defined by RFC7030.

Index

• func NewRouter(cfg *ServerConfig) (http.Handler, error)
• type Attribute
• type AttributeValueSET
• type CA
• type CSRAttrs
  • func (a CSRAttrs) Marshal() ([]byte, error)
  • func (a *CSRAttrs) Unmarshal(b []byte) error
• type Client
  • func (c *Client) CACerts(ctx context.Context) ([]*x509.Certificate, error)
  • func (c *Client) CSRAttrs(ctx context.Context) (CSRAttrs, error)
  • func (c *Client) Enroll(ctx context.Context, r *x509.CertificateRequest) (*x509.Certificate, error)
  • func (c *Client) Reenroll(ctx context.Context, r *x509.CertificateRequest) (*x509.Certificate, error)
  • func (c *Client) ServerKeyGen(ctx context.Context, r *x509.CertificateRequest) (*x509.Certificate, []byte, error)
  • func (c *Client) TPMEnroll(ctx context.Context, r *x509.CertificateRequest, ekCerts []*x509.Certificate, ...) ([]byte, []byte, []byte, error)
• type Error
• type Logger
  • func LoggerFromContext(ctx context.Context) Logger
• type ServerConfig

Functions

func NewRouter

func NewRouter(cfg *ServerConfig) (http.Handler, error)

NewRouter creates a new EST server mux.

Types

type Attribute

type Attribute struct {
	Type   asn1.ObjectIdentifier
	Values AttributeValueSET
}

Attribute is a CSR Attribute type, as defined by RFC7030 4.5.2.

type AttributeValueSET

type AttributeValueSET []interface{}

AttributeValueSET is an ASN.1 SET of CSR attribute values.

type CA

type CA interface {
	// CACerts requests a copy of the current CA certificates. See RFC7030 4.1.
	CACerts(ctx context.Context, aps string, r *http.Request) ([]*x509.Certificate, error)

	// CSRAttrs requests a list of CA-desired CSR attributes. The returned list
	// may be empty. See RFC7030 4.5.
	CSRAttrs(ctx context.Context, aps string, r *http.Request) (CSRAttrs, error)

	// Enroll requests a new certificate. See RFC7030 4.2.
	Enroll(ctx context.Context, csr *x509.CertificateRequest, aps string, r *http.Request) (*x509.Certificate, error)

	// Reenroll requests renewal/rekey of an existing certificate. See RFC7030
	// 4.2.
	Reenroll(ctx context.Context, cert *x509.Certificate, csr *x509.CertificateRequest, aps string, r *http.Request) (*x509.Certificate, error)

	// ServerKeyGen requests a new certificate and a private key. The key must
	// be returned as a DER-encoded PKCS8 PrivateKeyInfo structure if additional
	// encryption is not being employed, or returned inside a CMS SignedData
	// structure which itself is inside a CMS EnvelopedData structure. See
	// RFC7030 4.4.
	ServerKeyGen(ctx context.Context, csr *x509.CertificateRequest, aps string, r *http.Request) (*x509.Certificate, []byte, error)

	// Revokation List
	RevocationList(ctx context.Context, r *http.Request) ([]byte, error)
}

CA is a Certificate Authority backing an EST server. The server can be connected to any backing CA by providing an implementation of this interface.

All operations receive:

• a context, from which the EST server logger can be retrieved by calling LoggerFromContext
• the optional URI additional path segment (RFC7030 3.2.2)
• the HTTP request object from the server, from which the HTTP headers passed by the client (including the Host header, to support virtual servers) can be obtained

Any error object returned from these functions which implements Error will be used by the EST server to determine the HTTP response code, human-readable error description, and Retry-After header value, if applicable. Any other error will be treated as an internal server error.

type CSRAttrs

type CSRAttrs struct {
	OIDs       []asn1.ObjectIdentifier
	Attributes []Attribute
}

CSRAttrs contains CSR attributes as defined by RFC7030 4.5.

CSR attributes are defined by RFC7030 as a sequence of AttrOrOID, where AttrOrOID is a CHOICE of Object Identifier or Attribute. For ease of use, CRSAttrs provides separately a list of Object Identifiers, and a list of Attributes.

When the EST client retrieves and parses CSR attributes from an EST server, attribute values of the ASN.1 types: - OBJECT IDENTIFIER - BOOLEAN - INTEGER - most STRING types

will be unmarshalled into the Attribute.Values field as standard Go asn1.ObjectIdentifier, bool, *big.Int and string types where possible, and they can be retrieved via a type assertion. Other types will be unmarshalled into an asn1.RawValue structure and must be interpreted by the caller.

func (CSRAttrs) Marshal

func (a CSRAttrs) Marshal() ([]byte, error)

Marshal returns the ASN.1 DER-encoding of a value.

func (*CSRAttrs) Unmarshal

func (a *CSRAttrs) Unmarshal(b []byte) error

Unmarshal parses an DER-encoded ASN.1 data structure and stores the result in the object. Attribute values of the ASN.1 types: - OBJECT IDENTIFIER - BOOLEAN - INTEGER - most STRING types

will be unmarshalled into standard Go asn1.ObjectIdentifier, bool, *big.Int and string types where possible, and can be retrieved via a type assertion. Other types will be unmarshalled into an asn1.RawValue structure and must be interpreted by the caller.

type Client

type Client struct {
	// Host is the host:path of the EST server excluding any URL path
	// component, e.g. est.server.com:8443
	Host string

	// AdditionalPathSegment is an optional label for EST servers to provide
	// service for multiple CAs. See RFC7030 3.2.2.
	AdditionalPathSegment string

	// ExplicitAnchor is the optional Explicit TA database. See RFC7030 3.6.1.
	ExplicitAnchor string

	// ImplicitAnchor is an optional Implicit TA database. If nil, the system
	// certificate pool will be used. See RFC7030 3.6.2.
	ImplicitAnchor string

	// CertificatePath are the client certificates to present to the EST server
	// during the handshake. If more than one certificate is provided, they
	// should be provided in order, with the end-entity certificate first, and
	// the root CA (or last intermediate CA) certificate last.
	CertificatePath string

	// PrivateKeyPath is the private key associated with the end-entity TLS
	// certificate. Any object implementing crypto.Signer may be used, to
	// support private keys resident on a hardware security module (HSM),
	// Trusted Platform Module (TPM) or other hardware device.
	PrivateKeyPath string

	// AdditionalHeaders are additional HTTP headers to include with the
	// request to the EST server.
	AdditionalHeaders map[string]string

	// HostHeader overrides the default Host header for the HTTP request to the
	// EST server, and is mostly useful for testing.
	HostHeader string

	// Username is an optional HTTP Basic Authentication username.
	Username string

	// Password is an optional HTTP Basic Authentication password.
	Password string

	// DisableKeepAlives disables HTTP keep-alives if set.
	DisableKeepAlives bool

	// InsecureSkipVerify controls whether the client verifies the EST server's
	// certificate chain and host name. If true, the client accepts any
	// certificate presented by the server and any host name in that certificate.
	// In this mode, TLS is susceptible to man-in-the-middle attacks. This should
	// be used only for testing. If used to obtain the CA certificates from an
	// otherwise untrusted EST server, those certificates must be manually
	// verified in some out-of-band manner before any further EST operations with
	// that server are performed.
	InsecureSkipVerify bool
}

Client is an EST client implementing the Enrollment over Secure Transport protocol as defined in RFC7030.

All EST client operations will return an error object implementing Error when the EST server returns any status other than 200 OK. The status code, description and, if applicable, retry-after seconds can be extracted from that object. In order to make the retry-after seconds available through this mechanism, note that a 202 Accepted response to enroll and reenroll operations is returned as an error for this purpose, even though 2** status codes indicate success.

func (*Client) CACerts

func (c *Client) CACerts(ctx context.Context) ([]*x509.Certificate, error)

CACerts requests a copy of the current CA certificates.

func (*Client) CSRAttrs

func (c *Client) CSRAttrs(ctx context.Context) (CSRAttrs, error)

CSRAttrs requests a list of CA-desired CSR attributes.

func (*Client) Enroll

func (c *Client) Enroll(ctx context.Context, r *x509.CertificateRequest) (*x509.Certificate, error)

Enroll requests a new certificate.

func (*Client) Reenroll

func (c *Client) Reenroll(ctx context.Context, r *x509.CertificateRequest) (*x509.Certificate, error)

Reenroll renews an existing certificate.

func (*Client) ServerKeyGen

func (c *Client) ServerKeyGen(ctx context.Context, r *x509.CertificateRequest) (*x509.Certificate, []byte, error)

ServerKeyGen requests a new certificate and a server-generated private key.

func (*Client) TPMEnroll

func (c *Client) TPMEnroll(
	ctx context.Context,
	r *x509.CertificateRequest,
	ekCerts []*x509.Certificate,
	ekPub []byte,
	akPub []byte,
) ([]byte, []byte, []byte, error)

TPMEnroll requests a certificate using the TPM 2.0 privacy preserving protocol for distributing credentials for keys on a TPM.

type Error

type Error interface {
	// StatusCode returns the HTTP status code.
	StatusCode() int

	// Error returns a human-readable description of the error.
	Error() string

	// RetryAfter returns the value in seconds after which the client should
	// retry the request.
	RetryAfter() int
}

Error represents an error which can be translated into an HTTP status code and message, and optionally specify a Retry-After period.

type Logger

type Logger interface {
	// Errorf uses fmt.Sprintf to log a formatted message.
	Errorf(format string, args ...interface{})

	// Errorw logs a message with some additional context. The variadic
	// key-value pairs are treated as they are in With.
	Errorw(format string, keysAndValues ...interface{})

	// Infof uses fmt.Sprintf to log a formatted message.
	Infof(format string, args ...interface{})

	// Infow logs a message with some additional context. The variadic
	// key-value pairs are treated as they are in With.
	Infow(format string, keysAndValues ...interface{})

	// Debugf uses fmt.Sprintf to log a formatted message.
	// Does not log by default, only for debugging purposes.
	Debugf(format string, args ...interface{})

	// Debugw logs a message with some additional context. The variadic
	// key-value pairs are treated as they are in With.
	// Does not log by default, only for debugging purposes.
	Debugw(format string, keysAndValues ...interface{})

	// With adds a variadic number of key-values pairs to the logging context.
	// The first element of the pair is used as the field key and should be a
	// string. Passing a non-string key or passing an orphaned key panics.
	With(keysAndValues ...interface{}) Logger
}

Logger is an interface for an EST server logger.

func LoggerFromContext

func LoggerFromContext(ctx context.Context) Logger

LoggerFromContext returns a logger included in a context.

type ServerConfig

type ServerConfig struct {
	// CA is an interface to the Certificate Authority backing the EST server.
	CA CA

	// Logger is an optional logger. The logger can be retrieved by the backing
	// CA from the HTTP request context using LoggerFromContext.
	Logger Logger

	// Timeout sets a request timeout. If zero, a reasonable default will be
	// used.
	Timeout time.Duration

	// AllowedHosts is an optional list of fully-qualified domain names
	// representing hosts which are allowed to serve the EST service.
	AllowedHosts []string

	// RateLimit is an optional rate limit expressed in requests per second.
	// If zero, no rate limit will be applied.
	RateLimit int

	// CheckBasicAuth is an optional callback function to check HTTP Basic
	// Authentication credentials. A nil error means that authentication was
	// successful, and a non-nil error means that it was not. If CheckBasicAuth
	// is nil, then HTTP Basic Authentication is not required for any EST
	// operation, but access to the /healthcheck endpoint will be blocked.
	CheckBasicAuth func(ctx context.Context, r *http.Request, aps, username, password string) error
}

ServerConfig contains EST server configuration options.