Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 109 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
A salt in the KERI ecosystem serves multiple critical cryptographic functions. At its most fundamental level, a salt is random data fed as an additional input to a one-way function that hashes data, passwords, or passphrases. This classical cryptographic definition, inherited from general password storage security practices, has been extended within KERI to support deterministic key generation and privacy-preserving credential architectures.
In KERI's key management infrastructure, salts are used as primary entropy sources for deriving cryptographic key pairs from human-memorable passphrases (called bran in KERI terminology). The salt is combined with the bran through key derivation functions to produce deterministic yet unpredictable private keys. This approach enables reproducible key generation - given the same salt and bran, the same keys will always be produced - while maintaining cryptographic strength through the salt's high entropy.
Within the ACDC (Authentic Chained Data Container) credential framework, salts take on an additional role as salty nonces or blinding factors. The u (UUID) field in ACDCs contains a high-entropy pseudorandom string that functions as a salt to prevent rainbow table attacks against credential content. This usage protects against correlation attacks where adversaries might precompute hashes of common credential values to identify holders.
KERI specifications mandate that salts provide approximately 128 bits of cryptographic strength as the minimum threshold for security. This entropy level ensures resistance to brute-force attacks and provides sufficient randomness for key derivation. The 128-bit standard aligns with KERI's broader cryptographic strength requirements and provides security margins appropriate for long-lived identifiers.
Entropy Standards: All salts MUST provide approximately 128 bits of cryptographic strength per KERI specifications and vLEI governance framework requirements. This entropy level ensures resistance to brute-force attacks and provides security margins appropriate for long-lived identifiers.
Generation: Use cryptographically secure random number generators (CSPRNGs) such as libsodium's random facilities. Never use basic PRNGs, predictable values, or low-entropy sources. The kli salt command generates properly formatted CESR-encoded salts with adequate entropy.
Storage Protection: Treat salts with the same security rigor as private keys:
--op flag, macOS Keychain with --kc flag)--insecure flag writes salts to filesystem in plaintext and MUST only be used in developmentArgon2id Parameters: When using libsodium's crypto_pwhash API for key derivation:
opslimit and memlimit parameters for your security/performance requirementsDeterministic Generation: The same salt and bran (passphrase) will always produce identical keys. This enables:
Keystore Context: The salt combines with the keystore's aeid (authentication encryption identifier) and user passcode to derive master key material. All AIDs created in that keystore derive their keys from this master material.
UUID Field Usage: The u field in ACDCs MUST contain a high-entropy pseudorandom string (typically 128+ bits) to prevent rainbow table attacks. This salt:
Salts must be generated using Cryptographically Secure Pseudorandom Number Generators (CSPRNGs) to ensure unpredictability. The KERI implementation leverages libsodium's random number generation facilities, which provide cryptographically strong entropy sources across multiple platforms. The use of CSPRNGs rather than basic PRNGs is critical - basic pseudorandom generators may pass statistical tests but can be distinguished from true randomness by intelligent attackers.
When used for key derivation, salts are processed through key stretching algorithms such as Argon2id (implemented via libsodium's crypto_pwhash API). These memory-hard functions combine the salt with the user's passphrase through computationally intensive operations that resist GPU and ASIC-based attacks. The Argon2id algorithm provides:
opslimit and memlimit parametersThe key derivation process produces Ed25519 signing key pairs and X25519 encryption key pairs from the salt-bran combination. The deterministic nature means the same salt and bran will always produce identical keys, enabling key recovery from backed-up credentials without storing private keys directly.
In ACDC credentials, salts function as blinding factors that hide credential content from correlation attacks. The high-entropy salt (typically 128 bits or more) is combined with credential attributes before hashing, ensuring that even identical attribute values produce different hashes across different credentials. This prevents:
The Salty Nonce Blinding Factor mechanism in Blindable State TELs (Transaction Event Logs) extends this concept to credential state management. Three cryptographic approaches are specified:
These mechanisms enable selective state disclosure where credential holders can control which verifiers can observe credential state (issued, revoked, suspended) by sharing or withholding the blinding salt.
Salts in KERI are encoded as CESR (Composable Event Streaming Representation) primitives, ensuring consistent representation across text and binary domains. The CESR encoding includes:
A typical salt encoding uses the 0A derivation code for "Random salt, seed, private key, or sequence number of length 128 bits." The CESR primitive structure ensures that salts can be:
Salts are stored in multiple contexts within KERI infrastructure:
Keystore Initialization: During kli init operations, salts are generated and stored in the keystore configuration. The vLEI ecosystem governance framework treats salts as equivalent in importance to private keys, requiring protection through:
ACDC UUID Fields: The u field in ACDC credentials contains a salt encoded as a high-entropy pseudorandom string. This field:
Configuration Files: For testing and development, salts may appear in configuration files, though the vLEI governance framework explicitly warns that "storing salts in configuration files is highly insecure" for production deployments. The --insecure flag in KERI tools writes salts to filesystem in plaintext for development only.
A special case exists for well-known witnesses used in testing environments. These witnesses use predetermined salts to initialize keystores, enabling predictable identifier generation for reproducible test scenarios. The documentation explicitly warns: "For testing purposes only! Never use well-known witnesses in production." The predictability that makes them useful for testing creates security vulnerabilities in production where witness identifiers must be cryptographically random.
The primary usage of salts in KERI is during keystore initialization via the kli init command:
kli init --name keystore_name --passcode <passcode> --salt <salt>
The salt parameter accepts a CESR-encoded random value, typically generated via kli salt. This salt, combined with the keystore's aeid (authentication encryption identifier) and the user's passcode, deterministically generates all key pairs for identifiers created in that keystore. The initialization process:
In the Signify signing-at-the-edge architecture, salts play a critical role in client initialization. The SignifyClient constructor accepts a bran parameter (passphrase), which is processed with a salt to derive the Client AID:
const bran = randomPasscode();
const client = new SignifyClient(adminUrl, bran, Tier.low, bootUrl);
Internally, the Signify controller transforms the bran:
this.bran = MtrDex.Salt_128 + 'A' + bran.substring(0, 21) // qb64 salt for seed
this.salter = new Salter({ qb64: this.bran, tier: this.tier })
This process:
The Salter primitive (one of the six core cesride primitives) represents a seed and has the ability to generate new Signer primitives (private keys). This architecture enables reproducible key generation while maintaining security through the salt's entropy.
In ACDC credentials, the u field provides correlation resistance through salt-based blinding:
{
"v": "ACDC10JSON00011c_",
"d": "EAdXt3gIXOf2BBWNHdSXCJnFJL5OuQPyM5K0neuniccM",
"u": "0ABghkDaG7OY1wjaDAE0qHcg",
"i": "did:keri:EBkPreYpZfFk66jpf3uFv7vklXKhzBrAqjsKAn2EDIPM",
"s": "ED6jrVPTzlSkUPqGGeIZ8a8FWS7a6s4reAXRZOkogZ2A",
"a": "EEveY4-9XgOcLxUderzwLIr9Bf7V_NHwY1lkFrn9y2PY"
}
The u field salt ensures that:
The Salty Nonce Blinding Factor mechanism enables selective credential state disclosure. An issuer can blind the state of a credential in a Transaction Event Log such that only parties possessing the salt can verify the credential's current state (issued, revoked, suspended).
This mechanism addresses the privacy requirement: "A credential holder may not want their employment state information shared with former possible employers in future interactions." By controlling salt distribution, the holder controls who can verify credential state, enabling:
The Salter is one of six core cesride cryptographic primitives. It:
The Salter primitive bridges the gap between human-memorable passphrases (bran) and cryptographically strong key material, using salts as the entropy source that ensures uniqueness and unpredictability.
The bran is KERI's term for a passphrase or seed used as primary input for key generation. The term was specifically chosen to avoid conflicts with existing KERI usage of "seed" and "salt" while maintaining semantic connection to seed-related concepts. Dr. Sam Smith explains: "We already use seed and salt for something else so bran is related to seed so we used a term that was evocative of its use but not conflict with already used seed."
The relationship between salt and bran:
A cryptonym is a cryptographic pseudonymous identifier derived from a random or pseudo-random secret seed or salt via a one-way cryptographic function. The salt serves as the entropy source for cryptonym generation, ensuring:
Cryptonyms exemplify how salts enable KERI's self-certifying identifier architecture, where identifiers are derived from cryptographic material rather than assigned by authorities.
Salts interact with SAID (Self-Addressing Identifier) computation in ACDCs. The u field salt is included in the SAID calculation, ensuring that:
The Diger primitive (digest representation) verifies that input data hashes to expected values. When salts are included in hashed data, the Diger verification confirms both the data and the salt's contribution to the hash.
The vLEI Ecosystem Governance Framework establishes strict requirements for salt management:
Generation: Salts MUST be generated using cryptographically secure random number generators providing approximately 128 bits of entropy. The use of basic PRNGs or predictable values compromises the entire key derivation security model.
Storage: Salts MUST be protected with the same rigor as private keys:
Lifecycle Management: Salts are typically immutable once generated for a keystore. Changing a salt would change all derived keys, effectively creating a new identity. The governance framework requires 18-month support for previous versions during specification upgrades, implying salt stability across version transitions.
The documentation repeatedly emphasizes the distinction between testing and production salt usage:
Testing Environments:
--insecure flagProduction Environments:
The governance framework explicitly warns: "For testing purposes, never put a salt in a file like this" when showing example configurations with exposed salt values.
In multi-signature group AIDs, each participant generates their own salt for their individual keystore. The group AID's security depends on:
This architecture ensures that compromise of one participant's salt doesn't compromise the entire group's security, maintaining the threshold structure security model where multiple independent attack surfaces must be overcome.
While salts themselves are not quantum-vulnerable (they're random data, not algorithmic constructs), their role in key derivation affects post-quantum security:
KERI's pre-rotation mechanism provides post-quantum security for identifier control even if current signing algorithms are compromised, and salts play a role in deriving the pre-rotated keys that enable this protection.
Blindable State TEL: Implement Salty Nonce Blinding Factor using one of three approaches:
The issuer performs blinding, but the issuee can request blinding for privacy protection. Only parties possessing the salt can verify credential state.
Development Environments:
--insecure flag--salt 0AAkG1BmB7xnXBxo2Aasxrq9 in test scriptsProduction Deployments:
In group multi-sig AIDs:
Salts are encoded as CESR primitives with:
0A for 128-bit random salt)The Salter primitive encapsulates this encoding and provides methods for key generation.
Per vLEI governance framework: