acme

package
v0.31.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 11, 2024 License: BSD-3-Clause Imports: 28 Imported by: 685

Documentation

Overview

Package acme provides an implementation of the Automatic Certificate Management Environment (ACME) spec, most famously used by Let's Encrypt.

The initial implementation of this package was based on an early version of the spec. The current implementation supports only the modern RFC 8555 but some of the old API surface remains for compatibility. While code using the old API will still compile, it will return an error. Note the deprecation comments to update your code.

See https://tools.ietf.org/html/rfc8555 for the spec.

Most common scenarios will want to use autocert subdirectory instead, which provides automatic access to certificates from Let's Encrypt and any other ACME-based CA.

Index

Constants

View Source 
const (
	// LetsEncryptURL is the Directory endpoint of Let's Encrypt CA.
	LetsEncryptURL = "https://acme-v02.api.letsencrypt.org/directory"

	// ALPNProto is the ALPN protocol name used by a CA server when validating
	// tls-alpn-01 challenges.
	//
	// Package users must ensure their servers can negotiate the ACME ALPN in
	// order for tls-alpn-01 challenge verifications to succeed.
	// See the crypto/tls package's Config.NextProtos field.
	ALPNProto = "acme-tls/1"
)
View Source 
const (
	StatusDeactivated = "deactivated"
	StatusExpired     = "expired"
	StatusInvalid     = "invalid"
	StatusPending     = "pending"
	StatusProcessing  = "processing"
	StatusReady       = "ready"
	StatusRevoked     = "revoked"
	StatusUnknown     = "unknown"
	StatusValid       = "valid"
)

ACME status values of Account, Order, Authorization and Challenge objects. See https://tools.ietf.org/html/rfc8555#section-7.1.6 for details.

Variables

View Source 
var (
	// ErrUnsupportedKey is returned when an unsupported key type is encountered.
	ErrUnsupportedKey = errors.New("acme: unknown key type; only RSA and ECDSA are supported")

	// ErrAccountAlreadyExists indicates that the Client's key has already been registered
	// with the CA. It is returned by Register method.
	ErrAccountAlreadyExists = errors.New("acme: account already exists")

	// ErrNoAccount indicates that the Client's key has not been registered with the CA.
	ErrNoAccount = errors.New("acme: account does not exist")
)

Functions

func AcceptTOS 

func AcceptTOS(tosURL string) bool

AcceptTOS always returns true to indicate the acceptance of a CA's Terms of Service during account registration. See Register method of Client for more details.

func JWKThumbprint 

func JWKThumbprint(pub crypto.PublicKey) (string, error)

JWKThumbprint creates a JWK thumbprint out of pub as specified in https://tools.ietf.org/html/rfc7638.

func RateLimit 

func RateLimit(err error) (time.Duration, bool)

RateLimit reports whether err represents a rate limit error and any Retry-After duration returned by the server.

See the following for more details on rate limiting: https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-5.6

Types

type Account 

