Documentation

Index

Constants

View Source
const (
	// AccContextKey account key
	AccContextKey = ContextKey("acc")
	// BaseURLContextKey baseURL key
	BaseURLContextKey = ContextKey("baseURL")
	// JwsContextKey jws key
	JwsContextKey = ContextKey("jws")
	// JwkContextKey jwk key
	JwkContextKey = ContextKey("jwk")
	// PayloadContextKey payload key
	PayloadContextKey = ContextKey("payload")
	// ProvisionerContextKey provisioner key
	ProvisionerContextKey = ContextKey("provisioner")
)

Variables

View Source
var (
	// StatusValid -- valid
	StatusValid = "valid"
	// StatusInvalid -- invalid
	StatusInvalid = "invalid"
	// StatusPending -- pending; e.g. an Order that is not ready to be finalized.
	StatusPending = "pending"
	// StatusDeactivated -- deactivated; e.g. for an Account that is not longer valid.
	StatusDeactivated = "deactivated"
	// StatusReady -- ready; e.g. for an Order that is ready to be finalized.
	StatusReady = "ready"
)

Functions

func BaseURLFromContext

func BaseURLFromContext(ctx context.Context) *url.URL

BaseURLFromContext returns the baseURL if one is stored in the context.

func JwkFromContext

func JwkFromContext(ctx context.Context) (*jose.JSONWebKey, error)

JwkFromContext searches the context for a JWK. Returns the JWK or an error.

func JwsFromContext

func JwsFromContext(ctx context.Context) (*jose.JSONWebSignature, error)

JwsFromContext searches the context for a JWS. Returns the JWS or an error.

func KeyAuthorization

func KeyAuthorization(token string, jwk *jose.JSONWebKey) (string, error)

KeyAuthorization creates the ACME key authorization value from a token and a jwk.

Types

type AError

type AError struct {
	Type        string        `json:"type"`
	Detail      string        `json:"detail"`
	Identifier  interface{}   `json:"identifier,omitempty"`
	Subproblems []interface{} `json:"subproblems,omitempty"`
	Status      int           `json:"-"`
}

AError is the error type as seen in acme request/responses.

func (*AError) Error

func (ae *AError) Error() string

Error allows AError to implement the error interface.

func (*AError) StatusCode

func (ae *AError) StatusCode() int

StatusCode returns the status code and implements the StatusCode interface.

type Account

type Account struct {
	Contact []string         `json:"contact,omitempty"`
	Status  string           `json:"status"`
	Orders  string           `json:"orders"`
	ID      string           `json:"-"`
	Key     *jose.JSONWebKey `json:"-"`
}

Account is a subset of the internal account type containing only those attributes required for responses in the ACME protocol.

func AccountFromContext

func AccountFromContext(ctx context.Context) (*Account, error)

AccountFromContext searches the context for an ACME account. Returns the account or an error.

func (*Account) GetID

func (a *Account) GetID() string

GetID returns the account ID.

func (*Account) GetKey

func (a *Account) GetKey() *jose.JSONWebKey

GetKey returns the JWK associated with the account.

func (*Account) IsValid

func (a *Account) IsValid() bool

IsValid returns true if the Account is valid.

func (*Account) ToLog

func (a *Account) ToLog() (interface{}, error)

ToLog enables response logging.

type AccountOptions

type AccountOptions struct {
	Key     *jose.JSONWebKey
	Contact []string
}

AccountOptions are the options needed to create a new ACME account.

type Authority

type Authority struct {

	// contains filtered or unexported fields

}

Authority is the layer that handles all ACME interactions.

func New

func New(signAuth SignAuthority, ops AuthorityOptions) (*Authority, error)

New returns a new Autohrity that implements the ACME interface.

func NewAuthority

func NewAuthority(db nosql.DB, dns, prefix string, signAuth SignAuthority) (*Authority, error)

NewAuthority returns a new Authority that implements the ACME interface.

Deprecated: NewAuthority exists for hitorical compatibility and should not be used. Use acme.New() instead.

func (*Authority) DeactivateAccount

func (a *Authority) DeactivateAccount(ctx context.Context, id string) (*Account, error)

DeactivateAccount deactivates an ACME account.

