Add extract_altnames() function

[andy/dehydrated.git] / README.md

diff --git a/README.md b/README.md
index a59ae0471586675e3e43cf6a5fc214a1112d0971..91700e95de0b79cedfebd66e76794e9b23ddea2c 100644 (file)
--- a/README.md
+++ b/README.md
@@ -4,16 +4,15 @@ This is a client for signing certificates with an ACME-server (currently only pr
 
 It uses the `openssl` utility for everything related to actually handling keys and certificates, so you need to have that installed.
 
 
 It uses the `openssl` utility for everything related to actually handling keys and certificates, so you need to have that installed.
 

-Other dependencies are (for now): curl, sed
-
-Perl no longer is a dependency.
-The only remaining perl code in this repository is the script you can use to convert your existing letsencrypt-keyfile into something openssl (and this script) can read.
+Other dependencies are: curl, sed, grep, mktemp (all found on almost any system, curl being the only exception)

 
 Current features:
 - Signing of a list of domains
 
 Current features:
 - Signing of a list of domains

-- Renewal if a certificate is about to expire
+- Renewal if a certificate is about to expire or SAN (subdomains) changed

 - Certificate revocation
 
 - Certificate revocation
 

+If you want to import existing keys from the official letsencrypt client have a look at [Import from official letsencrypt client](https://github.com/lukas2511/letsencrypt.sh/wiki/Import-from-official-letsencrypt-client).
+

 Please keep in mind that this software and even the acme-protocol are relatively young and may still have some unresolved issues.
 Feel free to report any issues you find with this script or contribute by submitting a pullrequest.
 
 Please keep in mind that this software and even the acme-protocol are relatively young and may still have some unresolved issues.
 Feel free to report any issues you find with this script or contribute by submitting a pullrequest.
 


@@ -22,18 +21,21 @@ Feel free to report any issues you find with this script or contribute by submit
 ```text
 Usage: ./letsencrypt.sh [-h] [command [argument]] [parameter [argument]] [parameter [argument]] ...
 
 ```text
 Usage: ./letsencrypt.sh [-h] [command [argument]] [parameter [argument]] [parameter [argument]] ...
 

-Default command: cron
+Default command: help

 
 Commands:
 
 Commands:

- --cron (-c)                      Sign/renew non-existant/changed(TODO)/expiring certificates.
- --sign (-s) domain.tld           Force-sign specific certificate from domains.txt, even if not yet expiring or changed.
+ --cron (-c)                      Sign/renew non-existant/changed/expiring certificates.

  --revoke (-r) path/to/cert.pem   Revoke specified certificate
  --help (-h)                      Show help text
  --env (-e)                       Output configuration variables for use in other scripts
 
 Parameters:
  --revoke (-r) path/to/cert.pem   Revoke specified certificate
  --help (-h)                      Show help text
  --env (-e)                       Output configuration variables for use in other scripts
 
 Parameters:

- --config (-f) path/to/config.sh  Use specified config file
+ --domain (-d) domain.tld         Use specified domain name(s) instead of domains.txt entry (one certificate!)
+ --force (-x)                     Force renew of certificate even if it is longer valid than value in RENEW_DAYS

  --privkey (-p) path/to/key.pem   Use specified private key instead of account key (useful for revocation)
  --privkey (-p) path/to/key.pem   Use specified private key instead of account key (useful for revocation)

+ --config (-f) path/to/config.sh  Use specified config file
+ --hook (-k) path/to/hook.sh      Use specified script for hooks
+ --challenge (-t) http-01|dns-01  Which challenge should be used? Currently http-01 and dns-01 are supported

 ```
 
 ### domains.txt
 ```
 
 ### domains.txt


@@ -48,35 +50,41 @@ example.net www.example.net wiki.example.net
 This states that there should be two certificates `example.com` and `example.net`,
 with the other domains in the corresponding line being their alternative names.
 
 This states that there should be two certificates `example.com` and `example.net`,
 with the other domains in the corresponding line being their alternative names.
 

-### example nginx config
+### $WELLKNOWN / challenge-response
+
+Boulder (acme-server) is looking for challenge responses under your domain in the `.well-known/acme-challenge` directory
+
+This script uses `http-01`-type verification (for now) so you need to have that directory available over normal http (no ssl).

 
 

-If you want to use nginx you can set up a location block to serve your challenge responses:
+A full URL would look like `http://example.org/.well-known/acme-challenge/c3VjaC1jaGFsbGVuZ2UtbXVjaA-aW52YWxpZC13b3c`.

 
 

+An example setup to get this to work would be:
+
+nginx.conf:

 ```
 ```

+...

 location /.well-known/acme-challenge {
 location /.well-known/acme-challenge {

-  root /var/www/letsencrypt;
+  alias /var/www/letsencrypt;

 }
 }

+...

 ```
 
 ```
 

-For this to work i'd suggest either configuring `/var/www/letsencrypt` as WELLKNOWN directory,
-or to create a symlink to the default location next to the script: `ln -s /var/www/letsencrypt .acme-challenges`
-
-## Import
-
-### import-account.pl
-
-This perl-script can be used to import the account key from the original letsencrypt client.
+config.sh:
+```bash
+...
+WELLKNOWN="/var/www/letsencrypt"
+...
+```

 
 

-You should copy `private_key.json` to the same directory as the script.
-The json-file can be found in a subdirectory of `/etc/letsencrypt/accounts/acme-v01.api.letsencrypt.org/directory`.
+An alternative to setting the WELLKNOWN variable would be to create a symlink to the default location next to the script (or BASEDIR):
+`ln -s /var/www/letsencrypt .acme-challenges`

 
 

-Usage: `./import-account.pl`
+### dns-01 challenge

 
 

-### import-certs.sh
+This script also supports the new `dns-01`-type verification. Be aware that at the moment this is not available on the production servers from letsencrypt. Please read https://community.letsencrypt.org/t/dns-challenge-is-in-staging/8322 for the current state of `dns-01` support.

 
 

-This script can be used to import private keys and certificates created by the original letsencrypt client.
+You need a hook script that deploys the challenge to your DNS server!

 
 

-By default it expects the certificates to be found under `/etc/letsencrypt`, which is the default output directory of the original client.
-You can change the path by setting LETSENCRYPT in your config file: ```LETSENCRYPT="/etc/letsencrypt"```.
+### Elliptic Curve Cryptography (ECC)

 
 

-Usage: `./import-certs.sh`
+This script also supports certificates with Elliptic Curve public keys! Be aware that at the moment this is not available on the production servers from letsencrypt. Please read https://community.letsencrypt.org/t/ecdsa-testing-on-staging/8809/ for the current state of ECC support.