SHA3 Family Security-Focused API Documentation

Version: 1.0
Last Updated: 2025-07-14
Security Classification: PUBLIC
Author: Phantom (phantom@metamui.id)

Overview

The SHA3 family provides cryptographic hash functions based on the Keccak sponge construction. Unlike SHA-2, SHA3 uses a fundamentally different algorithm design offering natural resistance to length extension attacks and providing both fixed-output hash functions and extendable output functions (XOF). This documentation provides security-focused guidance for using SHA3 in the MetaMUI cryptographic library.

Standard: NIST FIPS 202
Construction: Keccak sponge with different rate/capacity configurations

Security Warnings ⚠️

  1. Not for Passwords: NEVER use SHA3 directly for password hashing - use Argon2
  2. Output Length Matters: For SHAKE functions, insufficient output length reduces security
  3. Domain Separation: Use different contexts for different applications
  4. Not Encryption: Hash functions are one-way, they cannot encrypt data
  5. Parameter Integrity: Never modify rate/capacity parameters from standard values

Fixed-Output Hash Functions

sha3_224(data: bytes) -> bytes[28]

Security Level: 112-bit collision resistance
Output Size: 28 bytes (224 bits)
Rate: 1152 bits, Capacity: 448 bits

Security Contract:

Attack Resistance: | Attack Type | Protected | Security Level | |————-|———–|—————-| | Collision | ✅ | 2^112 operations | | Preimage | ✅ | 2^224 operations | | Second Preimage | ✅ | 2^224 operations | | Length Extension | ✅ | Naturally immune | | Timing Attack | ✅ | Constant time |

sha3_256(data: bytes) -> bytes[32]

Security Level: 128-bit collision resistance
Output Size: 32 bytes (256 bits)
Rate: 1088 bits, Capacity: 512 bits

Security Contract:

Attack Resistance: | Attack Type | Protected | Security Level | |————-|———–|—————-| | Collision | ✅ | 2^128 operations | | Preimage | ✅ | 2^256 operations | | Second Preimage | ✅ | 2^256 operations | | Length Extension | ✅ | Naturally immune | | Timing Attack | ✅ | Constant time |

Recommended Use Cases:

sha3_384(data: bytes) -> bytes[48]

Security Level: 192-bit collision resistance
Output Size: 48 bytes (384 bits)
Rate: 832 bits, Capacity: 768 bits

Security Contract:

Attack Resistance: | Attack Type | Protected | Security Level | |————-|———–|—————-| | Collision | ✅ | 2^192 operations | | Preimage | ✅ | 2^384 operations | | Second Preimage | ✅ | 2^384 operations | | Length Extension | ✅ | Naturally immune | | Timing Attack | ✅ | Constant time |

Recommended Use Cases:

sha3_512(data: bytes) -> bytes[64]

Security Level: 256-bit collision resistance
Output Size: 64 bytes (512 bits)
Rate: 576 bits, Capacity: 1024 bits

Security Contract:

Attack Resistance: | Attack Type | Protected | Security Level | |————-|———–|—————-| | Collision | ✅ | 2^256 operations | | Preimage | ✅ | 2^512 operations | | Second Preimage | ✅ | 2^512 operations | | Length Extension | ✅ | Naturally immune | | Timing Attack | ✅ | Constant time |

Recommended Use Cases:

Extendable Output Functions (XOF)

shake128(data: bytes, outputLength: int) -> bytes[outputLength]

Security Level: 128-bit for any output length
Rate: 1344 bits, Capacity: 256 bits

Security Contract:

Attack Resistance: | Attack Type | Protected | Security Level | |————-|———–|—————-| | Distinguishing | ✅ | 2^128 operations | | Collision | ✅ | 2^128 operations (for any output length) | | Preimage | ✅ | 2^128 operations | | Length Extension | ✅ | Not applicable | | Timing Attack | ✅ | Constant time |

Recommended Use Cases:

shake256(data: bytes, outputLength: int) -> bytes[outputLength]

Security Level: 256-bit for any output length
Rate: 1088 bits, Capacity: 512 bits

Security Contract:

Attack Resistance: | Attack Type | Protected | Security Level | |————-|———–|—————-| | Distinguishing | ✅ | 2^256 operations | | Collision | ✅ | 2^256 operations (for any output length) | | Preimage | ✅ | 2^256 operations | | Length Extension | ✅ | Not applicable | | Timing Attack | ✅ | Constant time |

Recommended Use Cases:

Security Implementation Details

Constant-Time Operations

// All operations use constant time
private fun keccakF1600(state: LongArray) {
    // 24 rounds of constant-time permutation
    for (round in 0 until KECCAK_ROUNDS) {
        // θ, ρ, π, χ, ι steps in constant time
    }
}

Secure State Management

// State is securely cleared after use
private fun secureClear() {
    state.fill(0)
    block.fill(0)
    blockSize = 0
}

Proper Padding

// NIST FIPS 202 compliant padding
// SHA3: delimitedSuffix = 0x06
// SHAKE: delimitedSuffix = 0x1F
block[blockSize] = delimitedSuffix
block[rateInBytes - 1] = (block[rateInBytes - 1].toInt() or 0x80).toByte()

Security Best Practices

1. Algorithm Selection

2. Output Length Guidelines

// SHAKE minimum output lengths for security levels
val output128 = shake128(data, 32)  // 128-bit security
val output256 = shake256(data, 64)  // 256-bit security

3. Domain Separation

// Use different prefixes for different purposes
val keyMaterial = shake256("KDF:$context:$input", keyLength)
val randomness = shake256("RNG:$context:$input", randomLength)
val commitment = sha3_256("COMMIT:$message")

4. Error Handling

// Validate inputs
require(outputLength > 0) { "Output length must be positive" }
require(outputLength <= MAX_OUTPUT) { "Output length too large" }

// Clear on error
try {
    return processInput(data)
} finally {
    secureClear()
}

Quantum Resistance Analysis

Current Security Levels (Classical)

Post-Quantum Security Levels

Recommendations for Quantum Resistance

Critical Security Requirements

1. Input Validation

2. State Protection

3. Implementation Integrity

4. Side-Channel Protection

Security Assessment: EXCELLENT

The SHA3 family provides exceptional security with novel sponge construction offering natural protection against length extension attacks. The variety of output lengths and extendable output functions make SHA3 suitable for a wide range of cryptographic applications.

Recommendation: APPROVED for all security applications, with SHA3-512 and SHAKE256 strongly recommended for maximum long-term security and quantum resistance.

Security Analysis

Threat Model: SHA3-256/512 Threat Model

The comprehensive threat analysis covers:

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