added documentation for PRS

[Koufan-De-King]

No description provided.

[francis-pouatcha]

Areas for Potential Improvement and Questions:

1. Salt Management:

   • How is the salt generated and stored? This is a critical detail for security. Ideally, each user should have a unique, randomly generated salt stored securely (e.g., in a secure database associated with the user's pending registration record).
   • Is the salt long enough? A salt should be sufficiently long (e.g., at least 16 bytes, preferably more) to be effective against rainbow table attacks.

2. OTP Generation:

   • What algorithm is used to generate the OTP? It should be a cryptographically secure pseudo-random number generator (CSPRNG).
   • What is the length of the OTP? A longer OTP (e.g., 6-8 digits) is generally more secure.
   • Is there a time limit for OTP validity? OTPs should expire after a short period (e.g., 5-10 minutes) to limit the window of opportunity for attackers.

3. PR Cache and FA Cache Implementation Details:

   • What kind of cache is being used? (e.g., Redis, Memcached, in-memory)
   • What are the eviction policies for these caches? This is important to ensure the caches don't grow indefinitely. For the PR cache, the 5-minute timeout is good. For the FA cache, you might need a different policy (e.g., LRU - Least Recently Used) or a maximum size.
   • Where are these caches hosted? Are they part of the OBS server, or are they separate services?

4. Error Handling:

   • The document mentions "Failed" if the OTP doesn't match. Consider adding more detail about how errors are handled throughout the registration process. What specific error messages are returned to the UserApp? What happens in case of network issues, SMS Gateway failures, or database errors?
   • The document should specify what happens if a user attempts to register a phone number that already exists in the FA cache.

5. Scalability:

   • Consider mentioning how the system will handle a large number of concurrent registration requests, especially given the target market in Africa. This might involve using load balancing, asynchronous processing, or other scaling techniques.

6. Public Key Usage:

   • The document mentions the UserApp generating a public key. While this is good for security, it's not entirely clear how this public key is used in the registration flow. Is it for encrypting communication between the UserApp and the OBS? If so, this should be clarified.
   • The document should also specify whether the generated public/private key pair is stored by the system or just by the user.

7. HTTPS Encryption:

   • While mentioned in the security considerations, explicitly state that all communication between the UserApp, OBS, PRS, DAS, and SMS Gateway must be over HTTPS.

8. Asynchronous Communication with SMS Gateway:

   • Consider making the communication with the SMS Gateway asynchronous. This will prevent the PRS from blocking while waiting for the SMS to be sent, improving responsiveness.

9. Rate Limiting:

   • Beyond the PR cache, implement rate limiting at the OBS and PRS levels to prevent abuse and denial-of-service attacks.

Minor Suggestions:

• Table of Contents: Consider adding hyperlinks to the sections in the Table of Contents for easier navigation.
• Acronym Expansion: Although most acronyms are defined, it might be helpful to have a dedicated "Glossary of Terms" section at the beginning or end of the document.
• Version Control: Add a version history section to track changes to the document.

[francis-pouatcha]

PRS (Pending Registration Service) Architecture Documentation

Table of Contents

• 1. Introduction
• 2. High-Level System Architecture
• 3. Registration Workflow
  • 3.1. Step-by-Step Process
  • 3.2. Proof-of-Work (PoW) Details
  • 3.3. Device Key Pair and Account Binding
  • 3.4. Account Recovery
• 4. Interaction with Other Modules
• 5. Data Flow and Sequence Diagram
• 6. Security Considerations
  • 6.1. Salt Management
  • 6.2. OTP Generation
  • 6.3. Public Key Usage
• 7. Caching Mechanisms
  • 7.1. PR Cache
  • 7.2. FA Cache
• 8. Error Handling
• 9. Scalability
• 10. Glossary of Terms
• 11. Version History
• 12. Conclusion

---

1. Introduction

The Pending Registration Service (PRS) is a critical backend service within the Webank system, tasked with managing user registrations, device binding, and OTP verification. It ensures a secure and seamless process for new users signing up for bank accounts by integrating with the OBS (Online Banking Service), an SMS gateway service, and other key modules.

Key Responsibilities:

• Generate and manage OTPs during registration.
• Manage device key pairs and their association with user accounts.
• Implement Proof-of-Work (PoW) mechanisms to prevent spam.
• Securely hash and validate user-provided registration data.
• Facilitate communication between the frontend and backend for user account creation.
• Support account recovery using phone numbers.

---

2. High-Level System Architecture

The PRS operates within a microservices ecosystem and is tightly integrated with the OBS and SMS Gateway. It performs the following key functions:

1. OTP Generation and Delivery: Generates unique OTPs for each registration attempt and sends them via SMS to the user.
2. Device Key Pair Management: Stores and manages the association between user accounts and device public keys.
3. Proof-of-Work (PoW): Provides a nonce and validates the PoW performed by the client to prevent spam.
4. Hashing and Validation: Implements secure hashing logic to prevent replay attacks or tampering during OTP verification.
5. Communication: Acts as the processing layer for requests originating from the OBS during the user registration process.

---

3. Registration Workflow

3.1. Step-by-Step Process

1. Frontend Registration Request:

   • A user accesses the registration page in the UserApp.
   • The UserApp generates a device key pair (public and private key). The private key is stored securely on the device and never transmitted to the server. The generated key pair should not be stored on the server.
   • The UserApp sends a request to the OBS to initiate the registration process.

2. Proof-of-Work Challenge:

   • The OBS generates a random nonce and a corresponding hash value (challenge).
   • The OBS sends the challenge back to the UserApp. The nonce is valid for a defined amount of time (e.g., 5 minutes).

3. PoW Computation:

   • The UserApp performs a computationally intensive task (PoW) using the provided challenge. This involves finding a value that, when combined with the challenge and hashed, produces a result that meets specific criteria (e.g., starts with a certain number of zeros). The difficulty of the PoW can be adjusted.

4. Registration Request with PoW and Device Public Key:

   • The UserApp sends a registration request to the OBS containing the user's phone number, the device public key, and the solution to the PoW challenge. This request also includes the original challenge's hash (sent back as proof that the correct challenge was solved).

5. PoW and Phone Number Validation:

   • The OBS verifies the PoW solution. If valid, it checks if the phone number is already in the pending registration cache (PR cache). Any repeat requests from the same phone number within 5 minutes are ignored.
   • If the phone number is not in the PR cache, it is temporarily stored.

6. Request Forwarded to PRS:

   • The OBS forwards the phone number, device public key, and a flag indicating successful PoW validation to the PRS.

7. OTP Generation and Hashing:

   • The PRS generates a unique OTP.
   • The PRS hashes the incoming data (phone number, device public key, OTP) with a unique salt per user. This produces an OTPHASH that is sent back to the OBS.
   • The PRS forwards the OTP to the user via an SMS Gateway.

8. Frontend OTP Confirmation:

   • The user receives the OTP and enters it in the UserApp's OTP confirmation page.
   • The UserApp sends a new request containing the phone number, device public key, OTP, and OTPHASH to the OBS.

9. Verification in PRS:

   • The OBS forwards the data to the PRS, which hashes the phone number, device public key, and OTP again with the same salt to generate a newOTPHASH.
   • If the newOTPHASH matches the original OTPHASH, the PRS sends an OK response back to the OBS, signifying successful OTP verification.

10. Account Creation and Device Binding:

    • Upon successful OTP verification, the OBS communicates with the DAS (Deposit Account Service) to create the user's bank account.
    • The OBS stores the device public key and associates it with the newly created account and the user's phone number.
    • The phone number is stored in a final account cache (FA cache) in the OBS to avoid repeated queries to the DAS.

3.2. Proof-of-Work (PoW) Details

• Algorithm: The PoW algorithm should be computationally intensive but easily verifiable. Examples include Hashcash or a similar algorithm where the difficulty can be adjusted.
• Challenge Generation: The OBS generates a random nonce (a large, random number) and hashes it to create a challenge.
• Difficulty Adjustment: The difficulty of the PoW (e.g., the number of leading zeros required in the hash result) can be adjusted based on server load or other factors to maintain an appropriate level of spam protection.
• Validation: The OBS checks if the provided PoW solution, when combined with the original challenge and hashed, meets the defined difficulty criteria.

3.3. Device Key Pair and Account Binding

• Generation: The UserApp generates the key pair using a cryptographically secure method (e.g., Elliptic Curve Cryptography).
• Storage: The private key is stored securely on the user's device (e.g., in the device's secure storage). The public key is sent to the server and associated with the user's account.
• Purpose: The key pair binds the user's device to their account. Future transactions or sensitive operations can be authorized by requiring a signature from the device's private key, ensuring that only the authorized device can perform these actions.

