@hapi/iron

Use Iron.seal() to encrypt a JavaScript object into a URI-friendly string and Iron.unseal() to decrypt it back. This process ensures message integrity and prevents tampering.

Important: You must explicitly pass an options object (like Iron.defaults) to these methods; they do not apply defaults automatically to ensure you are aware of the security properties being used.

Note on Serialization: seal() uses JSON.stringify(). Properties with undefined values will be omitted from the sealed object.

const obj = {
    a: 1,
    b: 2,
    c: [3, 4, 5],
    d: {
        e: 'f'
    }
};

const password = 'some_not_random_password_that_is_at_least_32_characters';

try {
    // Seal the object
    const sealed = await Iron.seal(obj, password, Iron.defaults);
    
    // Unseal the object
    const unsealed = await Iron.unseal(sealed, password, Iron.defaults);
    console.log(unsealed);
} catch (err) {
    console.log(err.message);
}

Iron methods accept an options object to customize key derivation, encryption, and integrity verification. The structure requires encryption and integrity sub-objects.

Encryption & Integrity Options

Both encryption and integrity objects support:

• algorithm (required): Supported values are 'aes-256-cbc' and 'aes-128-ctr' for encryption, and 'sha256' for integrity.
• iv (optional): An initialization vector buffer.

Key Derivation Options

When using a password string for key generation, you can configure:

• salt (optional): A pre-generated salt buffer.
• saltBits (required if salt is not provided): The size of the salt.
• iterations (required): Number of iterations for key derivation (default is 1).
• minPasswordlength (required): Minimum password string length (default is 32).

Seal/Unseal Specific Options

• ttl: Sealed object lifetime in milliseconds (0 for forever, default is 0).
• timestampSkewSec: Permitted clock skew in seconds for expirations (default is 60).
• localtimeOffsetMsec: Local clock offset in milliseconds (default is 0).

const options = {
    encryption: {
        saltBits: 256,
        algorithm: 'aes-256-cbc',
        iterations: 1
    },
    integrity: {
        saltBits: 256,
        algorithm: 'sha256',
        iterations: 1
    },
    ttl: 0,
    timestampSkewSec: 60,
    localtimeOffsetMsec: 0
};

The SealOptions interface allows you to customize the security and lifecycle of the sealed object. It is divided into two main configuration blocks: encryption and integrity.

Top-level options

• encryption: A SealOptionsSub object defining encryption parameters.
• integrity: A SealOptionsSub object defining HMAC/integrity parameters.
• ttl: Sealed object lifetime in milliseconds (0 for forever).
• timestampSkewSec: Permitted clock skew for incoming expirations in seconds (defaults to 60).
• localtimeOffsetMsec: Local clock time offset in milliseconds.

SealOptionsSub (used by both encryption and integrity)

• algorithm: The algorithm used (e.g., 'aes-256-cbc' for encryption or 'sha256' for integrity). Defaults to 'aes-256-cbc' for encryption and 'sha256' for integrity.
• saltBits: Length of the random salt (defaults to 256).
• iterations: Number of iterations for key derivation (defaults to 1).
• minPasswordlength: Minimum password size (defaults to 32).

const options: SealOptions = {
    encryption: {
        algorithm: 'aes-256-cbc',
        iterations: 1000
    },
    integrity: {
        algorithm: 'sha256',
        iterations: 1000
    },
    ttl: 3600000 // 1 hour
};

Use seal() to encrypt and sign an object into a single string, and unseal() to verify the signature and decrypt it back into its original object. This is the primary high-level API for securing data.

Password Formats

To use seal and unseal, the password parameter can be:

• A string or Buffer (used for both encryption and integrity).
• An object with { id, secret } (where secret is used for both).
• An object with { id, encryption, integrity } (allowing different secrets for encryption and HMAC).
• An object used as a lookup table when unseal is called with a passwordId (e.g., { myId: { encryption: '...', integrity: '...' } }).

Options

Both functions accept an options object to override exports.defaults:

• ttl: Time-to-live in milliseconds. If set, the seal will expire.
• timestampSkewSec: Permitted clock skew in seconds for expiration checks.
• localtimeOffsetMsec: Local clock offset in milliseconds.
• encryption: Configuration for the encryption algorithm (e.g., algorithm, saltBits, iterations).
• integrity: Configuration for the HMAC (e.g., algorithm, saltBits, iterations).

const Iron = require('@hapi/iron');

const password = 'my-secret-password';
const object = { foo: 'bar' };

(async () => {
    // Seal the object
    const sealed = await Iron.seal(object, password, { ttl: 1000 * 60 });

    // Unseal the object
    const unsealed = await Iron.unseal(sealed, password);
    console.log(unsealed); // { foo: 'bar' }
})();

encrypt(password, options, data) and decrypt(password, options, data) provide low-level encryption/decryption services using the derived key from a password.

Parameters

• password: A string or Buffer used to derive the key.
• options: Configuration object (see generateKey for details). Must include an algorithm from exports.algorithms.
• data: The data to encrypt (as a UTF-8 string) or decrypt (as a Buffer).

Returns

• encrypt: Resolves to { encrypted: Buffer, key: Object }.
• decrypt: Resolves to the decrypted UTF-8 string.

const Iron = require('@hapi/iron');

const password = 'password';
const data = 'hello world';
const options = { algorithm: 'aes-256-cbc' };

(async () => {
    const { encrypted, key } = await Iron.encrypt(password, options, data);
    const decrypted = await Iron.decrypt(password, options, encrypted);
    console.log(decrypted); // 'hello world'
})();