or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

asymmetric-cryptography.md digital-signatures.md hash-functions.md hmac.md index.md key-derivation.md key-exchange.md random-generation.md symmetric-encryption.md

tile.json

Symmetric Encryption

AES and other symmetric encryption algorithms for data confidentiality. Provides encryption and decryption using shared secret keys.

Capabilities

Create Cipher (Password-based)

Creates a cipher object for encryption using a password-derived key.

/**
 * Create cipher for encryption using password-derived key
 * @param {string} algorithm - Cipher algorithm (e.g., 'aes192', 'aes256')
 * @param {string} password - Password string for key derivation
 * @returns {Cipher} Cipher object for encryption
 */
function createCipher(algorithm, password) { }

/**
 * Cipher object for encryption operations
 * @class Cipher
 */
/**
 * Update cipher with data to encrypt
 * @param {string|Buffer} data - Data to encrypt (string or Buffer)
 * @param {string} [inputEncoding] - Input encoding if data is string
 * @param {string} [outputEncoding] - Output encoding for encrypted data
 * @returns {string|Buffer} Encrypted data chunk
 */
Cipher.prototype.update = function(data, inputEncoding, outputEncoding) { };

/**
 * Finalize encryption and get remaining encrypted data
 * @param {string} [outputEncoding] - Output encoding for final encrypted chunk
 * @returns {string|Buffer} Final encrypted data chunk
 */
Cipher.prototype.final = function(outputEncoding) { };

Create Cipher with IV

Creates a cipher object using explicit key and initialization vector.

/**
 * Create cipher for encryption using explicit key and IV
 * @param {string} algorithm - Cipher algorithm (e.g., 'aes-256-cbc', 'aes-128-gcm')
 * @param {Buffer} key - Encryption key as Buffer
 * @param {Buffer} iv - Initialization vector as Buffer
 * @returns {Cipher} Cipher object for encryption
 */
function createCipheriv(algorithm, key, iv) { }

Create Decipher (Password-based)

Creates a decipher object for decryption using a password-derived key.

/**
 * Create decipher for decryption using password-derived key
 * @param {string} algorithm - Cipher algorithm (e.g., 'aes192', 'aes256')
 * @param {string} password - Password string for key derivation
 * @returns {Decipher} Decipher object for decryption
 */
function createDecipher(algorithm, password) { }

/**
 * Decipher object for decryption operations
 * @class Decipher
 */
/**
 * Update decipher with encrypted data
 * @param {string|Buffer} data - Encrypted data to decrypt (string or Buffer)
 * @param {string} [inputEncoding] - Input encoding if data is string
 * @param {string} [outputEncoding] - Output encoding for decrypted data
 * @returns {string|Buffer} Decrypted data chunk
 */
Decipher.prototype.update = function(data, inputEncoding, outputEncoding) { };

/**
 * Finalize decryption and get remaining decrypted data
 * @param {string} [outputEncoding] - Output encoding for final decrypted chunk
 * @returns {string|Buffer} Final decrypted data chunk
 */
Decipher.prototype.final = function(outputEncoding) { };

Create Decipher with IV

Creates a decipher object using explicit key and initialization vector.

/**
 * Create decipher for decryption using explicit key and IV
 * @param {string} algorithm - Cipher algorithm (e.g., 'aes-256-cbc', 'aes-128-gcm')
 * @param {Buffer} key - Decryption key as Buffer
 * @param {Buffer} iv - Initialization vector as Buffer
 * @returns {Decipher} Decipher object for decryption
 */
function createDecipheriv(algorithm, key, iv) { }

Get Supported Ciphers

Returns list of supported cipher algorithms.

/**
 * Get array of supported cipher algorithm names
 * @returns {string[]} Array of supported cipher algorithm strings
 */
function getCiphers() { }

/**
 * Alias for getCiphers()
 * @returns {string[]} Array of supported cipher algorithm strings
 */
function listCiphers() { }

Class Constructors

Direct access to cipher and decipher classes.

/**
 * Cipher class constructor (equivalent to createCipher result)
 * @constructor
 */
function Cipher() { }

/**
 * Cipheriv class constructor (equivalent to createCipheriv result)
 * @constructor
 */
function Cipheriv() { }

/**
 * Decipher class constructor (equivalent to createDecipher result)
 * @constructor
 */
function Decipher() { }

/**
 * Decipheriv class constructor (equivalent to createDecipheriv result)
 * @constructor
 */
function Decipheriv() { }

Usage Examples

Basic Password-based Encryption

Simple encryption and decryption using passwords.

const crypto = require('crypto-browserify');

// Encrypt data with password
function encryptWithPassword(plaintext, password) {
  const cipher = crypto.createCipher('aes192', password);
  let encrypted = cipher.update(plaintext, 'utf8', 'hex');
  encrypted += cipher.final('hex');
  return encrypted;
}

// Decrypt data with password
function decryptWithPassword(encrypted, password) {
  const decipher = crypto.createDecipher('aes192', password);
  let decrypted = decipher.update(encrypted, 'hex', 'utf8');
  decrypted += decipher.final('utf8');
  return decrypted;
}

// Usage
const plaintext = 'This is secret data';
const password = 'my-secret-password';

const encrypted = encryptWithPassword(plaintext, password);
console.log('Encrypted:', encrypted);

