acme

README

acme

ACME-complient Go client library and a command line tool. Neither has 3rd party dependencies. Also, see https://letsencrypt.org.

Contents of this repo:

• / - ACME client Go package. See godoc for acme package. The package has been imported to golang.org/x/crypto/acme/internal/acme. I will keep github.com/google/acme package mirroring crypto/acme/internal/acme until it becomes exported as golang.org/x/crypto/acme.
• /cmd/acme/ - cli tool, similar to the official letsencrypt.

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

command line tool usage

Quick install with go get -u github.com/google/acme/cmd/acme.

1. You need to have a user account, registered with the CA. This is represented by an RSA private key.

The easiest is to let acme tool generate it for you:

    acme reg mailto:email@example.com

If you already have a key or want to generate one manually:

    mkdir -p ~/config/acme
    openssl genrsa -out ~/config/acme/account.pem 2048
    acme reg mailto:email@example.com

The latter version assumes that default acme config dir is ~/config/acme. Yours may vary. Check with acme help reg.

The "mailto:email@example.com" in the example above is a contact argument. While some ACME CA may let you register without providing any contact info, it is recommended to use one. For instance a CA might need to notify cert owners with an update.

1. Agree with the ACME CA Terms of Service.

Before requesting your first certificate, you may need to agree with the terms of the CA. You can check the status of our account with:

    acme whoami

and look for "Accepted: ..." line. If it says "no", check CA's terms document provided as a link in "Terms: ..." field and agree by executing:

    acme update -update

1. Request a new certificate for your domain.

The easiest way to do this is:

    acme cert example.com

The above command will generate a new certificate key (unless one already exists), and send a certifcate request. The location of the output files is ~/.config.acme, but depends on your environment. Check with acme help cert.

If you don't want auto-generated cert key, one can always be generated upfront:

    openssl genrsa -out cert.key 2048

in which case the cert command will look something like this:

    acme cert -k cert.key example.com

Note that for certificate request command to succeed, it needs to be executed in a way allowing for resolving authorization challenges (domain ownership proof). This typically means the command should be executed on the same host the domain is served from.

If the latter is not possible, use -manual flag and follow the instructions:

    acme cert -manual example.com

License

(c) Google, 2015. Licensed under Apache-2 license.

Documentation

Overview

Package acme provides an ACME client implementation. See https://tools.ietf.org/html/draft-barnes-acme-04 spec for details.

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

Index

• Constants
• func FetchCert(client *http.Client, url string, bundle bool) ([][]byte, error)
• func JWKThumbprint(pub *rsa.PublicKey) string
• type Account
• type Authorization
• type AuthzID
• type CertSource
• type Challenge
• type ChallengeSet
• type Client
  • func (c *Client) Accept(chal *Challenge) (*Challenge, error)
  • func (c *Client) Authorize(url, domain string) (*Authorization, error)
  • func (c *Client) CertSource() CertSource
  • func (c *Client) CreateCert(url string, csr []byte, exp time.Duration, bundle bool) (der [][]byte, certURL string, err 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) PostJWS(url string, body interface{}) (*http.Response, error)
  • func (c *Client) Register(url string, a *Account) error
  • func (c *Client) UpdateReg(url string, a *Account) error
• type Endpoint
  • func Discover(client *http.Client, url string) (Endpoint, error)
• type Error
  • func (e *Error) Error() string
• type RetryError
  • func (re RetryError) Error() string

Constants

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

ACME server response statuses

const (
	ErrBadCSR       = "urn:acme:error:badCSR"
	ErrBadNonce     = "urn:acme:error:badNonce"
	ErrConnection   = "urn:acme:error:connection"
	ErrDNSSec       = "urn:acme:error:dnssec"
	ErrMalformed    = "urn:acme:error:malformed"
	ErrInternal     = "urn:acme:error:serverInternal"
	ErrTLS          = "urn:acme:error:tls"
	ErrUnauthorized = "urn:acme:error:unauthorized"
	ErrUnknownHost  = "urn:acme:error:unknownHost"
	ErrRateLimited  = "urn:acme:error:rateLimited"
)

