12 KiB
| title | name | category | editor | contributors | |
|---|---|---|---|---|---|
| WAKU-RLN-KEYSTORE | Waku RLN Keystore | Standards Track | Jimmy Debe <jimmy@status.im> |
|
Abstract
This specification describes how RLN, Rate Limit Nullifier, credentials are securely stored in a JSON schema.
Summary
A keystore is a construct to store a user’s keys. The keys will be encrypted and decrypted based on methods specified in this specification. The keystore stores a user's credentials locally and uses 32/RLN-V1 as a spam-prevention mechanism by generating zero-knowledge proofs.
Background
The secure storage of keys is important in peer-to-peer messaging applications.
A WAKU-RLN-KEYSTORE uses zero-knowledge proofs for anonymous rate-limiting for messaging frameworks.
Generated credentials by a user are encrypted and stored in the keystore to be retrieved over a network.
With 32/RLN-V1, sending and receiving
messages will ensure a message rate for a network is being followed while preserving the anonymity of the message owner.
Waku RLN Keystore Format:
A format example of a keystore used by a 17/WAKU2-RLN-Relay.
const Keystore {
application: "waku-rln-relay" ,
appIdentifier: "string",
version: "string",
credentials: {
"membershipHash": {
crypto: {
cipher: "string",
cipherparams: {
iv: "string",
},
ciphertext: "string",
kdf: "string",
kdfparams: {
dklen: integer,
c: integer,
prf: "string",
salt: "string",
},
mac: "string",
}
}
}
}
Specification
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
The keystore MUST be generated by a cryptographic construction with password verification and decryption.
Keystore modules MUST include metadata, key derivation function, checksum, cipher, and a membership hash.
Metadata:
Information about the keystore SHOULD be stored in the metadata.
The declaration of application, version, and appIdentifier COULD occur in the metadata.
application: current application, MUST be a stringversion: application version, MUST be a string, SHOULD follow semantic versioningappIdentifier: application identifier, MUST be a string
Credentials:
After RLN credentials are generated, it MUST be stored in a JSON schema.
The Waku RLN credentials MUST consist of a membershipHash and WakuCredential.
The membershipHash will be an identity hash of the user.
The WakuCredential will store to encryption portion of the keystore.
There COULD be multiple credentials stored in a keystore, categorized by the membershipHash.
Each contruct MUST include the keypair:
key: [
membershipHash]: pair: [WakuCredential]
membershipHash
The membershipHash SHOULD be generated by user's participating in a membership group,
as decribed in 32/RLN-V1.
Each user SHOULD register to the group with an identity_commitment stored in a Merkle tree.
A cryptographic hash function that SHOULD be used to generate the membershipHash is SHA256,
other hash functions MAY be used.
The hash function that is used,
SHOULD be mentioned in the verison attribute.
To generate the membershipHash,
the treeIndex, membershipContract, chainId and identityCredential attributes SHOULD be used to create a hexadecimal string.
- it MUST NOT already exist in the keystore.
treeIndex
After a user registers to a group,
a treeIndex value of the position in the Merkle tree SHOULD be returned.
- it MUST be a Merkle tree data structure filled with
identity_commitmentfrom user registrations. - it MUST be a hexadecimal string
membershipContract
For decentralized membership registrations,
the membershipContract SHOULD be a contractAddress from a public blockchain using smart contracts.
- it MUST be a string.
chainId
It uniquely defines the chain upon which the registration has occurred.
The chainId SHOULD be the blockchain identifier used for membershipcontract,
as described in EIP155.
- it MUST be a string
identityCredential
The identityCredential MUST be derived after a succussful decryption of the keystore.
The identityCredential MUST be constructed with the identity_secret, identity_secret_hash, identity_commitment values.
- it MUST be a hash of
identity_commitmentstored in a Merkle tree. - it MUST be a string.
identity_secret
The identity_secret MUST be constructed with identity_nullifier + identity_trapdoor values.
identity_nullifier: Random 32 byte valueidentity_trapdoor: Random 32 byte value
identity_secret_hash
Used to derive the identity_commitment of the user, and
as a private input for zero-knowledge proof generation.
- it MUST be created with
identity_secretas a parameter for the hash function. - This secret hash SHOULD be kept private by the user.
identity_commitment
- it SHOULD be created with
identity_secret_hashby using the hash function Poseidon, as described in Poseidon Paper. - it MUST be used by a user for group registering.
WakuCredential
The WakuCredential will store values used for encrypting and decrypting user's keystores.
- it MUST be used for password verification.
- it MUST follow EIP-2335
- it SHOULD use SHA256 as the hash function
KDF
The password-based encryption used SHOULD be KDF, key derivation function, to produce a derived key from a password and other parameters. The keystore COULD use PBKDF2 password-based encryption, as described in RFC 2898.
A WakuCredential object MUST include:
| Name | Description |
|---|---|
| password | used to encrypt keystore and decryption key |
| secret | key to be encrypted |
| pubKey | public key |
| path | HD, hardened derivation, path used to generate the secret |
| checksum | hash function |
| cipher | cipher function |
crypto: {
cipher: "string" // The cipher function
cipherparams: {
iv: "string" // The cipher parameters
},
ciphertext: "string" // The cipher message,
kdf: "string" // KDF Function,
kdfparams: {
param: integer // Salt value and iteration count,
dklen: integer // Length in octets of derived key, MUST be positive integer,
c: "string" // Iteration count, MUST be positive integer,
prf: "string" // Underlying pseudorandom function,
salt: "string" // Produces a large set of keys based on the password
},
mac: "string" // Checksum
}
Decryption
The keystore SHOULD decrypt a user's credentials using a password and the membershipHash,
using PBKDF2 that returns the decryptionKey key.
The decryption key is used to verify the keystore is correct.
- To generate the
decryptionKey, it MUST be constructed from a password and KDF, as desrcibed in ERC-2335: BLS12-381 Keystore. - The
decryptionKey, is derived from the cipher function and cipher parameters described in the KDF used in the keystore.
Test Vectors
RLN uses Poseidon hash algorithm to generate the identityCredential,
as described in Poseidon Paper.
The keystore hash algorithm used is SHA256.
Input:
application: "waku-rln-relay"appIdentifier: "01234567890abcdef"version: "0.2"hashFunction: "poseidonHash"password: "sup3rsecure"
identityCredential = {
IDTrapdoor: [
211, 23, 66, 42, 179, 130, 131, 111, 201, 205, 244, 34, 27, 238, 244,
216, 131, 240, 188, 45, 193, 172, 4, 168, 225, 225, 43, 197, 114, 176,
126, 9,
],
IDNullifier: [
238, 168, 239, 65, 73, 63, 105, 19, 132, 62, 213, 205, 191, 255, 209, 9,
178, 155, 239, 201, 131, 125, 233, 136, 246, 217, 9, 237, 55, 89, 81,
42,
],
IDSecretHash: [
150, 54, 194, 28, 18, 216, 138, 253, 95, 139, 120, 109, 98, 129, 146,
101, 41, 194, 36, 36, 96, 152, 152, 89, 151, 160, 118, 15, 222, 124,
187, 4,
],
IDCommitment: [
112, 216, 27, 89, 188, 135, 203, 19, 168, 211, 117, 13, 231, 135, 229,
58, 94, 20, 246, 8, 33, 65, 238, 37, 112, 97, 65, 241, 255, 93, 171, 15,
],
}
membership = {
chainId: "0xAA36A7",
treeIndex: 8,
address: "0x8e1F3742B987d8BA376c0CBbD7357fE1F003ED71",
}
Output:
application: "waku-rln-relay",
appIdentifier: "01234567890abcdef",
version: "0.2",
credentials: {
"9DB2B4718A97485B9F70F68D1CC19F4E10F0B4CE943418838E94956CB8E57548": {
crypto: {
cipher: "aes-128-ctr",
cipherparams: {
iv: "fd6b39eb71d44c59f6bf5ff3d8945c80",
},
ciphertext: "9c72f47ce95de03ed34502d0288e7576b66b51b9e7d5ae882c27bd89f94e6a03c2c44c2ddf0c982e72003d67212105f1b64614f57cabb0ceadab7e07be165eee1121ad6b81951368a9f3be2dd99ea294515f6013d5f2bd4702a40e36cfde2ea298b23b31e5ce719d8040c3331f73d6bf44f88bca39bac0e917d8bf545500e4f40d321c235426a80f315ac70666acbd3bdf803fbc1e7e7103fed466525ed332b25d72b2dbedf6fa383b2305987c1fe276b029570519b3e79930edf08c1029868d05c2c08ab61d7c64f63c054b4f6a5a12d43cdc79751b6fe58d3ed26b69443eb7c9f7efce27912340129c91b6b813ac94efd5776a40b1dda896d61357de208c7c47a14af911cc231355c8093ee6626e89c07e1037f9e0b22c690e3e049014399ca0212c509cb04c71c7860d1b17a0c47711c490c27bad2825926148a1f15a507f36ba2cdaa04897fce2914e53caed0beaf1bebd2a83af76511cc15bff2165ff0860ad6eca1f30022d7739b2a6b6a72f2feeef0f5941183cda015b4631469e1f4cf27003cab9a90920301cb30d95e4554686922dc5a05c13dfb575cdf113c700d607896011970e6ee7d6edb61210ab28ac8f0c84c606c097e3e300f0a5f5341edfd15432bef6225a498726b62a98283829ad51023b2987f30686cfb4ea3951f3957654035ec291f9b0964a3a8665d81b16cec20fb40f944d5f9bf03ac1e444ad45bae3fa85e7465ce620c0966d8148d6e2856f676c4fbbe3ebe470453efb4bbda1866680037917e37765f680e3da96ef3991f3fe5cda80c523996c2234758bf5f7b6d052dc6942f5a92c8b8eec5d2d8940203bbb6b1cba7b7ebc1334334ca69cdb509a5ea58ec6b2ebaea52307589eaae9430eb15ad234c0c39c83accdf3b77e52a616e345209c5bc9b442f9f0fa96836d9342f983a7",
kdf: "pbkdf2",
kdfparams: {
dklen: 32,
c: 1000000,
prf: "hmac-sha256",
salt: "60f0aa92fbf63a8356dfdbed2ab18058",
},
mac: "51a227ac6db7f2797c63925880b3db664e034231a4c68daa919ab42d8df38bc6",
},
}
Security Considerations
1.) Add a Password
An attacker can identify which credential belongs to a combination of chainId and
contractAddress pair by brute forcing the treeIndex iteratively to find a hash match.
The RECOMMENDED solution is to add a password to the construction of membershipHash to prevent this attack.
The RECOMMENDED membershipHash Construction:
membershipHashSHOULD be constructed withtreeIndex,membershipContract,identityCredential,membershipPasswordmembershipPassword: a new password created to private attacks compromising keystore credentials.
- The user MUST store the
membershipPasswordprivately.
Copyright
Copyright and related rights waived via CC0.