DADI SSL

Automated SSL certificate generation for the DADI Stack.

Overview

DADI SSL is a lightweight fully automated totally free SSL generation service that fits seemlessly into the DADI suite of microservices, as all major routing modules including restify and express.

It uses the letsencrypt certificate authority to register, create and automatically update multi-domain SSL certificates for use on single-server instances of your application.

It is recommended that load balanced services should apply certificates as part of the security policy, which is usually free.

Getting started

1. Install the @dadi/ssl module:

npm install @dadi/ssl --save

2. Add the library to your project file:

const SSL = require('@dadi/ssl')

3. Add preferences:

// Example: select a domain and location to store certificates.
const ssl = new SSL()
  .useDomains(['somedomain.com'])
  .storeIn('/data/app/dadi-ssl/certs', true)
  .registerTo('[e-mail]')
  .secureServerRestart(serverRestartFunction)
  .useListeningServer(listeningServer)
  .start()

4. Using with your server

// Example

// Specify domain(s), a directory and a registration address.
const ssl = new SSL()
  .useDomains(['somedomain.com'])
  .storeIn('/data/app/dadi-ssl/certs', true)
  .registerTo('[e-mail]')

// Start listening server on port 80.
const listeningServer = restify.createServer({
  port: 80
})

// Start secure server on port 443, with key and certificate files.
const server = restify.createServer({
  port: 443,
  key: ssl.getKey(),
  certificate: ssl.getCertificate()
})

// Add your servers and start the process.
ssl
  .secureServerRestart(serverRestartFunction)
  .useListeningServer(listeningServer)
  .start()

Required settings

.useDomains(domains)

Select the domains to register. Must be an array.

// Example
.useDomains(['foo.somedomain.com', 'bar.somedomain.com', 'somedomain.com'])

.registerTo(email)

Set the email address for the certificate registration.

// Example
.registerTo('[e-mail]')

.secureServerRestart(serverRestartFunction)

Pass a server restart method to be called after successful certificate generation.

// Example
.secureServerRestart(restartFunction)

.useListeningServer(listeningServer)

A listening server running on port 80 allows the service to perform the necessary challenge requests.

// Example
.useListeningServer(listeningServer)

Optional settings

.storeIn(domains)

Select a directory to store certificate, and whether to force creation if the directory doesn't exist.

// Example
.storeIn('/data/app/dadi-ssl/certs', true)

.autoRenew(autoRenew)

Whether to auto renew certificates two days before expiry.

Default: true

// Example
.autoRenew(true)

.byteLength(length)

Bytelength of certificate. Can be between 512 and 4096. Higher = more secure, but slower to generate. Certificates with 2048 are assumed to be uncompromisable until the year 2030.

Default: 2048

// Example
.byteLength(4096)

.useEnvironment(environment)

Select which letsencrypt environment to use. Can be useful when debugging or avoiding usage limits (20/day).

Options: production, staging

// Example
.useEnvironment('staging')

Terminators

.start()

Initialises the process of creating certificates.

// Example
new SSL()
  .useDomains(['somedomain.com'])
  .registerTo('[e-mail]')
  .secureServerRestart(serverRestartFunction)
  .useListeningServer(listeningServer)
  .start()

.getKey()

Get contents of the key file (domain.key). Useful for the key attribute of your server options.

const ssl = new SSL()

ssl.getKey()

.getCertificate()

Get contents of the certificate chain file (chained.pem). Useful for the certificate attribute of your server options.

const ssl = new SSL()

ssl.getCertificate()

Limitation

Letsencrypt will allow a maximum of 20 requests per domain, per day.

Generation of certificates requests a response directly to the server that made the request which can't be guarenteed when using a load balancer.