README.md

client-sessions is connect middleware that implements sessions in encrypted tamper-free cookies. For a complete introduction to encrypted client side sessions, refer to Francois Marier's blog post on the subject;

NOTE: It is not recommended using both this middleware and connect's built-in session middleware.

Installation

npm install client-sessions

Usage

Basic usage:

var sessions = require("client-sessions");
app.use(sessions({
  cookieName: 'mySession', // cookie name dictates the key name added to the request object
  secret: 'blargadeeblargblarg', // should be a large unguessable string
  duration: 24 * 60 * 60 * 1000, // how long the session will stay valid in ms
  activeDuration: 1000 * 60 * 5 // if expiresIn < activeDuration, the session will be extended by activeDuration milliseconds
}));

app.use(function(req, res, next) {
  if (req.mySession.seenyou) {
    res.setHeader('X-Seen-You', 'true');
  } else {
    // setting a property will automatically cause a Set-Cookie response
    // to be sent
    req.mySession.seenyou = true;
    res.setHeader('X-Seen-You', 'false');
  }
});

You can control more specific cookie behavior during setup:

app.use(sessions({
  cookieName: 'mySession', // cookie name dictates the key name added to the request object
  secret: 'blargadeeblargblarg', // should be a large unguessable string
  duration: 24 * 60 * 60 * 1000, // how long the session will stay valid in ms
  cookie: {
    path: '/api', // cookie will only be sent to requests under '/api'
    maxAge: 60000, // duration of the cookie in milliseconds, defaults to duration above
    ephemeral: false, // when true, cookie expires when the browser closes
    httpOnly: true, // when true, cookie is not accessible from javascript
    secure: false // when true, cookie will only be sent over SSL. use key 'secureProxy' instead if you handle SSL not in your node process
  }
}));

You can have multiple cookies:

// a 1 week session
app.use(sessions({
  cookieName: 'shopping_cart',
  secret: 'first secret',
  duration: 7 * 24 * 60 * 60 * 1000
}));

// a 2 hour encrypted session
app.use(sessions({
  cookieName: 'authenticated',
  secret: 'first secret',
  duration: 2 * 60 * 60 * 1000
}));

In this example, there's a 2 hour authentication session, but shopping carts persist for a week.

Finally, you can use requestKey to force the name where information can be accessed on the request object.

var sessions = require("client-sessions");
app.use(sessions({
  cookieName: 'mySession',
  requestKey: 'forcedSessionKey', // requestKey overrides cookieName for the key name added to the request object.
  secret: 'blargadeeblargblarg', // should be a large unguessable string or Buffer
  duration: 24 * 60 * 60 * 1000, // how long the session will stay valid in ms
}));

app.use(function(req, res, next) {
  // requestKey forces the session information to be
  // accessed via forcedSessionKey
  if (req.forcedSessionKey.seenyou) {
    res.setHeader('X-Seen-You', 'true');
  }
  next();
});

Cryptography

A pair of encryption and signature keys are derived from the secret option via HMAC-SHA-256; the secret isn't used directly to encrypt or compute the MAC.

The key-derivation function, in pseudocode:

  encKey := HMAC-SHA-256(secret, 'cookiesession-encryption');
  sigKey := HMAC-SHA-256(secret, 'cookiesession-signature');

The AES-256-CBC cipher is used to encrypt the session contents, with an HMAC-SHA-256 authentication tag (via Encrypt-then-Mac composition). A random 128-bit Initialization Vector (IV) is generated for each encryption operation (this is the AES block size regardless of the key size). The CBC-mode input is padded with the usual PKCS#5 scheme.

In pseudocode, the encryption looks like the following, with || denoting concatenation. The createdAt and duration parameters are decimal strings.

  sessionText := cookieName || '=' || sessionJson
  iv := secureRandom(16 bytes)
  ciphertext := AES-256-CBC(encKey, iv, sessionText)
  payload := iv || '.' || ciphertext || '.' || createdAt || '.' || duration
  hmac := HMAC-SHA-256(sigKey, payload)
  cookie := base64url(iv) || '.' ||
    base64url(ciphertext) || '.' ||
    createdAt || '.' ||
    duration || '.' ||
    base64url(hmac)

For decryption, a constant-time equality operation is used to verify the HMAC output to avoid the plausible timing attack.

Advanced Cryptographic Options

The defaults are secure, but may not suit your requirements. Some example scenarios:

• You want to use randomly-generated keys instead of using the key-derivation function used in this module.
• AES-256 is overkill for the type of data you store in the session (e.g. not personally-identifiable or sensitive) and you'd like to trade-off decreasing the security level for CPU economy.
• SHA-256 is maybe too weak for your application and you want to have more MAC security by using SHA-512, which grows the size of your cookies slightly.

If the defaults don't suit your needs, you can customize client-sessions. Beware: Changing keys and/or algorithms will make previously-generated Cookies invalid!

Configuring Keys

To configure independent encryption and signature (HMAC) keys:

app.use(sessions({
  encryptionKey: loadFromKeyStore('session-encryption-key'),
  signatureKey: loadFromKeyStore('session-signature-key'),
  // ... other options discussed above ...
}));

Configuring Algorithms

To specify custom algorithms and keys:

app.use(sessions({
  // use WEAKER-than-default encryption:
  encryptionAlgorithm: 'aes128',
  encryptionKey: loadFromKeyStore('session-encryption-key'),
  // use a SHORTER-than-default MAC:
  signatureAlgorithm: 'sha256-drop128',
  signatureKey: loadFromKeyStore('session-signature-key'),
  // ... other options discussed above ...
}));

Encryption Algorithms

Supported CBC-mode encryptionAlgorithms (and key length requirements):

Cipher	Key length
aes128	16 bytes
aes192	24 bytes
aes256	32 bytes

These key lengths are exactly as required by the Advanced Encryption Standard.

Signature (HMAC) Algorithms

Supported HMAC signatureAlgorithms (and key length requirements):

HMAC	Minimum Key Length	Maximum Key Length
sha256	32 bytes	64 bytes
sha256-drop128	32 bytes	64 bytes
sha384	48 bytes	128 bytes
sha384-drop192	48 bytes	128 bytes
sha512	64 bytes	128 bytes
sha512-drop256	64 bytes	128 bytes

The HMAC key length requirements are derived from RFC 2104 section 3. The maximum key length can be exceeded, but it doesn't increase the security of the signature.

The -dropN algorithms discard the latter half of the HMAC output, which provides some additional protection against SHA2 length-extension attacks on top of HMAC. The same technique is used in the upcoming JSON Web Algorithms AES_CBC_HMAC_SHA2 authenticated cipher.

Generating Keys

One can easily generate both AES and HMAC-SHA2 keys via command line: openssl rand -base64 32 for a 32-byte (256-bit) key. It's easy to then parse that output into a Buffer:

function loadKeyFromStore(name) {
  var text = myConfig.keys[name];
  return Buffer.from(text, 'base64');
}

Key Constraints

If you specify encryptionKey or signatureKey, you must supply the other as well.

The following constraints must be met or an Error will be thrown:

1. both keys must be Buffers.
2. the keys must be different.
3. the encryption key are exactly the length required (see above).
4. the signature key has at least the length required (see above).

Based on the above, please note that if you specify a secret and a signatureAlgorithm, you need to use sha256 or sha256-drop128.

License

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.