Predefined Error.Type values by the ACME spec.

Functions

func FetchCert

func FetchCert(client *http.Client, url string, bundle bool) ([][]byte, error)

FetchCert retrieves already issued certificate from the given url, in DER format. The returned value will also contain CA (the issuer) certificate if bundle == true.

When the request succeeds but certificate is unavailable at the time, the function returns nil and error will be of RetryError type.

DefaultClient is used if client argument is nil.

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 `json:"uri"`

	// Contact is a slice of contact info used during registration.
	Contact []string `json:"contact"`

	// The terms user has agreed to.
	// Zero value indicates that the user hasn't agreed yet.
	AgreedTerms string `json:"agreement"`

	// Actual terms of a CA.
	CurrentTerms string `json:"terms"`

	// Authz is the authorization URL used to initiate a new authz flow.
	Authz string `json:"authz"`

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

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

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

type Authorization

type Authorization struct {
	ChallengeSet
	Identifier AuthzID
	URI        string
	Status     string
}

Authorization encodes an authorization response.

type AuthzID

type AuthzID struct {
	Type  string `json:"type,omitempty"`
	Value string `json:"value,omitempty"`
}

AuthzID encodes an ID for something to authorize, typically a domain.

type CertSource

type CertSource interface {
	// Cert obtains a new certificate from the CA.
	Cert(*x509.CertificateRequest) ([]byte, error)
}

CertSource can obtain new certificates.

type Challenge

type Challenge struct {
	Type   string
	URI    string `json:"uri"`
	Token  string
	Status string
}

Challenge encodes a returned CA challenge.

type ChallengeSet

type ChallengeSet struct {
	Challenges   []Challenge
	Combinations [][]int
}

ChallengeSet encodes a set of challenges, together with permitted combinations.

type Client

type Client struct {
	http.Client
	Key *rsa.PrivateKey
}

Client implements ACME spec.

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(url, 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.

The url argument is an authz URL, usually obtained with c.Register.

func (*Client) CertSource

func (c *Client) CertSource() CertSource

CertSource creates new CertSource using client c.

func (*Client) CreateCert

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

CreateCert requests a new certificate. It always returns a non-empty long-lived certURL. The cert der bytes, however, may be nil even if no error occurred. The returned value will also contain CA (the issuer) certificate if bundle is true.

url is typically an Endpoint.CertURL. csr is a DER encoded certificate signing request.

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, usually obtained with c.Register.

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 usually a Challenge.Token value.

func (*Client) PostJWS

func (c *Client) PostJWS(url string, body interface{}) (*http.Response, error)

PostJWS makes a request to the specified url with JWS-signed body. The body argument must be JSON-serializable.

func (*Client) Register

func (c *Client) Register(url string, a *Account) error

Register create a new registration by following the "new-reg" flow. It populates the a argument with the response received from the server. Existing field values may be overwritten.

The url argument is typically an Endpoint.RegURL.

func (*Client) UpdateReg

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

UpdateReg updates existing registration. It populates the a argument with the response received from the server. Existing field values may be overwritten.

The url argument is an Account.URI, usually obtained with c.Register.

type Endpoint

type Endpoint struct {
	RegURL    string `json:"new-reg"`
	AuthzURL  string `json:"new-authz"`
	CertURL   string `json:"new-cert"`
	RevokeURL string `json:"revoke-cert"`
}

Endpoint is ACME server directory.

func Discover

func Discover(client *http.Client, url string) (Endpoint, error)

Discover performs ACME server discovery using provided url and client. If client argument is nil, DefaultClient will be used.

type Error

type Error struct {
	Status int
	Type   string
	Detail string
	// Response is the original server response used to construct the Error,
	// with Response.Body closed.
	Response *http.Response `json:"-"`
}

Error is an ACME error.

func (*Error) Error

func (e *Error) Error() string

type RetryError

type RetryError time.Duration

RetryError is a "temporary" error indicating that the request can be retried after the specified duration.

func (RetryError) Error

func (re RetryError) Error() string