func (*Authority) FinalizeOrder

func (a *Authority) FinalizeOrder(ctx context.Context, accID, orderID string, csr *x509.CertificateRequest) (*Order, error)

FinalizeOrder attempts to finalize an order and generate a new certificate.

func (*Authority) GetAccount

func (a *Authority) GetAccount(ctx context.Context, id string) (*Account, error)

GetAccount returns an ACME account.

func (*Authority) GetAccountByKey

func (a *Authority) GetAccountByKey(ctx context.Context, jwk *jose.JSONWebKey) (*Account, error)

GetAccountByKey returns the ACME associated with the jwk id.

func (*Authority) GetAuthz

func (a *Authority) GetAuthz(ctx context.Context, accID, authzID string) (*Authz, error)

GetAuthz retrieves and attempts to update the status on an ACME authz before returning.

func (*Authority) GetCertificate

func (a *Authority) GetCertificate(accID, certID string) ([]byte, error)

GetCertificate retrieves the Certificate by ID.

func (*Authority) GetDirectory

func (a *Authority) GetDirectory(ctx context.Context) (*Directory, error)

GetDirectory returns the ACME directory object.

func (a *Authority) GetLink(ctx context.Context, typ Link, abs bool, inputs ...string) string

GetLink returns the requested link from the directory.

func (*Authority) GetLinkExplicit

func (a *Authority) GetLinkExplicit(typ Link, provName string, abs bool, baseURL *url.URL, inputs ...string) string

GetLinkExplicit returns the requested link from the directory.

func (*Authority) GetOrder

func (a *Authority) GetOrder(ctx context.Context, accID, orderID string) (*Order, error)

GetOrder returns an ACME order.

func (*Authority) GetOrdersByAccount

func (a *Authority) GetOrdersByAccount(ctx context.Context, id string) ([]string, error)

GetOrdersByAccount returns the list of order urls owned by the account.

func (*Authority) LoadProvisionerByID

func (a *Authority) LoadProvisionerByID(id string) (provisioner.Interface, error)

LoadProvisionerByID calls out to the SignAuthority interface to load a provisioner by ID.

func (*Authority) NewAccount

func (a *Authority) NewAccount(ctx context.Context, ao AccountOptions) (*Account, error)

NewAccount creates, stores, and returns a new ACME account.

func (*Authority) NewNonce

func (a *Authority) NewNonce() (string, error)

NewNonce generates, stores, and returns a new ACME nonce.

func (*Authority) NewOrder

func (a *Authority) NewOrder(ctx context.Context, ops OrderOptions) (*Order, error)

NewOrder generates, stores, and returns a new ACME order.

func (*Authority) UpdateAccount

func (a *Authority) UpdateAccount(ctx context.Context, id string, contact []string) (*Account, error)

UpdateAccount updates an ACME account.

func (*Authority) UseNonce

func (a *Authority) UseNonce(nonce string) error

UseNonce consumes the given nonce if it is valid, returns error otherwise.

func (*Authority) ValidateChallenge

func (a *Authority) ValidateChallenge(ctx context.Context, accID, chID string, jwk *jose.JSONWebKey) (*Challenge, error)

ValidateChallenge attempts to validate the challenge.

type AuthorityOptions

type AuthorityOptions struct {
	Backdate provisioner.Duration
	// DB is the database used by nosql.
	DB nosql.DB
	// DNS the host used to generate accurate ACME links. By default the authority
	// will use the Host from the request, so this value will only be used if
	// request.Host is empty.
	DNS string
	// Prefix is a URL path prefix under which the ACME api is served. This
	// prefix is required to generate accurate ACME links.
	// E.g. https://ca.smallstep.com/acme/my-acme-provisioner/new-account --
	// "acme" is the prefix from which the ACME api is accessed.
	Prefix string
}

AuthorityOptions required to create a new ACME Authority.

type Authz

type Authz struct {
	Identifier Identifier   `json:"identifier"`
	Status     string       `json:"status"`
	Expires    string       `json:"expires"`
	Challenges []*Challenge `json:"challenges"`
	Wildcard   bool         `json:"wildcard"`
	ID         string       `json:"-"`
}

