Merge branch 'master' of github.com:Daplie/letiny-core
This commit is contained in:
AJ ONeal
commit
78c9daa059
|
|
@ -0,0 +1,3 @@
|
||||||
|
ISRG
|
||||||
|
Anatol Sommer <anatol@anatol.at>
|
||||||
|
AJ ONeal <aj@daplie.com> (https://daplie.com/)
|
||||||
330
README.md
330
README.md
|
|
@ -14,11 +14,11 @@ Supports all of:
|
||||||
This is a library / framework for building letsencrypt clients.
|
This is a library / framework for building letsencrypt clients.
|
||||||
You probably want one of these pre-built clients instead:
|
You probably want one of these pre-built clients instead:
|
||||||
|
|
||||||
* `letsencrypt` (100% compatible with the official client)
|
* [`letsencrypt`](https://github.com/Daplie/node-letsencrypt) (compatible with the official client)
|
||||||
* `letiny` (lightweight client)
|
* `letiny` (lightweight client cli)
|
||||||
* `letsencrypt-express` (automatic https for express)
|
* `letsencrypt-express` (automatic https for express)
|
||||||
|
|
||||||
## Usage:
|
## Install & Usage:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install --save letiny-core
|
npm install --save letiny-core
|
||||||
|
|
@ -34,77 +34,242 @@ You will follow these steps to obtain certificates:
|
||||||
* implement a method to get the challenge token as `getChallenge`
|
* implement a method to get the challenge token as `getChallenge`
|
||||||
* implement a method to remove the challenge token as `removeChallenge`
|
* 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 letiny-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/letiny-core.git ~/letiny-core
|
||||||
|
pushd ~/letiny-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
|
||||||
|
LeCore.registerNewAccount(options, cb) // returns "regr" registration data
|
||||||
|
|
||||||
|
{ newRegUrl: '<url>' // no defaults, specify acmeUrls.newAuthz
|
||||||
|
, email: '<email>' // valid email (server checks MX records)
|
||||||
|
, accountPrivateKeyPem: '<ASCII PEM>' // callback to allow user interaction for tosUrl
|
||||||
|
, agreeToTerms: fn (tosUrl, cb) {} // must specify agree=tosUrl to continue (or falsey to end)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Registration
|
||||||
|
LeCore.getCertificate(options, cb) // returns (err, pems={ key, cert, ca })
|
||||||
|
|
||||||
|
{ newAuthzUrl: '<url>' // specify acmeUrls.newAuthz
|
||||||
|
, newCertUrl: '<url>' // specify acmeUrls.newCert
|
||||||
|
|
||||||
|
, domainPrivateKeyPem: '<ASCII PEM>'
|
||||||
|
, accountPrivateKeyPem: '<ASCII PEM>'
|
||||||
|
, domains: ['example.com']
|
||||||
|
|
||||||
|
, setChallenge: fn (hostname, key, val, cb)
|
||||||
|
, removeChallenge: fn (hostname, key, cb)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Discovery URLs
|
||||||
|
LeCore.getAcmeUrls(acmeDiscoveryUrl, cb) // returns (err, acmeUrls={newReg,newAuthz,newCert,revokeCert})
|
||||||
|
```
|
||||||
|
|
||||||
|
Helpers & Stuff
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Constants
|
||||||
|
LeCore.productionServerUrl // https://acme-v01.api.letsencrypt.org/directory
|
||||||
|
LeCore.stagingServerUrl // https://acme-staging.api.letsencrypt.org/directory
|
||||||
|
LeCore.acmeChallengePrefix // /.well-known/acme-challenge/
|
||||||
|
LeCore.configDir // /etc/letsencrypt/
|
||||||
|
LeCore.logsDir // /var/log/letsencrypt/
|
||||||
|
LeCore.workDir // /var/lib/letsencrypt/
|
||||||
|
LeCore.knownEndpoints // new-authz, new-cert, new-reg, revoke-cert
|
||||||
|
|
||||||
|
|
||||||
|
// HTTP Client Helpers
|
||||||
|
LeCore.Acme // Signs requests with JWK
|
||||||
|
acme = new Acme(lePrivateKey) // privateKey format is abstract
|
||||||
|
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
|
||||||
|
|
||||||
|
// Note: some of these are not async,
|
||||||
|
// but they will be soon. Don't rely
|
||||||
|
// on their API yet.
|
||||||
|
|
||||||
|
// Crypto Helpers
|
||||||
|
LeCore.leCrypto
|
||||||
|
generateRsaKeypair(bitLen, exponent, cb); // returns { privateKeyPem, privateKeyJwk, publicKeyPem, publicKeyMd5 }
|
||||||
|
thumbprint(lePubKey) // generates public key thumbprint
|
||||||
|
generateSignature(lePrivKey, bodyBuf, nonce) // generates a signature
|
||||||
|
privateJwkToPems(jwk) // { n: '...', e: '...', iq: '...', ... } to PEMs
|
||||||
|
privatePemToJwk // PEM to JWK (see line above)
|
||||||
|
importPemPrivateKey(privateKeyPem) // (internal) returns abstract private key
|
||||||
|
```
|
||||||
|
|
||||||
|
For testing and development, you can also inject the dependencies you want to use:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
LeCore = LeCore.create({
|
||||||
|
request: require('request')
|
||||||
|
, leCrypto: rquire('./lib/letsencrypt-forge')
|
||||||
|
});
|
||||||
|
|
||||||
|
// now uses node `request` (could also use jQuery or Angular in the browser)
|
||||||
|
LeCore.getAcmeUrls(discoveryUrl, function (err, urls) {
|
||||||
|
console.log(urls);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
Below you'll find a stripped-down example. You can see the full example in the example folder.
|
||||||
|
|
||||||
|
* [example/](https://github.com/Daplie/letiny-core/blob/master/example/)
|
||||||
|
|
||||||
|
#### Register Account & Domain
|
||||||
|
|
||||||
|
This is how you **register an ACME account** and **get an HTTPS certificate**
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
'use strict';
|
'use strict';
|
||||||
|
|
||||||
var LeCore = require('letiny-core');
|
var LeCore = require('letiny-core');
|
||||||
|
|
||||||
var accountPrivateKeyPem = '...'; // leCrypto.generateRsaKeypair(bitLen, exp, cb)
|
var email = 'user@example.com'; // CHANGE TO YOUR EMAIL
|
||||||
var domainPrivateKeyPem = '...'; // (same)
|
var domains = 'example.com'; // CHANGE TO YOUR DOMAIN
|
||||||
var challengeStore = { /*get, set, remove*/ }; // see below for example
|
var acmeDiscoveryUrl = LeCore.stagingServerUrl; // CHANGE to production, when ready
|
||||||
|
|
||||||
LeCore.getAcmeUrls(
|
var accountPrivateKeyPem = null;
|
||||||
LeCore.stagingServerUrl // or choose LeCore.productionServerUrl
|
var domainPrivateKeyPem = null;
|
||||||
, function (err, urls) {
|
var acmeUrls = null;
|
||||||
|
|
||||||
|
LeCore.leCrypto.generateRsaKeypair(2048, 65537, function (err, pems) {
|
||||||
|
// ...
|
||||||
|
LeCore.getAcmeUrls(acmeDiscoveryUrl, function (err, urls) {
|
||||||
|
// ...
|
||||||
|
runDemo();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
function runDemo() {
|
||||||
LeCore.registerNewAccount(
|
LeCore.registerNewAccount(
|
||||||
{ newRegUrl: urls.newReg
|
{ newRegUrl: acmeUrls.newReg
|
||||||
, email: 'user@example.com'
|
, email: email
|
||||||
, accountPrivateKeyPem: accountPrivateKeyPem
|
, accountPrivateKeyPem: accountPrivateKeyPem
|
||||||
, agreeToTerms: function (tosUrl, done) {
|
, agreeToTerms: function (tosUrl, done) {
|
||||||
// agree to these exact terms
|
|
||||||
done(null, tosUrl);
|
// agree to the exact version of these terms
|
||||||
|
done(null, tosUrl);
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
, function (err, regr) {
|
||||||
, function (err, regr) {
|
|
||||||
|
|
||||||
// Note: you should save the registration
|
LeCore.getCertificate(
|
||||||
// record to disk (or db)
|
{ newAuthzUrl: acmeUrls.newAuthz
|
||||||
|
, newCertUrl: acmeUrls.newCert
|
||||||
|
|
||||||
LeCore.getCertificate(
|
, domainPrivateKeyPem: domainPrivateKeyPem
|
||||||
{ newAuthzUrl: urls.newAuthz
|
, accountPrivateKeyPem: accountPrivateKeyPem
|
||||||
, newCertUrl: urls.newCert
|
, domains: domains
|
||||||
|
|
||||||
, domainPrivateKeyPem: domainPrivateKeyPem
|
, setChallenge: challengeStore.set
|
||||||
, accountPrivateKeyPem: accountPrivateKeyPem
|
, removeChallenge: challengeStore.remove
|
||||||
|
}
|
||||||
|
, function (err, certs) {
|
||||||
|
|
||||||
, setChallenge: challengeStore.set
|
// Note: you should save certs to disk (or db)
|
||||||
, removeChallenge: challengeStore.remove
|
certStore.set(domains[0], certs, function () {
|
||||||
}
|
|
||||||
, function (err, certs) {
|
|
||||||
|
|
||||||
// Note: you should save certs to disk (or db)
|
// ...
|
||||||
|
|
||||||
}
|
|
||||||
)
|
|
||||||
|
|
||||||
}
|
});
|
||||||
|
|
||||||
|
}
|
||||||
|
);
|
||||||
|
}
|
||||||
);
|
);
|
||||||
|
}
|
||||||
}
|
|
||||||
);
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**But wait**, there's more!
|
||||||
|
See [example/letsencrypt.js](https://github.com/Daplie/letiny-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)
|
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
|
to respond to `/.well-known/acme-challenge/xxxxxxxx` with the proper token
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
var localCerts = require('localhost.daplie.com-certificates'); // needs default certificates
|
var https = require('https');
|
||||||
var http = require('http');
|
var http = require('http');
|
||||||
var httsp = require('https');
|
|
||||||
|
|
||||||
|
|
||||||
|
var LeCore = deps.LeCore;
|
||||||
|
var httpsOptions = deps.httpsOptions;
|
||||||
|
var challengeStore = deps.challengeStore;
|
||||||
|
var certStore = deps.certStore;
|
||||||
|
|
||||||
|
|
||||||
|
//
|
||||||
|
// Challenge Handler
|
||||||
|
//
|
||||||
function acmeResponder(req, res) {
|
function acmeResponder(req, res) {
|
||||||
if (0 !== req.url.indexOf(LeCore.acmeChallengePrefixUrl)) {
|
if (0 !== req.url.indexOf(LeCore.acmeChallengePrefix)) {
|
||||||
res.end('Hello World!');
|
res.end('Hello World!');
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
LeCore.
|
var key = req.url.slice(LeCore.acmeChallengePrefix.length);
|
||||||
|
|
||||||
|
challengeStore.get(req.hostname, key, function (err, val) {
|
||||||
|
res.end(val || 'Error');
|
||||||
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
http.createServer()
|
|
||||||
|
//
|
||||||
|
// 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/letiny-core/blob/master/example/serve.js)
|
||||||
|
|
||||||
|
#### Put some storage in place
|
||||||
|
|
||||||
Finally, you need an implementation of `challengeStore`:
|
Finally, you need an implementation of `challengeStore`:
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
|
|
@ -122,77 +287,28 @@ var challengeStore = {
|
||||||
cb(null);
|
cb(null);
|
||||||
}
|
}
|
||||||
};
|
};
|
||||||
```
|
|
||||||
|
|
||||||
## API
|
var certCache = {};
|
||||||
|
var certStore = {
|
||||||
The Goodies
|
set: function (hostname, certs, cb) {
|
||||||
|
certCache[hostname] = certs;
|
||||||
```javascript
|
cb(null);
|
||||||
{ newRegUrl: '...' // no defaults, specify LeCore.nproductionServerUrl
|
|
||||||
|
|
||||||
// Accounts
|
|
||||||
LeCore.registerNewAccount(options, cb) // returns (err, acmeUrls={newReg,newAuthz,newCert,revokeCert})
|
|
||||||
|
|
||||||
{ newRegUrl: '...' // no defaults, specify LeCore.newAuthz
|
|
||||||
, email: '...' // valid email (server checks MX records)
|
|
||||||
, agreeToTerms: fn (tosUrl, cb) {} // callback to allow user interaction for tosUrl
|
|
||||||
// cb(err=null, agree=tosUrl) // must specify agree=tosUrl to continue (or falsey to end)
|
|
||||||
}
|
}
|
||||||
|
, get: function (hostname, cb) {
|
||||||
// Registration
|
cb(null, certCache[hostname]);
|
||||||
LeCore.getCertificate(options, cb)
|
}
|
||||||
|
, remove: function (hostname, cb) {
|
||||||
{ newAuthzUrl: '...' // no defaults, specify acmeUrls.newAuthz
|
delete certCache[hostname];
|
||||||
|
cb(null);
|
||||||
|
}
|
||||||
|
};
|
||||||
```
|
```
|
||||||
|
|
||||||
Helpers & Stuff
|
**But wait**, there's more!
|
||||||
|
See
|
||||||
|
|
||||||
```javascript
|
* [example/challenge-store.js](https://github.com/Daplie/letiny-core/blob/master/challenge-store.js)
|
||||||
// Constants
|
* [example/cert-store.js](https://github.com/Daplie/letiny-core/blob/master/cert-store.js)
|
||||||
LeCore.productionServerUrl // https://acme-v01.api.letsencrypt.org/directory
|
|
||||||
LeCore.stagingServerUrl // https://acme-staging.api.letsencrypt.org/directory
|
|
||||||
LeCore.acmeChallengePrefix // /.well-known/acme-challenge/
|
|
||||||
LeCore.configDir // /etc/letsencrypt/
|
|
||||||
LeCore.logsDir // /var/log/letsencrypt/
|
|
||||||
LeCore.workDir // /var/lib/letsencrypt/
|
|
||||||
LeCore.knownEndpoints // new-authz, new-cert, new-reg, revoke-cert
|
|
||||||
|
|
||||||
|
|
||||||
// HTTP Client Helpers
|
|
||||||
LeCore.Acme // Signs requests with JWK
|
|
||||||
acme = new Acme(lePrivateKey) // privateKey format is abstract
|
|
||||||
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
|
|
||||||
|
|
||||||
// Note: some of these are not async,
|
|
||||||
// but they will be soon. Don't rely
|
|
||||||
// on their API yet.
|
|
||||||
|
|
||||||
// Crypto Helpers
|
|
||||||
LeCore.leCrypto
|
|
||||||
generateRsaKeypair(bitLen, exponent, cb); // returns { privateKeyPem, privateKeyJwk, publicKeyPem, publicKeyMd5 }
|
|
||||||
thumbprint(lePubKey) // generates public key thumbprint
|
|
||||||
generateSignature(lePrivKey, bodyBuf, nonce) // generates a signature
|
|
||||||
privateJwkToPems(jwk) // { n: '...', e: '...', iq: '...', ... } to PEMs
|
|
||||||
privatePemToJwk // PEM to JWK (see line above)
|
|
||||||
importPemPrivateKey(privateKeyPem) // (internal) returns abstract private key
|
|
||||||
```
|
|
||||||
|
|
||||||
For testing and development, you can also inject the dependencies you want to use:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
LeCore = LeCore.create({
|
|
||||||
request: require('request')
|
|
||||||
, leCrypto: rquire('./lib/letsencrypt-forge')
|
|
||||||
});
|
|
||||||
|
|
||||||
// now uses node `request` (could also use jQuery or Angular in the browser)
|
|
||||||
LeCore.getAcmeUrls(discoveryUrl, function (err, urls) {
|
|
||||||
console.log(urls);
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## Authors
|
## Authors
|
||||||
|
|
||||||
|
|
|
||||||
23
package.json
23
package.json
|
|
@ -1,18 +1,25 @@
|
||||||
{
|
{
|
||||||
"name": "letiny-core",
|
"name": "letiny-core",
|
||||||
"version": "1.0.0",
|
"version": "1.0.1",
|
||||||
"description": "A framework for building letsencrypt clients, forked from `letiny`",
|
"description": "A framework for building letsencrypt clients, forked from letiny",
|
||||||
"authors": [
|
|
||||||
"Anatol Sommer <anatol@anatol.at>",
|
|
||||||
"AJ ONeal <aj@daplie.com>"
|
|
||||||
],
|
|
||||||
"main": "node.js",
|
"main": "node.js",
|
||||||
"browser": "browser.js",
|
"browser": "browser.js",
|
||||||
"license": "MPL-2.0",
|
"directories": {
|
||||||
|
"example": "example",
|
||||||
|
"test": "test"
|
||||||
|
},
|
||||||
|
"scripts": {
|
||||||
|
"test": "node example/letsencrypt.js"
|
||||||
|
},
|
||||||
"repository": {
|
"repository": {
|
||||||
"type": "git",
|
"type": "git",
|
||||||
"url": "https://github.com/Daplie/letiny-core.git"
|
"url": "git+https://github.com/Daplie/letiny-core.git"
|
||||||
},
|
},
|
||||||
|
"license": "MPL-2.0",
|
||||||
|
"bugs": {
|
||||||
|
"url": "https://github.com/Daplie/letiny-core/issues"
|
||||||
|
},
|
||||||
|
"homepage": "https://github.com/Daplie/letiny-core#readme",
|
||||||
"keywords": [
|
"keywords": [
|
||||||
"tiny",
|
"tiny",
|
||||||
"acme",
|
"acme",
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue