Camellia Security-Focused API Documentation

Algorithm: Camellia-256
Type: Symmetric Block Cipher
Security Level: 256-bit
Block Size: 128 bits (16 bytes)
Key Size: 256 bits (32 bytes)
Modes: ECB, CBC, CTR, GCM
Standard: ISO/IEC 18033-3, IETF RFC 3713

Table of Contents

1. Security Contract
2. Attack Resistance Matrix
3. Secure Usage Examples
4. Common Mistakes
5. Performance vs Security
6. Platform-Specific Notes
7. Compliance Information

Security Contract

encrypt(key: Uint8Array, plaintext: Uint8Array, mode: string, iv?: Uint8Array): Uint8Array

Preconditions:

• key MUST be exactly 32 bytes (256 bits)
• plaintext length depends on mode (ECB/CBC require padding)
• mode MUST be one of: ‘ECB’, ‘CBC’, ‘CTR’, ‘GCM’
• iv required for CBC/CTR/GCM modes (16 bytes)
• iv MUST be unique for each encryption with same key

Postconditions:

• Returns ciphertext (same size as padded plaintext)
• For GCM mode, includes 16-byte authentication tag
• Ciphertext indistinguishable from random without key
• Original plaintext not recoverable without key

Side Effects:

• May allocate memory for padding
• No timing variations based on key or data

decrypt(key: Uint8Array, ciphertext: Uint8Array, mode: string, iv?: Uint8Array): Uint8Array

Preconditions:

• key MUST match encryption key exactly
• ciphertext MUST be valid encrypted data
• mode MUST match encryption mode
• iv MUST match encryption IV (if used)

Postconditions:

• Returns original plaintext
• For GCM mode, verifies authentication tag
• Removes padding for ECB/CBC modes
• Returns null if authentication fails (GCM only)

Side Effects:

• Constant-time operations
• No timing leaks on padding validation

Attack Resistance Matrix

✅ Attacks Prevented

Attack Type	Protection Mechanism	Security Level
Brute Force	256-bit key space	2^256 operations
Differential Cryptanalysis	18 rounds, strong S-boxes	> 2^256 complexity
Linear Cryptanalysis	FL/FL^-1 functions	> 2^256 complexity
Related-Key Attacks	Strong key schedule	No practical attacks
Slide Attacks	Round constants	Not vulnerable
Algebraic Attacks	Complex round function	No practical attacks

❌ Attacks NOT Prevented (Mode-Dependent)

Attack Type	Vulnerable Modes	Mitigation Required
Padding Oracle	CBC with PKCS#7	Use GCM mode
IV Reuse	CTR, GCM	Unique IV per encryption
Malleability	ECB, CBC, CTR	Use GCM for authentication
Pattern Leakage	ECB	Never use ECB mode
Chosen Ciphertext	All except GCM	Use authenticated encryption

⚠️ Security Limitations

1. Block Cipher Modes: Security depends heavily on mode selection
2. IV Management: Reusing IVs breaks security in CTR/GCM
3. No Built-in Authentication: Only GCM provides authentication
4. Padding Vulnerabilities: CBC mode susceptible to padding attacks

Secure Usage Examples

Authenticated Encryption with GCM

import { Camellia } from '@metamui/camellia';
import { randomBytes } from '@metamui/random';

class SecureCamellia {
  static encrypt(
    key: Uint8Array,
    plaintext: Uint8Array,
    associatedData?: Uint8Array
  ): {
    ciphertext: Uint8Array;
    iv: Uint8Array;
    tag: Uint8Array;
  } {
    if (key.length !== 32) {
      throw new Error('Key must be 256 bits (32 bytes)');
    }
    
    // Generate random IV for GCM
    const iv = randomBytes(16);
    
    // Encrypt with authentication
    const result = Camellia.encryptGCM(
      key,
      iv,
      plaintext,
      associatedData
    );
    
    return {
      ciphertext: result.ciphertext,
      iv: iv,
      tag: result.tag
    };
  }
  
  static decrypt(
    key: Uint8Array,
    ciphertext: Uint8Array,
    iv: Uint8Array,
    tag: Uint8Array,
    associatedData?: Uint8Array
  ): Uint8Array | null {
    try {
      return Camellia.decryptGCM(
        key,
        iv,
        ciphertext,
        tag,
        associatedData
      );
    } catch (e) {
      // Authentication failed
      return null;
    }
  }
}

Secure File Encryption

class FileEncryptor {
  private static readonly CHUNK_SIZE = 64 * 1024; // 64KB chunks
  
  static async encryptFile(
    key: Uint8Array,
    inputFile: File
  ): Promise<Uint8Array> {
    // Use CTR mode for streaming
    const iv = randomBytes(16);
    const cipher = new Camellia.CTR(key, iv);
    
    const chunks: Uint8Array[] = [];
    const reader = inputFile.stream().getReader();
    
    try {
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        
        // Encrypt chunk
        const encryptedChunk = cipher.update(value);
        chunks.push(encryptedChunk);
      }
      
      // Finalize
      const lastChunk = cipher.finalize();
      if (lastChunk.length > 0) {
        chunks.push(lastChunk);
      }
      
      // Prepend IV to ciphertext
      const totalLength = 16 + chunks.reduce((sum, chunk) => sum + chunk.length, 0);
      const result = new Uint8Array(totalLength);
      result.set(iv, 0);
      
      let offset = 16;
      for (const chunk of chunks) {
        result.set(chunk, offset);
        offset += chunk.length;
      }
      
      return result;
    } finally {
      reader.releaseLock();
    }
  }
}

Key Derivation and Encryption

import { Argon2 } from '@metamui/argon2';

