go/lego
go/lego
1
0
Fork 0
mirror of https://github.com/go-acme/lego.git synced 2024-12-23 01:07:23 +02:00
Code Issues Releases Activity

Prepare release v1.0.0 (#559)

Browse Source 
* Prepare release v1.0.0

* review: remove infrastructure items from CHANGELOG.md

* review: updated CHANGELOG.md message

* review: added ACME v1 reference in README.md

* review: README.md updates

* review: removed experimental note
This commit is contained in:
Wyatt Johnson 2018-05-30 18:03:08 -06:00 committed by GitHub
parent 6004e599ed
commit fefeb24353
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 78 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
CHANGELOG.md
View File

@ -1,5 +1,13 @@
# Changelog # Changelog
## [v1.0.0] - 2018-05-30
### Changed:
- **[lib]** ACME v2 Support.
- **[dnsprovider]** Renamed `/providers/dns/googlecloud` to `/providers/dns/gcloud`.
- **[dnsprovider]** Modified Google Cloud provider `gcloud.NewDNSProviderServiceAccount` function to extract the project id directly from the service account file.
- **[dnsprovider]** Made errors more verbose for the Cloudflare provider.
## [v0.5.0] - 2018-05-29 ## [v0.5.0] - 2018-05-29
### Added: ### Added:

121
README.md
View File

@ -1,4 +1,5 @@
# lego # lego
Let's Encrypt client and ACME library written in Go Let's Encrypt client and ACME library written in Go
[![GoDoc](https://godoc.org/github.com/xenolf/lego/acme?status.svg)](https://godoc.org/github.com/xenolf/lego/acme) [![GoDoc](https://godoc.org/github.com/xenolf/lego/acme?status.svg)](https://godoc.org/github.com/xenolf/lego/acme)
@ -6,37 +7,47 @@ Let's Encrypt client and ACME library written in Go
[![Dev Chat](https://img.shields.io/badge/dev%20chat-gitter-blue.svg?label=dev+chat)](https://gitter.im/xenolf/lego) [![Dev Chat](https://img.shields.io/badge/dev%20chat-gitter-blue.svg?label=dev+chat)](https://gitter.im/xenolf/lego)
[![Beerpay](https://beerpay.io/xenolf/lego/badge.svg)](https://beerpay.io/xenolf/lego) [![Beerpay](https://beerpay.io/xenolf/lego/badge.svg)](https://beerpay.io/xenolf/lego)
#### General ## Installation
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. 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) 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. and put the binary somewhere convenient. lego does not assume anything about the location you run it from.
To install from source, just run To install from source, just run:
```
```bash
go get -u github.com/xenolf/lego go get -u github.com/xenolf/lego
``` ```
To build lego inside a Docker container, just run To build lego inside a Docker container, just run
```
```bash
docker build -t lego . docker build -t lego .
``` ```
The container is, by default, built from `master`. That will build lego from the current source, if you want to build a different
This can be overridden by supplying a build argument containing a git SHA or reference. version, you can checkout the desired branch/tag/commit, and re-running the
above mentioned command.
If you want to tag the binary with the designated release, you can do so by
passing the version identifier as a [`--build-arg`](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg)
```bash ```bash
docker build --build-arg LEGO_VERSION=tags/v0.5.0 -t lego . docker build --build-arg LEGO_VERSION=v1.0.0 -t lego .
``` ```
##### From the package manager Otherwise the release will be tagged with the `dev` version identifier.
### From the package manager
- [ArchLinux (AUR)](https://aur.archlinux.org/packages/lego-git): - [ArchLinux (AUR)](https://aur.archlinux.org/packages/lego-git):
```
yaourt -S lego-git ```bash
``` yaourt -S lego-git
#### Features ```
## Features
- Register with CA - Register with CA
- Obtain certificates, both from scratch or with an existing CSR - Obtain certificates, both from scratch or with an existing CSR
@ -55,33 +66,9 @@ 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. When using the standard `--path` option, all certificates and account configurations are saved to a folder *.lego* in the current working directory.
#### Sudo ## Usage
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 four options:
- Use setcap 'cap_net_bind_service=+ep' /path/to/program ```text
- 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)).
- Pass the `--webroot` option and specify the path to your webroot folder. In this case the challenge will be written in a file in `.well-known/acme-challenge/` inside your webroot.
- Pass the `--dns` option and specify a DNS provider.
#### 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 `--http` and `--tls` options to instruct
lego to listen on that interface: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 challenge.
TLS Port:
- All TLS handshakes on port 443 for the TLS-SNI challenge.
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: NAME:
lego - Let's Encrypt client written in Go lego - Let's Encrypt client written in Go
@ -119,7 +106,35 @@ GLOBAL OPTIONS:
--version, -v print the version --version, -v print the version
``` ```
##### CLI Example ### 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 four options:
- Use setcap 'cap_net_bind_service=+ep' /path/to/program
- 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)).
- Pass the `--webroot` option and specify the path to your webroot folder. In this case the challenge will be written in a file in `.well-known/acme-challenge/` inside your webroot.
- Pass the `--dns` option and specify a DNS provider.
### 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 `--http` and `--tls` options to instruct
lego to listen on that interface: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 challenge.
TLS Port:
- All TLS handshakes on port 443 for the TLS-SNI challenge.
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.
### 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. 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.
If your environment does not allow you to bind to these ports, please read [Port Usage](#port-usage). If your environment does not allow you to bind to these ports, please read [Port Usage](#port-usage).
@ -127,7 +142,7 @@ If your environment does not allow you to bind to these ports, please read [Port
Obtain a certificate: Obtain a certificate:
```bash ```bash
$ lego --email="foo@bar.com" --domains="example.com" run lego --email="foo@bar.com" --domains="example.com" run
``` ```
(Find your certificate in the `.lego` folder of current working directory.) (Find your certificate in the `.lego` folder of current working directory.)
@ -135,19 +150,19 @@ $ lego --email="foo@bar.com" --domains="example.com" run
To renew the certificate: To renew the certificate:
```bash ```bash
$ lego --email="foo@bar.com" --domains="example.com" renew lego --email="foo@bar.com" --domains="example.com" renew
``` ```
To renew the certificate only if it's older than 30 days To renew the certificate only if it's older than 30 days
```bash ```bash
$ lego --email="foo@bar.com" --domains="example.com" renew --days 30 lego --email="foo@bar.com" --domains="example.com" renew --days 30
``` ```
Obtain a certificate using the DNS challenge and AWS Route 53: Obtain a certificate using the DNS challenge and AWS Route 53:
```bash ```bash
$ AWS_REGION=us-east-1 AWS_ACCESS_KEY_ID=my_id AWS_SECRET_ACCESS_KEY=my_key lego --email="foo@bar.com" --domains="example.com" --dns="route53" run AWS_REGION=us-east-1 AWS_ACCESS_KEY_ID=my_id AWS_SECRET_ACCESS_KEY=my_key lego --email="foo@bar.com" --domains="example.com" --dns="route53" run
``` ```
Note that `--dns=foo` implies `--exclude=http-01`. lego will not attempt other challenges if you've told it to use DNS instead. Note that `--dns=foo` implies `--exclude=http-01`. lego will not attempt other challenges if you've told it to use DNS instead.
@ -155,7 +170,7 @@ Note that `--dns=foo` implies `--exclude=http-01`. lego will not attempt other c
Obtain a certificate given a certificate signing request (CSR) generated by something else: Obtain a certificate given a certificate signing request (CSR) generated by something else:
```bash ```bash
$ lego --email="foo@bar.com" --csr=/path/to/csr.pem run lego --email="foo@bar.com" --csr=/path/to/csr.pem run
``` ```
(lego will infer the domains to be validated based on the contents of the CSR, so make sure the CSR's Common Name and optional SubjectAltNames are set correctly.) (lego will infer the domains to be validated based on the contents of the CSR, so make sure the CSR's Common Name and optional SubjectAltNames are set correctly.)
@ -163,12 +178,12 @@ $ lego --email="foo@bar.com" --csr=/path/to/csr.pem run
lego defaults to communicating with the production Let's Encrypt ACME server. If you'd like to test something without issuing real certificates, consider using the staging endpoint instead: lego defaults to communicating with the production Let's Encrypt ACME server. If you'd like to test something without issuing real certificates, consider using the staging endpoint instead:
```bash ```bash
$ lego --server=https://acme-staging.api.letsencrypt.org/directory … lego --server=https://acme-staging.api.letsencrypt.org/directory …
``` ```
#### DNS Challenge API Details ## DNS Challenge API Details
##### AWS Route 53 ### AWS Route 53
The following AWS IAM policy document describes the permissions required for lego to complete the DNS challenge. The following AWS IAM policy document describes the permissions required for lego to complete the DNS challenge.
Replace `<INSERT_YOUR_HOSTED_ZONE_ID_HERE>` with the Route 53 zone ID of the domain you are authorizing. Replace `<INSERT_YOUR_HOSTED_ZONE_ID_HERE>` with the Route 53 zone ID of the domain you are authorizing.
@ -200,7 +215,7 @@ Replace `<INSERT_YOUR_HOSTED_ZONE_ID_HERE>` with the Route 53 zone ID of the dom
} }
``` ```
#### ACME Library Usage ## ACME Library Usage
A valid, but bare-bones example use of the acme package: A valid, but bare-bones example use of the acme package:
@ -240,7 +255,7 @@ if err != nil {
} }
// We specify an http port of 5002 and an tls port of 5001 on all interfaces // We specify an http port of 5002 and an tls port of 5001 on all interfaces
// because we aren't running as root and can't bind a listener to port 80 and 443 // 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 // (used later when we attempt to pass challenges). Keep in mind that we still
// need to proxy challenge traffic to port 5002 and 5001. // need to proxy challenge traffic to port 5002 and 5001.
client.SetHTTPAddress(":5002") client.SetHTTPAddress(":5002")
@ -276,3 +291,7 @@ fmt.Printf("%#v\n", certificates)
// ... all done. // ... all done.
``` ```
## ACME v1
lego introduced support for ACME v2 in [v1.0.0](https://github.com/xenolf/lego/releases/tag/v1.0.0), if you still need to utilize ACME v1, you can do so by using the [v0.5.0](https://github.com/xenolf/lego/releases/tag/v0.5.0) version.