Documentation Aerogear API documentation & specifications.

AeroGear Security OTP Specification

AeroGear Security OTP Specification

This is a initial proposal on having a two factor authentication layer on mobile applications.

Scenarios - v0.0.1

Random Generation: secrets are generated randomly at provisioning stage and must be stored immediately and kept secure during their life cycle. - RFC 4226


After installing the application, the user will be able to create your own account. Before the HTTP request is sent to the server, mobile application applies a key derivation function which generates the secret shared key (SHA-1, SHA-256 or SHA-512) based on RFC 2898:

Secret shared key: user data + time + interval


  • user data: login, password

  • time: current time (UTC)

  • interval: represents the time in seconds, since the elapsed time.

The secret key will be stored on device for the calculation of a one-time password value. When the first request comes to the server it runs the same algorithm to generate the secret, store it and validate the OTP.



After a user has entered the login and password, mobile application will retrieve the secret from storage for the OTP calculation and send it back to the server. The server will retrieve the secret locally and validate the OTP.



Deterministic Generation: secrets are derived from a master seed, both at provisioning and verification stages and generated on-the-fly whenever it is required. - RFC 4226


This scenarios aims to describe a common workflow for JavaScript aplications and can also be provided to native clients


TOTP as a password-based key derivation (password + OTP)





Shared Secret key expiration


Common questions

  • How it will affect Android, iOS and JavaScript projects?

These libraries are optional and not a requirement.