Authz is a subset of the Authz type containing only those attributes required for responses in the ACME protocol.

func (*Authz) GetID

func (a *Authz) GetID() string

GetID returns the Authz ID.

func (*Authz) ToLog

func (a *Authz) ToLog() (interface{}, error)

ToLog enables response logging.

type CertOptions

type CertOptions struct {
	AccountID     string
	OrderID       string
	Leaf          *x509.Certificate
	Intermediates []*x509.Certificate
}

CertOptions options with which to create and store a cert object.

type Challenge

type Challenge struct {
	Type      string  `json:"type"`
	Status    string  `json:"status"`
	Token     string  `json:"token"`
	Validated string  `json:"validated,omitempty"`
	URL       string  `json:"url"`
	Error     *AError `json:"error,omitempty"`
	ID        string  `json:"-"`
	AuthzID   string  `json:"-"`
}

Challenge is a subset of the challenge type containing only those attributes required for responses in the ACME protocol.

func (*Challenge) GetAuthzID

func (c *Challenge) GetAuthzID() string

GetAuthzID returns the parent Authz ID that owns the Challenge.

func (*Challenge) GetID

func (c *Challenge) GetID() string

GetID returns the Challenge ID.

func (*Challenge) ToLog

func (c *Challenge) ToLog() (interface{}, error)

ToLog enables response logging.

type ChallengeOptions

type ChallengeOptions struct {
	AccountID  string
	AuthzID    string
	Identifier Identifier
}

ChallengeOptions is the type used to created a new Challenge.

type Clock

type Clock int

Clock that returns time in UTC rounded to seconds.

func (*Clock) Now

func (c *Clock) Now() time.Time

Now returns the UTC time rounded to seconds.

type ContextKey

type ContextKey string

ContextKey is the key type for storing and searching for ACME request essentials in the context of a request.

type Directory

type Directory struct {
	NewNonce   string `json:"newNonce,omitempty"`
	NewAccount string `json:"newAccount,omitempty"`
	NewOrder   string `json:"newOrder,omitempty"`
	NewAuthz   string `json:"newAuthz,omitempty"`
	RevokeCert string `json:"revokeCert,omitempty"`
	KeyChange  string `json:"keyChange,omitempty"`
}

Directory represents an ACME directory for configuring clients.

func (*Directory) ToLog

func (d *Directory) ToLog() (interface{}, error)

ToLog enables response logging for the Directory type.

type Error

type Error struct {
	Type       ProbType
	Detail     string
	Err        error
	Status     int
	Sub        []*Error
	Identifier *Identifier
}

Error is an ACME error type complete with problem document.

func AccountDoesNotExistErr

func AccountDoesNotExistErr(err error) *Error

AccountDoesNotExistErr returns a new acme error.

func AlreadyRevokedErr

func AlreadyRevokedErr(err error) *Error

AlreadyRevokedErr returns a new acme error.

func BadCSRErr

func BadCSRErr(err error) *Error

BadCSRErr returns a new acme error.

func BadNonceErr

func BadNonceErr(err error) *Error

BadNonceErr returns a new acme error.

func BadPublicKeyErr

func BadPublicKeyErr(err error) *Error

BadPublicKeyErr returns a new acme error.

func BadRevocationReasonErr

func BadRevocationReasonErr(err error) *Error

BadRevocationReasonErr returns a new acme error.

func BadSignatureAlgorithmErr

func BadSignatureAlgorithmErr(err error) *Error

BadSignatureAlgorithmErr returns a new acme error.

func CaaErr

func CaaErr(err error) *Error

CaaErr returns a new acme error.

func CompoundErr

func CompoundErr(err error) *Error

CompoundErr returns a new acme error.

func ConnectionErr

func ConnectionErr(err error) *Error

ConnectionErr returns a new acme error.

func DNSErr

func DNSErr(err error) *Error

DNSErr returns a new acme error.

func ExternalAccountRequiredErr

func ExternalAccountRequiredErr(err error) *Error

ExternalAccountRequiredErr returns a new acme error.

func IncorrectResponseErr

func IncorrectResponseErr(err error) *Error

IncorrectResponseErr returns a new acme error.

func InvalidContactErr

