# Understanding Mosaic's PKI architecture

Mosaic's Public Key Infrastructure (PKI) architecture ensures secure authentication, data integrity, and confidentiality in communications between Mosaic server and mobile SDKs. It uses cryptographic key pairs—public and private keys—to encrypt data, verify identities, and establish trust between user's devices and Mosaic by:

- Assuring device identity when communicating with Mosaic
- Assuring authenticator to device identity when using authenticators that utilize data stored on the local device or device-specific authentication


Mosaic leverages both device keys and authenticator keys to sign authentication and assertion messages. Using this model, Mosaic allows disabling or revoking a device or its authenticators on the server side when needed.

## PKI for devices: Device binding

To validate a device, Mosaic leverages a unique private/public key pair, issued as a result of device crypto-binding. These are RSA 2048-bit keys generated via standard OS tools for iOS and Android, or [Web Crypto](https://www.w3.org/TR/WebCryptoAPI/) for browsers. For example, Apple provides a specific API call `SecKeyGeneratePair()`, which creates a public and private key.

- Device binding occurs when the mobile app executes the [Register device](/guides/orchestration/journeys/register_device) journey step.
- The **public key** is exported to Mosaic, where it is saved in the Mosaic database as part of the actual device record. It enables message validation and non-repudiation during communication with the device.
- The **private key** is stored on the device and never leaves it, leveraging the mobile OS's API capabilities, including **Keychain (Apple devices)**, **Keystore (Android devices)**, and **IndexedDB (Web browsers)**. The mobile OS APIs will use the most secure storage available based on the device and key type. For browsers, [Web Crypto](https://www.w3.org/TR/WebCryptoAPI/) is used for key management and signing operations, ensuring cryptographic security in web environments.


- After initial device binding, a journey can validate a device by invoking the [Known Device Status](/guides/orchestration/journeys/validate_device) step, which sends a challenge to the client side to sign it with the private key.


See also: [Device management](/guides/user/how_devices_work), [Manage devices](/guides/user/manage_devices), [Secure device identity](/guides/risk/secure_device_identity).

```mermaid
sequenceDiagram
    autonumber
    participant User
    participant MobileApp
    participant IDO as Mosaic SDK / OS
    participant M as Mosaic Server

    User->>MobileApp: Launch mobile app
    MobileApp->>IDO: Registration journey
    IDO->>IDO: Collect device data
    IDO->>IDO: Check for device ID <br /> & derive device ID from Keychain/Keystore
    IDO->>IDO: Generate private/public key pair (RSA 2048)
    IDO->>M: Request signing <br /> with device private key
    M->>M: Generate device key ID <br />& store public key along with device key ID
    MobileApp->>IDO: Login journey
    IDO->>IDO: Known device? <br />&sign challenge
    IDO->>M: Validate device
    M->>IDO: Device is known
    MobileApp->>IDO: Authenticate
    IDO->>M:Validate
    M->>IDO: Complete journey with JWT Token
    IDO->>MobileApp: Grant access
    MobileApp->>User: Done
```

## PKI for authenticators

Authenticators utilize the OS ability to protect private keys with biometrics (fingerprint or Face ID). A private/public key pair is generated for the given authenticator, and requires the user to present their biometrics during registration and authentication. This ties the user biometrics into the PKI process.

- OS APIs on Android and iOS generate a key pair.
- The public key is exported to Mosaic.
- The private key is stored securely by the OS, and protected by requiring the user to present their biometrics.


```mermaid
sequenceDiagram
    autonumber
    participant User
    participant MobileApp
    participant IDO as Mosaic SDK / OS
    participant M as Mosaic Server

    User->>MobileApp: Launch mobile app
    MobileApp->>IDO: Registration journey
    IDO->>M: Start registration journey
    M->>IDO: Request registration
    User->>IDO: Present biometrics
    IDO->>IDO: Generate private/public<br>key pair (RSA 2048)
    IDO->>M: Send public key for registration
    M->>M: Store public key<br>as biometric authenticator
    M->>IDO: Journey done

    MobileApp->>IDO: Login journey
    IDO->>M: Start Login journey
    M->>IDO: Send challenge for<br>biometric authentication
    User->>IDO: Present biometrics
    IDO->>IDO: Sign challenge with private key
    IDO->>M:Send signed challenge
    M ->>M: validate with public key
    M->>IDO: Complete journey with JWT Token
    IDO->>MobileApp: Grant access
    MobileApp->>User: Done
```

See also: [Register mobile biometrics](/guides/orchestration/journeys/register_mobile_biometrics) journey step and [Mobile biometrics authentication](/guides/orchestration/journeys/authenticate_mobile_biometrics) journey step.

## JWT

Upon successful authentication, Mosaic issues a JWT ([Json Web Token](https://jwt.io/introduction)). The token adheres to standard JWT specification and uses a JSON structure that is used for validation and preventing data tampering. The token includes information such as the username, application name, expiration date, and other parameters being passed by the application on the authentication request.

See also: [Token reference](/openapi/token_reference), [Validate tokens](/guides/user/validate_tokens).