react-native-device-crypto
Advanced tools
Readme
React Native Device Crypto provides functionality to use hardware-based secure encryption. To further protect sensitive data within your app, you can incorporate cryptography into your biometric authentication workflow. After the user authenticates successfully using a biometric prompt, your app can perform a cryptographic operation. For example, if you authenticate, your app can then perform encryption, decryption and signing.
Also, the module allows you to
Extremely secure iOS encryption and decryption via secure enclave, elliptic curves. Very secure Android encryption and decryption via Android KeyStore.
This package requires a compiled SDK version of 30 (Android 11.0) or higher The Android side uses the android.security.keystore API and requires a minimum SDK version of 23, due to availability of the hardware-backed security.
This package requires an iOS target SDK version of iOS 11 or higher
Ensure that you have the NSFaceIDUsageDescription entry set in your react native iOS project, or Face ID will not work properly. This description will be presented to the user the first time a biometrics action is taken, and the user will be asked if they want to allow the app to use Face ID. If the user declines the usage of face id for the app, the getBiometryType function will indicate biometrics is unavailable until the face id permission is specifically allowed for the app by the user.
Run yarn add react-native-device-crypto or npm i react-native-device-crypto
1 a. If React Native version <= 0.59: react-native link react-native-device-crypto and check MainApplication.java to verify the package was added.
Run pod install in ios/ directory to install iOS dependencies.
If you want to support FaceID, add a NSFaceIDUsageDescription entry in your Info.plist.
Re-build your Android and iOS projects.
Please see Example Project for fully working project.
When a user enrolls in biometrics, a key pair is generated. The private key is stored securely on the device and the public key is sent to a server for registration. When the user wishes to authenticate, the user is prompted for biometrics, which unlocks the securely stored private key. Then a cryptographic signature is generated and sent to the server for verification. The server then verifies the signature. If the verification was successful, the server returns an appropriate response and authorizes the user.
async getOrCreateAsymmetricKey(alias: string, options: KeyCreationParams): Promise<string>
Creates an asymmetric key in the secure hardware with given access parameters. Returns Public Key if successfull.
interface KeyCreationParams {
accessLevel: AccessLevel;
invalidateOnNewBiometry?: boolean;
}
invalidateOnNewBiometry : The key has been invalidated when the user removes biometry or enrolls new biometry if this is true. (This is irreversable)
| Access Level | Description |
|---|---|
| Always | The key is always accessible even if the device locked. (aka unrestricted key) |
| Unlocked device | The key is accessible when the device has been unlocked. (aka unrestricted key) |
| Authentication Required | The key is accessible when the user authenticate their selves with biometry. (aka restricted key) |
Cryptography algorithms
256-bit ECC Keys for Suite-B EC (aka secp256k1) EC (Elliptic Curve) keypair on iOS
NIST P-256 (aka secp256r1 aka prime256v1) EC (Elliptic Curve) keypair on Android
async getOrCreateSymmetricKey(alias: string, options: KeyCreationParams): Promise<boolean>
Creates a symmetric key in the secure hardware with given access parameters. Returns true if successfull
interface KeyCreationParams {
accessLevel: AccessLevel;
invalidateOnNewBiometry?: boolean;
}
invalidateOnNewBiometry : The key has been invalidated when the user removes biometry or enrolls new biometry if this is true. (This is irreversable)
| Access Level | Description |
|---|---|
| Always | The key is always accessible even if the device locked. (aka unrestricted key) |
| Unlocked device | The key is accessible when the device has been unlocked. (aka unrestricted key) |
| Authentication Required | The key is accessible when the user authenticate their selves with biometry. (aka restricted key) |
Cryptography algorithms
AES256
Note for IOS :
We don’t explicitly create the symmetric key. Instead, we call native SecKeyCreateEncryptedData to create a symmetric key for you. This function creates the symmetric key, uses it to encrypt your data, and then encrypts the key itself with the public key (We create in background to provide it later on encrypt/decrypt operations). It then packages all of this data together and returns it to you. You then transmit it to a receiver, who uses the corresponding private key in a call to native SecKeyCreateDecryptedData to reverse the operation.
That is why encrypt method returns IV as NotRequired on IOS.
async isKeyExists(alias: string, keyType: KeyTypes): Promise<boolean>
Checks the key is exist in secure hardware or not.
async getPublicKey(alias: string): Promise<string>
Gets PEM formatted public key.
async deleteKey(alias: string): Promise<boolean>
Deletes the key from secure hardware. (This is irreversable.)
async sign(alias: string, plainText: string, options: BiometryParams): Promise<string>
Signs the given string with private key and returns Base64 encoded signature.
unlockedDeviceRequired and authenticationRequired should be true when creating the key in this case), the user must authenticate their biometric credentials each time before your app accesses the key. async encrypt(alias: string, plainText: string, options: BiometryParams): Promise<EncryptionResult>
Encrypts the given string with the secret key and returns Base64 encoded encrypted text and IV code.
iv is always NotRequired. Please see the note on getOrCreateSymmetricKeyunlockedDeviceRequired and authenticationRequired should be true when creating the key in this case), the user must authenticate their biometric credentials each time before your app accesses the key.async decrypt(alias: string, plainText: string, iv: string, options: BiometryParams): Promise<string>
Decrypts the given Base64 encoded encrypted text with IV and the secret key.
iv ignored on IOS and cannot be null. Please see the note on getOrCreateSymmetricKeyunlockedDeviceRequired and authenticationRequired should be true when creating the key in this case), the user must authenticate their biometric credentials each time before your app accesses the key.async isBiometryEnrolled(): Promise<boolean>
Checks if the user can authenticate with biometrics. This requires at least one biometric sensor to be present, enrolled, and available on the device.
async deviceSecurityLevel(): Promise<SecurityLevel>
Checks the devices security level.
| Return Value | Description |
|---|---|
| NOT_PROTECTED | The device has no protection. |
| PIN_OR_PATTERN | The device is secured by pin or password. |
| BIOMETRY | The device is secured by biometric authentication. |
async getBiometryType(): Promise<BiometryType>
Gets the biometric scanner type if the device has biometric hardware.
| Return Value | Platform | Description |
|---|---|---|
| NONE | All | The device has no biometric hardware or could not determined. |
| TOUCH | All | The biometric hardware detects fingerprint |
| FACE | All | The biometric hardware performs face authentication |
| IRIS | Android only | The biometric hardware performs iris authentication |
async authenticateWithBiometry(options: BiometryParams): Promise<boolean>
One method of protecting sensitive information or premium content within your app is to request biometric authentication, such as using face recognition or fingerprint recognition. To display a system prompt that requests the user to authenticate using biometric credentials. After the user authenticates, you can check whether the user authenticated or not.
See the contributing guide to learn how to contribute to the repository and the development workflow.
ISC
FAQs
Cryptographic operations inside the secure hardware for React Native
The npm package react-native-device-crypto receives a total of 352 weekly downloads. As such, react-native-device-crypto popularity was classified as not popular.
We found that react-native-device-crypto demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
NIST's new AI Risk Management Framework aims to enhance the security and reliability of generative AI systems and address the unique challenges of malicious AI exploits.
Security News
This episode of the Risky Biz podcast discusses how the rise of small open source packages and the shift towards individual maintainers makes the ecosystem more vulnerable to supply chain attacks.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.