Categorygithub.com/eggsampler/acme/v3
modulepackage
3.6.1
Repository: https://github.com/eggsampler/acme.git
Documentation: pkg.go.dev
Overview
Versions
2
Dependencies
32
Dependents
6
Files
2k SLOC

# README

eggsampler/acme

GoDoc Build Status Coverage Status

About

eggsampler/acme is a Go client library implementation for RFC8555 (previously ACME v2). This library can be used with the Let's Encrypt Certificate Authority (CA), but also other ACME compliant CA's such as ZeroSSL.

The library is designed to provide a zero external dependency wrapper over exposed directory endpoints and provide objects in easy to use structures.

Requirements

A Go version of at least 1.11 is required as this repository is designed to be imported as a Go module.

Usage

Simply import the module into a project,

import "github.com/eggsampler/acme/v3"

Note the /v3 major version at the end. Due to the way modules function, this is the major version as represented in the go.mod file and latest git repo semver tag. All functions are still exported and called using the acme package name.

Examples

A simple certbot-like example is provided in the examples/certbot directory. This code demonstrates account registration, new order submission, fulfilling challenges, finalising an order and fetching the issued certificate chain.

An example of how to use the autocert package is also provided in examples/autocert.

Tests

The tests can be run against an instance of boulder or pebble.

Challenge fulfilment is designed to use the new challtestsrv server present inside boulder and pebble which responds to dns queries and challenges as required.

To run tests against an already running instance of boulder or pebble, use the test target in the Makefile.

Some convenience targets for launching pebble/boulder using their respective docker compose files have also been included in the Makefile.

# Functions

EncodeDNS01KeyAuthorization encodes a key authorization and provides a value to be put in the TXT record for the _acme-challenge DNS entry.
GenerateARICertID constructs a certificate identifier as described in draft-ietf-acme-ari-03, section 4.1.
JWKThumbprint creates a JWK thumbprint out of pub as specified in https://tools.ietf.org/html/rfc7638.
NewAcctOptAgreeTOS sets the new account request as agreeing to the terms of service.
NewAcctOptExternalAccountBinding adds an external account binding to the new account request Code adopted from jwsEncodeJSON.
NewAcctOptOnlyReturnExisting sets the new client request to only return existing accounts.
NewAcctOptWithContacts adds contacts to a new account request.
NewClient creates a new acme client given a valid directory url.
WhitelistHosts implements a simple whitelist HostCheck.
WithAcceptLanguage sets an Accept-Language header on http requests.
WithHTTPClient Allows setting a custom http client for acme connections.
WithHTTPTimeout sets a timeout on the http client used by the Client.
WithInsecureSkipVerify sets InsecureSkipVerify on the http client transport tls client config used by the Client.
WithRetryCount sets the number of times the acme client retries when receiving an api error (eg, nonce failures, etc).
WithRootCerts sets the httpclient transport to use a given certpool for root certs.
WithUserAgentSuffix appends a user agent suffix for http requests to acme resources.

# Constants

Different possible challenge types provided by an ACME server.
Different possible challenge types provided by an ACME server.
Different possible challenge types provided by an ACME server.
Different possible challenge types provided by an ACME server.
ChallengeTypeTLSSNI01 is deprecated and should not be used.
LetsEncryptProduction holds the production directory url.
LetsEncryptStaging holds the staging directory url.
10.
3.
2.
6.
5.
1.
9.
8.
4.
0.
ZeroSSLProduction holds the ZeroSSL directory url.

# Variables

ErrRenewalInfoNotSupported is returned by Client.GetRenewalInfo if the renewal info entry isn't present on the acme directory (ie, it's not supported by the acme server).
ErrUnsupportedKey is returned when an unsupported key type is encountered.

# Structs

Account structure representing fields in an account object.
Authorization object returned when fetching an authorization in an order.
AutoCert is a stateful certificate manager for issuing certificates on connecting hosts.
Challenge object fetched in an authorization or directly from the challenge url.
Client structure to interact with an ACME server.
Directory object as returned from the client's directory url upon creation of client.
ExternalAccountBinding holds the key identifier and mac key provided for use in servers that support/require external account binding.
Identifier object used in order and authorization objects See https://tools.ietf.org/html/rfc8555#section-7.1.4.
NewAccountRequest object used for submitting a request for a new account.
Order object returned when fetching or creating a new order.
OrderList of challenge objects.
Problem represents an error returned by an acme server.
RenewalInfo stores the server-provided suggestions on when to renew certificates.
No description provided by the author

# Type aliases

HostCheck function prototype to implement for checking hosts against before issuing certificates.
KeyID is the account key identity provided by a CA during registration.
NewAccountOptionFunc function prototype for passing options to NewClient.
OptionFunc function prototype for passing options to NewClient.