type Account struct {
	// URI is the account unique ID, which is also a URL used to retrieve
	// account data from the CA.
	// When interfacing with RFC 8555-compliant CAs, URI is the "kid" field
	// value in JWS signed requests.
	URI string

	// Contact is a slice of contact info used during registration.
	// See https://tools.ietf.org/html/rfc8555#section-7.3 for supported
	// formats.
	Contact []string

	// Status indicates current account status as returned by the CA.
	// Possible values are StatusValid, StatusDeactivated, and StatusRevoked.
	Status string

	// OrdersURL is a URL from which a list of orders submitted by this account
	// can be fetched.
	OrdersURL string

	// The terms user has agreed to.
	// A value not matching CurrentTerms indicates that the user hasn't agreed
	// to the actual Terms of Service of the CA.
	//
	// It is non-RFC 8555 compliant. Package users can store the ToS they agree to
	// during Client's Register call in the prompt callback function.
	AgreedTerms string

	// Actual terms of a CA.
	//
	// It is non-RFC 8555 compliant. Use Directory's Terms field.
	// When a CA updates their terms and requires an account agreement,
	// a URL at which instructions to do so is available in Error's Instance field.
	CurrentTerms string

	// Authz is the authorization URL used to initiate a new authz flow.
	//
	// It is non-RFC 8555 compliant. Use Directory's AuthzURL or OrderURL.
	Authz string

	// Authorizations is a URI from which a list of authorizations
	// granted to this account can be fetched via a GET request.
	//
	// It is non-RFC 8555 compliant and is obsoleted by OrdersURL.
	Authorizations string

	// Certificates is a URI from which a list of certificates
	// issued for this account can be fetched via a GET request.
	//
	// It is non-RFC 8555 compliant and is obsoleted by OrdersURL.
	Certificates string

	// ExternalAccountBinding represents an arbitrary binding to an account of
	// the CA which the ACME server is tied to.
	// See https://tools.ietf.org/html/rfc8555#section-7.3.4 for more details.
	ExternalAccountBinding *ExternalAccountBinding
}

Account is a user account. It is associated with a private key. Non-RFC 8555 fields are empty when interfacing with a compliant CA.

type Authorization 

type Authorization struct {
	// URI uniquely identifies a authorization.
	URI string

	// Status is the current status of an authorization.
	// Possible values are StatusPending, StatusValid, StatusInvalid, StatusDeactivated,
	// StatusExpired and StatusRevoked.
	Status string

	// Identifier is what the account is authorized to represent.
	Identifier AuthzID

	// The timestamp after which the CA considers the authorization invalid.
	Expires time.Time

	// Wildcard is true for authorizations of a wildcard domain name.
	Wildcard bool

	// Challenges that the client needs to fulfill in order to prove possession
	// of the identifier (for pending authorizations).
	// For valid authorizations, the challenge that was validated.
	// For invalid authorizations, the challenge that was attempted and failed.
	//
	// RFC 8555 compatible CAs require users to fuflfill only one of the challenges.
	Challenges []*Challenge

	// A collection of sets of challenges, each of which would be sufficient
	// to prove possession of the identifier.
	// Clients must complete a set of challenges that covers at least one set.
	// Challenges are identified by their indices in the challenges array.
	// If this field is empty, the client needs to complete all challenges.
	//
	// This field is unused in RFC 8555.
	Combinations [][]int
}

Authorization encodes an authorization response.

type AuthorizationError 

type AuthorizationError struct {
	// URI uniquely identifies the failed Authorization.
	URI string

	// Identifier is an AuthzID.Value of the failed Authorization.
	Identifier string

	// Errors is a collection of non-nil error values of Challenge items
	// of the failed Authorization.
	Errors []error
}

AuthorizationError indicates that an authorization for an identifier did not succeed. It contains all errors from Challenge items of the failed Authorization.

func (*AuthorizationError) Error 

func (a *AuthorizationError) Error() string

type AuthzID 

type AuthzID struct {
	Type  string // The type of identifier, "dns" or "ip".
	Value string // The identifier itself, e.g. "example.org".
}

AuthzID is an identifier that an account is authorized to represent.

func DomainIDs 

func DomainIDs(names ...string) []AuthzID

DomainIDs creates a slice of AuthzID with "dns" identifier type.

func IPIDs 

func IPIDs(addr ...string) []AuthzID

IPIDs creates a slice of AuthzID with "ip" identifier type. Each element of addr is textual form of an address as defined in RFC 1123 Section 2.1 for IPv4 and in RFC 5952 Section 4 for IPv6.

type CRLReasonCode 

type CRLReasonCode int

CRLReasonCode identifies the reason for a certificate revocation. 