class PasswordBasedEncryption {
  static async encryptWithPassword(
    password: string,
    plaintext: Uint8Array
  ): Promise<{
    ciphertext: Uint8Array;
    salt: Uint8Array;
    iv: Uint8Array;
    tag: Uint8Array;
  }> {
    // Generate random salt
    const salt = randomBytes(16);
    
    // Derive key from password
    const key = await Argon2.hash(password, salt, {
      outputLength: 32,
      timeCost: 3,
      memoryCost: 65536,
      parallelism: 4
    });
    
    // Encrypt with derived key
    const { ciphertext, iv, tag } = SecureCamellia.encrypt(
      key,
      plaintext
    );
    
    // Clear derived key
    key.fill(0);
    
    return { ciphertext, salt, iv, tag };
  }
  
  static async decryptWithPassword(
    password: string,
    ciphertext: Uint8Array,
    salt: Uint8Array,
    iv: Uint8Array,
    tag: Uint8Array
  ): Promise<Uint8Array | null> {
    // Derive same key
    const key = await Argon2.hash(password, salt, {
      outputLength: 32,
      timeCost: 3,
      memoryCost: 65536,
      parallelism: 4
    });
    
    // Decrypt
    const plaintext = SecureCamellia.decrypt(
      key,
      ciphertext,
      iv,
      tag
    );
    
    // Clear derived key
    key.fill(0);
    
    return plaintext;
  }
}

Common Mistakes

❌ Using ECB Mode

// NEVER DO THIS - ECB mode leaks patterns!
function insecureEncrypt(key: Uint8Array, data: Uint8Array): Uint8Array {
  return Camellia.encryptECB(key, data);
}

// Identical plaintext blocks produce identical ciphertext blocks
// This reveals patterns in the data!

❌ IV Reuse in CTR/GCM Modes

// CATASTROPHIC - Never reuse IV with same key!
class InsecureEncryptor {
  private key = randomBytes(32);
  private iv = randomBytes(16); // REUSED FOR EVERY ENCRYPTION!
  
  encrypt(plaintext: Uint8Array): Uint8Array {
    // This breaks security completely!
    return Camellia.encryptCTR(this.key, this.iv, plaintext);
  }
}

// CORRECT - New IV for each encryption
class SecureEncryptor {
  private key = randomBytes(32);
  
  encrypt(plaintext: Uint8Array): { iv: Uint8Array; ciphertext: Uint8Array } {
    const iv = randomBytes(16); // Fresh IV
    const ciphertext = Camellia.encryptCTR(this.key, iv, plaintext);
    return { iv, ciphertext };
  }
}

❌ Padding Oracle Vulnerabilities

// VULNERABLE - CBC mode with improper padding handling
function vulnerableDecrypt(key: Uint8Array, ciphertext: Uint8Array, iv: Uint8Array): Uint8Array | null {
  try {
    const plaintext = Camellia.decryptCBC(key, iv, ciphertext);
    return plaintext;
  } catch (e) {
    // WRONG - Different errors for padding vs other failures
    if (e.message.includes('padding')) {
      throw new Error('Invalid padding');
    } else {
      throw new Error('Decryption failed');
    }
  }
}

// SECURE - Use authenticated encryption
function secureDecrypt(key: Uint8Array, ciphertext: Uint8Array, iv: Uint8Array, tag: Uint8Array): Uint8Array | null {
  // GCM mode prevents padding oracle attacks
  return Camellia.decryptGCM(key, iv, ciphertext, tag);
}

Performance vs Security

Mode Selection Guide

Mode	Security	Performance	Use Case
ECB	❌ Insecure	Fastest	Never use
CBC	⚠️ Padding attacks	Fast	Legacy only
CTR	✅ Secure*	Fast, parallel	Streaming
GCM	✅ Authenticated	Moderate	Recommended

*Requires unique IV and separate authentication

Performance Characteristics

// Benchmark results (approximate)
// Platform: Intel i7-10700K @ 3.8GHz
// 
// ECB: ~500 MB/s (never use!)
// CBC: ~450 MB/s
// CTR: ~480 MB/s (parallelizable)
// GCM: ~350 MB/s (includes authentication)

Platform-Specific Notes

All Platforms

• Ensure constant-time implementations
• Use hardware acceleration where available
• Clear key material after use
• Validate IV uniqueness

JavaScript/TypeScript

• Consider WebCrypto API for performance
• Use crypto.getRandomValues() for IVs
• Avoid string conversions in hot paths

Native Platforms

• Leverage AES-NI instructions (similar optimizations apply)
• Use platform-specific secure random
• Consider memory locking for keys

Compliance Information

Standards Compliance

• ISO/IEC 18033-3: International standard
• IETF RFC 3713: Internet standard
• NESSIE: Selected algorithm
• CRYPTREC: Recommended cipher (Japan)

Certifications

• Approved by Japanese government
• Used in various standards (TLS, IPsec)
• Patent-free implementation

Recommended Practices

✅ Always:

• Use GCM mode for new applications
• Generate random IVs for each encryption
• Implement proper key management
• Use 256-bit keys

❌ Never:

• Use ECB mode
• Reuse IVs
• Implement custom padding schemes
• Store keys in plaintext

---

Security Notice: Camellia is a secure cipher when used correctly. Mode selection and IV management are critical. For questions, contact security@metamui.id

Last Updated: 2025-07-06
**Version: 3.0.0
License: BSL-1.1

Security Analysis

Threat Model: Camellia-256 Threat Model

The comprehensive threat analysis covers:

• Algorithm-specific attack vectors
• Implementation vulnerabilities
• Side-channel considerations
• Quantum resistance analysis (where applicable)
• Deployment recommendations

For complete security analysis and risk assessment, see the dedicated threat model documentation.