3.4. Account Recovery

• Mechanism: If a user loses their device, they can initiate an account recovery process using their registered phone number.
• Process:
  1. The user installs the UserApp on a new device.
  2. The UserApp generates a new device key pair.
  3. The user initiates the account recovery process and provides their phone number.
  4. The OBS sends an OTP to the registered phone number via the SMS Gateway.
  5. The user enters the OTP in the UserApp.
  6. Upon successful OTP verification, the OBS updates the account's associated device public key with the new public key generated by the new device.
  7. The old public key becomes invalid.
• Security: This process ensures that only the user controlling the registered phone number can bind a new device to their account.

---

4. Interaction with Other Modules

1. OBS (Online Banking Service):

• Acts as the gateway for registration requests and forwards them to the PRS.
• Manages the PR cache and FA cache.
• Provides the PoW challenge to the UserApp.
• Validates the PoW solution.
• Initiates account creation with the DAS.
• Associates device public keys with user accounts.

2. SMS Gateway:

• Sends OTPs generated by the PRS to the user's phone number.

3. DAS (Deposit Account Service):

• Creates the user's bank account upon successful OTP verification.

---

5. Data Flow and Sequence Diagram

Data Flow

1. The user initiates the registration process in the frontend (UserApp).
2. The OBS generates a PoW challenge and manages caching.
3. The UserApp completes the PoW and sends the registration request.
4. The OBS validates the PoW and forwards requests to the PRS.
5. The PRS generates OTPs, hashes the registration data, and validates OTPs upon verification.
6. The OBS associates the device public key with the user's account.