const (
	CRLReasonUnspecified          CRLReasonCode = 0
	CRLReasonKeyCompromise        CRLReasonCode = 1
	CRLReasonCACompromise         CRLReasonCode = 2
	CRLReasonAffiliationChanged   CRLReasonCode = 3
	CRLReasonSuperseded           CRLReasonCode = 4
	CRLReasonCessationOfOperation CRLReasonCode = 5
	CRLReasonCertificateHold      CRLReasonCode = 6
	CRLReasonRemoveFromCRL        CRLReasonCode = 8
	CRLReasonPrivilegeWithdrawn   CRLReasonCode = 9
	CRLReasonAACompromise         CRLReasonCode = 10
)

CRL reason codes as defined in RFC 5280.

type CertOption 

type CertOption interface {
	// contains filtered or unexported methods
}

CertOption is an optional argument type for the TLS ChallengeCert methods for customizing a temporary certificate for TLS-based challenges.

func WithKey 

func WithKey(key crypto.Signer) CertOption

WithKey creates an option holding a private/public key pair. The private part signs a certificate, and the public part represents the signee.

func WithTemplate 

func WithTemplate(t *x509.Certificate) CertOption

WithTemplate creates an option for specifying a certificate template. See x509.CreateCertificate for template usage details.

In TLS ChallengeCert methods, the template is also used as parent, resulting in a self-signed certificate. The DNSNames field of t is always overwritten for tls-sni challenge certs.

type Challenge 

type Challenge struct {
	// Type is the challenge type, e.g. "http-01", "tls-alpn-01", "dns-01".
	Type string

	// URI is where a challenge response can be posted to.
	URI string

	// Token is a random value that uniquely identifies the challenge.
	Token string

	// Status identifies the status of this challenge.
	// In RFC 8555, possible values are StatusPending, StatusProcessing, StatusValid,
	// and StatusInvalid.
	Status string

	// Validated is the time at which the CA validated this challenge.
	// Always zero value in pre-RFC 8555.
	Validated time.Time

	// Error indicates the reason for an authorization failure
	// when this challenge was used.
	// The type of a non-nil value is *Error.
	Error error
}

Challenge encodes a returned CA challenge. Its Error field may be non-nil if the challenge is part of an Authorization with StatusInvalid.

type Client 

type Client struct {
	// Key is the account key used to register with a CA and sign requests.
	// Key.Public() must return a *rsa.PublicKey or *ecdsa.PublicKey.
	//
	// The following algorithms are supported:
	// RS256, ES256, ES384 and ES512.
	// See RFC 7518 for more details about the algorithms.
	Key crypto.Signer

	// HTTPClient optionally specifies an HTTP client to use
	// instead of http.DefaultClient.
	HTTPClient *http.Client

	// DirectoryURL points to the CA directory endpoint.
	// If empty, LetsEncryptURL is used.
	// Mutating this value after a successful call of Client's Discover method
	// will have no effect.
	DirectoryURL string

	// RetryBackoff computes the duration after which the nth retry of a failed request
	// should occur. The value of n for the first call on failure is 1.
	// The values of r and resp are the request and response of the last failed attempt.
	// If the returned value is negative or zero, no more retries are done and an error
	// is returned to the caller of the original method.
	//
	// Requests which result in a 4xx client error are not retried,
	// except for 400 Bad Request due to "bad nonce" errors and 429 Too Many Requests.
	//
	// If RetryBackoff is nil, a truncated exponential backoff algorithm
	// with the ceiling of 10 seconds is used, where each subsequent retry n
	// is done after either ("Retry-After" + jitter) or (2^n seconds + jitter),
	// preferring the former if "Retry-After" header is found in the resp.
	// The jitter is a random value up to 1 second.
	RetryBackoff func(n int, r *http.Request, resp *http.Response) time.Duration

	// UserAgent is prepended to the User-Agent header sent to the ACME server,
	// which by default is this package's name and version.
	//
	// Reusable libraries and tools in particular should set this value to be
	// identifiable by the server, in case they are causing issues.
	UserAgent string

	// KID is the key identifier provided by the CA. If not provided it will be
	// retrieved from the CA by making a call to the registration endpoint.
	KID KeyID
	// contains filtered or unexported fields
}

