react-native-device-crypto
Advanced tools
Cryptographic operations inside the secure hardware for React Native
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, keychain and 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-keychain or npm i react-native-keychain
1 a. If React Native version <= 0.59: react-native link react-native-keychain 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.
| Access Level | Description |
|---|---|
| Always | unlockedDeviceRequired is false. This overrides other parameters. (aka unrestricted key) |
| Unlocked device | unlockedDeviceRequired is true. (aka unrestricted key) |
| Biometry | authenticationRequired is true. (unlockedDeviceRequired is true defacto.) (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
| Access Level | Description |
|---|---|
| Always | unlockedDeviceRequired is false. This overrides other parameters. (aka unrestricted key) |
| Unlocked device | unlockedDeviceRequired is true. (aka unrestricted key) |
| Biometry | authenticationRequired is true. (unlockedDeviceRequired is true defacto.) (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 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
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
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.