The subject (primary domain on certificate) will be the id, so it's very important that the order of the given domains be deterministic.

var altnames = ['example.com', 'www.example.com'];

greenlock
    .add({
        subject: altnames[0],
        altnames: altnames
    })
    .then(function() {
        // saved config to db (or file system)
    });

Issuance and renewal will start immediately, and run continually.

The store callbacks will be called every any of your certificates are renewed.

However, you can do a quick one-off check with get.

It will return a certificate immediately (if available), or wait for the renewal to complete (or for it to fail again).

greenlock
    .get({ servername: subject })
    .then(function(pems) {
        if (pems && pems.privkey && pems.cert && pems.chain) {
            console.info('Success');
        }
        //console.log(pems);
    })
    .catch(function(e) {
        console.error('Big bad error:', e.code);
        console.error(e);
    });

Greenlock.create()

Creates an instance of greenlock with environment-level values.

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

    // 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
});

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"
      }
    }
});

Greenlock#add()

Greenlock is a Automated Certificate Management Environment.

Once you add a "site", it will begin to automatically renew, immediately.

The certificates will provided to the store callbacks as soon as they are ready, and whenever they renew. Failure to renew will be reported to the notify callback.

You can also retrieve them one-off with get.

gl.add({
    subject: 'example.com',
    altnames: ['example.com', 'www.example.com', 'exampleapi.com']
});

Greenlock#get()

Disclaimer: This is only intended for testing, demos, and SNICallback (in Greenlock Express).

Greenlock is intended to be left running to allow it to fetech and renew certifictates automatically.

It is intended that you use the store callbacks to new certificates instantly as soon as they renew. This also protects you from accidentally stampeding the Let's Encrypt API with hundreds (or thousands) of certificate requests.

• Store Callback Documentation

return greenlock.get({ servername }).then(function(site) {
    if (!site) {
        console.log(servername + ' was not found in any site config');
        return;
    }

    var privkey = site.pems.privkey;
    var fullchain = site.pems.cert + '\n' + site.pems.chain + '\n';
    console.log(privkey);
    console.log(fullchain);
});

Greenlock#renew()

This will renew only domains that have reached their renewAt or are within the befault renewOffset.

Note: This runs at regular intervals, multiple times a day, in the background. You are not required to call it. If you implement the store callbacks, the certificates will automatically be saved (and if you don't implement them, they all get saved to disk).

return greenlock.renew({}).then(function(results) {
    results.forEach(function(site) {
        if (site.error) {
            console.error(site.subject, site.error);
            return;
        }
        console.log('Renewed certificate for', site.subject, site.altnames);
    });
});

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
});

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 Certificate & Domain Management

Full Docs: https://git.rootprojects.org/root/greenlock-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 and Certificate Store

Full Docs: https://git.rootprojects.org/root/greenlock-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 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 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

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.