greenlock.js-ARCHIVED/README.md

302 lines
10 KiB
Markdown
Raw Normal View History

2015-12-11 11:23:47 +00:00
letsencrypt
===========
2015-12-14 19:37:22 +00:00
Automatic [Let's Encrypt](https://letsencrypt.org) HTTPS Certificates for node.js
2015-12-11 11:23:47 +00:00
* [Automatic HTTPS with ExpressJS](https://github.com/Daplie/letsencrypt-express)
* [Automatic live renewal](https://github.com/Daplie/letsencrypt-express#how-automatic)
* On-the-fly HTTPS certificates for Dynamic DNS (in-process, no server restart)
* Works with node cluster out of the box
* usable [via commandline](https://github.com/Daplie/letsencrypt-cli) as well
2015-12-13 06:40:03 +00:00
* Free SSL (HTTPS Certificates for TLS)
* [90-day certificates](https://letsencrypt.org/2015/11/09/why-90-days.html)
2015-12-12 13:11:05 +00:00
2015-12-13 09:04:44 +00:00
**See Also**
* [Let's Encrypt in (exactly) 90 seconds with Caddy](https://daplie.com/articles/lets-encrypt-in-literally-90-seconds/)
* [lego](https://github.com/xenolf/lego): Let's Encrypt for golang
2016-04-18 17:01:35 +00:00
STOP
====
**These aren't the droids you're looking for.**
This is a low-level library for implementing CLIs,
system tools, and abstracting storage backends (file vs db, etc).
This is not the thing to use in your webserver directly.
2016-04-18 17:27:55 +00:00
### Use [letsencrypt-express](https://github.com/Daplie/letsencrypt-express) if...
you are planning to use one of these:
2016-04-18 17:01:35 +00:00
* `express`
* `connect`
* raw `https`
* raw `spdy`
2016-04-19 04:43:28 +00:00
* `restify` (same as raw https)
* `hapi` See [letsencrypt-hapi](https://github.com/Daplie/letsencrypt-hapi)
* `koa` See [letsencrypt-koa](https://github.com/Daplie/letsencrypt-koa)
* `rill` (similar to koa example)
2016-04-18 17:01:35 +00:00
2016-04-18 17:27:55 +00:00
### Use [letsencrypt-cli](https://github.com/Daplie/letsencrypt-cli) if...
2016-04-18 17:01:35 +00:00
2016-04-18 17:27:55 +00:00
You are planning to use one of these:
2016-04-18 17:26:15 +00:00
* `bash`
* `fish`
* `zsh`
* `cmd.exe`
* `PowerShell`
2015-12-12 13:11:05 +00:00
Install
=======
```bash
npm install --save letsencrypt
```
2015-12-13 09:04:44 +00:00
Usage
=====
2015-12-12 22:16:02 +00:00
2016-04-18 17:26:15 +00:00
### letsencrypt
2015-12-12 22:16:02 +00:00
2016-04-18 17:26:15 +00:00
There are **NO DEFAULTS**.
2015-12-16 13:07:56 +00:00
2016-04-18 17:26:15 +00:00
A number of **constants** (such as LE.stagingServerUrl and LE.configDir)
2015-12-17 10:38:46 +00:00
are exported for your convenience, but all required options must be specified by the library invoking the call.
Open an issue if you need a variable for something that isn't there yet.
2015-12-13 11:09:06 +00:00
```javascript
2015-12-17 10:38:46 +00:00
var LE = require('letsencrypt');
2015-12-13 09:04:44 +00:00
2015-12-17 10:38:46 +00:00
var config = {
, server: LE.stagingServerUrl // or LE.productionServerUrl
, configDir: require('homedir')() + '/letsencrypt/etc' // or /etc/letsencrypt or wherever
, privkeyPath: ':config/live/:hostname/privkey.pem' //
, fullchainPath: ':config/live/:hostname/fullchain.pem' // Note: both that :config and :hostname
, certPath: ':config/live/:hostname/cert.pem' // will be templated as expected
, chainPath: ':config/live/:hostname/chain.pem' //
, debug: false
};
var handlers = {
setChallenge: function (opts, hostname, key, val, cb) {} // called during the ACME server handshake, before validation
, removeChallenge: function (opts, hostname, key, cb) {} // called after validation on both success and failure
, getChallenge: function (opts, hostname, key, cb) {} // this is special because it is called by the webserver
// (see letsencrypt-cli/bin & letsencrypt-express/standalone),
// not by the library itself
, agreeToTerms: function (tosUrl, cb) {} // gives you an async way to expose the legal agreement
// (terms of use) to your users before accepting
};
var le = LE.create(config, handlers);
// checks :conf/renewal/:hostname.conf
le.register({ // and either renews or registers
domains: ['example.com'] // CHANGE TO YOUR DOMAIN
, email: 'user@email.com' // CHANGE TO YOUR EMAIL
, agreeTos: false // set to true to automatically accept an agreement
// which you have pre-approved (not recommended)
2015-12-13 09:04:44 +00:00
}, function (err) {
2015-12-17 10:38:46 +00:00
2015-12-13 09:04:44 +00:00
if (err) {
2015-12-17 10:38:46 +00:00
// Note: you must have a webserver running
// and expose handlers.getChallenge to it
// in order to pass validation
// See letsencrypt-cli and or letsencrypt-express
2015-12-13 09:04:44 +00:00
console.error('[Error]: node-letsencrypt/examples/standalone');
console.error(err.stack);
} else {
console.log('success');
}
2015-12-12 22:16:02 +00:00
});
```
**However**, due to the nature of what this library does, it has a few more "moving parts"
2015-12-12 22:16:44 +00:00
than what makes sense to show in a minimal snippet.
2015-12-12 22:16:02 +00:00
API
===
2015-12-12 13:11:05 +00:00
2015-12-13 09:04:44 +00:00
```javascript
2016-04-18 17:26:15 +00:00
LetsEncrypt.create(leConfig, handlers, backend) // wraps a given "backend" (the python or node client)
2015-12-16 09:11:31 +00:00
LetsEncrypt.stagingServer // string of staging server for testing
le.middleware() // middleware for serving webrootPath to /.well-known/acme-challenge
le.sniCallback(hostname, function (err, tlsContext) {}) // uses fetch (below) and formats for https.SNICallback
le.register({ domains, email, agreeTos, ... }, cb) // registers or renews certs for a domain
le.fetch({domains, email, agreeTos, ... }, cb) // fetches certs from in-memory cache, occasionally refreshes from disk
le.validate(domains, cb) // do some sanity checks before attempting to register
le.registrationFailureCallback(err, args, certInfo, cb) // called when registration fails (not implemented yet)
2015-12-13 09:04:44 +00:00
```
2015-12-12 15:38:14 +00:00
2015-12-16 09:11:31 +00:00
### `LetsEncrypt.create(backend, leConfig, handlers)`
2015-12-12 22:06:36 +00:00
2015-12-16 09:11:31 +00:00
#### leConfig
2015-12-12 22:06:36 +00:00
The arguments passed here (typically `webpathRoot`, `configDir`, etc) will be merged with
2015-12-12 22:19:28 +00:00
any `args` (typically `domains`, `email`, and `agreeTos`) and passed to the backend whenever
it is called.
2015-12-12 22:06:36 +00:00
Typically the backend wrapper will already merge any necessary backend-specific arguments.
**Example**:
2015-12-12 13:11:05 +00:00
```javascript
2015-12-12 22:06:36 +00:00
{ webrootPath: __dirname, '/acme-challenge'
2015-12-12 13:11:05 +00:00
, fullchainTpl: '/live/:hostname/fullchain.pem'
, privkeyTpl: '/live/:hostname/fullchain.pem'
, configDir: '/etc/letsencrypt'
2015-12-12 22:06:36 +00:00
}
```
2015-12-12 13:11:05 +00:00
2015-12-13 01:04:12 +00:00
Note: `webrootPath` can be set as a default, semi-locally with `webrootPathTpl`, or per
2015-12-16 09:11:31 +00:00
registration as `webrootPath` (which overwrites `leConfig.webrootPath`).
2015-12-13 01:04:12 +00:00
2015-12-12 22:06:36 +00:00
#### handlers *optional*
2015-12-12 13:11:05 +00:00
2015-12-12 22:06:36 +00:00
`h.setChallenge(hostnames, name, value, cb)`:
2015-12-12 13:11:05 +00:00
2015-12-12 22:06:36 +00:00
default is to write to fs
2015-12-12 13:11:05 +00:00
2015-12-12 22:06:36 +00:00
`h.getChallenge(hostnames, value cb)`
2015-12-12 13:11:05 +00:00
2015-12-12 22:06:36 +00:00
default is to read from fs
`h.sniRegisterCallback(args, currentCerts, cb)`
The default is to immediately call `cb(null, null)` and register (or renew) in the background
during the `SNICallback` phase. Right now it isn't reasonable to renew during SNICallback,
but around February when it is possible to use ECDSA keys (as opposed to RSA at present),
registration will take very little time.
This will not be called while another registration is already in progress.
**SECURITY WARNING**: If you use this option with a custom `h.validate()`, make sure that `args.domains`
refers to domains you expect, otherwise an attacker will spoof SNI and cause your server to rate-limit
letsencrypt.org and get blocked. Note that `le.validate()` will check A records before attempting to
register to help prevent such possible attacks.
2015-12-12 13:11:05 +00:00
2015-12-12 22:06:36 +00:00
`h.validate(domains, cb)`
When specified this will override `le.validate()`. You will need to do this if the ip address of this
server is not one specified in the A records for your domain.
### `le.middleware()`
An express handler for `/.well-known/acme-challenge/<challenge>`.
Will call `getChallenge([hostname], key, cb)` if present or otherwise read `challenge` from disk.
Example:
```javascript
app.use('/', le.middleware())
2015-12-12 13:11:05 +00:00
```
2015-12-12 22:06:36 +00:00
### `le.sniCallback(hostname, function (err, tlsContext) {});`
Will call `fetch`. If fetch does not return certificates or returns expired certificates
it will call `sniRegisterCallback(args, currentCerts, cb)` and then return the error,
the new certificates, or call `fetch` a final time.
Example:
```javascript
2015-12-12 22:21:02 +00:00
var server = require('https').createServer({ SNICallback: le.sniCallback, cert: '...', key: '...' });
2015-12-12 22:06:36 +00:00
server.on('request', app);
2015-12-12 13:11:05 +00:00
```
2015-12-12 22:06:36 +00:00
### `le.register({ domains, email, agreeTos, ... }, cb)`
Get certificates for a domain
Example:
2015-12-12 22:17:32 +00:00
```javascript
2015-12-12 22:06:36 +00:00
le.register({
domains: ['example.com', 'www.example.com']
, email: 'user@example.com'
2015-12-13 01:04:12 +00:00
, webrootPath: '/srv/www/example.com/public'
2015-12-12 22:06:36 +00:00
, agreeTos: true
}, function (err, certs) {
// err is some error
console.log(certs);
/*
{ cert: "contents of fullchain.pem"
, key: "contents of privkey.pem"
, renewedAt: <date in milliseconds>
, duration: <duration in milliseconds (90-days)>
2015-12-12 13:11:05 +00:00
}
2015-12-12 22:06:36 +00:00
*/
});
2015-12-12 13:11:05 +00:00
```
2015-12-12 22:06:36 +00:00
### `le.isValidDomain(hostname)`
returns `true` if `hostname` is a valid ascii or punycode domain name.
(also exposed on the main exported module as `LetsEncrypt.isValidDomain()`)
### `le.validate(args, cb)`
Used internally, but exposed for convenience. Checks `LetsEncrypt.isValidDomain()`
2015-12-13 06:40:03 +00:00
and then checks to see that the current server
2015-12-12 22:06:36 +00:00
Called before `backend.register()` to validate the following:
* the hostnames don't use any illegal characters
* the server's actual public ip (via api.apiify.org)
2015-12-13 06:40:03 +00:00
* the A records for said hostnames
2015-12-12 22:06:36 +00:00
### `le.fetch(args, cb)`
Used internally, but exposed for convenience.
Checks in-memory cache of certificates for `args.domains` and calls then calls `backend.fetch(args, cb)`
**after** merging `args` if necessary.
2015-12-13 05:03:48 +00:00
### `le.registrationFailureCallback(err, args, certInfo, cb)`
Not yet implemented
2015-12-12 13:11:05 +00:00
This is what `args` looks like:
```javascript
{ domains: ['example.com', 'www.example.com']
, email: 'user@email.com'
, agreeTos: true
, configDir: '/etc/letsencrypt'
, fullchainTpl: '/live/:hostname/fullchain.pem' // :hostname will be replaced with the domainname
2015-12-13 01:04:12 +00:00
, privkeyTpl: '/live/:hostname/privkey.pem'
, webrootPathTpl: '/srv/www/:hostname/public'
, webrootPath: '/srv/www/example.com/public' // templated from webrootPathTpl
2015-12-12 13:11:05 +00:00
}
```
This is what the implementation should look like:
(it's expected that the client will follow the same conventions as
the python client, but it's not necessary)
2015-12-13 11:09:06 +00:00
Change History
==============
2016-04-18 17:01:35 +00:00
* v1.4.x I can't remember... but it's better!
2015-12-16 09:19:08 +00:00
* v1.1.0 Added letiny-core, removed node-letsencrypt-python
* v1.0.2 Works with node-letsencrypt-python
* v1.0.0 Thar be dragons
2015-12-13 11:09:06 +00:00
2015-12-11 11:23:47 +00:00
LICENSE
=======
Dual-licensed MIT and Apache-2.0
See LICENSE