logos-messaging/specs
1
0
Fork 0
mirror of https://github.com/logos-messaging/specs.git synced 2026-01-02 06:03:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update rln-keystore.md

Browse Source
This commit is contained in:
Jimmy Debe 2025-07-30 20:49:21 -04:00 committed by GitHub
parent 9992da00d8
commit 493dc2e2f8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 65 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
standards/application/rln-keystore.md
View File

@ -8,25 +8,33 @@ contributors:
---
## Abstract
This specification describes how RLN, Rate Limit Nullifier,
This specification describes how the 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](/spec/32/) as a spam-prevention mechanism by generating zero-knowledge proofs.
## Background
A keystore is a construct to store a user’s cryptographic keys.
The keys are encrypted and decrypted based on the methods specified in this specification.
A [17/WAKU2-RLN-RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md)
keystore stores a node's credentials locally and
[32/RLN-V1](https://github.com/vacp2p/rfc-index/blob/main/vac/32/rln-v1.md) is used as a spam-prevention mechanism with the help of zero-knowledge proofs.
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](/spec/32/), sending and receiving
messages will ensure a message rate for a network is being followed while preserving the anonymity of the message owner.
Zero-knowledge proofs are used to have anonymous rate-limiting for messaging frameworks.
Node's Credentials are encrypted and
stored in the keystore to be retrieved at any time over the Waku network.
With [32/RLN-V1](https://github.com/vacp2p/rfc-index/blob/main/vac/32/rln-v1.md), sending and receiving
messages will ensure a message rate for the network is being followed while preserving the anonymity of the message owner.
## 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](https://www.ietf.org/rfc/rfc2119.txt).
### Waku RLN Keystore Format:
A format example of a keystore used by a [17/WAKU2-RLN-Relay](/spec/17/).
A format example of a keystore used by a [17/WAKU2-RLN-Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md).
```js
const Keystore {
@ -56,18 +64,14 @@ const Keystore {
```
## 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](https://www.ietf.org/rfc/rfc2119.txt).
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.
The keystore MUST be generated using a cryptographic construction that supports password verification and decryption.
Keystore modules MUST include metadata, a key derivation function, a checksum, a 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.
The declaration of `application`, `version`, and `appIdentifier` MAY occur in the metadata.
- `application` : current application, MUST be a string
- `version` : application version, MUST be a string, SHOULD follow semantic versioning
@ -75,59 +79,69 @@ The declaration of `application`, `version`, and `appIdentifier` COULD occur in
### 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`.
After the RLN credentials are generated, it MUST be stored in a JSON schema.
The 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`.
The `WakuCredential` will store the encryption portion of the keystore.
There MAY 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](/spec/32/).
The `membershipHash` SHOULD be generated by users participating in a membership group,
as decribed in [32/RLN-V1](https://github.com/vacp2p/rfc-index/blob/main/vac/32/rln-v1.md).
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](https://www.rfc-editor.org/rfc/rfc4634.txt),
other hash functions MAY be used.
The hash function that is used,
SHOULD be mentioned in the `verison` attribute.
The hash function used SHOULD be defined in the `verison` attribute.
It MUST NOT already exist in the keystore.
To generate the `membershipHash` the following attributes SHOULD be used to create a hexadecimal string:
- `treeIndex` :
- `membershipContract`
- `chainId`,
- `identityCredential`
- `rateLimit`
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_commitment` from user registrations.
- it MUST be a hexadecimal string
- it MUST be a Merkle tree data structure filled with the `identity_commitment` from user registrations.
- it SHOULD 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.
the `membershipContract` SHOULD be a `contractAddress` of a smart contract deployed on a blockchain.
- it SHOULD 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`,
The `chainId` SHOULD be the blockchain identifier used for `membershipContract`,
as described in [EIP155](https://eips.ethereum.org/EIPS/eip-155).
- 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_commitment` stored 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 value
- `identity_trapdoor` : Random 32 byte value
@ -138,24 +152,29 @@ as a private input for zero-knowledge proof generation.
- it MUST be created with `identity_secret` as a parameter for the hash function.
- This secret hash SHOULD be kept private by the user.
###### `identity_commitment`
###### `identity_commitment`
- it SHOULD be created with `identity_secret_hash` by using the hash function Poseidon,
as described in [Poseidon Paper](https://eprint.iacr.org/2019/458.pdf).
- it MUST be used by a user for group registering.
##### `rateLimit`
- it SHOULD be the user's membership rate limit
#### WakuCredential
The `WakuCredential` will store values used for encrypting and decrypting user's keystores.
The `WakuCredential` will store values used for encrypting and decrypting a user's keystore.
- it MUST be used for password verification.
- it MUST follow [EIP-2335](https://eips.ethereum.org/EIPS/eip-2335)
- it SHOULD use [SHA256](https://www.rfc-editor.org/rfc/rfc4634.txt) 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,
The keystore MAY use PBKDF2 password-based encryption,
as described in [RFC 2898](https://www.ietf.org/rfc/rfc2898.txt).
A `WakuCredential` object MUST include:
@ -191,9 +210,11 @@ crypto: {
```
#### 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.
The `decryptionKey` 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](https://eips.ethereum.org/EIPS/eip-2335).
- The `decryptionKey`, is derived from the cipher function and
@ -289,8 +310,8 @@ The RECOMMENDED `membershipHash` Construction:
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
1. [32/RLN-V1](/spec/32/)
2. [17/WAKU2-RLN-RELAY](/spec/17/)
1. [32/RLN-V1](https://github.com/vacp2p/rfc-index/blob/main/vac/32/rln-v1.md)
2. [17/WAKU2-RLN-RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md)
3. [SHA256](https://www.rfc-editor.org/rfc/rfc4634.txt)
4. [EIP155](https://eips.ethereum.org/EIPS/eip-155)
5. [Poseidon Paper](https://eprint.iacr.org/2019/458.pdf)