# **Secure Login with mTLS, PIN, and Signed Challenge**
> This document outlines the technical specifications for a secure mobile application login process utilizing mutual Transport Layer Security (mTLS), online PIN verification, and signed challenge-response for enhanced security.

## 1. Actors and Participants

- **User:** Initiates the login process.
- **Mobile App:** Provides the user interface and interacts with backend services.
- **Flutter SDK:** Software development kit used by the mobile app for secure communication, PIN handling, and challenge signing.
- **Apisix:** API Gateway responsible for mTLS verification and routing requests to backend services.
- **Token Service (TS):** Manages login challenges, interacts with other services, and validates login attempts.
- **Certificate Service (CS):** Validates PINs, retrieves user keys from a secure storage, and encrypts challenge data.
- **Backend:** Banking system accessed after successful login.

## 2. Functionality

### User Input:

1. The user launches the mobile app.
2. The app prompts the user to enter an online PIN.
3. The user enters the PIN.

### PIN and mTLS:

1. The mobile app sends the entered PIN to the Flutter SDK.
2. The Flutter SDK establishes an mTLS connection directly with Apisix using its own certificate and private key.
3. Apisix verifies the client certificate (issued to the mobile app) to ensure it originates from a trusted Certificate Authority (CA).

### Challenge and Encryption:

1. The TS generates a login challenge containing a unique nonce value.
2. The TS sends the challenge (nonce) and the hashed PIN to the CS.
3. The CS validates the hashed PIN against the stored value in the database.
4. The CS retrieves the user's public key associated with the private key stored securely within the Secure Element (SE).
5. The CS encrypts the login challenge data (including the nonce) using the user's public key.

### Challenge Response:

1. The CS sends the encrypted login challenge data back to the TS.
2. The TS forwards the encrypted data to the mobile app through the Flutter SDK.
3. The mobile app (via Flutter SDK) securely accesses the Secure Element.
4. The SDK decrypts the challenge data using the user's private key stored within the SE.
5. The SDK signs the decrypted challenge data using the same private key.
6. The SDK sends the signed challenge data back to the TS.

### Signature Verification and Login:

1. The TS receives the signed challenge data.
2. The CS retrieves the user's public key from the certificate (previously validated by Apisix).
3. The CS validates the signature using the user's public key and the original challenge data itself.
4. If the signature is valid, the CS informs the TS of a successful login.
5. The TS relays the login success message to the mobile app through the SDK.

### Backend Access:

1. The mobile app establishes a secure banking session with the backend system.
2. The user can now access banking functionalities.

## 3. Security Considerations

- All communication between the mobile app (via Flutter SDK) and backend services (Apisix and TS) is secured using mTLS.
- The user's online PIN is hashed before transmission and stored securely in the database.
- The user's private key is stored within a secure enclave or Secure Element (SE) on the mobile device, isolated from the main app environment.
- A challenge-response mechanism with a nonce value prevents replay attacks.
- The mobile app signs the challenge data using the user's private key, ensuring data integrity and preventing tampering.

## 4. Technical Requirements

- The mobile app development should utilize the Flutter SDK for secure communication, PIN handling, and challenge signing.
- The backend services (Apisix and TS) should implement secure protocols for mTLS, challenge generation, and user authentication.
- The mobile app environment should have a secure enclave or Secure Element (SE) capability for storing the user's private key.
- The database used for storing hashed PINs should be a secure database management system.

## 5. Open Issues/Next Steps

- Specify the format and content of the login data sent between the mobile app and backend.
- Define the error handling procedures for various stages of the transaction signing process.
- Determine the certificate lifecycle management process (renewal, revocation).

## 6. Sequence Diagram