Sequence Diagram

sequenceDiagram
    participant UserApp
    participant OBS
    participant PRcache
    participant FAcache
    participant PRS
    participant SMSGateway
    participant DAS

    UserApp->>UserApp: Generate device key pair
    UserApp->>OBS: Initiate registration
    OBS->>OBS: Generate nonce and challenge hash
    OBS-->>UserApp: PoW challenge (nonce, challenge hash)

    UserApp->>UserApp: Perform PoW (find solution)
    UserApp->>OBS: Register (phone number, public key, PoW solution, challenge hash)
    OBS->>OBS: Verify PoW solution
    OBS->>PRcache: Store phone number in pending registration cache
    OBS->>PRS: Forward registration (phone number, public key, PoW valid flag)
    PRS->>PRS: Generate OTP
    PRS->>PRS: Hash (phone number, public key, OTP, salt) -> OTPHASH
    PRS->>SMSGateway: Send OTP via SMS
    SMSGateway-->>UserApp: OTP sent to user
    PRS-->>OBS: Return OTPHASH
    OBS-->>UserApp: OTPHASH

    UserApp->>UserApp: Store OTPHASH
    UserApp->>OBS: Verify OTP (phone number, public key, inputOTP, OTPHASH)
    OBS->>PRS: Forward verification data
    PRS->>PRS: Hash (phone number, public key, inputOTP, salt) -> newOTPHASH
    PRS->>PRS: Compare newOTPHASH with OTPHASH
    alt OTP matches
        PRS-->>OBS: OK
        OBS->>DAS: Create account (phone number)
        DAS-->>OBS: AccountID, balance
        OBS->>OBS: Associate public key with account and phone number
        OBS-->>FAcache: Store phone number in final account cache
        OBS-->>UserApp: Registration successful
    else OTP does not match
        PRS-->>OBS: Failed
        OBS-->>UserApp: OTP verification failed
    end

