Skip to content

Commit 1575f89

Browse files
mCodexmCodex
committed
Update README.md
1 parent 2ba30fa commit 1575f89

File tree

1 file changed

+32
-233
lines changed

1 file changed

+32
-233
lines changed

‎README.md‎

Lines changed: 32 additions & 233 deletions
Original file line numberDiff line numberDiff line change
@@ -1,256 +1,55 @@
1-
# React Native Sensitive Info
1+
<img alt="Cover" src="./cover.png" />
2+
3+
<center>
24

5+
[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)
6+
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
37
[![npm version](https://badge.fury.io/js/react-native-sensitive-info.svg)](https://badge.fury.io/js/react-native-sensitive-info)
48
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5-
[![Open Source Love](https://badges.frapsoft.com/os/v2/open-source.png?v=103)](https://github.com/ellerbrock/open-source-badges/)
6-
7-
`react-native-sensitive-info` manages all data stored in Android Shared Preferences, iOS Keychain and Windows Credentials. You can set and get all key/value using simple methods.
8-
9-
10-
# Help Wanted
9+
![npm bundle size](https://img.shields.io/bundlephobia/min/react-native-sensitive-info)
1110

12-
Hi 👋! It's been 3 years since I released RNSensitiveInfo's first version only to fix a problem that I was facing at that moment. I was starting my career as JS Developer and RNSensitiveInfo helped me a lot through my learning path. Unfortunately, I don't have too much time as I wanted to, to support by myself this awesome library that we've built so far. So, I'm looking for developers who could help during this journey... We have so many pending issues, features, security improvements, unity/integration tests that could be done... I'm still willing to help and take care of releasing it.
11+
</center>
1312

14-
Feel free to contact me,
13+
# React Native Sensitive Info
1514

16-
Best Regards!
15+
`react-native-sensitive-info` manages all data stored in Android Shared Preferences, iOS Keychain and Windows Credentials. You can set and get all key/value using simple methods.
1716

1817
# Install
1918

20-
Install `react-native-sensitive-info` using:
21-
22-
``npm i -S react-native-sensitive-info`` or ``yarn add react-native-sensitive-info``
23-
24-
## Linking project
25-
26-
### Automatically
27-
28-
`react-native link react-native-sensitive-info`
29-
30-
### Manually
31-
32-
#### iOS
33-
34-
If you are using Cocoapods add the following line to your Podfile:
35-
```ruby
36-
pod 'react-native-sensitive-info', path: "../node_modules/react-native-sensitive-info"
37-
```
38-
39-
otherwise follow those steps:
40-
41-
In XCode, in the project navigator:
42-
43-
* Right click Libraries
44-
* Add Files to [your project's name]
45-
* Go to node_modules/react-native-sensitive-info
46-
* Add the .xcodeproj file
47-
48-
In XCode, in the project navigator, select your project.
49-
50-
* Add the libRNSensitiveInfo.a from the RNSensitiveInfo project to your project's Build Phases ➜ Link Binary With Libraries
51-
* Click .xcodeproj file you added before in the project navigator and go the Build Settings tab. Make sure 'All' is toggled on (instead of 'Basic').
52-
* Look for Header Search Paths and make sure it contains both $(SRCROOT)/../react-native/React and $(SRCROOT)/../../React - mark both as recursive. (Should be OK by default.)
53-
54-
Run your project (Cmd+R)
19+
Install `react-native-sensitive-info` version (v6.0.0) which uses keystore to encrypt data before saving into Android:
5520

56-
#### macos (https://github.com/ptmt/react-native-macos)
57-
58-
Same steps as iOS but change the Base SDK to macOS in Libraries/RNSensitiveInfo.xcodeproj.
59-
60-
#### Android
61-
62-
Go to `settings.gradle` inside your android project folder and paste this lines there:
63-
64-
```java
65-
include ':react-native-sensitive-info'
66-
67-
project(':react-native-sensitive-info').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-sensitive-info/android')
68-
```
69-
70-
and paste it into `build.gradle`:
71-
72-
```java
73-
compile project(':react-native-sensitive-info')
74-
```
75-
76-
In your `MainApplication.java` add:
77-
```java
78-
import br.com.classapp.RNSensitiveInfo.RNSensitiveInfoPackage; //<- You must import this
79-
80-
protected List<ReactPackage> getPackages() {
81-
return Arrays.<ReactPackage>asList(
82-
new MainReactPackage(),
83-
new RNSensitiveInfoPackage(), // <- Add this line
84-
);
85-
}
21+
```bash
22+
npm i -S react-native-sensitive-info@next
8623
```
8724

88-
Sync gradle and go :)
89-
90-
#### Windows
91-
92-
* Open the solution in Visual Studio for your Windows apps.
93-
94-
* Right click your in the Explorer and click Add > Existing Project....
95-
96-
* Navigate to ./<app-name>/node_modules/react-native-sensitive-info/windows/RNSensitiveInfo/RNSensitiveInfo/ and add RNSensitiveInfo.csproj.
97-
98-
* Right click on your React Native Windows app under your solutions directory and click Add > Reference....
99-
100-
* Check the RNSensitiveInfo you just added and press Ok
101-
102-
* Open MainPage.cs in your app
103-
25+
```bash
26+
yarn add react-native-sensitive-info@next
10427
```
105-
using RNSqlite2;
106-
107-
get
108-
{
109-
return new List<IReactPackage>
110-
{
111-
new MainReactPackage(),
112-
new RNSensitiveInfoPackage(),
113-
};
114-
}
115-
```
116-
11728

118-
### Expo
119-
120-
As noted by by [@Palisand](https://github.com/Palisand) in [this issue](https://github.com/mCodex/react-native-sensitive-info/issues/50#issuecomment-334583668), it's not possible to use this module with Expo, unless your project is detached. The same is true for any modules with native code, it's not an issue with `react-native-sensitive-info`. You may want to try [SecureStore](https://docs.expo.io/versions/latest/sdk/securestore.html) from Expo itself.
121-
122-
# Methods
123-
124-
We unified our library's methods to bring more efficiency and simplify the usability for other developers. We hope that you enjoy it. :)
125-
126-
`isHardwareDetected()`: resolves to a boolean that indicates the detection of fingerprint hardware
127-
128-
`hasEnrolledFingerprints()`: resolves to a boolean that indicates the enrollment status of fingerprints on the device
129-
130-
`isSensorAvailable`: resolves to a boolean that indicates the overall availability of fingerprint sensor (a combination of the previous two methods)
131-
132-
`setItem(key, value, options)`: You can insert data into shared preferences & keychain using this promise method.
133-
134-
`getItem(key, options)`: This promise will get value from given key.
135-
136-
`deleteItem(key, options)`: It will delete value from given key
137-
138-
`getAllItems(options)`: Will retrieve all keys and values from Shared Preferences & Keychain
139-
140-
"Options" is a new parameter (optional) that you can pass to our methods. But what does it do? Now, you can select which keychain's service (iOS) and shared preferences's name (android) you can use. To do so:
141-
142-
```javascript
143-
SInfo.setItem('key1', 'value1', {
144-
sharedPreferencesName: 'mySharedPrefs',
145-
keychainService: 'myKeychain'
146-
});
147-
```
148-
149-
If you used Android's getDefaultSharedPreferences in your project the shared preference's name that you are looking for is: **com.mypackage.MyApp_preferences**. On the other hand if you used iOS's Keychain the default service is: **app** which is our default too.
150-
151-
### Android Specific Options
152-
153-
#### showModal & strings
154-
155-
When passing in `touchID` and `showModal` (Android only) options as `true`, an Android native prompt will show up asking for user's authentication. This behavior is similar to that of iOS.
156-
157-
You can control strings associated with a modal prompt via `strings` option:
158-
```javascript
159-
strings: {
160-
header: 'Sign in',
161-
description: 'Place finger to authenticate',
162-
hint: 'Touch',
163-
success: 'Fingerprint recognized',
164-
notRecognized: 'Fingerprint not recognized, try again',
165-
cancel: 'Cancel',
166-
cancelled: 'Authentication was cancelled', // reject error message
167-
}
168-
```
169-
170-
#### setInvalidatedByBiometricEnrollment
171-
172-
If you want to control the behaviour on android when new Fingers are enrolled or removed on the device [https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setInvalidatedByBiometricEnrollment(boolean)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setInvalidatedByBiometricEnrollment(boolean)) on any device with API level greater than 24 (`Android version >= N`). You should call during the initialization of your app to the function `setInvalidatedByBiometricEnrollment`.
173-
This will re-initialise the internal android Key generator with the flag set to keep/invalidate the credentials upon fingers change.
174-
175-
```javascript
176-
import SInfo from 'react-native-sensitive-info';
177-
178-
SInfo.setInvalidatedByBiometricEnrollment(false);
179-
```
180-
If you do not call to this function the default value is set to `true`.
181-
182-
### iOS Specific Options
183-
184-
#### kSecAccessControl
185-
186-
When passing in the `touchID` option as `true`, you can also set `kSecAccessControl`. For example:
187-
188-
```javascript
189-
SInfo.setItem('key1', 'value1', {
190-
keychainService: 'myKeychain',
191-
kSecAccessControl: 'kSecAccessControlTouchIDCurrentSet',
192-
sharedPreferencesName: 'mySharedPrefs',
193-
touchID: true
194-
});
195-
```
196-
197-
Note: By default `kSecAccessControl` will get set to `kSecAccessControlUserPresence`.
198-
199-
#### kSecAttrSynchronizable
200-
201-
You can set this to `true` in order to sync the keychain items with iCloud.
202-
203-
Note: By default `kSecAttrSynchronizable` will get set to `false`.
204-
205-
206-
# How to use?
207-
208-
Here is a simple example:
209-
210-
```javascript
211-
import SInfo from 'react-native-sensitive-info';
212-
213-
SInfo.setItem('key1', 'value1', {
214-
sharedPreferencesName: 'mySharedPrefs',
215-
keychainService: 'myKeychain'
216-
}).then((value) =>
217-
console.log(value) //value 1
218-
);
219-
220-
SInfo.setItem('key2', 'value2', {});
221-
222-
SInfo.getItem('key1', {
223-
sharedPreferencesName: 'mySharedPrefs',
224-
keychainService: 'myKeychain'}).then(value => {
225-
console.log(value) //value1
226-
});
227-
228-
SInfo.getItem('key2',{}).then(value => {
229-
console.log(value) //value2
230-
});
231-
232-
SInfo.getAllItems({
233-
sharedPreferencesName: 'mySharedPrefs',
234-
keychainService: 'myKeychain'}).then(values => {
235-
console.log(values) //value1, value2
236-
});
237-
```
29+
# Docs
23830

239-
# Protect your item with fingerprint
240-
As jailbroken device can access your iOS Keychain/ Android shared preference and key store in plain text, it is necessary to add another layer of protection so even jailbreaking won't leak your data (like refresh_token or bank account password).
241-
- for iOS it is implemented though [Access Control](https://developer.apple.com/documentation/security/secaccesscontrol). Everytime when app wants to access the protected keychain item, a prompt by iOS will show up. Only when authentication success will the app get the keychain item.
242-
- for Android it is implemented though [FingerprintManager](https://developer.android.com/reference/android/hardware/fingerprint/FingerprintManager.html) + Keystore. Keystore has a function called `setUserAuthenticationRequired` which makes Keystore requires user authentication before getting value. However Android doesn't nicely user to scan their finger, it just throws error. Here is where FingerprintManager comes in. However (AGAIN) FingerprintManager doesn't show prompt for you, so you need to build UI yourself to let user to know that it is time to scan fingerprint.
31+
Check out the [docs](https://mcodex.github.io/react-native-sensitive-info/docs)
24332

244-
**The example in the repo shows how to use this feature and how to build some Android UI based on callbacks.**
33+
# Contributors ✨
24534

246-
**NOTE: fingerprint will only work with Android 6.0 and above.**
35+
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
24736

248-
HELP NEEDED: It will be nice if someone can build an Android native prompt to make Android touch as easy to use as iOS. Maybe we can borrow some code from [google's example](https://github.com/googlesamples/android-FingerprintDialog)
37+
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
38+
<!-- prettier-ignore-start -->
39+
<!-- markdownlint-disable -->
40+
<table>
41+
<tr>
42+
<td align="center"><a href="https://mcodex.github.io"><img src="https://avatars2.githubusercontent.com/u/5920613?v=4" width="100px;" alt=""/><br /><sub><b>Mateus Andrade</b></sub></a><br /><a href="https://github.com/mCodex/react-native-sensitive-info/commits?author=mcodex" title="Documentation">📖</a> <a href="https://github.com/mCodex/react-native-sensitive-info/commits?author=mcodex" title="Code">💻</a> <a href="https://github.com/mCodex/react-native-sensitive-info/pulls?q=is%3Apr+reviewed-by%3Amcodex" title="Reviewed Pull Requests">👀</a> <a href="#ideas-mcodex" title="Ideas, Planning, & Feedback">🤔</a></td>
43+
<td align="center"><a href="https://github.com/maggialejandro"><img src="https://avatars1.githubusercontent.com/u/3394748?v=4" width="100px;" alt=""/><br /><sub><b>Alejandro</b></sub></a><br /><a href="https://github.com/mCodex/react-native-sensitive-info/commits?author=maggialejandro" title="Code">💻</a> <a href="#maintenance-maggialejandro" title="Maintenance">🚧</a></td>
44+
</tr>
45+
</table>
24946

250-
# Use with redux-persist
47+
<!-- markdownlint-enable -->
48+
<!-- prettier-ignore-end -->
49+
<!-- ALL-CONTRIBUTORS-LIST:END -->
25150

252-
If you would like to use [redux-persist](https://github.com/rt2zz/redux-persist) to store information from your Redux state into secure storage, you can use [redux-persist-sensitive-storage](https://github.com/CodingZeal/redux-persist-sensitive-storage), which provides a custom storage back-end for redux-persist that uses react-native-sensitive-info.
51+
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
25352

25453
# Contributing
25554

256-
Pull requests are always welcome :)
55+
Pull requests are always welcome :)

0 commit comments

Comments
 (0)