connections.js

ABOUT

This module is concerned with the establishment and maintenance of https connections to the server and redirects any attempted connections to non-secure port(s). The primary output of this module is an HTTPS server

REQUIREMENTS & ASSUMPTIONS

require('../security.json')
const fs = require('fs')
const https = require('https')
const http = require('http')
const cert = require('./secrets').fetchSecret('CERTIFICATE')
const key = require('./secrets').fetchSecret('PRIV_KEY')
// const ca = require('./secrets').fetchSecret('CERT_AUTH') // Not needed if you aren't rolling your own CA
const { constants } = require('crypto')

const port = require('./secrets').fetchSecret('PORT') || 8080

_spartan assumes information related to keys or certificates to be SECRET. The path to the key and certificate files are saved in the .env file. See secrets for more information on how to set this up.

_spartan uses the default node ciphers for now. See node docs if you want to change this

The CA (Certificate Authority) variable is commented out, but left in the base code in the event that you’re using a local CA (versus letsencrypt or another vendor)

SOME WORDS ABOUT CERTIFICATES

Setting up an HTTPS server in node requires at least two pieces of information:

  • a certificate => grants permissions to use encrypted communication via Public Key Infrastructure, and also authenticates the identity of the certificate‚Äôs holder.
  • a private key => generates a Certificate Signing Request (CSR), and later secures and verifies connections using the certificate created per request
  • a certificate authority bundle file (optional) => generates and validates certificates & signing requests.

To be clear, use of the connections module to set up an HTTPS server may not be necessary for your application. If you’re using other tools or services (such as Apache or Nginx) to perform this function, you can modify your security policy to state: connectionPolicy.enabled = false && connectionPolicy.compensatingControl = true

AVAILABLE METHODS

Module Instantiation

method name description params returns
secureServer returns functions to create a secure https server N/A secure server (Https) or Error for key/cert issues
redirectHttp returns functions to create an insecure server to redirect http connections to the secure server N/A server (Http) or Error

USAGE

// where security = require('security')
let secureConnection = security.connections.secureServer
let redirectSecure = security.connections.redirectHttp

Secure Server

method name description params returns
secureServer() configures the secure server for use in the application app Application, callback Function Success message (String) or Error

USAGE

// where app = express() or similar
secureConnection(app, function (request, response) {
  console.log('I\'m listening...')
})

The connections module uses the default nodejs ciphers in their default order and prevents the use of TLSv1.0 (e.g. only TLS1.1 or better is allowed) by default. You can change this in the connections module by modifying the options object:

  // in connections.js
const options = {
  secureOptions: constants.SSL_OP_NO_TLSv1, // prevents use of TLSv1
  key: fs.readFileSync(key),
  cert: fs.readFileSync(cert),
  // ca: fs.readFileSync(ca), // again, you don't need this if you're not rolling your own CA
  // ciphers: ciphers => only use this if you're not using the default ciphers
  honorCipherOrder: true
  }

Redirect Server

method name description params returns
redirectHttp() configures the redirect server for use in the application N/A Error

USAGE

// where redirectSecure = security.connections.redirectHttp
redirectSecure()

ERRORS

  • (‘https/connection-policy-not-enabled’) => thrown if the connection policy object is not enabled. To change this, change connectionPolicy.enabled = true in security.json
  • (‘https/invalid-certificate-path’) => thrown if the path to the HTTPS certificate is invalid or the cert file could not be found
  • (‘https/invalid-key-path’) => thrown if the path to the HTTPS private key is invalid or the key file could not be found