3 min read • 17 views
Privacy Kit includes a simplified hierarchical key derivation system that enables secure, granular control over encrypted data.
// Generate a master key
const masterKey = PrivacyKit.generateMasterKey();
// Derive keys using paths
const userKey = PrivacyKit.deriveKey(masterKey, ["users"]);
const aliceDataKey = PrivacyKit.deriveKey(masterKey, ["users", "alice", "data"]);
const aliceEmailKey = PrivacyKit.deriveKey(masterKey, ["users", "alice", "emails"]);
const bobPhotoKey = PrivacyKit.deriveKey(masterKey, ["users", "bob", "photos"]);
// Derive unlimited keys from the same parent
const aliceEmail1Key = PrivacyKit.deriveKey(masterKey, ["users", "alice", "emails", "1"]);
const aliceEmail2Key = PrivacyKit.deriveKey(masterKey, ["users", "alice", "emails", "2"]);
// In your main application with master key access
const masterKey = retrieveMasterKey();
const aliceSubtreeKey = PrivacyKit.deriveKey(masterKey, ["users", "alice"]);
// Share aliceSubtreeKey with a trusted third-party service
sendKeyToThirdParty(aliceSubtreeKey);
// --- On the third-party service ---
const receivedKey = getKeyFromMainApp(); // This is aliceSubtreeKey
// Third party can access only Alice's data
const aliceEmailKey = PrivacyKit.deriveKey(receivedKey, ["emails"]);
const alicePhotoKey = PrivacyKit.deriveKey(receivedKey, ["photos"]);
// Cannot access Bob's data or move up the tree
// const bobKey = PrivacyKit.deriveKey(receivedKey, ["../bob"]); // Would fail
1.1. Master Key: A cryptographically secure random 32-byte value that serves as the root for all key derivations.
1.2. Chain Code: A 32-byte value used as the basis for deriving child keys.
1.3. Path: An ordered sequence of string segments that define the derivation path from a parent key to a child key.
1.4. Derived Key: A 32-byte key produced as the final output of the key derivation process.
2.1. All cryptographic operations SHALL use HMAC-SHA-512 as defined in RFC 2104 and FIPS 180-4.
2.2. The master key SHALL serve directly as the initial chain code:
GetInitialChainCode(masterKey):
return masterKey
2.3. The derivation of a child chain code from a parent chain code SHALL be computed as:
DeriveChildChainCode(parentChainCode, segment):
data = Buffer.concat([Buffer.alloc(1, 0), Buffer.from(segment)]) // 0x00 is a separator byte
I = HMAC-SHA-512(key=parentChainCode, message=data)
return I.subarray(0, 32) // First half becomes the new chain code
2.4. The final derived key SHALL be computed from the last chain code:
DeriveKeyFromChainCode(chainCode, finalSegment):
data = Buffer.concat([Buffer.alloc(1, 0), Buffer.from(finalSegment)])
I = HMAC-SHA-512(key=chainCode, message=data)
return I.subarray(32) // Second half becomes the derived key
2.5. For a multi-segment path, the derivation SHALL be computed iteratively:
DeriveKeyPath(masterKey, [segment_1, segment_2, ..., segment_n]):
chainCode = masterKey
// Process all segments except the last one
for i = 1 to n-1:
chainCode = DeriveChildChainCode(chainCode, segment_i)
// Process the final segment to get the actual key
return DeriveKeyFromChainCode(chainCode, segment_n)
2.6. For a path with a single segment, the derivation SHALL be:
DeriveKeyPath(masterKey, [segment]):
return DeriveKeyFromChainCode(masterKey, segment)
3.1. One-Way Derivation: Given a derived key or chain code, it MUST be computationally infeasible to derive the parent chain code.
3.2. Collision Resistance: It MUST be computationally infeasible to find two different paths that derive the same key from a given master key.
3.3. Key Isolation: Compromise of one derived key MUST NOT lead to compromise of any key not in its direct derivation path.
4.1. All string path segments MUST be encoded as UTF-8 prior to being used as input to the HMAC function.
4.2. The master key MUST be generated using a cryptographically secure random number generator and MUST be 32 bytes in length.
4.3. Implementations MUST validate that path segments contain only valid characters according to the application's requirements.
4.4. Implementations MUST NOT allow path segments that could potentially allow traversal up the hierarchy (e.g., ".." segments).
@ex3ndr@ex3ndr@founders@ex3ndr