func InvalidContactErr(err error) *Error

InvalidContactErr returns a new acme error.

func MalformedErr

func MalformedErr(err error) *Error

MalformedErr returns a new acme error.

func NotImplemented

func NotImplemented(err error) *Error

NotImplemented returns a new acme error.

func OrderNotReadyErr

func OrderNotReadyErr(err error) *Error

OrderNotReadyErr returns a new acme error.

func RateLimitedErr

func RateLimitedErr(err error) *Error

RateLimitedErr returns a new acme error.

func RejectedIdentifierErr

func RejectedIdentifierErr(err error) *Error

RejectedIdentifierErr returns a new acme error.

func ServerInternalErr

func ServerInternalErr(err error) *Error

ServerInternalErr returns a new acme error.

func TLSErr

func TLSErr(err error) *Error

TLSErr returns a new acme error.

func UnauthorizedErr

func UnauthorizedErr(err error) *Error

UnauthorizedErr returns a new acme error.

func UnsupportedContactErr

func UnsupportedContactErr(err error) *Error

UnsupportedContactErr returns a new acme error.

func UnsupportedIdentifierErr

func UnsupportedIdentifierErr(err error) *Error

UnsupportedIdentifierErr returns a new acme error.

func UserActionRequiredErr

func UserActionRequiredErr(err error) *Error

UserActionRequiredErr returns a new acme error.

func Wrap

func Wrap(err error, wrap string) *Error

Wrap attempts to wrap the internal error.

func (*Error) Cause

func (e *Error) Cause() error

Cause returns the internal error and implements the Causer interface.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

func (*Error) Official

func (e *Error) Official() bool

Official returns true if this error's type is listed in §6.7 of RFC 8555. Error types in §6.7 are registered under IETF urn namespace:

"urn:ietf:params:acme:error:"

and should include the namespace as a prefix when appearing as a problem document.

RFC 8555 also says:

This list is not exhaustive.  The server MAY return errors whose
"type" field is set to a URI other than those defined above.  Servers
MUST NOT use the ACME URN namespace for errors not listed in the
appropriate IANA registry (see Section 9.6).  Clients SHOULD display
the "detail" field of all errors.

In this case Official returns `false` so that a different namespace can be used.

func (*Error) StatusCode

func (e *Error) StatusCode() int

StatusCode returns the status code and implements the StatusCode interface.

func (*Error) ToACME

func (e *Error) ToACME() *AError

ToACME returns an acme representation of the problem type. For official errors, the IETF ACME namespace is prepended to the error type. For our own errors, we use an (yet) unregistered smallstep acme namespace.

type Identifier

type Identifier struct {
	Type  string `json:"type"`
	Value string `json:"value"`
}

Identifier encodes the type that an order pertains to.

type Interface

type Interface interface {
	GetDirectory(ctx context.Context) (*Directory, error)
	NewNonce() (string, error)
	UseNonce(string) error

	DeactivateAccount(ctx context.Context, accID string) (*Account, error)
	GetAccount(ctx context.Context, accID string) (*Account, error)
	GetAccountByKey(ctx context.Context, key *jose.JSONWebKey) (*Account, error)
	NewAccount(ctx context.Context, ao AccountOptions) (*Account, error)
	UpdateAccount(context.Context, string, []string) (*Account, error)

	GetAuthz(ctx context.Context, accID string, authzID string) (*Authz, error)
	ValidateChallenge(ctx context.Context, accID string, chID string, key *jose.JSONWebKey) (*Challenge, error)

	FinalizeOrder(ctx context.Context, accID string, orderID string, csr *x509.CertificateRequest) (*Order, error)
	GetOrder(ctx context.Context, accID string, orderID string) (*Order, error)
	GetOrdersByAccount(ctx context.Context, accID string) ([]string, error)
	NewOrder(ctx context.Context, oo OrderOptions) (*Order, error)

	GetCertificate(string, string) ([]byte, error)

	LoadProvisionerByID(string) (provisioner.Interface, error)
	GetLink(ctx context.Context, linkType Link, absoluteLink bool, inputs ...string) string
	GetLinkExplicit(linkType Link, provName string, absoluteLink bool, baseURL *url.URL, inputs ...string) string
}