Client is an ACME client.

The only required field is Key. An example of creating a client with a new key is as follows: 

key, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
	log.Fatal(err)
}
client := &Client{Key: key}

func (*Client) Accept 

func (c *Client) Accept(ctx context.Context, chal *Challenge) (*Challenge, error)

Accept informs the server that the client accepts one of its challenges previously obtained with c.Authorize.

The server will then perform the validation asynchronously.

func (*Client) AccountKeyRollover 

func (c *Client) AccountKeyRollover(ctx context.Context, newKey crypto.Signer) error

AccountKeyRollover attempts to transition a client's account key to a new key. On success client's Key is updated which is not concurrency safe. On failure an error will be returned. The new key is already registered with the ACME provider if the following is true:

  • error is of type acme.Error
  • StatusCode should be 409 (Conflict)
  • Location header will have the KID of the associated account

More about account key rollover can be found at https://tools.ietf.org/html/rfc8555#section-7.3.5.

func (*Client) Authorize 

func (c *Client) Authorize(ctx context.Context, domain string) (*Authorization, error)

Authorize performs the initial step in the pre-authorization flow, as opposed to order-based flow. The caller will then need to choose from and perform a set of returned challenges using c.Accept in order to successfully complete authorization.

Once complete, the caller can use AuthorizeOrder which the CA should provision with the already satisfied authorization. For pre-RFC CAs, the caller can proceed directly to requesting a certificate using CreateCert method.

If an authorization has been previously granted, the CA may return a valid authorization which has its Status field set to StatusValid.

More about pre-authorization can be found at https://tools.ietf.org/html/rfc8555#section-7.4.1.

func (*Client) AuthorizeIP 

func (c *Client) AuthorizeIP(ctx context.Context, ipaddr string) (*Authorization, error)

AuthorizeIP is the same as Authorize but requests IP address authorization. Clients which successfully obtain such authorization may request to issue a certificate for IP addresses.

See the ACME spec extension for more details about IP address identifiers: https://tools.ietf.org/html/draft-ietf-acme-ip.

func (*Client) AuthorizeOrder 

func (c *Client) AuthorizeOrder(ctx context.Context, id []AuthzID, opt ...OrderOption) (*Order, error)

AuthorizeOrder initiates the order-based application for certificate issuance, as opposed to pre-authorization in Authorize. It is only supported by CAs implementing RFC 8555.

The caller then needs to fetch each authorization with GetAuthorization, identify those with StatusPending status and fulfill a challenge using Accept. Once all authorizations are satisfied, the caller will typically want to poll order status using WaitOrder until it's in StatusReady state. To finalize the order and obtain a certificate, the caller submits a CSR with CreateOrderCert.

func (*Client) CreateCert deprecated 

func (c *Client) CreateCert(ctx context.Context, csr []byte, exp time.Duration, bundle bool) (der [][]byte, certURL string, err error)

CreateCert was part of the old version of ACME. It is incompatible with RFC 8555.

Deprecated: this was for the pre-RFC 8555 version of ACME. Callers should use CreateOrderCert.

func (*Client) CreateOrderCert 

func (c *Client) CreateOrderCert(ctx context.Context, url string, csr []byte, bundle bool) (der [][]byte, certURL string, err error)

CreateOrderCert submits the CSR (Certificate Signing Request) to a CA at the specified URL. The URL is the FinalizeURL field of an Order created with AuthorizeOrder.

If the bundle argument is true, the returned value also contain the CA (issuer) certificate chain. Otherwise, only a leaf certificate is returned. The returned URL can be used to re-fetch the certificate using FetchCert.

This method is only supported by CAs implementing RFC 8555. See CreateCert for pre-RFC CAs.

