react-native-ssl-manager
React Native SSL Pinning provides seamless SSL certificate pinning integration for enhanced network security in React Native apps. This module enables developers to easily implement and manage certificate pinning, protecting applications against man-in-the-middle (MITM) attacks. With dynamic configuration options and the ability to toggle SSL pinning, it's particularly useful for development and testing scenarios.
Features
- 🔒 Easy SSL certificate pinning implementation
- 🔄 Dynamic enabling/disabling of SSL pinning
- ⚡ Optimized for development and testing workflows
- 📱 Cross-platform support (iOS & Android)
- 🛠️ Simple configuration using JSON
- 🚀 Performance-optimized implementation
Installation
npm install react-native-ssl-manager
Usage
Basic Setup
import {
initializeSslPinning,
setUseSSLPinning,
getUseSSLPinning
} from 'react-native-ssl-manager';
const sslConfig = {
"domains": {
"development": "api.dev.example.com",
"production": "api.example.com"
},
"sha256Keys": {
"api.dev.example.com": [
"sha256/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=",
"sha256/YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY="
],
"api.example.com": [
"sha256/ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ=",
"sha256/WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW="
]
}
};
await initializeSslPinning(JSON.stringify(sslConfig));
await setUseSSLPinning(true);
const isEnabled = await getUseSSLPinning();
console.log('SSL Pinning enabled:', isEnabled);
Configuration File (ssl_config.json)
Create a configuration file with your domain certificates. Example structure:
{
"domains": {
"development": "api.dev.example.com",
"production": "api.example.com"
},
"sha256Keys": {
"api.dev.example.com": [
"sha256/certificate-hash-1=",
"sha256/certificate-hash-2="
],
"api.example.com": [
"sha256/certificate-hash-3=",
"sha256/certificate-hash-4="
]
}
}
API Reference
initializeSslPinning(configJsonString: string): Promise<any>
Initializes the SSL pinning configuration with the provided JSON string configuration.
await initializeSslPinning(JSON.stringify(sslConfig));
setUseSSLPinning(usePinning: boolean): void
Enables or disables SSL pinning dynamically.
await setUseSSLPinning(true);
await setUseSSLPinning(false);
getUseSSLPinning(): Promise<boolean>
Retrieves the current state of SSL pinning.
const isEnabled = await getUseSSLPinning();
Important Notes ⚠️
Restarting After SSL Pinning Changes
When using setUseSSLPinning
, a restart of the application is required for changes to take effect. This is because SSL pinning is implemented at the native level.
Using React Native Restart
First, install react-native-restart:
npm install react-native-restart
yarn add react-native-restart
For iOS, run pod install:
cd ios && pod install
Then use it in your code:
import RNRestart from 'react-native-restart';
const toggleSSLPinning = async (enabled: boolean) => {
await setUseSSLPinning(enabled);
RNRestart.Restart();
};
const handleSSLToggle = async (enabled: boolean) => {
await saveAppState();
await setUseSSLPinning(enabled);
Alert.alert(
'Restart Required',
'The app needs to restart to apply security changes.',
[
{
text: 'Restart Now',
onPress: () => RNRestart.Restart()
}
]
);
};
Development and Testing Benefits
For Developers
- Quick Toggling: Easily switch SSL pinning on/off during development
- Performance Optimization: Minimize SSL verification overhead during development
- Flexible Configuration: Support multiple environments with different certificates
For QA Teams
- Efficient Testing: Quickly verify API behavior with and without SSL pinning
- Issue Investigation: Easily isolate SSL-related issues
- Environment Switching: Seamlessly test across different environments
Best Practices
-
Environment Management
- Keep separate configurations for development and production
- Store production certificates securely
-
Performance Optimization
- Enable SSL pinning only when necessary during development
- Use development certificates for testing environments
-
Security Considerations
- Always enable SSL pinning in production
- Regularly update certificates before expiration
- Maintain multiple backup certificates
Roadmap 🗺️
We're actively working on expanding the capabilities of react-native-ssl-manager. Here are our planned features:
Upcoming Features
- 📱 Expo Plugin Integration
- Native SSL pinning support for Expo projects
- Seamless configuration through expo-config-plugin
- Auto-linking capabilities for Expo development builds
- Support for Expo's development client
Testing with Proxyman 🔍
Proxyman is a powerful tool for testing SSL pinning implementation. Here's how you can verify your SSL pinning configuration:
Setup Verification
Common Test Scenarios
Troubleshooting Tips
- If requests succeed with Proxyman while SSL pinning is enabled, check your configuration
- Verify that the SHA256 hashes in your config match your server certificates
- Test both development and production environments separately
This integration with Proxyman makes it easy to:
- Verify SSL pinning implementation
- Debug API communications
- Validate security configurations
- Speed up development and testing workflows
Contributing
See the contributing guide to learn how to contribute to the repository and the development workflow.
License
For open source projects, say how it is licensed.
Made with create-react-native-library