Heratio Framework API Reference

KeyManager
in package

Manages the master encryption key with key-ID tracking and purpose-specific subkey derivation.

The master key is stored at /etc/atom/encryption.key (outside web root). Subkeys are derived via HKDF for separate purposes:

  • "file-encryption" → Layer 1 (digital objects on disk)
  • "field-encryption" → Layer 2 (database column encryption)
  • "hmac-index" → Blind index generation

Key file format (V2): Line 1: hex-encoded 32-byte master key (64 hex chars) Line 2: key_id (uint32, decimal string)

V1 format (backward-compatible): just the hex key, key_id defaults to 1.

Table of Contents

Constants

PURPOSE_FIELD  = 'field-encryption'
PURPOSE_FILE  = 'file-encryption'
PURPOSE_HMAC  = 'hmac-index'

Methods

clearCache()  : void
Clear all cached keys and derived subkeys.
deriveKey()  : string
Derive a purpose-specific subkey via HKDF.
generateKey()  : string
Generate a new random encryption key.
getKeyId()  : int
Get the current key ID.
getKeyPath()  : string
Get the path where the key is stored.
hasSodium()  : bool
Check if libsodium is available.
keyExists()  : bool
Check if the key file exists on disk.
loadKey()  : string
Load the master encryption key from disk.
saveKey()  : void
Write a key (with key_id) to the key file with secure permissions.
validateKey()  : bool
Validate a key is the correct length.

Constants

PURPOSE_FIELD

public mixed PURPOSE_FIELD = 'field-encryption'

PURPOSE_FILE

public mixed PURPOSE_FILE = 'file-encryption'

PURPOSE_HMAC

public mixed PURPOSE_HMAC = 'hmac-index'

Methods

clearCache()

Clear all cached keys and derived subkeys.

public static clearCache() : void

deriveKey()

Derive a purpose-specific subkey via HKDF.

public static deriveKey(string $purpose) : string

Uses HKDF-SHA256 to derive a 32-byte subkey from the master key, scoped to a specific purpose. This means file encryption and field encryption use different effective keys, limiting blast radius.

Parameters
$purpose : string

One of PURPOSE_FILE, PURPOSE_FIELD, PURPOSE_HMAC

Return values
string

generateKey()

Generate a new random encryption key.

public static generateKey() : string
Return values
string —

32 bytes of random data

getKeyId()

Get the current key ID.

public static getKeyId() : int
Return values
int

getKeyPath()

Get the path where the key is stored.

public static getKeyPath() : string
Return values
string

hasSodium()

Check if libsodium is available.

public static hasSodium() : bool
Return values
bool

keyExists()

Check if the key file exists on disk.

public static keyExists() : bool
Return values
bool

loadKey()

Load the master encryption key from disk.

public static loadKey() : string
Tags
throws
RuntimeException

if key file is missing or invalid

Return values
string

saveKey()

Write a key (with key_id) to the key file with secure permissions.

public static saveKey(string $key[, int $keyId = 1 ]) : void
Parameters
$key : string

Raw 32-byte key

$keyId : int = 1

Key identifier for rotation tracking

Tags
throws
RuntimeException

if directory creation or write fails

validateKey()

Validate a key is the correct length.

public static validateKey(string $key) : bool
Parameters
$key : string
Return values
bool 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results