AJ ONeal ca2e5cdb99 | ||
---|---|---|
examples | ||
test | ||
.gitignore | ||
LICENSE | ||
README.md | ||
index.js | ||
package.json |
README.md
Greenlock™ for Express.js
formerly letsencrypt-express
Free SSL, Free Wildcard SSL, and Fully Automated HTTPS made dead simple
certificates issued by Let's Encrypt v2 via ACME
| Sponsored by ppl | Greenlock™ is for Web Servers, Web Browsers, and node.js middleware systems.
Features
- Automatic HTTPS
- Free SSL
- Free Wildcard SSL
- Multiple domain support (up to 100 altnames per SAN)
- Dynamic Virtual Hosting (vhost)
- Automatical renewal (10 to 14 days before expiration)
- Great ACME support
- ACME draft 11
- Let's Encrypt v2
- Let's Encrypt v1
- Full node.js support
- Extensible Plugin Support
- AWS (S3, Route53)
- Azure
- CloudFlare
- Consul
- Digital Ocean
- etcd
- Redis
Install
npm install --save greenlock-express@2.x
Install (optional)
More efficient RSA key generation (optional): (important for those on ARM devices like Raspberry Pi)
npm install --save ursa
Let's Encrypt v01 (pre-draft ACME spec) compatibility (optional): (important for those on ARM devices like Raspberry Pi)
npm install --save le-acme-core
become a communityMember
If you're the kind of person that likes the kinds of stuff that I do, well, I want to do more of it and I'd like to get you involved.
When you set the communityMember
option to true
I save your
email and I'm able to inform you when there are mandatory updates
(such as with Let's Encrypt v2), notify you of important security issues,
give you early access to similar projects, and
get your feedback from time to time.
I'll also get a hash of domain names that receive and renew certificates, which is a metric that has long interested me and may help me in getting non-developers involved in this and future projects.
QuickStart
Screencast
Watch the QuickStart demonstration: https://youtu.be/e8vaR4CEZ5s
Beyond the QuickStart (Part 2)
Security Concerns (Part 3)
- 0:00 - Potential Attacks, and Mitigation
Working Example Code
Here's a completely working example that will get you started.
git clone https://git.coolaj86.com/coolaj86/greenlock-express.js.git
pushd greenlock-express.js
npm install
popd
# edit 'email' and 'approveDomains' in
# greenlock-express.js/examples/simple.js
node greenlock-express.js/examples/simple.js
All you have to do is start the webserver and then visit it at its domain name.
app.js
:
'use strict';
require('greenlock-express').create({
// Let's Encrypt v2 is ACME draft 11
version: 'draft-11'
// Note: If at first you don't succeed, switch to staging to debug
// https://acme-staging-v02.api.letsencrypt.org/directory
, server: 'https://acme-v02.api.letsencrypt.org/directory'
// Where the certs will be saved, MUST have write access
, configDir: '~/.config/acme/'
// You MUST change this to a valid email address
, email: 'john.doe@example.com'
// You MUST change these to valid domains
// NOTE: all domains will validated and listed on the certificate
, approveDomains: [ 'example.com', 'www.example.com' ]
// You MUST NOT build clients that accept the ToS without asking the user
, agreeTos: true
, app: require('express')().use('/', function (req, res) {
res.setHeader('Content-Type', 'text/html; charset=utf-8')
res.end('Hello, World!\n\n💚 🔒.js');
})
// Join the community to get notified of important updates
, communityMember: true
// Contribute telemetry data to the project
, telemetry: true
//, debug: true
}).listen(80, 443);
What if the example didn't work?
Double check the following:
- Public Facing IP for
http-01
challenges- Are you running this as a public-facing webserver (good)? or localhost (bad)?
- Does
ifconfig
show a public address (good)? or a private one - 10.x, 192.168.x, etc (bad)? - If you're on a non-public server, are you using the
dns-01
challenge?
- correct ACME version
- Let's Encrypt v2 (ACME v2) must use
version: 'draft-11'
- Let's Encrypt v1 must use
version: 'v01'
- Let's Encrypt v2 (ACME v2) must use
- valid email
- You MUST set
email
to a valid address - MX records must validate (
dig MX example.com
for'john@example.com'
)
- You MUST set
- valid DNS records
- You MUST set
approveDomains
to real domains - Must have public DNS records (test with
dig +trace A example.com; dig +trace www.example.com
for[ 'example.com', 'www.example.com' ]
)
- You MUST set
- write access
- You MUST set
configDir
to a writeable location (test withtouch ~/acme/etc/tmp.tmp
)
- You MUST set
- port binding privileges
- You MUST be able to bind to ports 80 and 443
- You can do this via
sudo
orsetcap
- API limits
- You MUST NOT exceed the API usage limits per domain, certificate, IP address, etc
- Red Lock, Untrusted
- You MUST use the production server url, not staging
- The API URL should not have 'acme-staging-v02', but should have 'acme-v02'
- Delete the
configDir
used for getting certificates in staging
Production vs Staging
If at first you don't succeed, stop and switch to staging.
There are a number of common problems related to system configuration - firewalls, ports, permissions, etc - that you are likely to run up against when using greenlock for your first time.
I've put a "dry run" in place with built-in diagnostics, so hopefully you get everything right on your first or second try.
However, in order to avoid being blocked by hitting the bad request rate limits
you should switch to using the staging
server for any testing or debugging.
https://acme-staging-v02.api.letsencrypt.org/directory
Working Examples
Example | Location + Description |
---|---|
QuickStart | examples/quickstart.js uses the fewest options and accepts all default settings. It's guaranteed to work for you. |
Production | examples/production.js shows how to require an express app (or other middleware system), expand the approveDomains callback, provides an example database shim, and exposes the server instance. |
Virtual Hosting | examples/vhost.js shows how to dynamically secure and serve domains based on their existance on the file system. |
HTTP2 (spdy) | Although greenlock uses spdy by default, examples/spdy.js demonstrates how to manually configure a node web server with Greenlock. |
HTTP2 (node) | examples/http2.js uses node's new HTTP2 module, which is NOT compatible with the existing middleware systems (and is not "stable" as of v10.0). |
WebSockets (ws) | examples/websockets.js demonstrates how to use Greenlock express with a websocket server. |
- | Build Your Own Be sure to tell me (@coolaj86) / us (@GreenlockHTTPS) about it. :) |
Full List | Check out the examples/ directory |
Plugins
IMPORTANT: Community plugins may or may not be maintained and working. Please try with the defaults before switching to community plugins.
HTTP-01 Challenges
Plugin | |
---|---|
Default (fs) | le-challenge-fs |
AWS S3 | llun/le-challenge-s3 |
Azure | kolarcz/node-le-challenge-azure-storage |
- | Build Your Own le-challenge-http-SPEC |
Full List | Search le-challenge- on npm |
DNS-01 Challenges
Plugin | |
---|---|
Manual (cli) | le-challenge-dns |
AWS Route 53 | thadeetrompetter/le-challenge-route53 |
CloudFlare | buschtoens/le-challenge-cloudflare |
CloudFlare | llun/le-challenge-cloudflare |
Digital Ocean | bmv437/le-challenge-digitalocean |
etcd | ceecko/le-challenge-etcd |
- | Build Your Own le-challenge-dns-SPEC |
Full List | Search le-challenge- on npm |
Account & Certificate Storage
Plugin | |
---|---|
Default (fs) | le-store-certbot |
AWS S3 | paco3346/le-store-awss3 |
AWS S3 | llun/le-store-s3 |
Consul | sebastian-software/le-store-consul |
json (fs) | paulgrove/le-store-simple-fs |
Redis | digitalbazaar/le-store-redis |
- | Build Your Own le-store-SPEC |
Full List | Search le-store- on npm |
Auto-SNI
Plugin | |
---|---|
Default | le-sni-auto |
(you probably wouldn't need or want to replace this)
Bugs: Please report bugs with the community plugins to the appropriate owner first, then here if you don't get a response.
Usage
The oversimplified example was the bait (because everyone seems to want an example that fits in 3 lines, even if it's terribly bad practices), now here's the switch.
We have another completely working example that will provides a little more to build off of.
git clone https://git.coolaj86.com/coolaj86/greenlock-express.js.git
pushd greenlock-express.js
npm install
popd
# replace 'fooCheckDb' in
# greenlock-express.js/examples/normal.js
node greenlock-express.js/examples/normal.js
It looks a little more like this:
serve.js
:
'use strict';
// returns an instance of greenlock.js with additional helper methods
var glx = require('greenlock-express').create({
server: 'https://acme-v02.api.letsencrypt.org/directory'
// Note: If at first you don't succeed, stop and switch to staging:
// https://acme-staging-v02.api.letsencrypt.org/directory
, version: 'draft-11' // Let's Encrypt v2 (ACME v2)
// If you wish to replace the default account and domain key storage plugin
, store: require('le-store-certbot').create({
configDir: require('path').join(require('os').homedir(), 'acme', 'etc')
, webrootPath: '/tmp/acme-challenges'
})
// Contribute telemetry data to the project
, telemetry: true
, approveDomains: approveDomains
});
var server = glx.listen(80, 443, function () {
console.log("Listening on port 80 for ACME challenges and 443 for express app.");
});
Note: You shouldn't be using the plain HTTP server for anything except, potentially, for error handling on the listen event (if the default print-and-quit behavior doesn't work for your use case). If you need to do that, here's how:
var plainServer = server.unencrypted;
plainServer.on('error', function (err) { ... });
The Automatic Certificate Issuance is initiated via SNI (httpsOptions.SNICallback
).
For security, domain validation MUST have an approval callback in production.
var http01 = require('le-challenge-fs').create({ webrootPath: '/tmp/acme-challenges' });
function approveDomains(opts, certs, cb) {
// This is where you check your database and associated
// email addresses with domains and agreements and such
// Opt-in to submit stats and get important updates
opts.communityMember = true;
// If you wish to replace the default challenge plugin, you may do so here
opts.challenges = { 'http-01': http01 };
// The domains being approved for the first time are listed in opts.domains
// Certs being renewed are listed in certs.altnames
if (certs) {
opts.domains = certs.altnames;
}
else {
opts.email = 'john.doe@example.com';
opts.agreeTos = true;
}
// NOTE: you can also change other options such as `challengeType` and `challenge`
// opts.challengeType = 'http-01';
// opts.challenge = require('le-challenge-fs').create({});
cb(null, { options: opts, certs: certs });
}
// handles acme-challenge and redirects to https
require('http').createServer(glx.middleware(require('redirect-https')())).listen(80, function () {
console.log("Listening for ACME http-01 challenges on", this.address());
});
var app = require('express')();
app.use('/', function (req, res) {
res.end('Hello, World!');
});
// handles your app
require('https').createServer(glx.httpsOptions, app).listen(443, function () {
console.log("Listening for ACME tls-sni-01 challenges and serve app on", this.address());
});
Security Warning:
If you don't do proper checks in approveDomains(opts, certs, cb)
an attacker will spoof SNI packets with bad hostnames and that will
cause you to be rate-limited and or blocked from the ACME server.
API
This module is an elaborate ruse (to provide an oversimplified example and to nab some SEO).
The API is actually located at greenlock.js options
(because all options are simply passed through to greenlock.js
proper without modification).
The only "API" consists of two options, the rest is just a wrapper around greenlock.js
to take LOC from 15 to 5:
opts.app
An express app in the formatfunction (req, res) { ... }
(nonext
).server = glx.listen(plainAddr, tlsAddr, onListen)
Accepts port numbers (or arrays of port numbers) to listen on, returns secure server.listen(80, 443)
listen(80, 443, onListenSecure)
listen(80, 443, onListenPlain, onListenSecure)
listen('localhost:80', '0.0.0.0:443')
listen('[::1]:80', '[::]:443')
listen('/tmp/glx.plain.sock', '/tmp/glx.secure.sock')
Brief overview of some simple options for greenlock.js
:
opts.server
set to https://acme-v02.api.letsencrypt.org/directory in productionopts.version
set tov01
for Let's Encrypt v1 ordraft-11
for Let's Encrypt v2 (mistakenly called ACME v2)opts.email
The default email to use to accept agreements.opts.agreeTos
When set totrue
, this always accepts the LetsEncrypt TOS. When a string it checks the agreement url first.opts.communityMember
Join the community to get notified of important updates and help make greenlock betteropts.approveDomains
can be either of:- An explicit array of allowed domains such as
[ 'example.com', 'www.example.com' ]
- A callback
function (opts, certs, cb) { cb(null, { options: opts, certs: certs }); }
for settingemail
,agreeTos
,domains
, etc (as shown in usage example above)
- An explicit array of allowed domains such as
opts.renewWithin
is the maximum number of days (in ms) before expiration to renew a certificate.opts.renewBy
is the minimum number of days (in ms) before expiration to renew a certificate.
Supported ACME versions
- Let's Encrypt v1 (aka v01)
- Let's Encrypt v2 (aka v02 or ACME draft 11)
- ACME draft 11 (ACME v2 is a misnomer)
- Wildcard domains (via dns-01 challenges)
*.example.com
tags: letsencrypt acme free ssl automated https node express.js