certificate

Documentation

Index

• Constants
• func MakeARICertID(leaf *x509.Certificate) (string, error)
• type Certifier
  • func NewCertifier(core *api.Core, resolver resolver, options CertifierOptions) *Certifier
  • func (c *Certifier) Get(url string, bundle bool) (*Resource, error)
  • func (c *Certifier) GetOCSP(bundle []byte) ([]byte, *ocsp.Response, error)
  • func (c *Certifier) GetRenewalInfo(req RenewalInfoRequest) (*RenewalInfoResponse, error)
  • func (c *Certifier) Obtain(request ObtainRequest) (*Resource, error)
  • func (c *Certifier) ObtainForCSR(request ObtainForCSRRequest) (*Resource, error)
  • func (c *Certifier) Renew(certRes Resource, bundle, mustStaple bool, preferredChain string) (*Resource, error)
  • func (c *Certifier) RenewWithOptions(certRes Resource, options *RenewOptions) (*Resource, error)
  • func (c *Certifier) Revoke(cert []byte) error
  • func (c *Certifier) RevokeWithReason(cert []byte, reason *uint) error
• type CertifierOptions
• type ObtainForCSRRequest
• type ObtainRequest
• type RenewOptions
• type RenewalInfoRequest
• type RenewalInfoResponse
  • func (r *RenewalInfoResponse) ShouldRenewAt(now time.Time, willingToSleep time.Duration) *time.Time
• type Resource

Constants

const (
	// DefaultOverallRequestLimit is the overall number of request per second
	// limited on the "new-reg", "new-authz" and "new-cert" endpoints.
	// From the documentation the limitation is 20 requests per second,
	// but using 20 as value doesn't work but 18 do.
	// https://letsencrypt.org/docs/rate-limits/
	// ZeroSSL has a limit of 7.
	// https://help.zerossl.com/hc/en-us/articles/17864245480093-Advantages-over-Using-Let-s-Encrypt#h_01HT4Z1JCJFJQFJ1M3P7S085Q9
	DefaultOverallRequestLimit = 18
)

Functions

func MakeARICertID

func MakeARICertID(leaf *x509.Certificate) (string, error)

MakeARICertID constructs a certificate identifier as described in draft-ietf-acme-ari-03, section 4.1.

Types

type Certifier

type Certifier struct {
	// contains filtered or unexported fields
}

Certifier A service to obtain/renew/revoke certificates.

func NewCertifier

func NewCertifier(core *api.Core, resolver resolver, options CertifierOptions) *Certifier

NewCertifier creates a Certifier.

func (*Certifier) Get

func (c *Certifier) Get(url string, bundle bool) (*Resource, error)

Get attempts to fetch the certificate at the supplied URL. The URL is the same as what would normally be supplied at the Resource's CertURL.

The returned Resource will not have the PrivateKey and CSR fields populated as these will not be available.

If bundle is true, the Certificate field in the returned Resource includes the issuer certificate.

func (*Certifier) GetOCSP

func (c *Certifier) GetOCSP(bundle []byte) ([]byte, *ocsp.Response, error)

GetOCSP takes a PEM encoded cert or cert bundle returning the raw OCSP response, the parsed response, and an error, if any.

The returned []byte can be passed directly into the OCSPStaple property of a tls.Certificate. If the bundle only contains the issued certificate, this function will try to get the issuer certificate from the IssuingCertificateURL in the certificate.

If the []byte and/or ocsp.Response return values are nil, the OCSP status may be assumed OCSPUnknown.

func (*Certifier) GetRenewalInfo

func (c *Certifier) GetRenewalInfo(req RenewalInfoRequest) (*RenewalInfoResponse, error)

GetRenewalInfo sends a request to the ACME server's renewalInfo endpoint to obtain a suggested renewal window. The caller MUST provide the certificate and issuer certificate for the certificate they wish to renew. The caller should attempt to renew the certificate at the time indicated by the ShouldRenewAt method of the returned RenewalInfoResponse object.

Note: this endpoint is part of a draft specification, not all ACME servers will implement it. This method will return api.ErrNoARI if the server does not advertise a renewal info endpoint.

https://datatracker.ietf.org/doc/draft-ietf-acme-ari

func (*Certifier) Obtain

func (c *Certifier) Obtain(request ObtainRequest) (*Resource, error)

Obtain tries to obtain a single certificate using all domains passed into it.

This function will never return a partial certificate. If one domain in the list fails, the whole certificate will fail.

func (*Certifier) ObtainForCSR

func (c *Certifier) ObtainForCSR(request ObtainForCSRRequest) (*Resource, error)

ObtainForCSR tries to obtain a certificate matching the CSR passed into it.

The domains are inferred from the CommonName and SubjectAltNames, if any. The private key for this CSR is not required.

If bundle is true, the []byte contains both the issuer certificate and your issued certificate as a bundle.

This function will never return a partial certificate. If one domain in the list fails, the whole certificate will fail.

func (*Certifier) Renew

func (c *Certifier) Renew(certRes Resource, bundle, mustStaple bool, preferredChain string) (*Resource, error)

Renew takes a Resource and tries to renew the certificate.

If the renewal process succeeds, the new certificate will be returned in a new CertResource. Please be aware that this function will return a new certificate in ANY case that is not an error. If the server does not provide us with a new cert on a GET request to the CertURL this function will start a new-cert flow where a new certificate gets generated.

If bundle is true, the []byte contains both the issuer certificate and your issued certificate as a bundle.

For private key reuse the PrivateKey property of the passed in Resource should be non-nil. Deprecated: use RenewWithOptions instead.

