Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including greenlock with all npm packages installed. Try it out:

var greenlock = require("greenlock")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

greenlock v4.0.4

The easiest Let's Encrypt client for Node.js and Browsers

New Documentation & v4 Migration Guide

We're still working on the full documentation for this new version, so please be patient.

To start, check out the Migration Guide.

"Greenlock Logo"

"Greenlock Function"

Greenlock is Let's Encrypt for JavaScript

| Built by Root for Hub

Greenlock™ is an Automated Certificate Management Environement 🔐.

| Greenlock | Greenlock Express | ACME.js |

It uses Let's Encrypt to generate Free SSL Certificates, including Wildcard SSL. It supports Automated Renewal of certs for Fully Automated HTTPS.

It's written in plain JavaScript and works in Node, Browsers, and WebPack.

the easiest way to integrate Let's Encrypt into your projects, products, and infrastructure.

  • [x] Wildcard Certificates
  • [x] IoT Environments
  • [x] Enterprise and On-Prem
  • [x] Private Networks
  • [x] Localhost Development
  • [x] Web Hosting Providers
  • [x] Commercial support

We've built it simple enough for Hobbyists, and robust enough for the Enterprise.

Greenlock.create({ configDir, packageAgent, maintainerEmail, staging })

Greenlock.create()

Creates an instance of greenlock with environment-level values.