CreateOrderCert returns an error if the CA's response is unreasonably large. Callers are encouraged to parse the returned value to ensure the certificate is valid and has the expected features.

func (*Client) DNS01ChallengeRecord 

func (c *Client) DNS01ChallengeRecord(token string) (string, error)

DNS01ChallengeRecord returns a DNS record value for a dns-01 challenge response. A TXT record containing the returned value must be provisioned under "_acme-challenge" name of the domain being validated.

The token argument is a Challenge.Token value.

func (*Client) DeactivateReg 

func (c *Client) DeactivateReg(ctx context.Context) error

DeactivateReg permanently disables an existing account associated with c.Key. A deactivated account can no longer request certificate issuance or access resources related to the account, such as orders or authorizations.

It only works with CAs implementing RFC 8555.

func (*Client) Discover 

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

Discover performs ACME server discovery using c.DirectoryURL.

It caches successful result. So, subsequent calls will not result in a network round-trip. This also means mutating c.DirectoryURL after successful call of this method will have no effect.

func (*Client) FetchCert 

func (c *Client) FetchCert(ctx context.Context, url string, bundle bool) ([][]byte, error)

FetchCert retrieves already issued certificate from the given url, in DER format. It retries the request until the certificate is successfully retrieved, context is cancelled by the caller or an error response is received.

If the bundle argument is true, the returned value also contains the CA (issuer) certificate chain.

FetchCert returns an error if the CA's response or chain was unreasonably large. Callers are encouraged to parse the returned value to ensure the certificate is valid and has expected features.

func (*Client) GetAuthorization 

func (c *Client) GetAuthorization(ctx context.Context, url string) (*Authorization, error)

GetAuthorization retrieves an authorization identified by the given URL.

If a caller needs to poll an authorization until its status is final, see the WaitAuthorization method.

func (*Client) GetChallenge 

func (c *Client) GetChallenge(ctx context.Context, url string) (*Challenge, error)

GetChallenge retrieves the current status of an challenge.

A client typically polls a challenge status using this method.

func (*Client) GetOrder 

func (c *Client) GetOrder(ctx context.Context, url string) (*Order, error)

GetOrder retrives an order identified by the given URL. For orders created with AuthorizeOrder, the url value is Order.URI.

If a caller needs to poll an order until its status is final, see the WaitOrder method.

func (*Client) GetReg 

func (c *Client) GetReg(ctx context.Context, url string) (*Account, error)

GetReg retrieves an existing account associated with c.Key.

The url argument is a legacy artifact of the pre-RFC 8555 API and is ignored.

func (*Client) HTTP01ChallengePath 

func (c *Client) HTTP01ChallengePath(token string) string

HTTP01ChallengePath returns the URL path at which the response for an http-01 challenge should be provided by the servers. The response value can be obtained with HTTP01ChallengeResponse.

The token argument is a Challenge.Token value.

func (*Client) HTTP01ChallengeResponse 

func (c *Client) HTTP01ChallengeResponse(token string) (string, error)

HTTP01ChallengeResponse returns the response for an http-01 challenge. Servers should respond with the value to HTTP requests at the URL path provided by HTTP01ChallengePath to validate the challenge and prove control over a domain name.

The token argument is a Challenge.Token value.

func (*Client) ListCertAlternates 

func (c *Client) ListCertAlternates(ctx context.Context, url string) ([]string, error)

ListCertAlternates retrieves any alternate certificate chain URLs for the given certificate chain URL. These alternate URLs can be passed to FetchCert in order to retrieve the alternate certificate chains.

If there are no alternate issuer certificate chains, a nil slice will be returned.

func (*Client) Register 

func (c *Client) Register(ctx context.Context, acct *Account, prompt func(tosURL string) bool) (*Account, error)

Register creates a new account with the CA using c.Key. It returns the registered account. The account acct is not modified.

