Lightweight library for getting Free SSL certifications through Let's Encrypt v2, using ACME (RFC 8555)
Go to file
AJ ONeal 0f20783f12 add comment on privkey and other useful pem data 2018-07-11 22:35:38 -06:00
examples v1.0.2 2018-04-16 01:04:06 +00:00
tests * the other callback 2018-07-04 00:36:33 -06:00
.gitignore * the other callback 2018-07-04 00:36:33 -06:00
.jshintrc add .jshintrc 2018-07-04 00:11:20 -06:00
LICENSE update LICENSE 2018-05-23 03:08:58 -06:00
README.md remove TODO section (now in issues) 2018-04-24 11:58:45 -06:00
compat.js update line endings (and add brackets to logs...) 2018-07-04 00:10:48 -06:00
node.js add comment on privkey and other useful pem data 2018-07-11 22:35:38 -06:00
package.json simplify keywords, add draft-12 2018-07-07 14:00:22 -06:00

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.

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
  • 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