{"id":18783573,"url":"https://github.com/sticknet/react-native-keychain","last_synced_at":"2025-10-19T12:21:24.141Z","repository":{"id":139605215,"uuid":"501287856","full_name":"sticknet/react-native-keychain","owner":"sticknet","description":null,"archived":false,"fork":false,"pushed_at":"2022-06-08T14:32:59.000Z","size":248,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2024-12-29T11:44:56.370Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sticknet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-08T14:32:42.000Z","updated_at":"2022-06-08T14:33:05.000Z","dependencies_parsed_at":"2024-07-09T17:15:58.343Z","dependency_job_id":null,"html_url":"https://github.com/sticknet/react-native-keychain","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sticknet%2Freact-native-keychain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sticknet%2Freact-native-keychain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sticknet%2Freact-native-keychain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sticknet%2Freact-native-keychain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sticknet","download_url":"https://codeload.github.com/sticknet/react-native-keychain/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239699579,"owners_count":19682574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T20:39:47.127Z","updated_at":"2025-10-19T12:21:24.053Z","avatar_url":"https://github.com/sticknet.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003ereact-native-keychain\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cimg\n    src=\"https://user-images.githubusercontent.com/378279/36642269-6195b10c-1a3d-11e8-9e1b-37a3d1bcf7b3.png\"\n    align=\"center\" width=\"150\" height=\"201\" alt=\"\"\n  /\u003e\n\u003c/p\u003e\n\n[![Travis](https://img.shields.io/travis/oblador/react-native-keychain.svg)](https://travis-ci.org/oblador/react-native-keychain) [![npm](https://img.shields.io/npm/v/react-native-keychain.svg)](https://npmjs.com/package/react-native-keychain) [![npm](https://img.shields.io/npm/dm/react-native-keychain.svg)](https://npmjs.com/package/react-native-keychain)\n\n# Keychain/Keystore Access for React Native\n\n- [Keychain/Keystore Access for React Native](#keychainkeystore-access-for-react-native)\n  - [Installation](#installation)\n  - [Usage](#usage)\n  - [API](#api)\n    - [`setGenericPassword(username, password, [{ accessControl, accessible, accessGroup, service, securityLevel }])`](#setgenericpasswordusername-password--accesscontrol-accessible-accessgroup-service-securitylevel-)\n    - [`getGenericPassword([{ authenticationPrompt, service, accessControl }])`](#getgenericpassword-authenticationprompt-service-accesscontrol-)\n    - [`resetGenericPassword([{ service }])`](#resetgenericpassword-service-)\n    - [`getAllGenericPasswordServices()`](#getallgenericpasswordservices)\n    - [`setInternetCredentials(server, username, password, [{ accessControl, accessible, accessGroup, securityLevel }])`](#setinternetcredentialsserver-username-password--accesscontrol-accessible-accessgroup-securitylevel-)\n    - [`hasInternetCredentials(server)`](#hasinternetcredentialsserver)\n    - [`getInternetCredentials(server, [{ authenticationPrompt }])`](#getinternetcredentialsserver--authenticationprompt-)\n    - [`resetInternetCredentials(server)`](#resetinternetcredentialsserver)\n    - [`requestSharedWebCredentials()` (iOS only)](#requestsharedwebcredentials-ios-only)\n    - [`setSharedWebCredentials(server, username, password)` (iOS only)](#setsharedwebcredentialsserver-username-password-ios-only)\n    - [`canImplyAuthentication([{ authenticationType }])` (iOS only)](#canimplyauthentication-authenticationtype--ios-only)\n    - [`getSupportedBiometryType()`](#getsupportedbiometrytype)\n    - [`getSecurityLevel([{ accessControl }])` (Android only)](#getsecuritylevel-accesscontrol--android-only)\n    - [Options](#options)\n      - [Data Structure Properties/Fields](#data-structure-propertiesfields)\n        - [`authenticationPrompt` Properties](#authenticationprompt-properties)\n      - [`Keychain.ACCESS_CONTROL` enum](#keychainaccess_control-enum)\n      - [`Keychain.ACCESSIBLE` enum](#keychainaccessible-enum)\n      - [`Keychain.AUTHENTICATION_TYPE` enum](#keychainauthentication_type-enum)\n      - [`Keychain.BIOMETRY_TYPE` enum](#keychainbiometry_type-enum)\n      - [`Keychain.SECURITY_LEVEL` enum (Android only)](#keychainsecurity_level-enum-android-only)\n      - [`Keychain.STORAGE_TYPE` enum (Android only)](#keychainstorage_type-enum-android-only)\n      - [`Keychain.SECURITY_RULES` enum (Android only)](#keychainsecurity_rules-enum-android-only)\n  - [Important Behavior](#important-behavior)\n    - [Rule 1: Automatic Security Level Upgrade](#rule-1-automatic-security-level-upgrade)\n  - [Manual Installation](#manual-installation)\n    - [iOS](#ios)\n      - [Option: Manually](#option-manually)\n      - [Option: With CocoaPods](#option-with-cocoapods)\n      - [Enable `Keychain Sharing` entitlement for iOS 10+](#enable-keychain-sharing-entitlement-for-ios-10)\n    - [Android](#android)\n      - [Option: Manually](#option-manually-1)\n      - [Proguard Rules](#proguard-rules)\n  - [Unit Testing with Jest](#unit-testing-with-jest)\n    - [Using a Jest `__mocks__` Directory](#using-a-jest-__mocks__-directory)\n    - [Using a Jest Setup File](#using-a-jest-setup-file)\n  - [Notes](#notes)\n    - [Android Notes](#android-notes)\n      - [Configuring the Android-specific behavior](#configuring-the-android-specific-behavior)\n    - [iOS Notes](#ios-notes)\n    - [macOS Catalyst](#macos-catalyst)\n    - [Security](#security)\n  - [Maintainers](#maintainers)\n  - [For Developers / Contributors](#for-developers--contributors)\n  - [License](#license)\n\n## Installation\n\n1. Run `yarn add react-native-keychain`\n\n   1 a. **Only for React Native \u003c= 0.59**: `$ react-native link react-native-keychain` and check `MainApplication.java` to verify the package was added. See manual installation below if you have issues with `react-native link`.\n\n2. Run `pod install` in `ios/` directory to install iOS dependencies.\n3. If you want to support FaceID, add a `NSFaceIDUsageDescription` entry in your `Info.plist`.\n4. Re-build your Android and iOS projects.\n\n## Usage\n\n```js\nimport * as Keychain from 'react-native-keychain';\n\nasync () =\u003e {\n  const username = 'zuck';\n  const password = 'poniesRgr8';\n\n  // Store the credentials\n  await Keychain.setGenericPassword(username, password);\n\n  try {\n    // Retrieve the credentials\n    const credentials = await Keychain.getGenericPassword();\n    if (credentials) {\n      console.log(\n        'Credentials successfully loaded for user ' + credentials.username\n      );\n    } else {\n      console.log('No credentials stored');\n    }\n  } catch (error) {\n    console.log(\"Keychain couldn't be accessed!\", error);\n  }\n  await Keychain.resetGenericPassword();\n};\n```\n\nSee `KeychainExample` for fully working project example.\n\nBoth `setGenericPassword` and `setInternetCredentials` are limited to strings only, so if you need to store objects etc, please use `JSON.stringify`/`JSON.parse` when you store/access it.\n\n## API\n\n### `setGenericPassword(username, password, [{ accessControl, accessible, accessGroup, service, securityLevel }])`\n\nWill store the username/password combination in the secure storage. Resolves to `{service, storage}` or rejects in case of an error. `storage` - is a name of used internal cipher for saving secret; `service` - name used for storing secret in internal storage (empty string resolved to valid default name).\n\n### `getGenericPassword([{ authenticationPrompt, service, accessControl }])`\n\nWill retrieve the username/password combination from the secure storage. Resolves to `{ username, password, service, storage }` if an entry exists or `false` if it doesn't. It will reject only if an unexpected error is encountered like lacking entitlements or permission.\n\n### `resetGenericPassword([{ service }])`\n\nWill remove the username/password combination from the secure storage. Resolves to `true` in case of success.\n\n### `getAllGenericPasswordServices()`\n\nWill retrieve all known service names for which a generic password has been stored (e.g., `setGenericPassword`).\n\n_Note_: on iOS this will actully read the encrypted entries, so it will trigger an authentication UI if you have encrypted any entries with password/biometry.\n\n### `setInternetCredentials(server, username, password, [{ accessControl, accessible, accessGroup, securityLevel }])`\n\nWill store the server/username/password combination in the secure storage. Resolves to `{ username, password, service, storage }`;\n\n### `hasInternetCredentials(server)`\n\nWill check if the username/password combination for server is available in the secure storage. Resolves to `true` if an entry exists or `false` if it doesn't.\n\n### `getInternetCredentials(server, [{ authenticationPrompt }])`\n\nWill retrieve the server/username/password combination from the secure storage. Resolves to `{ username, password }` if an entry exists or `false` if it doesn't. It will reject only if an unexpected error is encountered like lacking entitlements or permission.\n\n### `resetInternetCredentials(server)`\n\nWill remove the server/username/password combination from the secure storage.\n\n### `requestSharedWebCredentials()` (iOS only)\n\nAsks the user for a shared web credential. Requires additional setup both in the app and server side, see [Apple documentation](https://developer.apple.com/documentation/security/shared_web_credentials). Resolves to `{ server, username, password }` if approved and `false` if denied and throws an error if not supported on platform or there's no shared credentials.\n\n### `setSharedWebCredentials(server, username, password)` (iOS only)\n\nSets a shared web credential. Resolves to `true` when successful.\n\n### `canImplyAuthentication([{ authenticationType }])` (iOS only)\n\nInquire if the type of local authentication policy is supported on this device with the device settings the user chose. Should be used in combination with `accessControl` option in the setter functions. Resolves to `true` if supported.\n\n### `getSupportedBiometryType()`\n\n**On iOS:** Get what type of hardware biometry support the device can use for biometric encryption. Resolves to a `Keychain.BIOMETRY_TYPE` value when supported and enrolled, otherwise `null`.\n\n**On Android:** Get what type of Class 3 (strong) biometry support the device has. Resolves to a `Keychain.BIOMETRY_TYPE` value when supported, otherwise `null`. In most devices this will return `FINGERPRINT` (except for Pixel 4 or similar where fingerprint sensor is not present).\n\n\u003e This method returns `null`, if the device haven't enrolled into fingerprint/FaceId. Even though it has hardware for it.\n\n### `getSecurityLevel([{ accessControl }])` (Android only)\n\nGet security level that is supported on the current device with the current OS. Resolves to `Keychain.SECURITY_LEVEL` enum value.\n\n### Options\n\n#### Data Structure Properties/Fields\n\n| Key                        | Platform     | Description                                                                                      | Default                                                                   |\n| -------------------------- | ------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |\n| **`accessControl`**        | All          | This dictates how a keychain item may be used, see possible values in `Keychain.ACCESS_CONTROL`. | _None_                                                                    |\n| **`accessible`**           | iOS only     | This dictates when a keychain item is accessible, see possible values in `Keychain.ACCESSIBLE`.  | _`Keychain.ACCESSIBLE.WHEN_UNLOCKED`_                                     |\n| **`accessGroup`**          | iOS only     | In which App Group to share the keychain. Requires additional setup with entitlements.           | _None_                                                                    |\n| **`authenticationPrompt`** | All          | What to prompt the user when unlocking the keychain with biometry or device password.            | See [`authenticationPrompt` Properties](#authenticationprompt-properties) |\n| **`authenticationType`**   | iOS only     | Policies specifying which forms of authentication are acceptable.                                | `Keychain.AUTHENTICATION_TYPE.DEVICE_PASSCODE_OR_BIOMETRICS`              |\n| **`service`**              | All          | Reverse domain name qualifier for the service associated with password.                          | _App bundle ID_                                                           |\n| **`storage`**              | Android only | Force specific cipher storage usage during saving the password                                   | Select best available storage                                             |\n| **`rules`**                | Android only | Force following to a specific security rules                                                     | `Keychain.RULES.AUTOMATIC_UPGRADE`                                        |\n\n##### `authenticationPrompt` Properties\n\n| Key               | Platform     | Description                                                                                | Default                           |\n| ----------------- | ------------ | ------------------------------------------------------------------------------------------ | --------------------------------- |\n| **`title`**       | All          | Title of the authentication prompt when requesting a stored secret.                        | `Authenticate to retrieve secret` |\n| **`subtitle`**    | Android only | Subtitle of the Android authentication prompt when requesting a stored secret.             | None. Optional                    |\n| **`description`** | Android only | Description of the Android authentication prompt when requesting a stored secret.          | None. Optional                    |\n| **`cancel`**      | Android only | Negative button text of the Android authentication prompt when requesting a stored secret. | `Cancel`                          |\n\n#### `Keychain.ACCESS_CONTROL` enum\n\n| Key                                           | Description                                                                            |\n| --------------------------------------------- | -------------------------------------------------------------------------------------- |\n| **`USER_PRESENCE`**                           | Constraint to access an item with either Touch ID or passcode.                         |\n| **`BIOMETRY_ANY`**                            | Constraint to access an item with Touch ID for any enrolled fingers.                   |\n| **`BIOMETRY_CURRENT_SET`**                    | Constraint to access an item with Touch ID for currently enrolled fingers.             |\n| **`DEVICE_PASSCODE`**                         | Constraint to access an item with a passcode.                                          |\n| **`APPLICATION_PASSWORD`**                    | Constraint to use an application-provided password for data encryption key generation. |\n| **`BIOMETRY_ANY_OR_DEVICE_PASSCODE`**         | Constraint to access an item with Touch ID for any enrolled fingers or passcode.       |\n| **`BIOMETRY_CURRENT_SET_OR_DEVICE_PASSCODE`** | Constraint to access an item with Touch ID for currently enrolled fingers or passcode. |\n\n\u003e Note #1: `BIOMETRY_ANY`, `BIOMETRY_CURRENT_SET`, `BIOMETRY_ANY_OR_DEVICE_PASSCODE`, `BIOMETRY_CURRENT_SET_OR_DEVICE_PASSCODE` - recognized by Android as a requirement for Biometric enabled storage (Till we got a better implementation);\n\u003e\n\u003e Note #2: For Android we support only two states: `None` (default) and `Fingerprint` (use only biometric protected storage); `Face` recognition fails with \"User not authenticated\" exception, see issue #318\n\nRefs:\n\n- \u003chttps://developer.apple.com/documentation/security/secaccesscontrolcreateflags?language=objc\u003e\n\n#### `Keychain.ACCESSIBLE` enum\n\n| Key                                       | Description                                                                                                                                                                            |\n| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **`WHEN_UNLOCKED`**                       | The data in the keychain item can be accessed only while the device is unlocked by the user.                                                                                           |\n| **`AFTER_FIRST_UNLOCK`**                  | The data in the keychain item cannot be accessed after a restart until the device has been unlocked once by the user.                                                                  |\n| **`ALWAYS`**                              | The data in the keychain item can always be accessed regardless of whether the device is locked.                                                                                       |\n| **`WHEN_PASSCODE_SET_THIS_DEVICE_ONLY`**  | The data in the keychain can only be accessed when the device is unlocked. Only available if a passcode is set on the device. Items with this attribute never migrate to a new device. |\n| **`WHEN_UNLOCKED_THIS_DEVICE_ONLY`**      | The data in the keychain item can be accessed only while the device is unlocked by the user. Items with this attribute do not migrate to a new device.                                 |\n| **`AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY`** | The data in the keychain item cannot be accessed after a restart until the device has been unlocked once by the user. Items with this attribute never migrate to a new device.         |\n| **`ALWAYS_THIS_DEVICE_ONLY`**             | The data in the keychain item can always be accessed regardless of whether the device is locked. Items with this attribute never migrate to a new device.                              |\n\nRefs:\n\n- \u003chttps://developer.apple.com/documentation/security/ksecattraccessiblewhenunlocked\u003e\n\n#### `Keychain.AUTHENTICATION_TYPE` enum\n\n| Key                                 | Description                                                                               |\n| ----------------------------------- | ----------------------------------------------------------------------------------------- |\n| **`DEVICE_PASSCODE_OR_BIOMETRICS`** | Device owner is going to be authenticated by biometry or device passcode.                 |\n| **`BIOMETRICS`**                    | Device owner is going to be authenticated using a biometric method (Touch ID or Face ID). |\n\nRefs:\n\n- \u003chttps://developer.apple.com/documentation/localauthentication/lapolicy\u003e\n\n#### `Keychain.BIOMETRY_TYPE` enum\n\n| Key               | Description                                                          |\n| ----------------- | -------------------------------------------------------------------- |\n| **`TOUCH_ID`**    | Device supports authentication with Touch ID. (iOS only)             |\n| **`FACE_ID`**     | Device supports authentication with Face ID. (iOS only)              |\n| **`FINGERPRINT`** | Device supports authentication with Fingerprint. (Android only)      |\n| **`FACE`**        | Device supports authentication with Face Recognition. (Android only) |\n| **`IRIS`**        | Device supports authentication with Iris Recognition. (Android only) |\n\nRefs:\n\n- \u003chttps://developer.apple.com/documentation/localauthentication/labiometrytype?language=objc\u003e\n\n#### `Keychain.SECURITY_LEVEL` enum (Android only)\n\nIf set, `securityLevel` parameter specifies minimum security level that the encryption key storage should guarantee for storing credentials to succeed.\n\n| Key               | Description                                                                                                                                                                                                                            |\n| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `ANY`             | no security guarantees needed (default value); Credentials can be stored in FB Secure Storage;                                                                                                                                         |\n| `SECURE_SOFTWARE` | requires for the key to be stored in the Android Keystore, separate from the encrypted data;                                                                                                                                           |\n| `SECURE_HARDWARE` | requires for the key to be stored on a secure hardware (Trusted Execution Environment or Secure Environment). Read [this article](https://developer.android.com/training/articles/keystore#ExtractionPrevention) for more information. |\n\n#### `Keychain.STORAGE_TYPE` enum (Android only)\n\n| Key   | Description                            |\n| ----- | -------------------------------------- |\n| `FB`  | Facebook compatibility cipher          |\n| `AES` | Encryptions without human interaction. |\n| `RSA` | Encryption with biometrics.            |\n\n#### `Keychain.SECURITY_RULES` enum (Android only)\n\n| Key                 | Description                                                                                                                                                 |\n| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `NONE`              | No rules. Be dummy, developer control everything                                                                                                            |\n| `AUTOMATIC_UPGRADE` | Upgrade secret to the best available storage as soon as it is available and user request secret extraction. Upgrade not applied till we request the secret. |\n\n## Important Behavior\n\n### Rule 1: Automatic Security Level Upgrade\n\nAs a rule library try to apply the best possible encryption and access method for storing secrets.\n\nWhat does it mean in practical use case?\n\n\u003e Scenario #1: User has a new phone and run on it an application with this module and store secret on device.\n\u003e Several days later user configures biometrics on the device and run application again. When the user will try to access the secret, the library will detect security enhancement and will upgrade secret storage to the best possible.\n\n---\n\nQ: What will happen if user disables/drops biometric usage?\n\nA: User will lose ability to extract secret from storage. On re-enable biometric access to the secret will be possible again.\n\n---\n\nQ: Is it possible to implement automatic downgrading?\n\nA: From security perspective any Automatic downgrading is treated as \"a loss of the trust\" point.\nDeveloper should implement own logic to allow downgrade and deal with \"security loss\". _(My recommendation - never do that!)_\n\n---\n\nQ: How to disable automatic upgrade?\n\nA: Do call `getGenericPassword({ ...otherProps, rules: \"none\" })` with extra property `rules` set to `none` string value.\n\n---\n\nQ: How to force a specific level of encryption during saving the secret?\n\nA: Do call `setGenericPassword({ ...otherProps, storage: \"AES\" })` with forced storage.\n\n\u003e Note: attempt to force storage `RSA` when biometrics is not available will force code to reject call with errors specific to device biometric configuration state.\n\n## Manual Installation\n\n### iOS\n\n#### Option: Manually\n\n- Right click on Libraries, select **Add files to \"…\"** and select `node_modules/react-native-keychain/RNKeychain.xcodeproj`\n- Select your project and under **Build Phases** -\u003e **Link Binary With Libraries**, press the + and select `libRNKeychain.a`.\n- make sure `pod 'RNKeychain'` is not in your `Podfile`\n\n#### Option: With [CocoaPods](https://cocoapods.org/)\n\nAdd the following to your `Podfile` and run `pod update`:\n\n```\npod 'RNKeychain', :path =\u003e '../node_modules/react-native-keychain'\n```\n\n#### Enable `Keychain Sharing` entitlement for iOS 10+\n\nFor iOS 10 you'll need to enable the `Keychain Sharing` entitlement in the `Capabilities` section of your build target. (See screenshot). Otherwise you'll experience the error shown below.\n\n![screen shot 2016-09-16 at 20 56 33](https://cloud.githubusercontent.com/assets/512692/18597833/15316342-7c50-11e6-92e7-781651e61563.png)\n\n```\nError: {\n  code = \"-34018\";\n  domain = NSOSStatusErrorDomain;\n  message = \"The operation couldn\\U2019t be completed. (OSStatus error -34018.)\";\n}\n```\n\n### Android\n\n#### Option: Manually\n\n- Edit `android/settings.gradle` to look like this (without the +):\n\n```diff\nrootProject.name = 'MyApp'\n\ninclude ':app'\n\n+ include ':react-native-keychain'\n+ project(':react-native-keychain').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-keychain/android')\n```\n\n- Edit `android/app/build.gradle` (note: **app** folder) to look like this:\n\n```diff\napply plugin: 'com.android.application'\n\nandroid {\n  ...\n}\n\ndependencies {\n  implementation fileTree(dir: 'libs', include: ['*.jar'])\n  implementation 'com.android.support:appcompat-v7:23.0.1'\n  implementation 'com.facebook.react:react-native:0.19.+'\n+ implementation project(':react-native-keychain')\n}\n```\n\n- Edit your `MainApplication.java` (deep in `android/app/src/main/java/...`) to look like this (note **two** places to edit):\n\n```diff\npackage com.myapp;\n\n+ import com.oblador.keychain.KeychainPackage;\n\n....\n\npublic class MainActivity extends extends ReactActivity {\n\n  @Override\n  protected List\u003cReactPackage\u003e getPackages() {\n      return Arrays.\u003cReactPackage\u003easList(\n              new MainReactPackage(),\n+             new KeychainPackage()\n      );\n  }\n  ...\n}\n```\n\n#### Proguard Rules\n\nOn Android builds that use proguard (like release), you may see the following error:\n\n```\nRNKeychainManager: no keychain entry found for service:\nJNI DETECTED ERROR IN APPLICATION: JNI FindClass called with pending exception java.lang.NoSuchFieldError: no \"J\" field \"mCtxPtr\" in class \"Lcom/facebook/crypto/cipher/NativeGCMCipher;\" or its superclasses\n```\n\nIf so, add a proguard rule in `proguard-rules.pro`:\n\n```\n-keep class com.facebook.crypto.** {\n   *;\n}\n```\n\n## Unit Testing with Jest\n\nThe keychain manager relies on interfacing with the native application itself. As such, it does not successfully compile and run in the context of a Jest test, where there is no underlying app to communicate with. To be able to call the JS functions exposed by this module in a unit test, you should mock them in one of the following two ways:\n\nFirst, let's create a mock object for the module:\n\n```js\nconst keychainMock = {\n  SECURITY_LEVEL_ANY: \"MOCK_SECURITY_LEVEL_ANY\",\n  SECURITY_LEVEL_SECURE_SOFTWARE: \"MOCK_SECURITY_LEVEL_SECURE_SOFTWARE\",\n  SECURITY_LEVEL_SECURE_HARDWARE: \"MOCK_SECURITY_LEVEL_SECURE_HARDWARE\",\n  setGenericPassword: jest.fn().mockResolvedValue(),\n  getGenericPassword: jest.fn().mockResolvedValue(),\n  resetGenericPassword: jest.fn().mockResolvedValue(),\n  ...\n}\n```\n\n### Using a Jest `__mocks__` Directory\n\n1. Read the [jest docs](https://jestjs.io/docs/en/manual-mocks#mocking-node-modules) for initial setup\n\n2. Create a `react-native-keychain` folder in the `__mocks__` directory and add `index.js` file in it. It should contain the following code:\n\n```javascript\nexport default keychainMock;\n```\n\n### Using a Jest Setup File\n\n1. In your Jest config, add a reference to a [setup file](https://jestjs.io/docs/en/configuration.html#setupfiles-array)\n\n2. Inside your setup file, set up mocking for this package:\n\n```javascript\njest.mock('react-native-keychain', () =\u003e keychainMock);\n```\n\nNow your tests should run successfully, though note that writing and reading to the keychain will be effectively a no-op.\n\n## Notes\n\n### Android Notes\n\nThe module will automatically use the appropriate CipherStorage implementation based on API level:\n\n- API level 16-22 will en/de crypt using Facebook Conceal\n- API level 23+ will en/de crypt using Android Keystore\n\nEncrypted data is stored in SharedPreferences.\n\nThe `setInternetCredentials(server, username, password)` call will be resolved as call to `setGenericPassword(username, password, server)`. Use the `server` argument to distinguish between multiple entries.\n\n#### Configuring the Android-specific behavior\n\nAndroid implementation has behavioural specifics incurred by existing inconsistency between implementations by different vendors. E.g., some Samsung devices show very slow startup of crypto system. To alleviate this, a warm-up strategy is introduced in Android implementation of this library.\n\nUsing default constructor you get default behaviour, i.e. with the warming up on.\n\n```java\n    private List\u003cReactPackage\u003e createPackageList() {\n      return Arrays.asList(\n        ...\n        new KeychainPackage(),  // warming up is ON\n        ...\n      )\n\n```\n\nThose who want finer control are required to use constructor with a builder which can be configured as they like:\n\n```java\n    private List\u003cReactPackage\u003e createPackageList() {\n      return Arrays.asList(\n        ...\n        new KeychainPackage(\n                new KeychainModuleBuilder()\n                        .withoutWarmUp()),   // warming up is OFF\n        ...\n      )\n```\n\n### iOS Notes\n\nIf you need Keychain Sharing in your iOS extension, make sure you use the same App Group and Keychain Sharing group names in your Main App and your Share Extension. To then share the keychain between the Main App and Share Extension, use the `accessGroup` and `service` option on `setGenericPassword` and `getGenericPassword`, like so: `getGenericPassword({ accessGroup: 'group.appname', service: 'com.example.appname' })`\n\nRefs:\n\n- \u003chttps://developer.apple.com/documentation/localauthentication\u003e\n- \u003chttps://developer.apple.com/documentation/security\u003e\n\n### macOS Catalyst\n\nThis package supports macOS Catalyst.\n\n### Security\n\nOn API levels that do not support Android keystore, Facebook Conceal is used to en/decrypt stored data. The encrypted data is then stored in SharedPreferences. Since Conceal itself stores its encryption key in SharedPreferences, it follows that if the device is rooted (or if an attacker can somehow access the filesystem), the key can be obtained and the stored data can be decrypted. Therefore, on such a device, the conceal encryption is only an obscurity. On API level 23+ the key is stored in the Android Keystore, which makes the key non-exportable and therefore makes the entire process more secure. Follow best practices and do not store user credentials on a device. Instead use tokens or other forms of authentication and re-ask for user credentials before performing sensitive operations.\n\n![Android Security Framework](https://source.android.com/security/images/authentication-flow.png)\n\n- [Android authentication](https://source.android.com/security/authentication)\n- [Android Cipher](https://developer.android.com/guide/topics/security/cryptography)\n- [Android Protected Confirmation](https://developer.android.com/training/articles/security-android-protected-confirmation)\n\n## Maintainers\n\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ca href=\"https://github.com/oblador\"\u003e\n          \u003cimg width=\"150\" height=\"150\" src=\"https://github.com/oblador.png?v=3\u0026s=150\"\u003e\n          \u003cbr /\u003e\n          \u003cstrong\u003eJoel Arvidsson\u003c/strong\u003e\n        \u003c/a\u003e\n        \u003cbr /\u003e\n        Author\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ca href=\"https://github.com/vonovak\"\u003e\n          \u003cimg width=\"150\" height=\"150\" src=\"https://github.com/vonovak.png?v=3\u0026s=150\"\u003e\n          \u003cbr /\u003e\n          \u003cstrong\u003eVojtech Novak\u003c/strong\u003e\n        \u003c/a\u003e\n        \u003cbr /\u003e\n        Maintainer\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ca href=\"https://github.com/pcoltau\"\u003e\n          \u003cimg width=\"150\" height=\"150\" src=\"https://github.com/pcoltau.png?v=3\u0026s=150\"\u003e\n          \u003cbr /\u003e\n          \u003cstrong\u003ePelle Stenild Coltau\u003c/strong\u003e\n        \u003c/a\u003e\n        \u003cbr /\u003e\n        Maintainer\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ca href=\"https://github.com/OleksandrKucherenko\"\u003e\n          \u003cimg width=\"150\" height=\"150\" src=\"https://github.com/OleksandrKucherenko.png?v=3\u0026s=150\"\u003e\n          \u003cbr /\u003e\n          \u003cstrong\u003eOleksandr Kucherenko\u003c/strong\u003e\n        \u003c/a\u003e\n        \u003cbr /\u003e\n        Contributor\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003ctbody\u003e\n\u003c/table\u003e\n\n## For Developers / Contributors\n\n- [How to Configure Android Studio for Development](android/README.md)\n\n## License\n\nMIT © Joel Arvidsson 2016-2020\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsticknet%2Freact-native-keychain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsticknet%2Freact-native-keychain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsticknet%2Freact-native-keychain/lists"}