The registration may require the caller to agree to the CA's Terms of Service (TOS). If so, and the account has not indicated the acceptance of the terms (see Account for details), Register calls prompt with a TOS URL provided by the CA. Prompt should report whether the caller agrees to the terms. To always accept the terms, the caller can use AcceptTOS.

When interfacing with an RFC-compliant CA, non-RFC 8555 fields of acct are ignored and prompt is called if Directory's Terms field is non-zero. Also see Error's Instance field for when a CA requires already registered accounts to agree to an updated Terms of Service.

func (*Client) RevokeAuthorization 

func (c *Client) RevokeAuthorization(ctx context.Context, url string) error

RevokeAuthorization relinquishes an existing authorization identified by the given URL. The url argument is an Authorization.URI value.

If successful, the caller will be required to obtain a new authorization using the Authorize or AuthorizeOrder methods before being able to request a new certificate for the domain associated with the authorization.

It does not revoke existing certificates.

func (*Client) RevokeCert 

func (c *Client) RevokeCert(ctx context.Context, key crypto.Signer, cert []byte, reason CRLReasonCode) error

RevokeCert revokes a previously issued certificate cert, provided in DER format.

The key argument, used to sign the request, must be authorized to revoke the certificate. It's up to the CA to decide which keys are authorized. For instance, the key pair of the certificate may be authorized. If the key is nil, c.Key is used instead.

func (*Client) TLSALPN01ChallengeCert 

func (c *Client) TLSALPN01ChallengeCert(token, domain string, opt ...CertOption) (cert tls.Certificate, err error)

TLSALPN01ChallengeCert creates a certificate for TLS-ALPN-01 challenge response. Servers can present the certificate to validate the challenge and prove control over a domain name. For more details on TLS-ALPN-01 see https://tools.ietf.org/html/draft-shoemaker-acme-tls-alpn-00#section-3

The token argument is a Challenge.Token value. If a WithKey option is provided, its private part signs the returned cert, and the public part is used to specify the signee. If no WithKey option is provided, a new ECDSA key is generated using P-256 curve.

The returned certificate is valid for the next 24 hours and must be presented only when the server name in the TLS ClientHello matches the domain, and the special acme-tls/1 ALPN protocol has been specified.

func (*Client) TLSSNI01ChallengeCert deprecated 

func (c *Client) TLSSNI01ChallengeCert(token string, opt ...CertOption) (cert tls.Certificate, name string, err error)

TLSSNI01ChallengeCert creates a certificate for TLS-SNI-01 challenge response.

Deprecated: This challenge type is unused in both draft-02 and RFC versions of the ACME spec.

func (*Client) TLSSNI02ChallengeCert deprecated 

func (c *Client) TLSSNI02ChallengeCert(token string, opt ...CertOption) (cert tls.Certificate, name string, err error)

TLSSNI02ChallengeCert creates a certificate for TLS-SNI-02 challenge response.

Deprecated: This challenge type is unused in both draft-02 and RFC versions of the ACME spec.

func (*Client) UpdateReg 

func (c *Client) UpdateReg(ctx context.Context, acct *Account) (*Account, error)

UpdateReg updates an existing registration. It returns an updated account copy. The provided account is not modified.

The account's URI is ignored and the account URL associated with c.Key is used instead.

func (*Client) WaitAuthorization 

func (c *Client) WaitAuthorization(ctx context.Context, url string) (*Authorization, error)

WaitAuthorization polls an authorization at the given URL until it is in one of the final states, StatusValid or StatusInvalid, the ACME CA responded with a 4xx error code, or the context is done.

It returns a non-nil Authorization only if its Status is StatusValid. In all other cases WaitAuthorization returns an error. If the Status is StatusInvalid, the returned error is of type *AuthorizationError.

func (*Client) WaitOrder 

func (c *Client) WaitOrder(ctx context.Context, url string) (*Order, error)

