Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

nativescript-ssl-pinning

1.1.15 • Public • Published

NativeScript-SSL-Pinning

NPM version Downloads TotalDownloads

A drop-in replacement for the default http module.

Note: This plugin is inspired by nativescript-ssl-pinning. Most of the code is taken from this. I've added angular support and also fixed some long term issues. Huge thanks to the original creator.

Some of the fixed issues are as follows

  • No support for wild card certificates.
  • The nativescript-https module did not handle any error responses (400 - 500).
  • Out of the box angular support no need to update previous apps just update the HttpClient module import.
  • Added support for multipart forms.

Features

  • Modern TLS & SSL security features
  • Shared connection pooling reduces request latency
  • Silently recovers from common connection problems
  • Everything runs on a native background thread
  • Transparent GZIP
  • HTTP/2 support

FAQ

What the flip is SSL pinning and all this security mumbo jumbo?

How to make your apps more secure with SSL pinning.

Do I have to use SSL pinning?

No. This plugin works out of the box without any security configurations needed. Either way you'll still benefit from all the features listed above.

Demo

git clone https://github.com/sai-gmbh/nativescript-ssl-pinning
cd nativescript-ssl-pinning/src
npm run demo.ios
npm run demo.android
npm run demo-angular.ios
npm run demo-angular.android

Installation

Add tns-platform-declarations for Android and iOS to your references.d.ts!

/// <reference path="./node_modules/tns-platform-declarations/android.d.ts" />
/// <reference path="./node_modules/tns-platform-declarations/ios.d.ts" />

We also recommend adding "skipLibCheck": true, to your tsconfig.json. More information on that can be found here.

Install the plugin:

tns plugin add nativescript-ssl-pinning

Examples

Hitting an API using GET method

import { SslPinning } from 'nativescript-ssl-pinning'
SslPinning.request({
    url: 'https://httpbin.org/get',
    method: 'GET',
})
.then((response) => console.log('response', response))
.catch((error) => console.error('error', error));

Angular Support

NativescriptSslPinningHttpClientModule internally overrides Angular's XHRBackend to make request through our SSL Plugin and transforms it back to angular responses. This will keep the interceptors functionality intact.

import {NativescriptSslPinningHttpClientModule} from "nativescript-ssl-pinning/angular"
@NgModule({
  imports: [
    // ...
    NativescriptSslPinningHttpClientModule
  ],
  declarations: [
    ExampleComponent,
  ],
  schemas: [
    NO_ERRORS_SCHEMA
  ]
})
export class AppModule {
}
 
@Component({...})
export class ExampleComponent implements OnInit {
  constructor(private http: HttpClient) {}
  
  ngOnInit() {
    this.http.get('https://httpbin.org/status/500').subscribe(res => console.log(res), err => console.log(err));
  }
}

Configuration

Installing your SSL certificate

Create a folder called assets in your projects app folder like so <project>/app/assets.

Enabling SSL pinning

import { knownFolders } from 'file-system'
import { SslPinning } from 'nativescript-ssl-pinning'
let dir = knownFolders.currentApp().getFolder('assets')
let certificate = dir.getFile('httpbin.org.cer').path
SslPinning.enableSSLPinning({ host: 'httpbin.org', certificate })

Once you've enabled SSL pinning you CAN NOT re-enable with a different host or certificate file.

Disabling SSL pinning

import { SslPinning } from 'nativescript-ssl-pinning'
SslPinning.disableSSLPinning()

All requests after calling this method will no longer utilize SSL pinning until it is re-enabled once again.

Options

export interface HttpsSSLPinningOptions {
    host: string
    certificate: string
    allowInvalidCertificates?: boolean
    validatesDomainName?: boolean
}
Option Description
host: string This must be the top level domain name eg httpbin.org.
certificate: string The uri path to your .cer certificate file.
allowInvalidCertificates?: boolean Default: false. This should always be false if you are using SSL pinning. Set this to true if you're using a self-signed certificate.
validatesDomainName?: boolean Default: true. Determines if the domain name should be validated with your pinned certificate.

Webpack / bundling

Since you're probably shipping a certificate with your app, make sure it's bundled by Webpack as well. You can do this by adding the certificate(s) with the CopyWebpackPlugin

new CopyWebpackPlugin([
    { from: { glob: "fonts/**" } },
    { from: { glob: "**/*.jpg" } },
    { from: { glob: "**/*.png" } },
    { from: { glob: "**/*.cer" } },  // add this line in webpack.config.js
], { ignore: [`${relative(appPath, appResourcesFullPath)}/**`] })

iOS Troubleshooting

Please educate yourself on iOS's App Transport Security before starting beef!

If you try and hit an https route without adding it to App Transport Security's whitelist it will not work! You can bypass this behavior by adding the following to your projects Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

This plugin does not add NSAllowsArbitraryLoads to your projects Info.plist for you.

Android troubleshooting

If you app crashes with a message that it's doing too much networkin on the main thread, then pass the option allowLargeResponse with value true to the request function.

Current Issues

  1. Multipart form requests are not supported by the plugin yet. For Angular users they'll go through Angular's own XHR but for native users it might fail.

Thanks

Who Why
Robert Laverty For creating and maintaining this plugin for a long time, before transfering it to me, with the help of Jeff Whelpley of GetHuman.
AFNetworking AFNetworking A delightful networking framework for iOS, OS X, watchOS, and tvOS.
Square okhttp An HTTP+HTTP/2 client for Android and Java applications.

Install

npm i nativescript-ssl-pinning

DownloadsWeekly Downloads

2

Version

1.1.15

License

Apache-2.0

Unpacked Size

116 kB

Total Files

39

Last publish

Collaborators

  • avatar