Documentation ¶
Overview ¶
Package acmez implements the higher-level flow of the ACME specification, RFC 8555: https://tools.ietf.org/html/rfc8555, specifically the sequence in Section 7.1 (page 21).
It makes it easy to obtain certificates with various challenge types using pluggable challenge solvers, and provides some handy utilities for implementing solvers and using the certificates. It DOES NOT manage certificates, it only gets them from the ACME server.
NOTE: This package's primary purpose is to get a certificate, not manage it. Most users actually want to *manage* certificates over the lifetime of long-running programs such as HTTPS or TLS servers, and should use CertMagic instead: https://github.com/caddyserver/certmagic.
COMPATIBILITY: Exported identifiers that are related to draft specifications are subject to change or removal without a major version bump.
Index ¶
- Constants
- func TLSALPN01ChallengeCert(challenge acme.Challenge) (*tls.Certificate, error)
- type CSRSource
- type Client
- func (c *Client) ObtainCertificate(ctx context.Context, account acme.Account, certPrivateKey crypto.Signer, ...) ([]acme.Certificate, error)
- func (c *Client) ObtainCertificateUsingCSR(ctx context.Context, account acme.Account, csr *x509.CertificateRequest) ([]acme.Certificate, error)
- func (c *Client) ObtainCertificateUsingCSRSource(ctx context.Context, account acme.Account, identifiers []acme.Identifier, ...) ([]acme.Certificate, error)
- type Payloader
- type Solver
- type Waiter
Constants ¶
const ACMETLS1Protocol = "acme-tls/1"
ACMETLS1Protocol is the ALPN value for the TLS-ALPN challenge handshake. See RFC 8737 §6.2.
Variables ¶
This section is empty.
Functions ¶
func TLSALPN01ChallengeCert ¶
func TLSALPN01ChallengeCert(challenge acme.Challenge) (*tls.Certificate, error)
TLSALPN01ChallengeCert creates a certificate that can be used for handshakes while solving the tls-alpn-01 challenge. See RFC 8737 §3.
Types ¶
type CSRSource ¶ added in v1.2.0
type CSRSource interface {
CSR(context.Context) (*x509.CertificateRequest, error)
}
CSRSource is an interface that provides users of this package the ability to provide a CSR as part of the ACME flow. This allows the final CSR to be provided just before the Order is finalized.
type Client ¶
type Client struct { *acme.Client // Map of solvers keyed by name of the challenge type. ChallengeSolvers map[string]Solver }
Client is a high-level API for ACME operations. It wraps a lower-level ACME client with useful functions to make common flows easier, especially for the issuance of certificates.
func (*Client) ObtainCertificate ¶
func (c *Client) ObtainCertificate(ctx context.Context, account acme.Account, certPrivateKey crypto.Signer, sans []string) ([]acme.Certificate, error)
ObtainCertificate is the same as ObtainCertificateUsingCSR, except it is a slight wrapper that generates the CSR for you. Doing so requires the private key you will be using for the certificate (different from the account private key). It obtains a certificate for the given SANs (domain names) using the provided account.
func (*Client) ObtainCertificateUsingCSR ¶
func (c *Client) ObtainCertificateUsingCSR(ctx context.Context, account acme.Account, csr *x509.CertificateRequest) ([]acme.Certificate, error)
ObtainCertificateUsingCSR obtains all resulting certificate chains using the given CSR, which must be completely and properly filled out (particularly its DNSNames and Raw fields - this usually involves creating a template CSR, then calling x509.CreateCertificateRequest, then x509.ParseCertificateRequest on the output). The Subject CommonName is NOT considered.
It implements every single part of the ACME flow described in RFC 8555 §7.1 with the exception of "Create account" because this method signature does not have a way to return the updated account object. The account's status MUST be "valid" in order to succeed.
As far as SANs go, this method currently only supports DNSNames, IPAddresses, Permanent Identifiers and Hardware Module Names on the CSR.
func (*Client) ObtainCertificateUsingCSRSource ¶ added in v1.2.0
func (c *Client) ObtainCertificateUsingCSRSource(ctx context.Context, account acme.Account, identifiers []acme.Identifier, source CSRSource) ([]acme.Certificate, error)
ObtainCertificateUsingCSRSource obtains all resulting certificate chains using the given ACME Identifiers and the CSRSource. The CSRSource can be used to create and sign a final CSR to be submitted to the ACME server just before finalization. The CSR must be completely and properly filled out, because the provided ACME Identifiers will be validated against the Identifiers that can be extracted from the CSR. This package currently supports the DNS, IP address, Permanent Identifier and Hardware Module Name identifiers. The Subject CommonName is NOT considered.
The CSR's Raw field containing the DER encoded signed certificate request must also be set. This usually involves creating a template CSR, then calling x509.CreateCertificateRequest, then x509.ParseCertificateRequest on the output.
The method implements every single part of the ACME flow described in RFC 8555 §7.1 with the exception of "Create account" because this method signature does not have a way to return the updated account object. The account's status MUST be "valid" in order to succeed.
type Payloader ¶ added in v1.1.0
Payloader is an optional interface for Solvers to implement. Its purpose is to return the payload sent to the CA when responding to a challenge. This interface is applicable when responding to "device-attest-01" challenges
If implemented, it will be called after Present() and if a Waiter is implemented it will be called after Wait(), just before the challenge is initiated with the server.
Implementations MUST honor context cancellation.
type Solver ¶
type Solver interface { // Present is called just before a challenge is initiated. // The implementation MUST prepare anything that is necessary // for completing the challenge; for example, provisioning // an HTTP resource, TLS certificate, or a DNS record. // // It MUST return quickly. If presenting the challenge token // will take time, then the implementation MUST do the // minimum amount of work required in this method, and // SHOULD additionally implement the Waiter interface. // For example, a DNS challenge solver might make a quick // HTTP request to a provider's API to create a new DNS // record, but it might be several minutes or hours before // the DNS record propagates. The API request should be // done in Present(), and waiting for propagation should // be done in Wait(). Present(context.Context, acme.Challenge) error // CleanUp is called after a challenge is finished, whether // successful or not. It MUST free/remove any resources it // allocated/created during Present. It SHOULD NOT require // that Present ran successfully. It MUST return quickly. CleanUp(context.Context, acme.Challenge) error }
Solver is a type that can solve ACME challenges. All implementations MUST honor context cancellation.
type Waiter ¶
Waiter is an optional interface for Solvers to implement. Its primary purpose is to help ensure the challenge can be solved before the server gives up trying to verify the challenge.
If implemented, it will be called after Present() but just before the challenge is initiated with the server. It blocks until the challenge is ready to be solved. (For example, waiting on a DNS record to propagate.) This allows challenges to succeed that would normally fail because they take too long to set up (i.e. the ACME server would give up polling DNS or the client would timeout its polling). By separating Present() from Wait(), it allows the slow part of all solvers to begin up front, rather than waiting on each solver one at a time.
It MUST NOT do anything exclusive of Present() that is required for the challenge to succeed. In other words, if Present() is called but Wait() is not, then the challenge should still be able to succeed assuming infinite time.
Implementations MUST honor context cancellation.
Directories ¶
Path | Synopsis |
---|---|
Package acme fully implements the ACME protocol specification as described in RFC 8555: https://tools.ietf.org/html/rfc8555.
|
Package acme fully implements the ACME protocol specification as described in RFC 8555: https://tools.ietf.org/html/rfc8555. |
examples
|
|