pin_validation_flow.md

Pin validation

Pin validation is comprised of two steps, first of the local pin validation (when configuring the wallet) to prevent users from selecting a trivial pin. Secondly the remote pin validation, where the user provided pin is compared with the previously registerd pin by the wallet_provider.

Local pin validation

This diagram illustrates the local validation that happens when the user configures a new pin, to make sure the user does not select a trivial pin like 000000.

Loading

sequenceDiagram
    %% Force ordering by explicitly setting up participants
    actor user
    participant platform
    participant wallet_app
    participant wallet_core
    participant wallet_provider
    title Local Pin Validation [3.1]

    user->>wallet_app: enter new pin
    activate user
        wallet_app->>wallet_core: validate pin
        alt pin invalid
            wallet_core-->>wallet_app: pin error
            Note over wallet_core,wallet_app: TooFewUniqueDigits,<br/>SequentialDigits, Other
            wallet_app->>user: render error & request new pin
        else pin valid
            wallet_core-->>wallet_app: pin success
            wallet_app->>user: render success
        end
    deactivate user

Remote pin validation

This diagram illustrates the remote validation, this occurs when the user has already configured her wallet and is e.g. trying to log in to the app.

Loading

sequenceDiagram
    %% Force ordering by explicitly setting up participants
    actor user
    participant platform
    participant wallet_app
    participant wallet_core
    participant wallet_provider
    title Remote Pin Validation [3.2]

    user->>wallet_app: enter existing pin
    activate user
        wallet_app->>wallet_core: unlock(pin)
        wallet_core->>wallet_core: getRegistration()
        alt no registration
            wallet_core-->>wallet_app: NotRegistered
            wallet_app->>user: show not registered
        end
        par sign challenge request
            wallet_core->>wallet_core: createChallenge(incrementAndStore(sequenceNumber))
            wallet_core->>platform: sign(challengeRequest)
            platform->>platform: signWithHwKey(challengeRequest)
            platform-->>wallet_core: signedChallengeRequest
        end
        wallet_core->>wallet_provider: requestChallenge(signedChallengeRequest)
        opt server error
        wallet_provider-->>wallet_core: server error
            wallet_core-->>wallet_app: error
            wallet_app->>user: show server error
        end
        wallet_provider-->>wallet_core: challenge
        par sign instruction
            wallet_core->>wallet_core: signWithPinKey(pin, challenge, incrementAndStore(sequenceNumber))
            wallet_core->>platform: sign(pinSignedInstruction)
            platform->>platform: signWithHwKey(pinSignedInstruction)
            platform-->>wallet_core: doubleSignedInstruction
        end
        wallet_core->>wallet_provider: instruction(doubleSignedInstruction)
        opt server error
            Note over wallet_provider,user: same as server error above
        end
        wallet_provider-->>wallet_core: result
        alt error
            wallet_core-->>wallet_app: pin error
            Note over wallet_core,wallet_app: IncorrectPin,<br/>Timeout, Blocked
            wallet_app->>user: render error & request new pin
        else success
            wallet_core-->>wallet_app: success
            wallet_app->>user: render unlocked
        end
    deactivate user