Mobile Libraries

iOS (Swift) and Android (Java) libraries are designed to extend the functionality of existing applications with advanced authorization and authentication capabilities. Securing the Mobile Application and, by extension, the use of the Mobile Libraries is a shared responsibility between Privakey and the developers leveraging the libraries.

The primary functions of the Mobile Libraries include:

  1. Generation and maintenance of asymmetric key-pairs

  2. Interaction with the Privakey CX Auth Service, including:

    1. Processing challenge responses

    2. Getting requests and request details

    3. Managing device details

Application developers will need to implement handlers for Privakey CX Auth Service originated notifications.

Account Binding

Account Binding is the process that governs the Privakey Enablement of a user device. This binding is protected by a series of controls.

Simple Binding

A Request Origin Server must initiate the Bind process with the CX Auth Service. This precludes rogue implementations of the Privakey Library from attempting to Bind to a deployed Auth Service.

The Request Origin server then makes an authenticated Bind Account call to the Privakey CX Auth service. The Bind Account call creates and returns a Session Token to the Request Origin Server which must return this token to the App. This Token is used to authenticate the App to the Auth Service. The Privakey CX Mobile Library completes the binding process by generating several RSA-2048 key-pairs to govern device authentication to the Auth Service and to enable strong user challenge responses (for more information, see Cryptographic Practices below).


When to bind a user account

Privakey does not dictate when an implementing service should bind a user account. However, it is important to note that the level of assurance associated with a Privakey-based Authorization or Authentication is only as strong as the level of assurance a service had when the invoked account binding.

Implementers should take care to only enable Privakey when the session level of assurance matches the intended level of assurance for Privakey-based authorizations.

Identity Provider Binding

An App Space configured to leverage an Identity Provider as the system of Authority for users allows the Mobile Apps to initiate the bind process. Once the bind endpoint is called, the Auth Service will look up the location of the Identity Provider and redirect the user to the authentication endpoint. There, they can input their credentials and start the authentication process. The Identity Provider will return an authentication credential which the Mobile App will send to the Auth Service. The Auth Service will use this to complete the authentication on the user's behalf and obtain the user's information from the Identity Provider. Once the authentication is successful, the Auth Service will associate the user to that device, completing the bind process.

Notes on the Security Principles of the Privakey Library

Cryptographic Practices

A key function of the Privakey CX Mobile Library is the generation, maintenance and use of asymmetric key-pairs.

In iOS, the key-pairs are generated by the framework's Keychain in an app-specific context and accessed using standard iOS protocols. In Android, the key-pairs are generated by the Android framework in the device's secure element. These keys are rotated, as often as every time they're used, based on a configuration value in the Privakey CX Auth Service.

Access Key-Pair

During account binding, the Privakey CX Mobile Library generates an Access Key-Pair that is leveraged in all subsequent interactions between the Privakey CX Mobile Library and the Privakey CX Auth Service. This key is used to authenticate a bound application instance to the Privakey CX Auth Service.

Authorization / Authentication Key-Pairs

Each application has up to two Authorization / Authentication RSA-2048 Key-Pairs. One key-pair is leveraged for biometric-based activities and the other for PIN-based activities.

Error Handling

Function calls return both success and error responses. These interfaces are documented in implementation documentation.


The libraries are not designed to output logs independent of the host applications logging capabilities. We recommend logging responses from the CX Library functions as needed.

Data Protection

Data requirements for the Mobile Libraries are limited to the Key material discussed in Cryptographic Practices and device-specific meta-data, including: a hash of the PIN (Android only), Account identifying information (Privakey ID, Device GUID, notification ID), key references, and device status. As this is stored in a namespace-specific data container, access is limited.

Communication Security

Privakey CX Auth Service should use TLS for protecting connections to Request origins and the Privakey CX Mobile Libraries. We recommend you set this up during deployment.


Privakey CX Mobile Library configuration values are limited to:

  • The URL of the auth service

  • Network related timeouts

These values are configured in the frameworks respective codebase and are compiled prior to deployment.