Loading

6. Security Considerations

• Hashing with Salt: Adds an extra layer of security to prevent brute-force attacks.
• Caching: Prevents spamming of registration requests.
• OTP Validation: Ensures the user has access to the registered phone number.
• HTTPS Encryption: Protects sensitive data during transmission. All communication between the UserApp, OBS, PRS, DAS, and SMS Gateway must be over HTTPS.
• Rate Limiting: Implement rate limiting at the OBS and PRS levels to prevent abuse and denial-of-service attacks.
• Proof-of-Work (PoW): Deters spam by requiring computational effort from the client before registration.
• Device Key Pair Binding: The user's device is cryptographically bound to their account, adding an extra layer of security for sensitive operations.

6.1. Salt Management

• Generation: A unique, randomly generated salt of at least 16 bytes (preferably more) must be created for each user during registration.
• Storage: The salt must be securely stored, associated with the user's pending registration record or account details.
• Usage: The salt is used in the hashing process for OTP verification.

6.2. OTP Generation

• Algorithm: A cryptographically secure pseudo-random number generator (CSPRNG) must be used to generate OTPs.
• Length: OTPs should be 6-8 digits long.
• Validity: OTPs should expire after a short period (e.g., 5-10 minutes).

6.3. Public Key Usage

• The device public key is used to bind a user's device to their account. This allows for secure authorization of sensitive operations by requiring a signature from the corresponding private key, which is stored securely on the device.

---

7. Caching Mechanisms

7.1. PR Cache

• Purpose: Prevents spamming of registration requests.
• Implementation: Can be implemented using Redis, Memcached, or an in-memory cache.
• Eviction Policy: Time-based eviction (e.g., 5 minutes).
• Hosting: Can be part of the OBS server or a separate service.

7.2. FA Cache

• Purpose: Avoids repeated queries to the DAS for account information.
• Implementation: Can be implemented using Redis, Memcached, or an in-memory cache.
• Eviction Policy: LRU (Least Recently Used) or a maximum size limit.
• Hosting: Can be part of the OBS server or a separate service.

---

8. Error Handling

• Detailed Error Messages: The system should provide specific error messages to the UserApp to guide users through the registration process. For example:
  • "Invalid phone number format."
  • "Phone number already registered."
  • "Incorrect OTP."
  • "PoW verification failed."
  • "Registration request timed out."
• Error Handling Mechanisms: The system should handle various error scenarios gracefully, including:
  • Network issues
  • SMS Gateway failures
  • Database errors
  • Invalid user input

---

9. Scalability

• Load Balancing: Use load balancing to distribute traffic across multiple instances of the OBS and PRS.
• Asynchronous Processing: Use asynchronous communication with the SMS Gateway to avoid blocking. Consider using message queues (e.g., RabbitMQ, Kafka) for inter-service communication.
• Database Scaling: Use a scalable database solution that can handle a large number of users and transactions.
• Caching: Utilize caching effectively to reduce database load.

---

10. Glossary of Terms

• DAS: Deposit Account Service
• OBS: Online Banking Service
• OTP: One-Time Password
• OTPHASH: The hash of the phone number, public key, and OTP.
• newOTPHASH: The newly computed hash to be compared with OTPHASH.
• PoW: Proof-of-Work
• PR Cache: Pending Registration Cache
• PRS: Pending Registration Service
• FA Cache: Final Account Cache
• CSPRNG: Cryptographically Secure Pseudo-Random Number Generator

---

11. Version History

Version	Date	Author	Changes
1.0	2023-10-27	Bard	Initial version of the PRS architecture document.
1.1	2023-10-28	Bard	Incorporated feedback, added details on PoW, device key pair management, and account recovery.

---

12. Conclusion

The PRS is an integral part of the Webank backend, designed to ensure secure, efficient, and user-friendly account registration. This document provides a comprehensive overview of the PRS architecture, including its functionality, interactions with other modules, security considerations, and scalability aspects. By adhering to the guidelines and principles outlined in this document, the development team can build a robust and reliable registration service for the Webank system.

[francis-pouatcha]

That is a sample document as generated by my language model.