Simple and secure SSL public key pinning for React Native. Uses OkHttp CertificatePinner on Android and TrustKit on iOS.
npm install react-native-ssl-public-key-pinning
OR for Yarn use:
yarn add react-native-ssl-public-key-pinning
Before building for iOS, make sure to run the following commands:
cd ios && pod install && cd ..
npx expo install react-native-ssl-public-key-pinning
and then follow the steps to create a development build or production build
expo-dev-client
Network Inspector on iOS (Optional)If you are building an iOS Expo development build and want to test out your pinning configuration, you will need to disable expo-dev-client
's network inspector as it interferes with the pinning setup. Note that the network inspector is automatically disabled on production builds and so this library would function properly on production builds without needing to go through the following steps.
expo-build-properties
npx expo install expo-build-properties
app.json
{
"expo": {
"plugins": [
[
"expo-build-properties",
{
"ios": {
"networkInspector": false
}
}
]
]
}
}
3. Run prebuild to update native files
npx expo prebuild
## 🚀Usage
1. Retrieve the base64-encoded SHA-256 public key hash of the certificates you want to pin. [More details on how to do this](#public-key-hash)
2. Call `initializeSslPinning` as early as possible in your App entry point with your SSL pinning configuration.
3. All network requests in your app should now have SSL pinning enabled!
### Pinning Example
```js
import { initializeSslPinning } from 'react-native-ssl-public-key-pinning';
await initializeSslPinning({
'google.com': {
includeSubdomains: true,
publicKeyHashes: [
'CLOmM1/OXvSPjw5UOYbAf9GKOxImEp9hhku9W90fHMk=',
'hxqRlPTu1bMS/0DITB1SSu0vd4u/8l8TjPgfaAp63Gc=',
'Vfd95BwDeSQo+NUYxVEEIlvkOlWY2SalKK1lPhzOx78=',
'QXnt2YHvdHR3tJYmQIr0Paosp6t/nggsEGD4QJZ3Q0g=',
'mEflZT5enoR1FuXLgYYGqnVEoZvmf9c2bVBpiOjYQ0c=',
],
},
});
// ...
// This request will have public key pinning enabled
const response = await fetch('https://www.google.com');
import { addSslPinningErrorListener } from 'react-native-ssl-public-key-pinning';
useEffect(() => {
const subscription = addSslPinningErrorListener((error) => {
// Triggered when an SSL pinning error occurs due to pin mismatch
console.log(error.serverHostname);
});
return () => {
subscription.remove();
};
}, []);
API | Description |
---|---|
isSslPinningAvailable(): boolean |
Returns whether the SslPublicKeyPinning NativeModule is available on the current app installation. Useful if you're using Expo Go and want to avoid initializing pinning if it's not available. |
initializeSslPinning(options: PinningOptions): Promise<void> |
Initializes and enables SSL public key pinning for the domains and options you specify. |
disableSslPinning(): Promise<void> |
Disables SSL public key pinning. |
addSslPinningErrorListener(callback: ErrorListenerCallback): EmitterSubscription |
Subscribes to SSL pinning errors due to pin mismatch. Useful if you would like to report errors or inform the user of security issues. |
Option | Type | Mandatory | Description |
---|---|---|---|
includeSubdomains |
boolean |
No | Whether all subdomains of the specified domain should also be pinned. Defaults to false . |
publicKeyHashes |
string[] |
Yes | An array of SSL pins, where each pin is the base64-encoded SHA-256 hash of a certificate's Subject Public Key Info. Note that at least two pins are needed per domain on iOS. |
expirationDate |
string |
No | A string containing the date, in yyyy-MM-dd format, on which the domain’s configured SSL pins expire, thus disabling pinning validation. If this is not set, then the pins do not expire. Expiration helps prevent connectivity issues in Apps which do not get updates to their pin set, such as when the user disables App updates. |
includeSubdomains: true
is not supported and you have to match your domains exactly. This is because wildcard domain support (which this library uses for includeSubdomains
) was only introduced in OkHttp v4.3, and RN v65 is the first version that upgraded OkHttp to v4.fetch
or XMLHttpRequest
would also be affected by the pinning (e.g. axios
). However, native libraries that implement their own methods of performing network requests would not be affected by the pinning configuration.initializeSslPinning
to throw an exception if only one pin is provided. react-native-code-push
or expo-updates
. Doing this will help ensure your key hashes are up to date without needing users to download a new version from the Play Store/App Store since all pinning configurations are done through the JS API.See the contributing guide to learn how to contribute to the repository and the development workflow.