AJ ONeal
2a881d9edb
|
5 ๋ ์ | |
---|---|---|
bin | 5 ๋ ์ | |
tests | 5 ๋ ์ | |
.gitignore | 5 ๋ ์ | |
.prettierrc | 5 ๋ ์ | |
LICENSE | 5 ๋ ์ | |
MIGRATION_GUIDE_V2_V3.md | 5 ๋ ์ | |
README.md | 5 ๋ ์ | |
accounts.js | 5 ๋ ์ | |
certificates.js | 5 ๋ ์ | |
errors.js | 5 ๋ ์ | |
greenlock.js | 5 ๋ ์ | |
manager-underlay.js | 5 ๋ ์ | |
order.js | 5 ๋ ์ | |
package-lock.json | 5 ๋ ์ | |
package.json | 5 ๋ ์ | |
plugins.js | 5 ๋ ์ | |
user-events.js | 5 ๋ ์ | |
utils.js | 5 ๋ ์ |
README.md
@root/greenlock
๐ Free SSL, Free Wildcard SSL, and Fully Automated HTTPS for Node.js and Browsers, issued by Let's Encrypt v2 via ACME
Greenlockโข is the easiest way to integrate Let's Encrypt into your projects, products, and infrastructure.
- Wildcard Certificates
- IoT Environments
- Enterprise and On-Prem
- Private Networks
- Localhost Development
- Web Hosting Providers
- Commercial support
We've built it simple enough for Hobbyists, and robust enough for the Enterprise.
JavaScript Library
Greenlock API (shared among JS implementations)
Instantiate
// Creates an instance of greenlock with certain default values
var gl = Greenlock.create({
// 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'
});
Parameter | Description |
---|---|
maintainerEmail | the developer contact for critical bug and security notifications |
packageAgent | if you publish your package for others to use, require('./package.json').name here |
Add Approved Domains
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
});
Parameter | Description |
---|---|
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].module | the name of your challenge module |
challenges[type].xxxx | module-specific options |
servername | the default servername to use for non-sni requests (many IoT clients) |
subscriberEmail | the contact who agrees to the Let's Encrypt Subscriber Agreement and the Greenlock Terms of Service this contact receives renewal failure notifications |
store | override the default storage module |
store.module | the name of your storage module |
store.xxxx | options specific to your storage module |
gl.add({
subject: 'example.com',
altnames: ['example.com', 'www.example.com', 'exampleapi.com']
});
Parameter | Description |
---|---|
subject | the first domain on, and identifier of the certificate |
altnames | first domain, plus additional domains note: the order should always be the same |
subscriberEmail | if different from the default (i.e. multi-tenant, whitelabel) |
agreeToTerms | if subscriber is different from the default |
challenges | (same as main config) use if this site needs to use non-default http-01 or dns-01 validation |
Issue Certificates
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);
});
Parameter | Description |
---|---|
servername | the first domain on, and identifier of the certificate |
Renew Certificates
This will renew only domains that have reached their renewAt
or are within the befault renewOffset
.
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);
});
});
Parameter | Type | Description |
---|---|---|
(optional) | ALL parameters are optional, but some should be paired | |
force | bool | force silly options, such as tiny durations |
issuedBefore | ms | Check domains issued before the given date in milliseconds |
expiresBefore | ms | Check domains that expire before the given date in milliseconds |
renewBefore | ms | Check domains that are scheduled to renew before the given date in milliseconds |
Force a certificate to renew
greenlock.update({ subject, renewAt: 0 }).then(function() {
return greenlock.renew({});
});
Note: only previous approved domains (via gl.add()
) may be renewed
Note: this will NOT throw an error. It will return an array of certifates or errors.
More
TODO
Node.js
npm install --save @root/greenlock
npm install --save greenlock-manager-fs
npm install --save greenlock-store-fs
npm install --save acme-http-01-standalone
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
- 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 infrastructure
Why 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.
You can use ACME (Let's Encrypt) with
- DNS-01 Challenges
- HTTP-01 Challenges
- In-Memory (Standalone)
- FileSystem (WebRoot)
- S3 (AWS, Digital Ocean, etc)
- TLS-ALPN-01 Challenges
- Contact us to learn about Greenlock Pro