var pkg = require('./package.json');
var gl = Greenlock.create({
    configDir: './greenlock.d/config.json',

    // Staging for testing environments
    staging: true,

    // This should be the contact who receives critical bug and security notifications
    // Optionally, you may receive other (very few) updates, such as important new features
    maintainerEmail: 'jon@example.com',

    // for an RFC 8555 / RFC 7231 ACME client user agent
    packageAgent: pkg.name + '/' pkg.version
});
ParameterDescription
configDirthe directory to use for file-based plugins
maintainerEmailthe developer contact for critical bug and security notifications
packageAgentif you publish your package for others to use, require('./package.json').name here
staginguse the Let's Encrypt staging URL instead of the production URL
directoryUrlfor use with other (not Let's Encrypt) ACME services, and the Pebble test server

Greenlock#manager.defaults()

Greenlock#manager.defaults()

Acts as a getter when given no arguments.

Otherwise sets default, site-wide values as described below.

greenlock.manager.defaults({
    // The "Let's Encrypt Subscriber" (often the same as the maintainer)
    // NOT the end customer (except where that is also the maintainer)
    subscriberEmail: 'jon@example.com',
    agreeToTerms: true
    challenges: {
      "http-01": {
        module: "acme-http-01-webroot",
        webroot: "/path/to/webroot"
      }
    }
});
ParameterDescription
agreeToTerms(default: false) either 'true' or a function that presents the Terms of Service and returns it once accepted
challenges['http-01']provide an http-01 challenge module
challenges['dns-01']provide a dns-01 challenge module
challenges['tls-alpn-01']provide a tls-alpn-01 challenge module
challenges[type].modulethe name of your challenge module
challenges[type].xxxxmodule-specific options
renewOffsetleave the default Other than for testing, leave this at the default of 45 days before expiration date ('-45d') . Can also be set like 5w, meaning 5 weeks after issue date
servernamethe default servername to use for non-sni requests (many IoT clients)
subscriberEmailthe contact who agrees to the Let's Encrypt Subscriber Agreement and the Greenlock Terms of Service
this contact receives renewal failure notifications
storeoverride the default storage module
store.modulethe name of your storage module
store.xxxxoptions specific to your storage module

Greenlock#remove({ subject })

Greenlock#manager.remove()

To stop certificates from being renewed, you must remove them.

If you are implementing your own manager callbacks, I recommend that you mark them as deleted (i.e. deleted_at in your database) rather than actually removing them. Just in case.

gl.remove({
    subject: 'example.com'
}).then(function(siteConfig) {
    // save the old site config elsewhere, just in case you need it again
});
ParameterDescription
subjectthe first domain on, and identifier of the certificate

Events

Most of the events bubble from ACME.js.

See https://git.rootprojects.org/root/acme.js#api-overview

TODO: document the greenlock-specific events.

SSL Cert & Domain Management

SSL Certificate & Domain Management

Full Docs: https://git.rootprojects.orggreenlock-manager-test.js

This is what keeps the mapping of domains <-> certificates. In many cases it will interact with the same database as the Key & Cert Store, and probably the code as well.

  • set({ subject, altnames, renewAt })
  • find({ servernames, renewBefore })
    // should return a list of site configs:
    [
        {
            subject: 'example.com',
            altnames: ['example.com', 'exampleapi.com'],
            renewAt: 1575197231760
        },
        {
            subject: '*.example.com',
            altnames: ['*.example.com'],
            renewAt: 1575197231760,
            challenges: {
                'dns-01': {
                    module: 'acme-dns-01-dnsimple',
                    apikey: 'xxxx'
                }
            }
        }
    ];
    
  • remove({ subject })
  • defaults() (both getter and setter)
    {
        "subscriberEmail": "jane@example.com",
        "agreeToTerms": true,
        "challenges": {
            "http-01": {
                "module": "acme-http-01-standalone"
            }
        }
    }
    

Key & Cert Storage

Key and Certificate Store

Full Docs: https://git.rootprojects.orggreenlock-store-test.js

This set of callbacks update your service with new certificates and keypairs.

Account Keys (JWK)

(though typically you only have one account key - because you only have one subscriber email)

  • accounts.setKeypair({ email, keypair })
  • accounts.checkKeypair({ email })

Certificate Keys (JWK + PEM)

(typically you have one for each set of domains, and each load balancer)

  • certificates.setKeypair({ subject, keypair })
  • certificates.checkKeypair({ subject }) (these are fine to implement the same as above, swapping subject/email)

Certificate PEMs

  • certificates.set({ subject, pems })
  • certificates.check({ subject })

ACME HTTP-01 Challenges

ACME Challenge HTTP-01 Strategies

Full Docs: https://git.rootprojects.org/root/acme-http-01-test.js

This validation and authorization strategy is done over plain HTTP on Port 80.

These are used to set files containing tokens that Let's Encrypt will fetch from each domain before authorizing a certificate.

NOT for Wildcards.

  • init({ request })
  • set({ challenge: { type, token, keyAuthorization, challengeUrl } })
  • get({ challenge: { type, token } })
  • remove({ challenge: { type, token } })

ACME DNS-01 Challenges

ACME Challenge DNS-01 Strategies

Full Docs https://git.rootprojects.org/root/acme-dns-01-test.js

This validation and authorization strategy is done over DNS on UDP and TCP ports 53.

For Wildcards

These are used to set TXT records containing tokens that Let's Encrypt will fetch for each domain before authorizing a certificate.

  • init({ request })
  • zones()
  • set({ challenge: { type, dnsZone, dnsPrefix, dnsHost, keyAuthorizationDigest } })
  • get({ challenge: { type, dnsZone, dnsPrefix, dnsHost } })
  • remove({ challenge: { type, dnsZone, dnsPrefix, dnsHost } })

Notes on HTTP-01 & DNS-01 Integrations

Notes on HTTP-01 & DNS-01 Integrations

For Public Web Servers running on a VPS, the default HTTP-01 challenge plugin will work just fine, for most people.

However, for environments that cannot be verified via public HTTP, such as

  • Wildcard Certificates
  • IoT Environments
  • Enterprise On-Prem
  • Private Networks

Greenlock provides an easy way to integrate Let's Encrypt with your existing services through a variety of DNS-01 challenges.

Why not use dns01 for everything?

Typically file propagation is faster and more reliably than DNS propagation. Therefore, http-01 will be preferred to dns-01 except when wildcards or private domains are in use.

http-01 will only be supplied as a defaut if no other challenge is provided.

Ready-made Integrations

Greenlock Express integrates between Let's Encrypt's ACME Challenges and many popular services.

TypeServicePlugin
dns-01CloudFlareacme-dns-01-cloudflare
dns-01Digital Oceanacme-dns-01-digitalocean
dns-01DNSimpleacme-dns-01-dnsimple
dns-01DuckDNSacme-dns-01-duckdns
http-01File System / Web Rootacme-http-01-webroot
dns-01GoDaddyacme-dns-01-godaddy
dns-01Gandiacme-dns-01-gandi
dns-01NameCheapacme-dns-01-namecheap
dns-01Name.comacme-dns-01-namedotcom
dns-01Route53 (AWS)acme-dns-01-route53
http-01S3 (AWS, Digital Ocean, Scaleway)acme-http-01-s3
dns-01Vultracme-dns-01-vultr
dns-01Build your ownacme-dns-01-test
http-01Build your ownacme-http-01-test
tls-alpn-01Contact us-

Search acme-http-01- or acme-dns-01- on npm to find more.

Commercial Support

Do you need...

  • training?
  • specific features?
  • different integrations?
  • bugfixes, on your timeline?
  • custom code, built by experts?
  • commercial support and licensing?

You're welcome to contact us in regards to IoT, On-Prem, Enterprise, and Internal installations, integrations, and deployments.

We have both commercial support and commercial licensing available.

We also offer consulting for all-things-ACME and Let's Encrypt.

Legal & Rules of the Road

Greenlock™ is a trademark of AJ ONeal

The rule of thumb is "attribute, but don't confuse". For example:

Built with Greenlock Express (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

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free