CipherSweet

• PHP
• Node.js

Key/Backend Rotation

CipherSweet aims to make key rotation and/or backend migration as pain-free as possible.

To use these APIs, first instantiate two CipherSweet instances. They can have different backends (e.g. FIPSCrypto to BoringCrypto), different keys, or both.

FieldRotator

const {
    CipherSweet,
    EncryptedField,
    FieldRotator
} = require('ciphersweet-js');

/**
 * @var {string} ciphertext
 * @var {CipherSweet} oldEngine
 * @var {CipherSweet} newEngine
 */
let oldField = new EncryptedField(oldEngine, 'contacts', 'ssn');
let newField = new EncryptedField(newEngine, 'contacts', 'ssn');

let rotator = new FieldRotator(oldField, newField);

if (rotator.needsReEncrypt(ciphertext)) {
    [ciphertext, indices] = rotator.prepareForUpdate(ciphertext);
}

You can optionally also provide additional authenticated data to this API, like so:

if (rotator.needsReEncrypt(ciphertext, 'old AAD')) {
    [ciphertext, indices] = rotator.prepareForUpdate(ciphertext, 'old AAD', 'new AAD');
}

The end result will be re-encrypted, and the ciphertext tag will be tied to "new AAD".

RowRotator

const {
    CipherSweet,
    EncryptedRow,
    RowRotator
} = require('ciphersweet-js');

/**
 * @var {string} ciphertext
 * @var {CipherSweet} oldEngine
 * @var {CipherSweet} newEngine
 */
let oldField = new EncryptedRow(oldEngine, 'contacts');
let newField = new EncryptedRow(newEngine, 'contacts');

let rotator = new RowRotator(oldField, newField);

if (rotator.needsReEncrypt(ciphertext)) {
    [ciphertext, indices] = rotator.prepareForUpdate(ciphertext);
}

MultiRowsRotator

const {
    CipherSweet,
    EncryptedMultiRows,
    MultiRowsRotator
} = require('ciphersweet-js');

/**
 * @var {string} ciphertext
 * @var {CipherSweet} oldEngine
 * @var {CipherSweet} newEngine
 */
let oldField = new EncryptedMultiRow(oldEngine);
let newField = new EncryptedMultiRow(newEngine);

let rotator = new MultiRowsRotator(oldField, newField);

if (rotator.needsReEncrypt(ciphertext)) {
    [ciphertext, indices] = rotator.prepareForUpdate(ciphertext);
}

Next: EncryptedFile