greenlock
Advanced tools
Greenlock v3 is in private beta (for backers) and will be available publicly by Nov 1st.
You can keep an eye for updates on the campaign page and, if this has been a useful project that's saved you time, please contribute.
Greenlock provides Free SSL, Free Wildcard SSL, and Fully Automated HTTPS
certificates issued by Let's Encrypt v2 via ACME
Greenlock works in the Commandline (cli), as a Web Server, in Web Browsers (WebCrypto), and with node.js (npm).
bash, fish, zsh, cmd.exe, PowerShell, and moreDocumentation for using Greenlock with http/https, Express.js, hapi, Koa, rill.
npm install --save greenlock@2.x
Optional for more efficient RSA key generation you must use node v10.12+ (important for those on ARM devices like Raspberry Pi)
If at first you don't succeed, stop and switch to staging.
I've implemented a "dry run" loopback test with self diagnostics so it's pretty safe to start off with the production URLs and be far less likely to hit the bad request rate limits.
However, if your first attempt to get a certificate fails I'd recommend switching to the staging acme server to debug - unless you're very clear on what the failure was and how to fix it.
{ server: 'https://acme-staging-v02.api.letsencrypt.org/directory' }
Watch the QuickStart demonstration: https://youtu.be/e8vaR4CEZ5s
Greenlock is built to incredibly easy to use, without sacrificing customization or extensibility.
The following examples range from just a few lines of code for getting started, to more robust examples that you might start with for an enterprise-grade use of the ACME api.
Note: For (fully) automatic HTTPS you may prefer the Express.js module
This works for most people, but it's not as fun as some of the other examples.
Great when
////////////////////
// INIT GREENLOCK //
////////////////////
var greenlock = require('greenlock').create({
email: 'user@example.com', // IMPORTANT: Change email and domains
agreeTos: true, // Accept Let's Encrypt v2 Agreement
configDir: '~/.config/acme', // A writable folder (a non-fs plugin)
communityMember: true, // Get (rare) non-mandatory updates about cool greenlock-related stuff (default false)
securityUpdates: true // Important and mandatory notices related to security or breaking API changes (default true)
});
////////////////////
// CREATE SERVERS //
////////////////////
var redir = require('redirect-https')();
require('http')
.createServer(greenlock.middleware(redir))
.listen(80);
require('spdy')
.createServer(greenlock.tlsOptions, function(req, res) {
res.end('Hello, Secure World!');
})
.listen(443);
Note: For (fully) automatic HTTPS you may prefer the Express.js module
Great when
////////////////////
// INIT GREENLOCK //
////////////////////
var path = require('path');
var os = require('os');
var Greenlock = require('greenlock');
var greenlock = Greenlock.create({
version: 'draft-12',
server: 'https://acme-v02.api.letsencrypt.org/directory',
// Use the approveDomains callback to set per-domain config
// (default: approve any domain that passes self-test of built-in challenges)
approveDomains: approveDomains,
// the default servername to use when the client doesn't specify
servername: 'example.com',
// If you wish to replace the default account and domain key storage plugin
store: require('le-store-fs').create({
configDir: path.join(os.homedir(), 'acme/etc'),
webrootPath: '/tmp/acme-challenges'
})
});
/////////////////////
// APPROVE DOMAINS //
/////////////////////
var http01 = require('le-challenge-fs').create({
webrootPath: '/tmp/acme-challenges'
});
function approveDomains(opts, certs, cb) {
// This is where you check your database and associated
// email addresses with domains and agreements and such
// Opt-in to submit stats and get important updates
opts.communityMember = true;
// If you wish to replace the default challenge plugin, you may do so here
opts.challenges = { 'http-01': http01 };
// The domains being approved for the first time are listed in opts.domains
// Certs being renewed are listed in certs.altnames
// certs.domains;
// certs.altnames;
opts.email = 'john.doe@example.com';
opts.agreeTos = true;
// NOTE: you can also change other options such as `challengeType` and `challenge`
// opts.challengeType = 'http-01';
// opts.challenge = require('le-challenge-fs').create({});
cb(null, { options: opts, certs: certs });
}
////////////////////
// CREATE SERVERS //
////////////////////
var redir = require('redirect-https')();
require('http')
.createServer(greenlock.middleware(redir))
.listen(80);
require('https')
.createServer(greenlock.tlsOptions, function(req, res) {
res.end('Hello, Secure World!');
})
.listen(443);
Here's a taste of the API that you might use if building a commandline tool or API integration that doesn't use node's SNICallback.
/////////////////////
// SET USER PARAMS //
/////////////////////
var opts = {
domains: [ 'example.com' // CHANGE EMAIL AND DOMAINS
, 'www.example.com' ]
, email: 'user@example.com'
, agreeTos: true // Accept Let's Encrypt v2 Agreement
, communityMember: true // Help make Greenlock better by submitting
// stats and getting updates
};
////////////////////
// INIT GREENLOCK //
////////////////////
var greenlock = require('greenlock').create({
version: 'draft-12'
, server: 'https://acme-v02.api.letsencrypt.org/directory'
, configDir: '/tmp/acme/etc'
});
///////////////////
// GET TLS CERTS //
///////////////////
greenlock.register(opts).then(function (certs) {
console.log(certs);
// privkey, cert, chain, expiresAt, issuedAt, subject, altnames
}, function (err) {
console.error(err);
});
The domain key and ssl certificates you get back can be used in a webserver like this:
var tlsOptions = {
key: certs.privkey,
cert: certs.cert + '\r\n' + certs.chain
};
require('https')
.createServer(tlsOptions, function(req, res) {
res.end('Hello, Secure World!');
})
.listen(443);
The configuration consists of 3 components:
'use strict';
var Greenlock = require('greenlock');
var greenlock;
// Storage Backend
var leStore = require('greenlock-store-fs').create({
configDir: '~/acme/etc' // or /etc/letsencrypt or wherever
, debug: false
});
// ACME Challenge Handlers
var leHttpChallenge = require('le-challenge-fs').create({
webrootPath: '~/acme/var/' // or template string such as
, debug: false // '/srv/www/:hostname/.well-known/acme-challenge'
});
function leAgree(opts, agreeCb) {
// opts = { email, domains, tosUrl }
agreeCb(null, opts.tosUrl);
}
greenlock = Greenlock.create({
version: 'draft-12' // 'draft-12' or 'v01'
// 'draft-12' is for Let's Encrypt v2 otherwise known as ACME draft 12
// 'v02' is an alias for 'draft-12'
// 'v01' is for the pre-spec Let's Encrypt v1
//
// staging API
//server: 'https://acme-staging-v02.api.letsencrypt.org/directory'
//
// production API
server: 'https://acme-v02.api.letsencrypt.org/directory'
, store: leStore // handles saving of config, accounts, and certificates
, challenges: {
'http-01': leHttpChallenge // handles /.well-known/acme-challege keys and tokens
}
, challengeType: 'http-01' // default to this challenge type
, agreeToTerms: leAgree // hook to allow user to view and accept LE TOS
//, sni: require('le-sni-auto').create({}) // handles sni callback
// renewals happen at a random time within this window
, renewWithin: 14 * 24 * 60 * 60 * 1000 // certificate renewal may begin at this time
, renewBy: 10 * 24 * 60 * 60 * 1000 // certificate renewal should happen by this time
, debug: false
//, log: function (debug) {console.log.apply(console, args);} // handles debug outputs
});
// If using express you should use the middleware
// app.use('/', greenlock.middleware());
//
// Otherwise you should see the test file for usage of this:
// greenlock.challenges['http-01'].get(opts.domain, key, val, done)
// Check in-memory cache of certificates for the named domain
greenlock.check({ domains: [ 'example.com' ] }).then(function (results) {
if (results) {
// we already have certificates
return;
}
// Register Certificate manually
greenlock.register({
domains: ['example.com'] // CHANGE TO YOUR DOMAIN (list for SANS)
, email: 'user@email.com' // CHANGE TO YOUR EMAIL
, agreeTos: '' // set to tosUrl string (or true) to pre-approve (and skip agreeToTerms)
, rsaKeySize: 2048 // 2048 or higher
, challengeType: 'http-01' // http-01, tls-sni-01, or dns-01
}).then(function (results) {
console.log('success');
}, function (err) {
// Note: you must either use greenlock.middleware() with express,
// manually use greenlock.challenges['http-01'].get(opts, domain, key, val, done)
// or have a webserver running and responding
// to /.well-known/acme-challenge at `webrootPath`
console.error('[Error]: node-greenlock/examples/standalone');
console.error(err.stack);
});
});
Here's what results looks like:
{ privkey: '' // PEM encoded private key
, cert: '' // PEM encoded cert
, chain: '' // PEM encoded intermediate cert
, issuedAt: 0 // notBefore date (in ms) parsed from cert
, expiresAt: 0 // notAfter date (in ms) parsed from cert
, subject: '' // example.com
, altnames: [] // example.com,www.example.com
}
The full end-user API is exposed in the example above and includes all relevant options.
greenlock.register(opts)
greenlock.check(opts)
We do expose a few helper functions:
TODO fetch domain tld list
The following variables will be tempalted in any strings passed to the options object:
~/ replaced with os.homedir() i.e. /Users/aj:hostname replaced with the first domain in the list i.e. example.comBy default SNI is made to lowercase and is automatically rejected if it contains invalid characters for a domain. This behavior can be modified:
__dns_allow_dangerous_names allow SNI names like "Robert'); DROP TABLE Students;"__dns_preserve_case passes SNI names such as "ExAMpLE.coM" without converting to lower caseIf you are developing an le-store-* or le-challenge-* plugin you need to be aware of
additional internal API expectations.
IMPORTANT:
Use v3.0.0 as your initial version - NOT v0.1.0 and NOT v1.0.0 and NOT v2.0.0.
This is to indicate that your module is compatible with v3 (v2.7+) of node-greenlock.
Since the public API for your module is defined by node-greenlock the major version should be kept in sync.
See greenlock-store-test and greenlock-store-fs
See greenlock-challenge-test, acme-http-01-cli, and acme-dns-01-cli
.set(opts);.get(opts);.remove(opts);greenlock-store-fs replaces le-store-certbot as the default storage plugindnsrenewWithin default to 14 daysAs the number of businesses using Greenlock commercially has increased, we've become more aware of the need for quick-turnaround support and licenses that allow for local private modifications. Currently we offer LTS support and commercial licensing models for IoT, On-Prem, and Web Hosting. Please contact us to learn more.
Our trademark policy is pretty much "attribute, but don't confuse". Your users should understand that your product uses Greenlock and not be confused to think that it is Greenlock.
Greenlock™ is a trademark of AJ ONeal
The rule of thumb is "attribute, but don't confuse". For example:
Built with Greenlock.js (a Root project).
Please contact us if you have any questions in regards to our trademark, attribution, and/or visible source policies. We want to build great software and a great community.
Greenlock™ | MPL-2.0 | Terms of Use | Privacy Policy
FAQs
Greenlock is Let's Encrypt (ACME) client for node.js
The npm package greenlock receives a total of 7,882 weekly downloads. As such, greenlock popularity was classified as popular.
We found that greenlock demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Popular npm packages like eslint-config-prettier were compromised after a phishing attack stole a maintainer’s token, spreading malicious updates.
Security News
/Research
A phishing attack targeted developers using a typosquatted npm domain (npnjs.com) to steal credentials via fake login pages - watch out for similar scams.
Security News
Knip hits 500 releases with v5.62.0, refining TypeScript config detection and updating plugins as monthly npm downloads approach 12M.