WaitOrder polls an order from the given URL until it is in one of the final states, StatusReady, StatusValid or StatusInvalid, the CA responded with a non-retryable error or the context is done.

It returns a non-nil Order only if its Status is StatusReady or StatusValid. In all other cases WaitOrder returns an error. If the Status is StatusInvalid, the returned error is of type *OrderError.

type Directory 

type Directory struct {
	// NonceURL indicates an endpoint where to fetch fresh nonce values from.
	NonceURL string

	// RegURL is an account endpoint URL, allowing for creating new accounts.
	// Pre-RFC 8555 CAs also allow modifying existing accounts at this URL.
	RegURL string

	// OrderURL is used to initiate the certificate issuance flow
	// as described in RFC 8555.
	OrderURL string

	// AuthzURL is used to initiate identifier pre-authorization flow.
	// Empty string indicates the flow is unsupported by the CA.
	AuthzURL string

	// CertURL is a new certificate issuance endpoint URL.
	// It is non-RFC 8555 compliant and is obsoleted by OrderURL.
	CertURL string

	// RevokeURL is used to initiate a certificate revocation flow.
	RevokeURL string

	// KeyChangeURL allows to perform account key rollover flow.
	KeyChangeURL string

	// Term is a URI identifying the current terms of service.
	Terms string

	// Website is an HTTP or HTTPS URL locating a website
	// providing more information about the ACME server.
	Website string

	// CAA consists of lowercase hostname elements, which the ACME server
	// recognises as referring to itself for the purposes of CAA record validation
	// as defined in RFC 6844.
	CAA []string

	// ExternalAccountRequired indicates that the CA requires for all account-related
	// requests to include external account binding information.
	ExternalAccountRequired bool
}

Directory is ACME server discovery data. See https://tools.ietf.org/html/rfc8555#section-7.1.1 for more details.

type Error 

type Error struct {
	// StatusCode is The HTTP status code generated by the origin server.
	StatusCode int
	// ProblemType is a URI reference that identifies the problem type,
	// typically in a "urn:acme:error:xxx" form.
	ProblemType string
	// Detail is a human-readable explanation specific to this occurrence of the problem.
	Detail string
	// Instance indicates a URL that the client should direct a human user to visit
	// in order for instructions on how to agree to the updated Terms of Service.
	// In such an event CA sets StatusCode to 403, ProblemType to
	// "urn:ietf:params:acme:error:userActionRequired" and a Link header with relation
	// "terms-of-service" containing the latest TOS URL.
	Instance string
	// Header is the original server error response headers.
	// It may be nil.
	Header http.Header
	// Subproblems may contain more detailed information about the individual problems
	// that caused the error. This field is only sent by RFC 8555 compatible ACME
	// servers. Defined in RFC 8555 Section 6.7.1.
	Subproblems []Subproblem
}

Error is an ACME error, defined in Problem Details for HTTP APIs doc http://tools.ietf.org/html/draft-ietf-appsawg-http-problem.

func (*Error) Error 

func (e *Error) Error() string

type ExternalAccountBinding 

type ExternalAccountBinding struct {
	// KID is the Key ID of the symmetric MAC key that the CA provides to
	// identify an external account from ACME.
	KID string

	// Key is the bytes of the symmetric key that the CA provides to identify
	// the account. Key must correspond to the KID.
	Key []byte
}

ExternalAccountBinding contains the data needed to form a request with an external account binding. See https://tools.ietf.org/html/rfc8555#section-7.3.4 for more details.

func (*ExternalAccountBinding) String 

func (e *ExternalAccountBinding) String() string

type KeyID 

type KeyID string

KeyID is the account key identity provided by a CA during registration.

type Order 