const decrypted = decryptWithPassword(encrypted, password);
console.log('Decrypted:', decrypted);

Advanced Encryption with Explicit Keys

More secure encryption using explicit keys and initialization vectors.

const crypto = require('crypto-browserify');

function encryptData(plaintext, key, iv) {
  const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
  let encrypted = cipher.update(plaintext, 'utf8', 'hex');
  encrypted += cipher.final('hex');
  return encrypted;
}

function decryptData(encrypted, key, iv) {
  const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
  let decrypted = decipher.update(encrypted, 'hex', 'utf8');
  decrypted += decipher.final('utf8');
  return decrypted;
}

// Generate secure key and IV
const key = crypto.randomBytes(32); // 256-bit key
const iv = crypto.randomBytes(16);  // 128-bit IV

const plaintext = 'Sensitive information';
const encrypted = encryptData(plaintext, key, iv);
const decrypted = decryptData(encrypted, key, iv);

console.log('Original:', plaintext);
console.log('Encrypted:', encrypted);
console.log('Decrypted:', decrypted);

File Encryption

Encrypt and decrypt files or large data streams.

const crypto = require('crypto-browserify');
const fs = require('fs');

function encryptFile(inputPath, outputPath, password) {
  const cipher = crypto.createCipher('aes256', password);
  const input = fs.createReadStream(inputPath);
  const output = fs.createWriteStream(outputPath);
  
  input.pipe(cipher).pipe(output);
  
  output.on('close', () => {
    console.log('File encrypted successfully');
  });
}

function decryptFile(inputPath, outputPath, password) {
  const decipher = crypto.createDecipher('aes256', password);
  const input = fs.createReadStream(inputPath);
  const output = fs.createWriteStream(outputPath);
  
  input.pipe(decipher).pipe(output);
  
  output.on('close', () => {
    console.log('File decrypted successfully');
  });
}

// Usage
encryptFile('secret.txt', 'secret.txt.enc', 'file-password');
decryptFile('secret.txt.enc', 'decrypted.txt', 'file-password');

Incremental Encryption

Encrypt data in chunks for streaming or large datasets.

const crypto = require('crypto-browserify');

// Streaming encryption
function createEncryptionStream(algorithm, key, iv) {
  const cipher = crypto.createCipheriv(algorithm, key, iv);
  
  return {
    update: (chunk) => cipher.update(chunk),
    final: () => cipher.final(),
    cipher: cipher
  };
}

// Usage
const key = crypto.randomBytes(32);
const iv = crypto.randomBytes(16);
const encStream = createEncryptionStream('aes-256-cbc', key, iv);

// Encrypt data in chunks
const chunk1 = encStream.update('First chunk of data', 'utf8', 'hex');
const chunk2 = encStream.update('Second chunk of data', 'utf8', 'hex');
const final = encStream.final('hex');

const fullEncrypted = chunk1 + chunk2 + final;
console.log('Encrypted stream:', fullEncrypted);

Supported Algorithms

Common cipher algorithms available:

AES (Advanced Encryption Standard)

'aes-128-cbc' - 128-bit key, CBC mode
'aes-192-cbc' - 192-bit key, CBC mode
'aes-256-cbc' - 256-bit key, CBC mode (recommended)
'aes-128-gcm' - 128-bit key, GCM mode (authenticated)
'aes-256-gcm' - 256-bit key, GCM mode (authenticated)

Legacy Algorithms

'aes192' - Password-based AES-192
'aes256' - Password-based AES-256
'des' - DES (not recommended)
'3des' - Triple DES

Get the complete list:

const crypto = require('crypto-browserify');
const supportedCiphers = crypto.getCiphers();
console.log('Available ciphers:', supportedCiphers);

Security Best Practices

Key Management

Use 256-bit keys for AES when possible
Generate keys using cryptographically secure random functions
Never hardcode keys in source code
Rotate keys regularly

Initialization Vectors

Always use a unique IV for each encryption operation
Generate IVs using cryptographically secure random functions
Store IVs alongside encrypted data (they don't need to be secret)

Algorithm Selection

Prefer authenticated encryption modes (GCM) when available
Use CBC mode with proper padding for general purposes
Avoid deprecated algorithms like DES

Password-based Encryption

Use strong passwords or derive keys using PBKDF2
Consider using createCipheriv with derived keys instead of createCipher

Error Handling

Encryption functions may throw errors in the following scenarios:

Unsupported algorithm: When the cipher algorithm is not available
Invalid key size: When the key length doesn't match algorithm requirements
Invalid IV size: When the IV length doesn't match algorithm requirements
Padding errors: During decryption with incorrect keys or corrupted data

const crypto = require('crypto-browserify');

try {
  const cipher = crypto.createCipher('invalid-algorithm', 'password');
} catch (err) {
  console.error('Unsupported cipher:', err.message);
}

try {
  // Wrong key size for AES-256 (needs 32 bytes)
  const wrongKey = Buffer.alloc(16);
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv('aes-256-cbc', wrongKey, iv);
} catch (err) {
  console.error('Invalid key size:', err.message);
}

// Handle decryption errors
try {
  const decipher = crypto.createDecipher('aes256', 'wrong-password');
  let decrypted = decipher.update('encrypted-data', 'hex', 'utf8');
  decrypted += decipher.final('utf8');
} catch (err) {
  console.error('Decryption failed:', err.message);
}

Version

Tile

Files