2015-06-13 04:45:04 +02:00
# lego
2015-10-19 19:58:04 +02:00
Let's Encrypt client and ACME library written in Go
2015-06-13 04:45:04 +02:00
2015-10-19 01:02:44 +02:00
[![GoDoc ](https://godoc.org/github.com/xenolf/lego/acme?status.svg )](https://godoc.org/github.com/xenolf/lego/acme)
2015-06-13 21:23:27 +02:00
[![Build Status ](https://travis-ci.org/xenolf/lego.svg?branch=master )](https://travis-ci.org/xenolf/lego)
2015-12-24 00:23:21 +02:00
[![Dev Chat ](https://img.shields.io/badge/dev%20chat-gitter-blue.svg?label=dev+chat )](https://gitter.im/xenolf/lego)
2015-06-13 21:23:27 +02:00
2015-12-15 23:27:41 +02:00
#### General
This is a work in progress. Please do *NOT* run this on a production server and please report any bugs you find!
2015-06-13 04:45:04 +02:00
2015-12-15 23:27:41 +02:00
#### 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 ](https://github.com/xenolf/lego/releases )
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
```
2015-10-20 22:55:00 +02:00
2015-10-19 01:02:44 +02:00
#### Current Status
2015-10-19 19:58:04 +02:00
The code in this repository is under development.
Current features:
- [x] Registering with a CA
- [x] Requesting Certificates
- [x] Renewing Certificates
- [x] Revoking Certificates
- [ ] Initiating account recovery
- Identifier validation challenges
2015-11-14 18:35:31 +02:00
- [x] HTTP (http-01)
2015-11-20 01:34:40 +02:00
- [x] TLS with Server Name Indication (tls-sni-01)
2015-11-14 18:35:31 +02:00
- [ ] Proof of Possession of a Prior Key (proofOfPossession-01)
2016-01-25 23:12:41 +02:00
- [x] DNS (dns-01)
2015-10-25 02:15:58 +02:00
- [x] Certificate bundling
- [x] Library support for OCSP
2015-06-13 04:45:04 +02:00
Please keep in mind that CLI switches and APIs are still subject to change.
2016-01-09 00:43:36 +02:00
When using the standard `--path` option, all certificates and account configurations are saved to a folder *.lego* in the current working directory.
2015-06-13 04:45:04 +02:00
2015-10-19 01:02:44 +02:00
#### Sudo
2015-12-15 23:27:41 +02:00
The CLI does not require root permissions but needs to bind to port 80 and 443 for certain challenges.
2015-06-13 04:45:04 +02:00
To run the CLI without sudo, you have two options:
2015-12-15 23:27:41 +02:00
- Use setcap 'cap_net_bind_service=+ep' /path/to/program
2016-01-09 00:43:36 +02:00
- Pass the `--http` or/and the `--tls` 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 )).
2015-12-15 23:27:41 +02:00
#### Port Usage
By default lego assumes it is able to bind to ports 80 and 443 to solve challenges.
2016-01-09 00:43:36 +02:00
If this is not possible in your environment, you can use the `--http` and `--tls` options to instruct
lego to listen on that interface:port for any incoming challenges.
2015-12-15 23:27:41 +02:00
2015-12-27 21:34:30 +02:00
If you are using this option, make sure you proxy all of the following traffic to these ports.
HTTP Port:
2015-12-20 13:38:38 +02:00
- All plaintext HTTP requests to port 80 which begin with a request path of `/.well-known/acme-challenge/` for the HTTP-01 challenge.
2015-12-27 21:34:30 +02:00
TLS Port:
2015-12-15 23:27:41 +02:00
- 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.
2015-06-13 04:45:04 +02:00
#### Usage
```
NAME:
lego - Let's encrypt client to go!
USAGE:
2015-10-19 19:58:04 +02:00
./lego [global options] command [command options] [arguments...]
2015-12-03 21:04:55 +02:00
2015-06-13 04:45:04 +02:00
VERSION:
2015-12-27 21:34:30 +02:00
0.2.0
2015-12-03 21:04:55 +02:00
2015-06-13 04:45:04 +02:00
COMMANDS:
2015-10-19 19:58:04 +02:00
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
2015-12-03 21:04:55 +02:00
2015-06-13 04:45:04 +02:00
GLOBAL OPTIONS:
2015-10-19 19:58:04 +02:00
--domains, -d [--domains option --domains option] Add domains to the process
2015-12-03 21:04:55 +02:00
--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.
2015-10-19 19:58:04 +02:00
--email, -m Email used for registration and recovery contact.
--rsa-key-size, -B "2048" Size of the RSA key.
2016-01-30 03:43:35 +02:00
--path "{$CWD}/.lego" Directory to use for storing the data
2015-12-27 21:34:30 +02:00
--exclude, -x [--exclude option --exclude option] Explicitly disallow solvers by name from being used. Solvers: "http-01", "tls-sni-01".
2016-01-30 03:43:35 +02:00
--http Set the port and interface to use for HTTP based challenges to listen on. Supported: interface:port or :port
--tls Set the port and interface to use for TLS based challenges to listen on. Supported: interface:port or :port
--dns Enable the DNS challenge for solving using a provider.
Credentials for providers have to be passed through environment variables.
For a more detailed explanation of the parameters, please see the online docs.
Valid providers:
cloudflare: CLOUDFLARE_EMAIL, CLOUDFLARE_API_KEY
digitalocean: DO_AUTH_TOKEN
dnsimple: DNSIMPLE_EMAIL, DNSIMPLE_API_KEY
route53: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
rfc2136: RFC2136_TSIG_KEY, RFC2136_TSIG_SECRET, RFC2136_NAMESERVER, RFC2136_ZONE
manual: none
2015-10-19 19:58:04 +02:00
--help, -h show help
--version, -v print the version
2015-11-01 01:29:01 +02:00
2016-01-30 03:43:35 +02:00
2015-06-13 04:45:04 +02:00
```
2015-10-17 23:02:52 +02:00
2015-12-08 04:33:40 +02:00
##### 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 ](https://github.com/xenolf/lego/releases ) page.
2015-12-15 23:27:41 +02:00
If your environment does not allow you to bind to these ports, please read [Port Usage ](#port-usage ).
2015-12-08 04:33:40 +02:00
Obtain a certificate:
```bash
$ lego --email="foo@bar.com" --domains="example.com" run
```
(Find your certificate in the `.lego` folder of current working directory.)
To renew the certificate:
```bash
$ lego --email="foo@bar.com" --domains="example.com" renew
```
2015-10-17 23:02:52 +02:00
#### ACME Library Usage
A valid, but bare-bones example use of the acme package:
```go
// 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.
2015-10-17 23:07:14 +02:00
const rsaKeySize = 2048
2015-10-17 23:02:52 +02:00
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.
2015-12-27 21:34:30 +02:00
client, err := acme.NewClient("http://192.168.99.100:4000", & myUser, rsaKeySize)
2015-12-07 13:18:58 +02:00
if err != nil {
2015-10-28 01:00:42 +02:00
log.Fatal(err)
}
2015-10-17 23:02:52 +02:00
2016-01-09 00:43:36 +02:00
// We specify an http port of 5002 and an tls port of 5001 on all interfaces because we aren't running as
2015-12-27 21:34:30 +02:00
// 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.
2016-01-09 00:43:36 +02:00
client.SetHTTPAddress(":5002")
client.SetTLSAddress(":5001")
2015-12-27 21:34:30 +02:00
2015-10-17 23:02:52 +02:00
// 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.
2015-10-23 10:15:57 +02:00
err = client.AgreeToTOS()
2015-10-17 23:02:52 +02:00
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.
2015-12-07 13:21:54 +02:00
bundle := false
2016-01-24 13:47:13 +02:00
certificates, failures := client.ObtainCertificate([]string{"mydomain.com"}, bundle, nil)
if len(failures) > 0 {
log.Fatal(failures)
2015-10-17 23:02:52 +02:00
}
2015-10-19 01:02:44 +02:00
// Each certificate comes back with the cert bytes, the bytes of the client's
2015-10-17 23:02:52 +02:00
// private key, and a certificate URL. This is where you should save them to files!
fmt.Printf("%#v\n", certificates)
// ... all done.
```