Interface is the acme authority interface.

type Link int

Link captures the link type.

const (
	// NewNonceLink new-nonce
	NewNonceLink Link = iota
	// NewAccountLink new-account
	NewAccountLink
	// AccountLink account
	AccountLink
	// OrderLink order
	OrderLink
	// NewOrderLink new-order
	NewOrderLink
	// OrdersByAccountLink list of orders owned by account
	OrdersByAccountLink
	// FinalizeLink finalize order
	FinalizeLink
	// NewAuthzLink authz
	NewAuthzLink
	// AuthzLink new-authz
	AuthzLink
	// ChallengeLink challenge
	ChallengeLink
	// CertificateLink certificate
	CertificateLink
	// DirectoryLink directory
	DirectoryLink
	// RevokeCertLink revoke certificate
	RevokeCertLink
	// KeyChangeLink key rollover
	KeyChangeLink
)

func (Link) String

func (l Link) String() string

type MockProvisioner

type MockProvisioner struct {
	Mret1                   interface{}
	Merr                    error
	MgetName                func() string
	MauthorizeSign          func(ctx context.Context, ott string) ([]provisioner.SignOption, error)
	MdefaultTLSCertDuration func() time.Duration
	MgetOptions             func() *provisioner.Options
}

MockProvisioner for testing

func (*MockProvisioner) AuthorizeSign

func (m *MockProvisioner) AuthorizeSign(ctx context.Context, ott string) ([]provisioner.SignOption, error)

AuthorizeSign mock

func (*MockProvisioner) DefaultTLSCertDuration

func (m *MockProvisioner) DefaultTLSCertDuration() time.Duration

DefaultTLSCertDuration mock

func (*MockProvisioner) GetName

func (m *MockProvisioner) GetName() string

GetName mock

func (*MockProvisioner) GetOptions

func (m *MockProvisioner) GetOptions() *provisioner.Options

type Order

type Order struct {
	Status         string       `json:"status"`
	Expires        string       `json:"expires,omitempty"`
	Identifiers    []Identifier `json:"identifiers"`
	NotBefore      string       `json:"notBefore,omitempty"`
	NotAfter       string       `json:"notAfter,omitempty"`
	Error          interface{}  `json:"error,omitempty"`
	Authorizations []string     `json:"authorizations"`
	Finalize       string       `json:"finalize"`
	Certificate    string       `json:"certificate,omitempty"`
	ID             string       `json:"-"`
}

Order contains order metadata for the ACME protocol order type.

func (*Order) GetID

func (o *Order) GetID() string

GetID returns the Order ID.

func (*Order) ToLog

func (o *Order) ToLog() (interface{}, error)

ToLog enables response logging.

type OrderOptions

type OrderOptions struct {
	AccountID   string       `json:"accID"`
	Identifiers []Identifier `json:"identifiers"`
	NotBefore   time.Time    `json:"notBefore"`
	NotAfter    time.Time    `json:"notAfter"`

	// contains filtered or unexported fields

}

OrderOptions options with which to create a new Order.

type ProbType

type ProbType int

ProbType is the type of the ACME problem.

func (ProbType) String

func (ap ProbType) String() string

String returns the string representation of the acme problem type, fulfilling the Stringer interface.

type Provisioner

type Provisioner interface {
	AuthorizeSign(ctx context.Context, token string) ([]provisioner.SignOption, error)
	GetName() string
	DefaultTLSCertDuration() time.Duration
	GetOptions() *provisioner.Options
}

Provisioner is an interface that implements a subset of the provisioner.Interface -- only those methods required by the ACME api/authority.

func ProvisionerFromContext

func ProvisionerFromContext(ctx context.Context) (Provisioner, error)

ProvisionerFromContext searches the context for a provisioner. Returns the provisioner or an error.

type SignAuthority

type SignAuthority interface {
	Sign(cr *x509.CertificateRequest, opts provisioner.SignOptions, signOpts ...provisioner.SignOption) ([]*x509.Certificate, error)
	LoadProvisionerByID(string) (provisioner.Interface, error)
}

SignAuthority is the interface implemented by a CA authority.

Directories

Path Synopsis
api