type Order struct {
	// URI uniquely identifies an order.
	URI string

	// Status represents the current status of the order.
	// It indicates which action the client should take.
	//
	// Possible values are StatusPending, StatusReady, StatusProcessing, StatusValid and StatusInvalid.
	// Pending means the CA does not believe that the client has fulfilled the requirements.
	// Ready indicates that the client has fulfilled all the requirements and can submit a CSR
	// to obtain a certificate. This is done with Client's CreateOrderCert.
	// Processing means the certificate is being issued.
	// Valid indicates the CA has issued the certificate. It can be downloaded
	// from the Order's CertURL. This is done with Client's FetchCert.
	// Invalid means the certificate will not be issued. Users should consider this order
	// abandoned.
	Status string

	// Expires is the timestamp after which CA considers this order invalid.
	Expires time.Time

	// Identifiers contains all identifier objects which the order pertains to.
	Identifiers []AuthzID

	// NotBefore is the requested value of the notBefore field in the certificate.
	NotBefore time.Time

	// NotAfter is the requested value of the notAfter field in the certificate.
	NotAfter time.Time

	// AuthzURLs represents authorizations to complete before a certificate
	// for identifiers specified in the order can be issued.
	// It also contains unexpired authorizations that the client has completed
	// in the past.
	//
	// Authorization objects can be fetched using Client's GetAuthorization method.
	//
	// The required authorizations are dictated by CA policies.
	// There may not be a 1:1 relationship between the identifiers and required authorizations.
	// Required authorizations can be identified by their StatusPending status.
	//
	// For orders in the StatusValid or StatusInvalid state these are the authorizations
	// which were completed.
	AuthzURLs []string

	// FinalizeURL is the endpoint at which a CSR is submitted to obtain a certificate
	// once all the authorizations are satisfied.
	FinalizeURL string

	// CertURL points to the certificate that has been issued in response to this order.
	CertURL string

	// The error that occurred while processing the order as received from a CA, if any.
	Error *Error
}

Order represents a client's request for a certificate. It tracks the request flow progress through to issuance.

type OrderError 

type OrderError struct {
	OrderURL string
	Status   string
}

OrderError is returned from Client's order related methods. It indicates the order is unusable and the clients should start over with AuthorizeOrder.

The clients can still fetch the order object from CA using GetOrder to inspect its state.

func (*OrderError) Error 

func (oe *OrderError) Error() string

type OrderOption 

type OrderOption interface {
	// contains filtered or unexported methods
}

OrderOption allows customizing Client.AuthorizeOrder call.

func WithOrderNotAfter 

func WithOrderNotAfter(t time.Time) OrderOption

WithOrderNotAfter sets order's NotAfter field.

func WithOrderNotBefore 

func WithOrderNotBefore(t time.Time) OrderOption

WithOrderNotBefore sets order's NotBefore field.

type Subproblem 

type Subproblem struct {
	// Type is a URI reference that identifies the problem type,
	// typically in a "urn:acme:error:xxx" form.
	Type string
	// Detail is a human-readable explanation specific to this occurrence of the problem.
	Detail string
	// Instance indicates a URL that the client should direct a human user to visit
	// in order for instructions on how to agree to the updated Terms of Service.
	// In such an event CA sets StatusCode to 403, Type to
	// "urn:ietf:params:acme:error:userActionRequired", and adds a Link header with relation
	// "terms-of-service" containing the latest TOS URL.
	Instance string
	// Identifier may contain the ACME identifier that the error is for.
	Identifier *AuthzID
}

A Subproblem describes an ACME subproblem as reported in an Error.

func (Subproblem) String 

func (sp Subproblem) String() string

Source Files

View all Source files

Directories

Path Synopsis
Package autocert provides automatic access to certificates from Let's Encrypt and any other ACME-based CA.
 Package autocert provides automatic access to certificates from Let's Encrypt and any other ACME-based CA.
internal/acmetest
Package acmetest provides types for testing acme and autocert packages.
 Package acmetest provides types for testing acme and autocert packages.
internal
acmeprobe
The acmeprober program runs against an actual ACME CA implementation.
 The acmeprober program runs against an actual ACME CA implementation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.