From ee4570322c9f02ca6a8ad2c3c93ec97106446e64 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Sun, 13 Dec 2015 01:04:44 -0800 Subject: [PATCH 1/7] Update README.md --- README.md | 101 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 68 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 3ed7891..f991654 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,12 @@ Automatic [Let's Encrypt](https://lettsencrypt.org) HTTPS Certificates for node. * Free SSL (HTTPS Certificates for TLS) * [90-day certificates](https://letsencrypt.org/2015/11/09/why-90-days.html) +**See Also** + +* See the node-letsencrypt [Examples](https://github.com/Daplie/node-letsencrypt/tree/master/examples) +* [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 + Install ======= @@ -19,7 +25,7 @@ npm install --save letsencrypt ``` Right now this uses [`letsencrypt-python`](https://github.com/Daplie/node-letsencrypt-python), -but it's built to be able to use a pure javasript version (in progress). +but it's built to be able to use a node-only javasript version (in progress). ```bash # install the python client (takes 2 minutes normally, 20 on a rasberry pi) @@ -35,36 +41,54 @@ There are a few partially written javascript implementation, but they use `forge Once the `forge` crud is gutted away it should slide right in without a problem. Ping [@coolaj86](https://coolaj86.com) if you'd like to help. -Usage Examples -======== +Usage +===== -Here's a small snippet: +Here's a simple snippet: -```javascript +``` +var config = require('./examples/config-minimal'); + +config.le.webrootPath = __dirname + './tests/acme-challenge'; + +var le = require('letsencrypt').create(config.backend, config.le); le.register({ - domains: ['example.com', 'www.example.com'] -, email: 'user@example.com' -, agreeTos: true -, webrootPath: '/srv/www/example.com/public' -}, function (err, certs) { - // do stuff + agreeTos: true +, domains: ['example.com'] // CHANGE TO YOUR DOMAIN +, email: 'user@email.com' // CHANGE TO YOUR EMAIL +}, function (err) { + if (err) { + console.error('[Error]: node-letsencrypt/examples/standalone'); + console.error(err.stack); + } else { + console.log('success'); + } + + plainServer.close(); + tlsServer.close(); }); + +// IMPORTANT +// you also need BOTH an http AND https server +// +// app.use('/', express.static(config.le.webrootPath)) ``` **However**, due to the nature of what this library does, it has a few more "moving parts" than what makes sense to show in a minimal snippet. -### One Time Registration +Examples +======== -* [commandline (standalone with "webroot")](https://github.com/Daplie/node-letsencrypt/blob/master/examples/commandline.js) +### One-Time Registration -```bash -# manual standalone registration via commandline -# (runs against testing server on tls port 5001) -node examples/commandline.js example.com,www.example.com user@example.net agree -``` +Register a 90-day certificate manually, on a whim + +#### Snippets [`commandline-minimal`](https://github.com/Daplie/node-letsencrypt/blob/master/examples/commandline-minimal.js): + +**Part 1: the Let's Encrypt client**: ```javascript 'use strict'; @@ -95,8 +119,10 @@ le.register({ plainServer.close(); tlsServer.close(); }); +``` - +**Part 2: Express Web Server**: +```javascript // // Express App // @@ -121,10 +147,22 @@ var tlsServer = require('https').createServer({ }); ``` +#### Runnable Demo + +* [commandline (standalone with "webroot")](https://github.com/Daplie/node-letsencrypt/blob/master/examples/commandline.js) + +```bash +# manual standalone registration via commandline +# (runs against testing server on tls port 5001) +node examples/commandline.js example.com,www.example.com user@example.net agree +``` + ### Express Fully Automatic HTTPS with ExpressJS using Free SSL certificates from Let's Encrypt +#### Snippets + * [Minimal ExpressJS Example](https://github.com/Daplie/node-letsencrypt/blob/master/examples/express-minimal.js) ```javascript @@ -190,6 +228,8 @@ require('https').createServer({ }); ``` +#### Runnable Example + * [Full ExpressJS Example](https://github.com/Daplie/node-letsencrypt/blob/master/examples/express.js) ```bash @@ -225,23 +265,18 @@ and then make sure to set all of of the following to a directory that your user * `logsDir` (python backend only) -See Also -======== - -* See [Examples](https://github.com/Daplie/node-letsencrypt/tree/master/examples) -* [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 - API === -* `LetsEncrypt.create(backend, bkDefaults, handlers)` -* `le.middleware()` -* `le.sniCallback(hostname, function (err, tlsContext) {})` -* `le.register({ domains, email, agreeTos, ... }, cb)` -* `le.fetch({domains, email, agreeTos, ... }, cb)` -* `le.validate(domains, cb)` -* `le.registrationFailureCallback(err, args, certInfo, cb)` +```javascript +LetsEncrypt.create(backend, bkDefaults, handlers) +le.middleware() +le.sniCallback(hostname, function (err, tlsContext) {}) +le.register({ domains, email, agreeTos, ... }, cb) +le.fetch({domains, email, agreeTos, ... }, cb) +le.validate(domains, cb) +le.registrationFailureCallback(err, args, certInfo, cb) +``` ### `LetsEncrypt.create(backend, bkDefaults, handlers)` From 8c30756fb47437784e9a62b6499f1e30181daf65 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Sun, 13 Dec 2015 01:11:57 -0800 Subject: [PATCH 2/7] Update README.md --- README.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index f991654..fab3508 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,9 @@ le.register({ }); // IMPORTANT -// you also need BOTH an http AND https server +// you also need BOTH an http AND https server that serve directly +// from webrootPath, which might as well be a special folder reserved +// only for acme/letsencrypt challenges // // app.use('/', express.static(config.le.webrootPath)) ``` @@ -269,13 +271,15 @@ API === ```javascript -LetsEncrypt.create(backend, bkDefaults, handlers) -le.middleware() -le.sniCallback(hostname, function (err, tlsContext) {}) -le.register({ domains, email, agreeTos, ... }, cb) -le.fetch({domains, email, agreeTos, ... }, cb) -le.validate(domains, cb) -le.registrationFailureCallback(err, args, certInfo, cb) +LetsEncrypt.create(backend, bkDefaults, handlers) // wraps a given "backend" (the python client) +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, occassionally refreshes from disk +le.validate(domains, cb) // do some sanity checks before attemping to register +le.registrationFailureCallback(err, args, certInfo, cb) // called when registration fails (not implemented yet) ``` ### `LetsEncrypt.create(backend, bkDefaults, handlers)` From 1149941da50072989c61a36bb7fb8f2fc31b91cb Mon Sep 17 00:00:00 2001 From: Marcus Nielsen Date: Sun, 13 Dec 2015 11:37:16 +0100 Subject: [PATCH 3/7] Docs: Fixes a typo i the readme. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fab3508..712bb47 100644 --- a/README.md +++ b/README.md @@ -308,7 +308,7 @@ look at the wrapper `backend-python.js`. } ``` -#### bkDefualts +#### bkDefaults The arguments passed here (typically `webpathRoot`, `configDir`, etc) will be merged with any `args` (typically `domains`, `email`, and `agreeTos`) and passed to the backend whenever From d2d3e057148d824b7d26699e98c78e453bae7c36 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Sun, 13 Dec 2015 03:09:06 -0800 Subject: [PATCH 4/7] Update README.md --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 712bb47..9844dff 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ Usage Here's a simple snippet: -``` +```javascript var config = require('./examples/config-minimal'); config.le.webrootPath = __dirname + './tests/acme-challenge'; @@ -517,6 +517,11 @@ return { }; ``` +Change History +============== + +v1.0.0 Thar be dragons + LICENSE ======= From 39df08b061c2ae94e8d36bfe2dafc37bb1a65837 Mon Sep 17 00:00:00 2001 From: Kohei TAKATA Date: Mon, 14 Dec 2015 19:58:20 +0900 Subject: [PATCH 5/7] Fix typo --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 9844dff..049343f 100644 --- a/README.md +++ b/README.md @@ -25,10 +25,10 @@ npm install --save letsencrypt ``` Right now this uses [`letsencrypt-python`](https://github.com/Daplie/node-letsencrypt-python), -but it's built to be able to use a node-only javasript version (in progress). +but it's built to be able to use a node-only javascript version (in progress). ```bash -# install the python client (takes 2 minutes normally, 20 on a rasberry pi) +# install the python client (takes 2 minutes normally, 20 on a raspberry pi) git clone https://github.com/letsencrypt/letsencrypt pushd letsencrypt @@ -37,7 +37,7 @@ pushd letsencrypt **moving towards a python-free version** -There are a few partially written javascript implementation, but they use `forge` instead of using node's native `crypto` and `ursa` - so their performance is outright horrific (especially on Rasbperry Pi et al). For the moment it's faster to use the wrapped python version. +There are a few partially written javascript implementation, but they use `forge` instead of using node's native `crypto` and `ursa` - so their performance is outright horrific (especially on Raspberry Pi et al). For the moment it's faster to use the wrapped python version. Once the `forge` crud is gutted away it should slide right in without a problem. Ping [@coolaj86](https://coolaj86.com) if you'd like to help. @@ -277,8 +277,8 @@ LetsEncrypt.stagingServer // string of staging 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, occassionally refreshes from disk -le.validate(domains, cb) // do some sanity checks before attemping to register +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) ``` @@ -326,7 +326,7 @@ Typically the backend wrapper will already merge any necessary backend-specific ``` Note: `webrootPath` can be set as a default, semi-locally with `webrootPathTpl`, or per -regesitration as `webrootPath` (which overwrites `defaults.webrootPath`). +registration as `webrootPath` (which overwrites `defaults.webrootPath`). #### handlers *optional* From ca239a2ea8468e9db8c011a504d2ce9e09de7a9b Mon Sep 17 00:00:00 2001 From: Paolo Bernasconi Date: Mon, 14 Dec 2015 14:37:22 -0500 Subject: [PATCH 6/7] Fix type for letsencrypt.org --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 049343f..5dab56a 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ letsencrypt =========== -Automatic [Let's Encrypt](https://lettsencrypt.org) HTTPS Certificates for node.js +Automatic [Let's Encrypt](https://letsencrypt.org) HTTPS Certificates for node.js * Automatic HTTPS with ExpressJS * Automatic live renewal (in-process) From 4457425b439113cfdc851de8fa59f7234d6b700f Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Mon, 14 Dec 2015 18:15:11 -0800 Subject: [PATCH 7/7] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5dab56a..83e7afe 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ Here's a simple snippet: ```javascript var config = require('./examples/config-minimal'); -config.le.webrootPath = __dirname + './tests/acme-challenge'; +config.le.webrootPath = __dirname + '/tests/acme-challenge'; var le = require('letsencrypt').create(config.backend, config.le); le.register({