PasscodeHelper is a Gaia helper library for modifying and checking the Firefox OS lockscreen passcode (i.e., pin) from within Gaia, performing functions such as checking whether an entered passcode is correct, and changing the code. This article documents how PasscodeHelper works.
High level overview
To fullfill the needs of the different apps (Lockscreen, Settings, FindMyDevice) that interact with the lockscreen passcode, and avoid reinventing the wheel for each one, we created the PasscodeHelper API. It is an abstraction on top of the Settings API, therefore it is an internal API that may only be used in highly-privileged Gaia code. It uses the Web Crypto API to encrypt the user's passcode, avoiding storing it in an unencrypted form.
Passcode security is enforced in two specific ways:
- We are using PBKDF2 to derive a cryptographic key from each user's password. Its input variables allows an iteration count that serves as a slowdown against brute force attacks.
- We customize the outcome of the algorithm with so-called salt, which is randomized for each new passcode. This protects against an attacker building a dictionary of hashes for the most common passwords.
The security parameters of PBKDF2 are in the source code but also stored in the settings. Storing them in the settings allows us to reproduce the algorithm that was used to compute the currently stored passcode. The parameters in the source code can be updated in the future to provide a better security margin, without any kind of compatibility problems.
PasscodeHelper API specifics
PasscodeHelper is a stateless object that has two externally exposed methods, checkPasscode() and setPasscode().
PasscodeHelper.setPasscode(aString) → Promise<TypedArray>
The setPasscode() function sets a new passcode, which can by any kind of string. The caller is not required to make any checks on the return value of the promise, but may check that the return value is truthy.
PasscodeHelper.checkPasscode(aString) → Promise<boolean>
The checkPasscode() function checks whether a user supplied passcode is indeed the correct passcode. It accepts a string (the passcode to check) and returns a Promise that resolves to a boolean indicating whether the supplied passcode is correct (true) or not (false.)