1193ae895a
Implement custom User-Agent string |
||
---|---|---|
acme | ||
.gitignore | ||
.travis.yml | ||
account.go | ||
CHANGELOG.md | ||
cli.go | ||
cli_handlers.go | ||
configuration.go | ||
crypto.go | ||
LICENSE | ||
README.md |
lego
Let's Encrypt client and ACME library written in Go
General
This is a work in progress. Please do NOT run this on a production server and please report any bugs you find!
Installation
lego supports both binary installs and install from source.
To get the binary just download the latest release for your OS/Arch from the release page and put the binary somewhere convenient. lego does not assume anything about the location you run it from.
To install from source, just run
go get -u github.com/xenolf/lego
Current Status
The code in this repository is under development.
Current features:
- Registering with a CA
- Requesting Certificates
- Renewing Certificates
- Revoking Certificates
- Initiating account recovery
- Identifier validation challenges
- HTTP (http-01)
- TLS with Server Name Indication (tls-sni-01)
- Proof of Possession of a Prior Key (proofOfPossession-01)
- DNS (dns-01) - Implemented in branch, blocked by upstream.
- Certificate bundling
- Library support for OCSP
Please keep in mind that CLI switches and APIs are still subject to change.
When using the standard --path option, all certificates and account configurations are saved to a folder .lego in the current working directory.
Sudo
The CLI does not require root permissions but needs to bind to port 80 and 443 for certain challenges. To run the CLI without sudo, you have two options:
- Use setcap 'cap_net_bind_service=+ep' /path/to/program
- Pass the
--httpPort
or/and the--tlsPort
option and specify a custom port to bind to. In this case you have to forward port 80/443 to these custom ports (see Port Usage).
Port Usage
By default lego assumes it is able to bind to ports 80 and 443 to solve challenges.
If this is not possible in your environment, you can use the --httpPort
and --tlsPort
options to instruct
lego to listen on that port for any incoming challenges.
If you are using this option, make sure you proxy all of the following traffic to these ports.
HTTP Port:
- All plaintext HTTP requests to port 80 which begin with a request path of
/.well-known/acme-challenge/
for the HTTP-01 challenge.
TLS Port:
- All TLS handshakes on port 443 for TLS-SNI-01.
This traffic redirection is only needed as long as lego solves challenges. As soon as you have received your certificates you can deactivate the forwarding.
Usage
NAME:
lego - Let's encrypt client to go!
USAGE:
./lego [global options] command [command options] [arguments...]
VERSION:
0.2.0
COMMANDS:
run Register an account, then create and install a certificate
revoke Revoke a certificate
renew Renew a certificate
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--domains, -d [--domains option --domains option] Add domains to the process
--server, -s "https://acme-v01.api.letsencrypt.org/directory" CA hostname (and optionally :port). The server certificate must be trusted in order to avoid further modifications to the client.
--email, -m Email used for registration and recovery contact.
--rsa-key-size, -B "2048" Size of the RSA key.
--path "${CWD}" Directory to use for storing the data
--exclude, -x [--exclude option --exclude option] Explicitly disallow solvers by name from being used. Solvers: "http-01", "tls-sni-01".
--httpPort Set the port to use for HTTP based challenges to listen on.
--tlsPort Set the port to use for TLS based challenges to listen on.
--help, -h show help
--version, -v print the version
CLI Example
Assumes the lego
binary has permission to bind to ports 80 and 443. You can get a pre-built binary from the releases page.
If your environment does not allow you to bind to these ports, please read Port Usage.
Obtain a certificate:
$ lego --email="foo@bar.com" --domains="example.com" run
(Find your certificate in the .lego
folder of current working directory.)
To renew the certificate:
$ lego --email="foo@bar.com" --domains="example.com" renew
ACME Library Usage
A valid, but bare-bones example use of the acme package:
// You'll need a user or account type that implements acme.User
type MyUser struct {
Email string
Registration *acme.RegistrationResource
key *rsa.PrivateKey
}
func (u MyUser) GetEmail() string {
return u.Email
}
func (u MyUser) GetRegistration() *acme.RegistrationResource {
return u.Registration
}
func (u MyUser) GetPrivateKey() *rsa.PrivateKey {
return u.key
}
// Create a user. New accounts need an email and private key to start.
const rsaKeySize = 2048
privateKey, err := rsa.GenerateKey(rand.Reader, rsaKeySize)
if err != nil {
log.Fatal(err)
}
myUser := MyUser{
Email: "you@yours.com",
key: privateKey,
}
// A client facilitates communication with the CA server. This CA URL is
// configured for a local dev instance of Boulder running in Docker in a VM.
client, err := acme.NewClient("http://192.168.99.100:4000", &myUser, rsaKeySize)
if err != nil {
log.Fatal(err)
}
// We specify an httpPort of 5002 and an tlsPort of 5001 because we aren't running as
// root and can't bind a listener to port 80 and 443
// (used later when we attempt to pass challenges).
// Keep in mind that we still need to proxy challenge traffic to port 5002 and 5001.
client.SetHTTPPort("5002")
client.SetTLSPort("5001")
// New users will need to register; be sure to save it
reg, err := client.Register()
if err != nil {
log.Fatal(err)
}
myUser.Registration = reg
// The client has a URL to the current Let's Encrypt Subscriber
// Agreement. The user will need to agree to it.
err = client.AgreeToTOS()
if err != nil {
log.Fatal(err)
}
// The acme library takes care of completing the challenges to obtain the certificate(s).
// Of course, the hostnames must resolve to this machine or it will fail.
bundle := false
certificates, err := client.ObtainCertificates([]string{"mydomain.com"}, bundle)
if err != nil {
log.Fatal(err)
}
// Each certificate comes back with the cert bytes, the bytes of the client's
// private key, and a certificate URL. This is where you should save them to files!
fmt.Printf("%#v\n", certificates)
// ... all done.