crypto: golang.org/x/crypto/acme/internal/acme Index | Files

package acme

import "golang.org/x/crypto/acme/internal/acme"

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

Package Files

acme.go jws.go types.go

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.

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.

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.
    // Zero value indicates that the user hasn't agreed yet.
    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
}

Client is an ACME client.

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) CreateCert

func (c *Client) CreateCert(ctx context.Context, url string, 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 url argument is an Directory.CertURL value, typically obtained from c.Discover. The csr is a DER encoded certificate signing request.

func (*Client) Discover

func (c *Client) Discover(url string) (*Directory, error)

Discover performs ACME server discovery using the provided discovery endpoint URL.

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 == true.

http.DefaultClient is used if client argument is nil.

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, typically obtained from 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 a Challenge.Token value.

func (*Client) Register

func (c *Client) Register(url string, a *Account) (*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 url argument is typically an Directory.RegURL obtained from c.Discover.

func (*Client) UpdateReg

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

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

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

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

Package acme imports 16 packages (graph). Updated about 6 hours ago. Refresh now. Tools for package owners.