John Shaver 16cbe77dff | ||
---|---|---|
examples | ||
tests | ||
LICENSE | ||
README.md | ||
compat.js | ||
node.js | ||
package.json |
README.md
| Sponsored by ppl | acme-v2.js (npm) | acme-v2-cli.js | greenlock.js | goldilocks.js |
acme-v2.js
A framework for building Let's Encrypt v2 (ACME draft 11) clients, successor to le-acme-core.js
.
Built by request.
Looking for Quick 'n' Easy™?
If you're looking for an ACME-enabled webserver, try goldilocks.js. If you're looking to build a webserver, try greenlock.js.
How to build ACME clients
As this is intended to build ACME clients, there is not a simple 2-line example.
I'd recommend first running the example CLI client with a test domain and then investigating the files used for that example:
node examples/cli.js
The example cli has the following prompts:
What web address(es) would you like to get certificates for? (ex: example.com,*.example.com)
What challenge will you be testing today? http-01 or dns-01? [http-01]
What email should we use? (optional)
What API style would you like to test? v1-compat or promise? [v1-compat]
Put the string 'mBfh0SqaAV3MOK3B6cAhCbIReAyDuwuxlO1Sl70x6bM.VNAzCR4THe4czVzo9piNn73B1ZXRLaB2CESwJfKkvRM' into a file at 'example.com/.well-known/acme-challenge/mBfh0SqaAV3MOK3B6cAhCbIReAyDuwuxlO1Sl70x6bM'
echo 'mBfh0SqaAV3MOK3B6cAhCbIReAyDuwuxlO1Sl70x6bM.VNAzCR4THe4czVzo9piNn73B1ZXRLaB2CESwJfKkvRM' > 'example.com/.well-known/acme-challenge/mBfh0SqaAV3MOK3B6cAhCbIReAyDuwuxlO1Sl70x6bM'
Then hit the 'any' key to continue...
When you've completed the challenge you can hit a key to continue the process.
If you place the certificate you receive back in tests/fullchain.pem
you can then test it with examples/https-server.js
.
examples/cli.js
examples/genkeypair.js
tests/compat.js
examples/https-server.js
examples/http-server.js
Let's Encrypt Directory URLs
# Production URL
https://acme-v02.api.letsencrypt.org/directory
# Staging URL
https://acme-staging-v02.api.letsencrypt.org/directory
Two API versions, Two Implementations
This library (acme-v2.js) supports ACME draft 11, otherwise known as Let's Encrypt v2 (or v02).
- ACME draft 11
- Let's Encrypt v2
- Let's Encrypt v02
The predecessor (le-acme-core) supports Let's Encrypt v1 (or v01), which was a hodge-podge of various drafts of the ACME spec early on.
- ACME early draft
- Let's Encrypt v1
- Let's Encrypt v01
This library maintains compatibility with le-acme-core so that it can be used as a drop-in replacement and requires no changes to existing code, but also provides an updated API more congruent with draft 11.
le-acme-core-compatible API (recommended)
Status: Stable, Locked, Bugfix-only
See Full Documentation at https://git.coolaj86.com/coolaj86/le-acme-core.js
var RSA = require('rsa-compat').RSA;
var acme = require('acme-v2/compat.js').ACME.create({ RSA: RSA });
//
// Use exactly the same as le-acme-core
//
Promise API (dev)
Status: Almost stable, but not semver locked
This API is a simple evolution of le-acme-core, but tries to provide a better mapping to the new draft 11 APIs.
// Create Instance (Dependency Injection)
var ACME = require('acme-v2').ACME.create({
RSA: require('rsa-compat').RSA
// other overrides
, request: require('request')
, promisify: require('util').promisify
// used for constructing user-agent
, os: require('os')
, process: require('process')
// used for overriding the default user-agent
, userAgent: 'My custom UA String'
, getUserAgentString: function (deps) { return 'My custom UA String'; }
// don't try to validate challenges locally
, skipChallengeTest: false
});
// Discover Directory URLs
ACME.init(acmeDirectoryUrl) // returns Promise<acmeUrls={keyChange,meta,newAccount,newNonce,newOrder,revokeCert}>
// Accounts
ACME.accounts.create(options) // returns Promise<regr> registration data
{ email: '<email>' // valid email (server checks MX records)
, accountKeypair: { // privateKeyPem or privateKeyJwt
privateKeyPem: '<ASCII PEM>'
}
, agreeToTerms: fn (tosUrl) {} // returns Promise with tosUrl
}
// Registration
ACME.certificates.create(options) // returns Promise<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) // return Promise
, removeChallenge: fn (hostname, key) // return Promise
}
Helpers & Stuff
// Constants
ACME.challengePrefixes['http-01'] // '/.well-known/acme-challenge'
ACME.challengePrefixes['dns-01'] // '_acme-challenge'
Changelog
- v1.0.5 - cleanup logging
- v1.0.4 - v6- compat use
promisify
from node's util or bluebird - v1.0.3 - documentation cleanup
- v1.0.2
- use
options.contact
to provide raw contact array - made
options.email
optional - file cleanup
- use
- v1.0.1
- Compat API is ready for use
- Eliminate debug logging
- Apr 10, 2018 - tested backwards-compatibility using greenlock.js
- Apr 5, 2018 - export http and dns challenge tests
- Apr 5, 2018 - test http and dns challenges (success and failure)
- Apr 5, 2018 - test subdomains and its wildcard
- Apr 5, 2018 - test two subdomains
- Apr 5, 2018 - test wildcard
- Apr 5, 2018 - completely match api for acme v1 (le-acme-core.js)
- Mar 21, 2018 - mostly matches le-acme-core.js API
- Mar 21, 2018 - can now accept values (not hard coded)
- Mar 20, 2018 - SUCCESS - got a test certificate (hard-coded)
- Mar 20, 2018 - download certificate
- Mar 20, 2018 - poll for status
- Mar 20, 2018 - finalize order (submit csr)
- Mar 20, 2018 - generate domain keypair
- Mar 20, 2018 - respond to challenges
- Mar 16, 2018 - get challenges
- Mar 16, 2018 - new order
- Mar 15, 2018 - create account
- Mar 15, 2018 - generate account keypair
- Mar 15, 2018 - get nonce
- Mar 15, 2018 - get directory