acme

Documentation

Overview

Package acme provides an ACME client implementation. See https://ietf-wg-acme.github.io/acme/ for details.

This package is a work in progress and makes no API stability promises.

Index

• Constants
• func AcceptTOS(string) bool
• func JWKThumbprint(pub *rsa.PublicKey) string
• type Account
• type Authorization
• type AuthzID
• type Challenge
• type Client
  • func (c *Client) Accept(chal *Challenge) (*Challenge, error)
  • func (c *Client) Authorize(domain string) (*Authorization, error)
  • func (c *Client) CreateCert(ctx context.Context, csr []byte, exp time.Duration, bundle bool) (der [][]byte, certURL string, err error)
  • func (c *Client) Discover() (Directory, error)
  • func (c *Client) FetchCert(ctx context.Context, url string, bundle bool) ([][]byte, error)
  • func (c *Client) GetAuthz(url string) (*Authorization, error)
  • func (c *Client) GetChallenge(url string) (*Challenge, error)
  • func (c *Client) GetReg(url string) (*Account, error)
  • func (c *Client) HTTP01Handler(token string) http.Handler
  • func (c *Client) Register(a *Account, prompt func(tos string) bool) (*Account, error)
  • func (c *Client) UpdateReg(a *Account) (*Account, error)
• type Directory
• type Error
  • func (e *Error) Error() string

Constants

const (
	StatusUnknown    = "unknown"
	StatusPending    = "pending"
	StatusProcessing = "processing"
	StatusValid      = "valid"
	StatusInvalid    = "invalid"
	StatusRevoked    = "revoked"
)

ACME server response statuses used to describe Authorization and Challenge states.

const LetsEncryptURL = "https://acme-v01.api.letsencrypt.org/directory"

LetsEncryptURL is the Directory endpoint of Let's Encrypt CA.

Functions

func AcceptTOS

func AcceptTOS(string) bool

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

func JWKThumbprint

func JWKThumbprint(pub *rsa.PublicKey) string

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

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.
	URI string

	// Contact is a slice of contact info used during registration.
	Contact []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.
	AgreedTerms string

	// Actual terms of a CA.
	CurrentTerms string

	// Authz is the authorization URL used to initiate a new authz flow.
	Authz string

	// Authorizations is a URI from which a list of authorizations
	// granted to this account can be fetched via a GET request.
	Authorizations string

	// Certificates is a URI from which a list of certificates
	// issued for this account can be fetched via a GET request.
	Certificates string
}

Account is a user account. It is associated with a private key.

type Authorization

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

	// Status identifies the status of an authorization.
	Status string

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

	// Challenges that the client needs to fulfill in order to prove possession
	// of the identifier (for pending authorizations).
	// For final authorizations, the challenges that were used.
	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.
	Combinations [][]int
}

Authorization encodes an authorization response.

type AuthzID

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

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

type Challenge

type Challenge struct {
	// Type is the challenge type, e.g. "http-01", "tls-sni-02", "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.
	Status string
}

Challenge encodes a returned CA challenge.

type Client

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

	// Key is the account key used to register with a CA and sign requests.
	Key *rsa.PrivateKey

	// 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
	// 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(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) Authorize

func (c *Client) Authorize(domain string) (*Authorization, error)

Authorize performs the initial step in an authorization 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.

func (*Client) CreateCert

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

CreateCert requests a new certificate. In the case where CA server does not provide the issued certificate in the response, CreateCert will poll certURL using c.FetchCert, which will result in additional round-trips. In such scenario the caller can cancel the polling with ctx.

If the bundle is true, the returned value will also contain CA (the issuer) certificate. The csr is a DER encoded certificate signing request.

func (*Client) Discover

func (c *Client) Discover() (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.

The returned value will also contain CA (the issuer) certificate if bundle is true.

func (*Client) GetAuthz

func (c *Client) GetAuthz(url string) (*Authorization, error)

GetAuthz retrieves the current status of an authorization flow.

A client typically polls an authz status using this method.

func (*Client) GetChallenge

func (c *Client) GetChallenge(url string) (*Challenge, error)

GetChallenge retrieves the current status of an challenge.

A client typically polls a challenge status using this method.

func (*Client) GetReg

func (c *Client) GetReg(url string) (*Account, error)

GetReg retrieves an existing registration. The url argument is an Account URI.

func (*Client) HTTP01Handler

func (c *Client) HTTP01Handler(token string) http.Handler

HTTP01Handler creates a new handler which responds to a http-01 challenge. The token argument is a Challenge.Token value.

func (*Client) Register

func (c *Client) Register(a *Account, prompt func(tos string) bool) (*Account, error)

Register creates a new account registration by following the "new-reg" flow. It returns registered account. The a argument is not modified.

The registration may require the caller to agree to the CA 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.

func (*Client) UpdateReg

func (c *Client) UpdateReg(a *Account) (*Account, error)

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

type Directory

type Directory struct {
	// RegURL is an account endpoint URL, allowing for creating new
	// and modifying existing accounts.
	RegURL string

	// AuthzURL is used to initiate Identifier Authorization flow.
	AuthzURL string

	// CertURL is a new certificate issuance endpoint URL.
	CertURL string

	// RevokeURL is used to initiate a certificate revocation flow.
	RevokeURL 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 RFC6844.
	CAA []string
}

Directory is ACME server discovery data.

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
	// Header is the original server error response headers.
	Header http.Header
}

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