From 2c2bbeacdb735b36bcb57a1b78cdf8752dc68794 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Mon, 18 Apr 2016 11:07:30 -0600 Subject: [PATCH] Update README.md --- README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/README.md b/README.md index 63f2d91..8cab438 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,76 @@ # letsencrypt-koa + Free SSL and Automatic HTTPS for node.js with KOA and other middleware systems via Let's Encrypt + +* Automatic Registration via SNI (`httpsOptions.SNICallback`) + * **registrations** require an **approval callback** in *production* +* Automatic Renewal (around 80 days) + * **renewals** are *fully automatic* and happen in the *background*, with **no downtime** +* Automatic vhost / virtual hosting + +All you have to do is start the webserver and then visit it at it's domain name. + +## Install + +``` +npm install --save letsencrypt-express +``` + +### Part 1: Setup + +```javascript +'use strict'; + +/* Note: using staging server url, remove .testing() for production +Using .testing() will overwrite the debug flag with true */ +var LEX = require('letsencrypt-express').testing(); + +var lex = LEX.create({ + configDir: require('os').homedir() + '/letsencrypt/etc' +, approveRegistration: function (hostname, cb) { // leave `null` to disable automatic registration + // Note: this is the place to check your database to get the user associated with this domain + cb(null, { + domains: [hostname] + , email: 'CHANGE_ME' // user@example.com + , agreeTos: true + }); + } +}); +``` + +WARNING: If you don't do any checks and simply complete `approveRegistration` callback, 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. Alternatively, You can run registration *manually*: + +```bash +npm install -g letsencrypt-cli + +letsencrypt certonly --standalone \ + --config-dir ~/letsencrypt/etc \ + --agree-tos --domains example.com --email user@example.com + +# Note: the '--webrootPath' option is also available if you don't want to shut down your webserver to get the cert. +``` + +### Part 2: Just add Koa + +```javascript +var http = require('http'); +var https = require('spdy'); // Note: some have reported trouble with `http2` and success with `spdy` +var koa = require('koa'); +var app = koa(); +var redirectHttps = koa().use(require('koa-force-ssl').callback(); + +app.use(function *() { + this.body = 'Hello World'; +}); + +var server = https.createServer(lex.httpsOptions, LEX.createAcmeResponder(lex, app.callback())); +var redirectServer = http.createServer(LEX.createAcmeResponder(lex, redirectHttps))); + +server.listen(443, function () { + console.log('Listening at https://localhost:' + this.address().port); +}); + +redirectServer.listen(80, function () { + console.log('Redirecting insecure traffic from http://localhost:' + this.address().port + ' to https'); +}); +```