coolaj86
/
le-acme-core.js
1
0
Fork 0
Code Issues Pull Requests Releases Activity

New location (self-hosted)

This commit is contained in:
AJ ONeal 2017-01-06 22:16:44 -07:00
parent 6b1b168e5a
commit 6d4cfca0bd
1 changed files with 3 additions and 345 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

348
README.md
View File

@ -1,347 +1,5 @@
<!-- BANNER_TPL_BEGIN -->
le-acme-core
=====
About Daplie: We're taking back the Internet!
--------------
Moved to https://git.daplie.com/Daplie/le-acme-core
Down with Google, Apple, and Facebook!
We're re-decentralizing the web and making it read-write again - one home cloud system at a time.
Tired of serving the Empire? Come join the Rebel Alliance:
<a href="mailto:jobs@daplie.com">jobs@daplie.com</a> | [Invest in Daplie on Wefunder](https://daplie.com/invest/) | [Pre-order Cloud](https://daplie.com/preorder/), The World's First Home Server for Everyone
<!-- BANNER_TPL_END -->
# le-acme-core
Looking for **letiny-core**? Check the [v1.x branch](https://github.com/Daplie/le-acme-core/tree/v1.x).
<!-- rename to le-acme-core -->
A framework for building letsencrypt clients, forked from `letiny`.
Supports all of:
* node with `ursa` (works fast)
* node with `forge` (works on windows)
* browser WebCrypto (not implemented, but... Let's Encrypt over WebRTC anyone?)
* any javascript implementation
### These aren't the droids you're looking for
This is a library / framework for building letsencrypt clients.
You probably want one of these pre-built clients instead:
* [`letsencrypt`](https://github.com/Daplie/node-letsencrypt) (compatible with the official client)
* `letiny` (lightweight client cli)
* [`letsencrypt-express`](https://github.com/Daplie/letsencrypt-express) (automatic https for express)
## Install & Usage:
```bash
npm install --save le-acme-core
```
To use the default dependencies:
```javascript
'use strict';
var ACME = require('le-acme-core').ACME.create();
```
For **testing** and **development**, you can also inject the dependencies you want to use:
```javascript
'use strict';
var ACME = require('le-acme-core').ACME.create({
request: require('request')
, RSA: require('rsa-compat').RSA
});
// now uses node `request` (could also use jQuery or Angular in the browser)
ACME.getAcmeUrls(discoveryUrl, function (err, urls) {
console.log(urls);
});
```
You will follow these steps to obtain certificates:
* discover ACME registration urls with `getAcmeUrls`
* register a user account with `registerNewAccount`
* implement a method to agree to the terms of service as `agreeToTos`
* get certificates with `getCertificate`
* implement a method to store the challenge token as `setChallenge`
* implement a method to get the challenge token as `getChallenge`
* implement a method to remove the challenge token as `removeChallenge`
### Demo
You can see this working for yourself, but you'll need to be on an internet connected computer with a domain.
Get a temporary domain for testing
```bash
npm install -g ddns-cli
ddns --random --email user@example.com --agree
```
Note: use **YOUR EMAIL** and accept the terms of service (run `ddns --help` to see them).
<!-- TODO tutorial on ddns -->
Install le-acme-core and its dependencies. **Note**: it's okay if you're on windows
and `ursa` fails to compile. It'll still work.
```bash
git clone https://github.com/Daplie/le-acme-core.git ~/le-acme-core
pushd ~/le-acme-core
npm install
```
Run the demo:
```bash
node examples/letsencrypt.js user@example.com example.com
```
Note: use **YOUR TEMPORARY DOMAIN** and **YOUR EMAIL**.
## API
The Goodies
```javascript
// Accounts
ACME.registerNewAccount(options, cb) // returns "regr" registration data
{ newRegUrl: '<url>' // no defaults, specify acmeUrls.newAuthz
, email: '<email>' // valid email (server checks MX records)
, accountKeypair: { // privateKeyPem or privateKeyJwt
privateKeyPem: '<ASCII PEM>'
}
, agreeToTerms: fn (tosUrl, cb) {} // must specify agree=tosUrl to continue (or falsey to end)
}
// Registration
ACME.getCertificate(options, cb) // returns (err, pems={ privkey (key), cert, chain (ca) })
{ newAuthzUrl: '<url>' // specify acmeUrls.newAuthz
, newCertUrl: '<url>' // specify acmeUrls.newCert
, domainKeypair: {
privateKeyPem: '<ASCII PEM>'
}
, accountKeypair: {
privateKeyPem: '<ASCII PEM>'
}
, domains: ['example.com']
, setChallenge: fn (hostname, key, val, cb)
, removeChallenge: fn (hostname, key, cb)
}
// Discovery URLs
ACME.getAcmeUrls(acmeDiscoveryUrl, cb) // returns (err, acmeUrls={newReg,newAuthz,newCert,revokeCert})
```
Helpers & Stuff
```javascript
// Constants
ACME.productionServerUrl // https://acme-v01.api.letsencrypt.org/directory
ACME.stagingServerUrl // https://acme-staging.api.letsencrypt.org/directory
ACME.acmeChallengePrefix // /.well-known/acme-challenge/
ACME.knownEndpoints // new-authz, new-cert, new-reg, revoke-cert
// HTTP Client Helpers
ACME.Acme // Signs requests with JWK
acme = new Acme(keypair) // 'keypair' is an object with `privateKeyPem` and/or `privateKeyJwk`
acme.post(url, body, cb) // POST with signature
acme.parseLinks(link) // (internal) parses 'link' header
acme.getNonce(url, cb) // (internal) HEAD request to get 'replay-nonce' strings
```
## Example
Below you'll find a stripped-down example. You can see the full example in the example folder.
* [example/](https://github.com/Daplie/le-acme-core/blob/master/example/)
#### Register Account & Domain
This is how you **register an ACME account** and **get an HTTPS certificate**
```javascript
'use strict';
var ACME = require('le-acme-core').ACME.create();
var RSA = require('rsa-compat').RSA;
var email = 'user@example.com'; // CHANGE TO YOUR EMAIL
var domains = 'example.com'; // CHANGE TO YOUR DOMAIN
var acmeDiscoveryUrl = ACME.stagingServerUrl; // CHANGE to production, when ready
var accountKeypair = null; // { privateKeyPem: null, privateKeyJwk: null };
var domainKeypair = null; // same as above
var acmeUrls = null;
RSA.generateKeypair(2048, 65537, function (err, keypair) {
accountKeypair = keypair;
// ...
ACME.getAcmeUrls(acmeDiscoveryUrl, function (err, urls) {
// ...
runDemo();
});
});
function runDemo() {
ACME.registerNewAccount(
{ newRegUrl: acmeUrls.newReg
, email: email
, accountKeypair: accountKeypair
, agreeToTerms: function (tosUrl, done) {
// agree to the exact version of these terms
done(null, tosUrl);
}
}
, function (err, regr) {
ACME.getCertificate(
{ newAuthzUrl: acmeUrls.newAuthz
, newCertUrl: acmeUrls.newCert
, domainKeypair: domainKeypair
, accountKeypair: accountKeypair
, domains: domains
, setChallenge: challengeStore.set
, removeChallenge: challengeStore.remove
}
, function (err, certs) {
// Note: you should save certs to disk (or db)
certStore.set(domains[0], certs, function () {
// ...
});
}
);
}
);
}
```
**But wait**, there's more!
See [example/letsencrypt.js](https://github.com/Daplie/le-acme-core/blob/master/example/letsencrypt.js)
#### Run a Server on 80, 443, and 5001 (https/tls)
That will fail unless you have a webserver running on 80 and 443 (or 5001)
to respond to `/.well-known/acme-challenge/xxxxxxxx` with the proper token
```javascript
var https = require('https');
var http = require('http');
var LeCore = deps.LeCore;
var httpsOptions = deps.httpsOptions;
var challengeStore = deps.challengeStore;
var certStore = deps.certStore;
//
// Challenge Handler
//
function acmeResponder(req, res) {
if (0 !== req.url.indexOf(LeCore.acmeChallengePrefix)) {
res.end('Hello World!');
return;
}
var key = req.url.slice(LeCore.acmeChallengePrefix.length);
challengeStore.get(req.hostname, key, function (err, val) {
res.end(val || 'Error');
});
}
//
// Server
//
https.createServer(httpsOptions, acmeResponder).listen(5001, function () {
console.log('Listening https on', this.address());
});
http.createServer(acmeResponder).listen(80, function () {
console.log('Listening http on', this.address());
});
```
**But wait**, there's more!
See [example/serve.js](https://github.com/Daplie/le-acme-core/blob/master/example/serve.js)
#### Put some storage in place
Finally, you need an implementation of `challengeStore`:
```javascript
var challengeCache = {};
var challengeStore = {
set: function (hostname, key, value, cb) {
challengeCache[key] = value;
cb(null);
}
, get: function (hostname, key, cb) {
cb(null, challengeCache[key]);
}
, remove: function (hostname, key, cb) {
delete challengeCache[key];
cb(null);
}
};
var certCache = {};
var certStore = {
set: function (hostname, certs, cb) {
certCache[hostname] = certs;
cb(null);
}
, get: function (hostname, cb) {
cb(null, certCache[hostname]);
}
, remove: function (hostname, cb) {
delete certCache[hostname];
cb(null);
}
};
```
**But wait**, there's more!
See
* [example/challenge-store.js](https://github.com/Daplie/le-acme-core/blob/master/challenge-store.js)
* [example/cert-store.js](https://github.com/Daplie/le-acme-core/blob/master/cert-store.js)
## Authors
* ISRG
* Anatol Sommer (https://github.com/anatolsommer)
* AJ ONeal <aj@daplie.com> (https://daplie.com)
## Licence
MPL 2.0
All of the code is available under the MPL-2.0.
Some of the files are original work not modified from `letiny`
and are made available under MIT and Apache-2.0 as well (check file headers).