coolaj86
/
greenlock.js-ARCHIVED
3
3
Fork 0
Code Issues 6 Pull Requests 1 Releases Activity
greenlock.js-ARCHIVED/README.md

552 lines
20 KiB
Markdown
Raw Permalink Normal View History

update docs
2019-11-01 11:08:54 +00:00
# New Documentation & [v2/v3 Migration Guide](https://git.rootprojects.org/root/greenlock.js/src/branch/v3/MIGRATION_GUIDE_V2_V3.md)
Initial commit
2019-10-16 00:26:05 +00:00
update docs
2019-11-01 11:08:54 +00:00
Greenlock v3 was just released from private beta **today** (Nov 1st, 2019).
wip: yeah!
2019-10-20 08:51:19 +00:00
update docs
2019-11-01 11:08:54 +00:00
We're still working on the full documentation for this new version,
so please be patient.
To start, check out the
[Migration Guide](https://git.rootprojects.org/root/greenlock.js/src/branch/v3/MIGRATION_GUIDE_V2_V3.md).
!["Greenlock Logo"](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/greenlock-1063x250.png 'Greenlock lock logo and work mark')
!["Greenlock Function"](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/from-not-secure-to-secure-url-bar.png 'from url bar showing not secure to url bar showing secure')
# [Greenlock](https://git.rootprojects.org/root/greenlock.js) is Let's Encrypt for JavaScript
| Built by [Root](https://rootprojects.org) for [Hub](https://rootprojects.org/hub/)
Greenlock™ is an Automated Certificate Management Environement 🔐.
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.
wip: yeah!
2019-10-20 08:51:19 +00:00
add some docs
2019-10-22 02:18:16 +00:00
- [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.
ignore TODOs for now
2019-10-22 02:30:57 +00:00
<!--
add some docs
2019-10-22 02:18:16 +00:00
# Localhost Development
<details>
<summary>HTTPS on Localhost</summary>
TODO
</details>
# WebServer with Automatic HTTPS
<details>
<summary>Learn more about the Greenlock Web Server</summary>
TODO
</details>
# Commandline
<details>
<summary>Learn more about the Greenlock CLI</summary>
TODO
</details>
ignore TODOs for now
2019-10-22 02:30:57 +00:00
-->
update docs
2019-11-01 11:24:01 +00:00
# JavaScript API
add some docs
2019-10-22 02:18:16 +00:00
update docs
2019-11-01 11:08:54 +00:00
<!--
add some docs
2019-10-22 02:18:16 +00:00
<details>
<summary>Greenlock API (shared among JS implementations)</summary>
update docs
2019-11-01 11:08:54 +00:00
-->
add some docs
2019-10-22 02:18:16 +00:00
update docs
2019-11-01 11:24:01 +00:00
<details>
<summary>Greenlock.create({ packageAgent, maintainerEmail, staging })</summary>
update docs
2019-11-01 11:27:39 +00:00
## Greenlock.create()
update docs
2019-11-01 11:24:01 +00:00
Creates an instance of greenlock with _environment_-level values.
wip: yeah!
2019-10-20 08:51:19 +00:00
add some docs
2019-10-22 02:18:16 +00:00
```js
update docs
2019-11-01 11:24:01 +00:00
var pkg = require('./package.json');
add some docs
2019-10-22 02:18:16 +00:00
var gl = Greenlock.create({
tabs -> spaces
2019-10-31 22:26:18 +00:00
// Staging for testing environments
staging: true,
add some docs
2019-10-22 02:18:16 +00:00
tabs -> spaces
2019-10-31 22:26:18 +00:00
// 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
update docs
2019-11-01 11:24:01 +00:00
maintainerEmail: 'jon@example.com',
// for an RFC 8555 / RFC 7231 ACME client user agent
packageAgent: pkg.name + '/' pkg.version
v3.0.2: various bugfixes
2019-10-29 05:18:13 +00:00
});
```
| 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 |
update docs
2019-11-01 11:24:01 +00:00
| staging | use the Let's Encrypt staging URL instead of the production URL |
| directoryUrl | for use with other (not Let's Encrypt) ACME services, and the Pebble test server |
v3.0.2: various bugfixes
2019-10-29 05:18:13 +00:00
<!--
| maintainerUpdates | (default: false) receive occasional non-critical notifications |
maintainerUpdates: true // default: false
-->
add some docs
2019-10-22 02:18:16 +00:00
update docs
2019-11-01 11:24:01 +00:00
</details>
<details>
<summary>Greenlock#manager.defaults()</summary>
update docs
2019-11-01 11:27:39 +00:00
## Greenlock#manager.defaults()
update docs
2019-11-01 11:24:01 +00:00
Acts as a getter when given no arguments.
Otherwise sets default, site-wide values as described below.
v3.0.2: various bugfixes
2019-10-29 05:18:13 +00:00
```js
greenlock.manager.defaults({
tabs -> spaces
2019-10-31 22:26:18 +00:00
// 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
update docs
2019-11-01 11:08:54 +00:00
challenges: {
"http-01": {
module: "acme-http-01-webroot",
webroot: "/path/to/webroot"
}
}
add some docs
2019-10-22 02:18:16 +00:00
});
```
updates for greenlock-express
2019-10-27 10:38:05 +00:00
| 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 |
v3.0.2: various bugfixes
2019-10-29 05:18:13 +00:00
| 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<br>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 |
add some docs
2019-10-22 02:18:16 +00:00
v3.0.2: various bugfixes
2019-10-29 05:18:13 +00:00
<!--
| serverId | an arbitrary name to distinguish this server within a cluster of servers |
-->
add some docs
2019-10-22 02:18:16 +00:00
update docs
2019-11-01 11:24:37 +00:00
</details>
update docs
2019-11-01 11:24:01 +00:00
<details>
<summary>Greenlock#add({ subject, altnames })</summary>
update docs
2019-11-01 11:27:39 +00:00
## Greenlock#add()
update docs
2019-11-01 11:24:01 +00:00
Greenlock is a **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`.
add some docs
2019-10-22 02:18:16 +00:00
```js
gl.add({
tabs -> spaces
2019-10-31 22:26:18 +00:00
subject: 'example.com',
altnames: ['example.com', 'www.example.com', 'exampleapi.com']
add some docs
2019-10-22 02:18:16 +00:00
});
wip: yeah!
2019-10-20 08:51:19 +00:00
```
add some docs
2019-10-22 02:18:16 +00:00
v3.0.12: issue in background on add
2019-10-30 08:27:17 +00:00
| Parameter | Description |
| --------------- | -------------------------------------------------------------------------------------------- |
| subject | the first domain on, and identifier of the certificate |
| altnames | first domain, plus additional domains<br>note: the order should always be the same |
| subscriberEmail | if different from the default (i.e. multi-tenant, whitelabel) |
| challenges | (same as main config) use if this site needs to use non-default http-01 or dns-01 validation |
add some docs
2019-10-22 02:18:16 +00:00
update docs
2019-11-01 11:24:01 +00:00
</details>
<details>
<summary>Greenlock#get({ servername })</summary>
update docs
2019-11-01 11:27:39 +00:00
## Greenlock#get()
update docs
2019-11-01 11:08:54 +00:00
**Disclaimer**: This is only intended for testing, demos, and SNICallback
(in [Greenlock Express](https://git.rootprojects.org/root/greenlock-express.js)).
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](https://git.rootprojects.org/root/greenlock-store-test.js)
v3.0.12: issue in background on add
2019-10-30 08:27:17 +00:00
```js
return greenlock.get({ servername }).then(function(site) {
tabs -> spaces
2019-10-31 22:26:18 +00:00
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);
v3.0.12: issue in background on add
2019-10-30 08:27:17 +00:00
});
```
update docs
2019-11-01 11:24:01 +00:00
| Parameter | Description |
| ---------- | ------------------------------------------------------------- |
| servername | any altname listed on the certificate (including the subject) |
</details>
<details>
update docs
2019-11-01 11:27:39 +00:00
<summary>Greenlock#renew({ renewBefore })</summary>
v3.0.12: issue in background on add
2019-10-30 08:27:17 +00:00
update docs
2019-11-01 11:27:39 +00:00
## Greenlock#renew()
add some docs
2019-10-22 02:18:16 +00:00
This will renew only domains that have reached their `renewAt` or are within the befault `renewOffset`.
update docs
2019-11-01 11:08:54 +00:00
**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).
add some docs
2019-10-22 02:18:16 +00:00
```js
v3.0.12: issue in background on add
2019-10-30 08:27:17 +00:00
return greenlock.renew({}).then(function(results) {
tabs -> spaces
2019-10-31 22:26:18 +00:00
results.forEach(function(site) {
if (site.error) {
console.error(site.subject, site.error);
return;
}
console.log('Renewed certificate for', site.subject, site.altnames);
});
v3.0.2: various bugfixes
2019-10-29 05:18:13 +00:00
});
add some docs
2019-10-22 02:18:16 +00:00
```
update docs
2019-11-01 11:08:54 +00:00
| Parameter | Type | Description |
| ----------- | ---- | ------------------------------------------------------------------------------- |
| (optional) | | ALL parameters are optional, but some should be paired |
| force | bool | force silly options, such as tiny durations |
| renewBefore | ms | Check domains that are scheduled to renew before the given date in milliseconds |
v3.0.12: issue in background on add
2019-10-30 08:27:17 +00:00
add some docs
2019-10-22 02:18:16 +00:00
<!--
update docs
2019-11-01 11:08:54 +00:00
| issuedBefore | ms | Check domains issued before the given date in milliseconds |
| expiresBefore | ms | Check domains that expire before the given date in milliseconds |
add some docs
2019-10-22 02:18:16 +00:00
-->
</details>
fix how docs render
2019-11-01 11:42:34 +00:00
<details>
<summary>Greenlock#remove({ subject })</summary>
## 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.
```js
gl.remove({
subject: 'example.com'
}).then(function(siteConfig) {
// save the old site config elsewhere, just in case you need it again
});
```
| Parameter | Description |
| --------- | ------------------------------------------------------ |
| subject | the first domain on, and identifier of the certificate |
</details>
update docs
2019-11-01 11:27:39 +00:00
<!--
add some docs
2019-10-22 02:18:16 +00:00
<details>
<summary>Node.js</summary>
update docs
2019-11-01 11:08:54 +00:00
-->
v3.0.19: doc fixes for markdown rendering
2019-11-01 11:47:32 +00:00
# Install
Greenlock comes with reasonable defaults but when you install it,
you should also install any plugins that you need.
ignore TODOs for now
2019-10-22 02:30:57 +00:00
add some docs
2019-10-22 02:18:16 +00:00
```bash
npm install --save @root/greenlock
updates for greenlock-express
2019-10-27 10:38:05 +00:00
npm install --save greenlock-manager-fs
npm install --save greenlock-store-fs
npm install --save acme-http-01-standalone
ignore TODOs for now
2019-10-22 02:30:57 +00:00
```
add some docs
2019-10-22 02:18:16 +00:00
updates for greenlock-express
2019-10-27 10:38:05 +00:00
<!--
add some docs
2019-10-22 02:18:16 +00:00
TODO
</details>
<details>
<summary>Express.js</summary>
ignore TODOs for now
2019-10-22 02:30:57 +00:00
add some docs
2019-10-22 02:18:16 +00:00
```js
'use strict';
var Greenlock = require(@root/greenlock-express);
var greenlock = Greenlock.create({
// for security and critical bug notices
maintainerEmail: 'jon@example.com'
// for
maintainerNewsletter: true
});
wip: yeah!
2019-10-20 08:51:19 +00:00
```
ignore TODOs for now
2019-10-22 02:30:57 +00:00
</details>
wip: yeah!
2019-10-20 08:51:19 +00:00
add some docs
2019-10-22 02:18:16 +00:00
<details>
<summary>WebPack</summary>
TODO
</details>
wip: yeah!
2019-10-20 08:51:19 +00:00
add some docs
2019-10-22 02:18:16 +00:00
<details>
<summary>VanillaJS for Browsers</summary>
TODO
</details>
ignore TODOs for now
2019-10-22 02:30:57 +00:00
-->
update docs
2019-11-01 11:27:39 +00:00
# Easy to Customize
<!-- greenlock-manager-test => greenlock-manager-custom -->
<!--
- [greenlock.js/examples/](https://git.rootprojects.org/root/greenlock.js/src/branch/master/examples)
-->
<details>
v3.0.19: doc fixes for markdown rendering
2019-11-01 11:47:32 +00:00
<summary>SSL Cert & Domain Management</summary>
update docs
2019-11-01 11:27:39 +00:00
fix how docs render
2019-11-01 11:42:34 +00:00
## SSL Certificate & Domain Management
update docs
2019-11-01 11:27:39 +00:00
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({ altnames, renewBefore })
```js
// 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)
```json
{
"subscriberEmail": "jane@example.com",
"agreeToTerms": true,
"challenges": {
"http-01": {
"module": "acme-http-01-standalone"
}
}
}
```
</details>
<details>
v3.0.19: doc fixes for markdown rendering
2019-11-01 11:47:32 +00:00
<summary>Key & Cert Storage</summary>
update docs
2019-11-01 11:27:39 +00:00
fix how docs render
2019-11-01 11:42:34 +00:00
## Key and Certificate Store
update docs
2019-11-01 11:27:39 +00:00
Full Docs: https://git.rootprojects.org/root/greenlock-store-test.js
This set of callbacks update your service with new certificates and keypairs.
fix how docs render
2019-11-01 11:42:34 +00:00
### Account Keys (JWK)
update docs
2019-11-01 11:27:39 +00:00
(though typically you only have one account key - because you only have one subscriber email)
- accounts.setKeypair({ email, keypair })
- accounts.checkKeypair({ email })
fix how docs render
2019-11-01 11:42:34 +00:00
### Certificate Keys (JWK + PEM)
update docs
2019-11-01 11:27:39 +00:00
(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)
fix how docs render
2019-11-01 11:42:34 +00:00
### Certificate PEMs
update docs
2019-11-01 11:27:39 +00:00
- certificates.set({ subject, pems })
- certificates.check({ subject })
</details>
<details>
v3.0.19: doc fixes for markdown rendering
2019-11-01 11:47:32 +00:00
<summary>ACME HTTP-01 Challenges</summary>
update docs
2019-11-01 11:27:39 +00:00
fix how docs render
2019-11-01 11:42:34 +00:00
## ACME Challenge HTTP-01 Strategies
update docs
2019-11-01 11:27:39 +00:00
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 } })
<!--
TODO: getAcmeHttp01Challenge
-->
</details>
<details>
v3.0.19: doc fixes for markdown rendering
2019-11-01 11:47:32 +00:00
<summary>ACME DNS-01 Challenges</summary>
update docs
2019-11-01 11:27:39 +00:00
fix how docs render
2019-11-01 11:42:34 +00:00
## ACME Challenge DNS-01 Strategies
update docs
2019-11-01 11:27:39 +00:00
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 } })
</details>
doc updates
2019-11-01 11:30:26 +00:00
<details>
<summary>Notes on HTTP-01 &amp; DNS-01 Integrations</summary>
fix how docs render
2019-11-01 11:42:34 +00:00
## Notes on HTTP-01 &amp; DNS-01 Integrations
doc updates
2019-11-01 11:30:26 +00:00
For Public Web Servers running on a VPS, the **default HTTP-01 challenge plugin**
fix how docs render
2019-11-01 11:42:34 +00:00
will work just fine, for most people.
doc updates
2019-11-01 11:30:26 +00:00
fix how docs render
2019-11-01 11:42:34 +00:00
However, for environments that cannot be verified via public HTTP, such as
update docs
2019-11-01 11:27:39 +00:00
doc updates
2019-11-01 11:30:26 +00:00
- **Wildcard Certificates**
- **IoT Environments**
- **Enterprise On-Prem**
- **Private Networks**
Greenlock provides an easy way to integrate Let's Encrypt with your existing services
fix how docs render
2019-11-01 11:42:34 +00:00
through a variety of **DNS-01** challenges.
### Why not use dns01 for everything?
doc updates
2019-11-01 11:30:26 +00:00
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.
</details>
# Ready-made Integrations
Greenlock Express integrates between Let's Encrypt's ACME Challenges and many popular services.
| Type | Service | Plugin |
| ----------- | ----------------------------------------------------------------------------------- | ------------------------ |
| dns-01 | CloudFlare | acme-dns-01-cloudflare |
| dns-01 | [Digital Ocean](https://git.rootprojects.org/root/acme-dns-01-digitalocean.js) | acme-dns-01-digitalocean |
| dns-01 | [DNSimple](https://git.rootprojects.org/root/acme-dns-01-dnsimple.js) | acme-dns-01-dnsimple |
| dns-01 | [DuckDNS](https://git.rootprojects.org/root/acme-dns-01-duckdns.js) | acme-dns-01-duckdns |
| http-01 | File System / [Web Root](https://git.rootprojects.org/root/acme-http-01-webroot.js) | acme-http-01-webroot |
| dns-01 | [GoDaddy](https://git.rootprojects.org/root/acme-dns-01-godaddy.js) | acme-dns-01-godaddy |
| dns-01 | [Gandi](https://git.rootprojects.org/root/acme-dns-01-gandi.js) | acme-dns-01-gandi |
| dns-01 | [NameCheap](https://git.rootprojects.org/root/acme-dns-01-namecheap.js) | acme-dns-01-namecheap |
| dns-01 | [Name&#46;com](https://git.rootprojects.org/root/acme-dns-01-namedotcom.js) | acme-dns-01-namedotcom |
| dns-01 | Route53 (AWS) | acme-dns-01-route53 |
| http-01 | S3 (AWS, Digital Ocean, Scaleway) | acme-http-01-s3 |
| dns-01 | [Vultr](https://git.rootprojects.org/root/acme-dns-01-vultr.js) | acme-dns-01-vultr |
| dns-01 | [Build your own](https://git.rootprojects.org/root/acme-dns-01-test.js) | acme-dns-01-test |
| http-01 | [Build your own](https://git.rootprojects.org/root/acme-http-01-test.js) | acme-http-01-test |
| tls-alpn-01 | [Contact us](mailto:support@therootcompany.com) | - |
Search `acme-http-01-` or `acme-dns-01-` on npm to find more.
update docs
2019-11-01 11:27:39 +00:00
update docs
2019-11-01 11:08:54 +00:00
# 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](mailto:aj@therootcompany.com) 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 &amp; Rules of the Road
Greenlock&trade; is a [trademark](https://rootprojects.org/legal/#trademark) of AJ ONeal
The rule of thumb is "attribute, but don't confuse". For example:
> Built with [Greenlock Express](https://git.rootprojects.org/root/greenlock.js) (a [Root](https://rootprojects.org) project).
Please [contact us](mailto:aj@therootcompany.com) 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&trade;](https://git.rootprojects.org/root/greenlock.js) |
MPL-2.0 |
[Terms of Use](https://therootcompany.com/legal/#terms) |
[Privacy Policy](https://therootcompany.com/legal/#privacy)