func (*Certifier) RenewWithOptions

func (c *Certifier) RenewWithOptions(certRes Resource, options *RenewOptions) (*Resource, error)

RenewWithOptions takes a Resource and tries to renew the certificate.

If the renewal process succeeds, the new certificate will be returned in a new CertResource. Please be aware that this function will return a new certificate in ANY case that is not an error. If the server does not provide us with a new cert on a GET request to the CertURL this function will start a new-cert flow where a new certificate gets generated.

If bundle is true, the []byte contains both the issuer certificate and your issued certificate as a bundle.

For private key reuse the PrivateKey property of the passed in Resource should be non-nil.

func (*Certifier) Revoke

func (c *Certifier) Revoke(cert []byte) error

Revoke takes a PEM encoded certificate or bundle and tries to revoke it at the CA.

func (*Certifier) RevokeWithReason

func (c *Certifier) RevokeWithReason(cert []byte, reason *uint) error

RevokeWithReason takes a PEM encoded certificate or bundle and tries to revoke it at the CA.

type CertifierOptions

type CertifierOptions struct {
	KeyType             certcrypto.KeyType
	Timeout             time.Duration
	OverallRequestLimit int
}

type ObtainForCSRRequest

type ObtainForCSRRequest struct {
	CSR *x509.CertificateRequest

	NotBefore                      time.Time
	NotAfter                       time.Time
	Bundle                         bool
	PreferredChain                 string
	AlwaysDeactivateAuthorizations bool
	// A string uniquely identifying a previously-issued certificate which this
	// order is intended to replace.
	// - https://datatracker.ietf.org/doc/html/draft-ietf-acme-ari-03#section-5
	ReplacesCertID string
}

ObtainForCSRRequest The request to obtain a certificate matching the CSR passed into it.

If `Bundle` is true, the `[]byte` contains both the issuer certificate and your issued certificate as a bundle.

If `AlwaysDeactivateAuthorizations` is true, the authorizations are also relinquished if the obtain request was successful. See https://datatracker.ietf.org/doc/html/rfc8555#section-7.5.2.

type ObtainRequest

type ObtainRequest struct {
	Domains    []string
	PrivateKey crypto.PrivateKey
	MustStaple bool

	NotBefore                      time.Time
	NotAfter                       time.Time
	Bundle                         bool
	PreferredChain                 string
	AlwaysDeactivateAuthorizations bool
	// A string uniquely identifying a previously-issued certificate which this
	// order is intended to replace.
	// - https://datatracker.ietf.org/doc/html/draft-ietf-acme-ari-03#section-5
	ReplacesCertID string
}

ObtainRequest The request to obtain certificate.

The first domain in domains is used for the CommonName field of the certificate, all other domains are added using the Subject Alternate Names extension.

A new private key is generated for every invocation of the function Obtain. If you do not want that you can supply your own private key in the privateKey parameter. If this parameter is non-nil it will be used instead of generating a new one.

If `Bundle` is true, the `[]byte` contains both the issuer certificate and your issued certificate as a bundle.

If `AlwaysDeactivateAuthorizations` is true, the authorizations are also relinquished if the obtain request was successful. See https://datatracker.ietf.org/doc/html/rfc8555#section-7.5.2.

type RenewOptions

type RenewOptions struct {
	NotBefore time.Time
	NotAfter  time.Time
	// If true, the []byte contains both the issuer certificate and your issued certificate as a bundle.
	Bundle                         bool
	PreferredChain                 string
	AlwaysDeactivateAuthorizations bool
	// Not supported for CSR request.
	MustStaple bool
}

RenewOptions options used by Certifier.RenewWithOptions.

type RenewalInfoRequest

type RenewalInfoRequest struct {
	Cert *x509.Certificate
}

RenewalInfoRequest contains the necessary renewal information.

type RenewalInfoResponse

type RenewalInfoResponse struct {
	acme.RenewalInfoResponse

	// RetryAfter header indicating the polling interval that the ACME server recommends.
	// Conforming clients SHOULD query the renewalInfo URL again after the RetryAfter period has passed,
	// as the server may provide a different suggestedWindow.
	// https://datatracker.ietf.org/doc/html/draft-ietf-acme-ari-03#section-4.2
	RetryAfter time.Duration
}

RenewalInfoResponse is a wrapper around acme.RenewalInfoResponse that provides a method for determining when to renew a certificate.

func (*RenewalInfoResponse) ShouldRenewAt

func (r *RenewalInfoResponse) ShouldRenewAt(now time.Time, willingToSleep time.Duration) *time.Time

ShouldRenewAt determines the optimal renewal time based on the current time (UTC),renewal window suggest by ARI, and the client's willingness to sleep. It returns a pointer to a time.Time value indicating when the renewal should be attempted or nil if deferred until the next normal wake time. This method implements the RECOMMENDED algorithm described in draft-ietf-acme-ari.

- (4.1-11. Getting Renewal Information) https://datatracker.ietf.org/doc/draft-ietf-acme-ari/

type Resource

type Resource struct {
	Domain            string `json:"domain"`
	CertURL           string `json:"certUrl"`
	CertStableURL     string `json:"certStableUrl"`
	PrivateKey        []byte `json:"-"`
	Certificate       []byte `json:"-"`
	IssuerCertificate []byte `json:"-"`
	CSR               []byte `json:"-"`
}

Resource represents a CA issued certificate. PrivateKey, Certificate and IssuerCertificate are all already PEM encoded and can be directly written to disk. Certificate may be a certificate bundle, depending on the options supplied to create it.