# Partial Flow 2.8 Validate entered PIN

## Overview

| Aspect                       | Description                                                                                                                                                                                                                                                                                                |
| ---------------------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Summary**                  | The system validates a PIN entered by the user. Too many failed attempts causes the app to be temporarily or permanently blocked. This behaviour is configurable.<br>For example, there may be four rounds of four attempts each. After the first three rounds, the app is blocked temporarily for 1 minute, then 5 minutes, then 1 hour.<br>After the final round, the app is blocked permanently. |
| **Goal**                     | Preventing unauthorized access to and actions in the app.                                                                                                                                                                                                                                                  |
| **Preconditions**            | *None*                                                                                                                                                                                                                                                                                                     |
| **Postconditions**           | Depends on the use case.                                                                                                                                                                                                                                                                                   |
| **Used by**                  | <ul><li>[UC2.3 Unlock the app](../use-cases/UC2.3_UnlockTheApp.md)</li><li>[PF2.4 Confirm a protected action](PF2.4_ConfirmProtectedAction.md)</li></ul>                                                                                                                                                   |
| **Parameters**               | *None*                                                                                                                                                                                                                                                                                                     |
| **Possible Results**         | <ul><li>Valid PIN</li><li>Retry</li><li>Back</li></ul>                                                                                                                                                                                                                                                     |
| **Additional Documentation** | <ul><li>[PIN Validation](../../architecture/use-cases/pin-validation.md)</li></ul>                                                                                                                                                                                                                         |
| **Possible errors**          | <ul><li>[No Internet](../errors.md#no-internet)</li><li>[Server Unreachable](../errors.md#server-unreachable)</li></li>                                                                                                                                                                                    |
| **Logical test cases**       | <ul><li>[LTC46 PIN is invalid timeout](../logical-test-cases.md#ltc46)</li><li>[LTC47 PIN is invalid Block](../logical-test-cases.md#ltc47)</li></ul>                                                                  |

---

## Flow

| #        | Description                                                                                                                                                                                                                             | Next                                                                                                             |
|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| **1.1**  | **System validates PIN, and applies PIN policy**                                                                                                                                                                                        |                                                                                                                  |
| 1.1a     | Case: Valid PIN when app not blocked                                                                                                                                                                                                    | Result: Valid PIN                                                                                                |
| 1.1b     | Case: App temporarily blocked                                                                                                                                                                                                           | 5                                                                                                                |
| 1.1c     | Case: App permanently blocked                                                                                                                                                                                                           | 9                                                                                                                |
| 1.1d     | Case: Invalid PIN (non-final round, first time)                                                                                                                                                                                         | 2                                                                                                                |
| 1.1e     | Case: Invalid PIN (non-final round, second time)                                                                                                                                                                                        | 3                                                                                                                |
| 1.1f     | Case: Invalid PIN (non-final round, third time)                                                                                                                                                                                         | 4                                                                                                                |
| 1.1g     | Case: Invalid PIN (non-final round, fourth time)                                                                                                                                                                                        | 5                                                                                                                |
| 1.1h     | Case: Invalid PIN at PID issuance (first round, fourth time)                                                                                                                                                                            | 11                                                                                                               |
| 1.1i     | Case: Invalid PIN (final round, first time)                                                                                                                                                                                             | 6                                                                                                                |
| 1.1j     | Case: Invalid PIN (final round, second time)                                                                                                                                                                                            | 7                                                                                                                |
| 1.1k     | Case: Invalid PIN (final round, third time)                                                                                                                                                                                             | 8                                                                                                                |
| 1.1l     | Case: Invalid PIN (final round, fourth time)                                                                                                                                                                                            | 9                                                                                                                |
| 1.1m     | Error: No internet                                                                                                                                                                                                                      | Error flow: [No Internet](../errors.md#no-internet)                                                              |
| 1.1n     | Error: Server unreachable                                                                                                                                                                                                               | Error flow: [Server Unreachable](../errors.md#server-unreachable)                                                |
| **2**    | **WHEN PIN INVALID, NON-FINAL ROUND, FIRST TIME**                                                                                                                                                                                       |                                                                                                                  |
| **2.1**  | **System displays prompt 'Wrong PIN, retry'**<ul><li>Message: wrong PIN, try again.</li><li>Actions: Close, Forgot PIN</li></ul>                                                                                                        |                                                                                                                  |
| 2.1a     | User selects Close                                                                                                                                                                                                                      | Result: Retry                                                                                                    |
| 2.1b     | User selects Forgot PIN                                                                                                                                                                                                                 | 10                                                                                                               |
| **3**    | **WHEN PIN INVALID, NON-FINAL ROUND, SECOND TIME**                                                                                                                                                                                      |                                                                                                                  |
| **3.1**  | **System displays prompt 'Wrong PIN, retry'**<ul><li>Message: wrong PIN, you have 2 more attempts.</li><li>Actions: Close, Forgot PIN</li></ul>                                                                                         |                                                                                                                  |
| 3.1a     | User selects Close                                                                                                                                                                                                                      | Result: Retry                                                                                                    |
| 3.1b     | User selects Forgot PIN                                                                                                                                                                                                                 | 10                                                                                                               |
| **4**    | **WHEN PIN INVALID, NON-FINAL ROUND, THIRD TIME**                                                                                                                                                                                       |                                                                                                                  |
| **4.1**  | **System displays prompt 'Wrong PIN, retry'**<ul><li>Message: wrong PIN, you have 1 more attempt. Then your app will be blocked temporarily.</li><li>Actions: Close, Forgot PIN</li></ul>                                               |                                                                                                                  |
| 4.1a     | User selects Close                                                                                                                                                                                                                      | Result: Retry                                                                                                    |
| 4.1b     | User selects Forgot PIN                                                                                                                                                                                                                 | 10                                                                                                               |
| **5**    | **WHEN APP TEMPORARILY BLOCKED (NON-FINAL ROUND, FOURTH FAILED ATTEMPT)**                                                                                                                                                               |                                                                                                                  |
| **5.1**  | **System displays screen 'Temporarily Blocked'**<ul><li>Message: app is blocked for X more seconds/minutes.</li><li>Actions: Delete Wallet, Forgot PIN, Back, Help</li></ul>                                                            |                                                                                                                  |
| 5.1a     | User selects Delete Wallet                                                                                                                                                                                                              | Go to: [UC9.4 Wipe all app data](../use-cases/UC9.4_WipeAllAppData.md)                                           |
| 5.1b     | User selects Back                                                                                                                                                                                                                       | Result: Back                                                                                                     |
| 5.1c     | User selects Help                                                                                                                                                                                                                       | Show placeholder 'under construction'                                                                            |
| 5.1d     | User selects Forgot PIN                                                                                                                                                                                                                 | 10                                                                                                               |
| 5.1e     | Event: timer expires                                                                                                                                                                                                                    | Result: Retry                                                                                                    |
| **6**    | **WHEN PIN INVALID, FINAL ROUND FIRST TIME**                                                                                                                                                                                            |                                                                                                                  |
| **6.1**  | **System displays prompt 'Wrong PIN, retry'**<ul><li>Message: wrong PIN, you have 3 more attempts. Then your app will be blocked permanently</li><li>Actions: Close, Forgot PIN</li></ul>                                               |                                                                                                                  |
| 6.1a     | User selects Close                                                                                                                                                                                                                      | Result: Retry                                                                                                    |
| 6.1b     | User selects Forgot PIN                                                                                                                                                                                                                 | 10                                                                                                               |
| **7**    | **WHEN PIN INVALID, FINAL ROUND SECOND TIME**                                                                                                                                                                                           |                                                                                                                  |
| **7.1**  | **System displays prompt 'Wrong PIN, retry'**<ul><li>Message: wrong PIN, you have 2 more attempts. Then your app will be blocked permanently</li><li>Actions: Close, Forgot PIN</li></ul>                                               |                                                                                                                  |
| 7.1a     | User selects Close                                                                                                                                                                                                                      | Result: Retry                                                                                                    |
| 7.1b     | User selects Forgot PIN                                                                                                                                                                                                                 | 10                                                                                                               |
| **8**    | **WHEN PIN INVALID, FINAL ROUND THIRD TIME**                                                                                                                                                                                            |                                                                                                                  |
| **8.1**  | **System displays prompt 'Wrong PIN, retry'**<ul><li>Message: wrong PIN, you have 1 more attempt. Then your app will be blocked permanently.</li><li>Actions: Close, Forgot PIN</li></ul>                                               |                                                                                                                  |
| 8.1a     | User selects Close                                                                                                                                                                                                                      | Result: Retry                                                                                                    |
| 8.1b     | User selects Forgot PIN                                                                                                                                                                                                                 | 10                                                                                                               |
| **9**    | **WHEN APP PERMANTLY BLOCKED (FINAL ROUND, FOURTH FAILED ATTEMPT)**                                                                                                                                                                     |                                                                                                                  |
| **9.1**  | **System displays screen 'App is Blocked'**<ul><li>Message: You have made too many failed PIN entries. If you want to use the wallet app you have to delete data and setup wallet again.</li><li>Actions: Delete Wallet, Help</li></ul> |                                                                                                                  |
| 9.1a     | User selects Delete Wallet                                                                                                                                                                                                              | Go to: [UC9.4 Wipe all app data](../use-cases/UC9.4_WipeAllAppData.md)                                           |
| 9.1b     | User selects Help                                                                                                                                                                                                                       | Show placeholder 'under construction'                                                                            |
| **10**   | **RECOVER FROM FORGOTTEN PIN**                                                                                                                                                                                                          |                                                                                                                  |
| **10.1** | **System displays screen 'Forgot PIN'**<ul><li>Forgot PIN?</li><li>Actions: Create a new PIN, Back</li></ul>                                                                                                                            |                                                                                                                  |
| 10.1a    | User selects Create a new PIN                                                                                                                                                                                                           | Go to: [UC2.3.2 Recover PIN](../use-cases/UC2.3.2_RecoverPIN.md)                                                 |
| 10.1b    | User selects Back                                                                                                                                                                                                                       | Result: Back                                                                                                     |
| **11**   | **WHEN PID ISSUANCE FAILS (FIRST ROUND, FOURTH FAILED ATTEMPT)**                                                                                                                                                                        |                                                                                                                  |
| **11.1** | **System displays screen 'Setup failed'**<ul><li>>Message: You have made too many failed PIN entries. Setup new PIN and try again</li><li>Actions: Try again</li></ul>                                                                  |                                                                                                                  |
| 11.1a    | User selects Try again                                                                                                                                                                                                                  | Go to: [UC2.1 Set up a remote PIN and biometric unlock](../use-cases/UC2.1_SetupRemotePinAndBiometricsUnlock.md) |