Secure Push Notifications

This is a step-by-step guide on how to set up Secure Push Notifications

Any personal data stored digitally needs to be properly protected, especially when it comes to financial information and payment details. With Pushwoosh Secure Push Notifications, every push you send to users is impossible to intercept, even if there's malware present on user's device.

How it works

To secure your customer communications and keep all users' personal data safe, we use the following encryption process:

  1. After your user logs in on their device, Pushwoosh Encryption Plugin generates an asymmetric pair of keys: Public and Private. The keys are unique for each device. A message encrypted with the Public Key may only be decrypted with the Private Key.

  2. The device sends the Public Key to Pushwoosh. All Public Keys are stored on a dedicated secure server.

  3. When you send a message to a specific device, Pushwoosh Encryption System software encrypts the message with the device's Public Key. The encrypted message is then transferred to the device, which deciphers the message with its Private Key.

To setup a secure push server, get the Pushwoosh Encryption Plugin and a secure endpoint, please reach out to your Customer Success Manager or our Customer Support team.

Add And Use The Plugin

1. Integrate Pushwoosh SDK

Make sure you have integrated the Pushwoosh SDK into your Cordova project. Refer to the guide to learn more: https://docs.pushwoosh.com/platform-docs/pushwoosh-sdk/cross-platform-frameworks/cordova/integrating-cordova-plugin

2. Add the Encryption Plugin to your project

To generate encryption keys and decipher messages, you will need to use our plugin.

cordova plugin add PATH_TO_SECURE_PUSHES_PLUGIN

To get the plugin, please contact your Customer Success Manager or our Customer Support team.

3. Modify config.xml

3.1. Open your project in Xcode;

3.2. Add a new target to your project (File -> New -> Target) and create a Notification Service Extension. Embed the extension in your app. In this guide, the extension is named SecurePushes, though you may choose any name.

3.3. Add PushwooshSecure framework to the freshly created extension. To do so, find the PushwooshSecure file in Frameworks (fig. 1).

config.xml
<edit-config file="*-Info.plist" mode="merge" target="NSLocationAlwaysAndWhenInUseUsageDescription">
<string>need location access to find things nearby</string>
</edit-config>
<edit-config file="*-Info.plist" mode="merge" target="NSLocationAlwaysUsageDescription">
<string>need location access to find things nearby</string>
</edit-config>
<edit-config file="*-Info.plist" mode="merge" target="NSLocationAlwaysAndWhenInUseUsageDescription">
<string>need location access to find things nearby</string>
</edit-config>
<edit-config file="*-Info.plist" mode="merge" target="NSLocationWhenInUseUsageDescription">
<string>need location access to find things nearby</string>
</edit-config>

4. Add the iOS notification service extension in your project.

Fig.1: PushwooshSecure should be located in the Frameworks group

Select the framework, go to Target Membership on File Inspector panel, and tick the checkbox right next to the extension (fig. 2).

Fig. 2: tick the checkbox next to the created extension, named SecurePushes in the picture

4.1. Now, you need to modify some code in the extension. Find the NotificationService.m file in the extension group (its name is the same as the extension's) and replace its contents with those of a different NotificationService.m file that's located in PATH_TO_SECURE_PUSHES_PLUGIN/src/ios directory.

4.2. Set the correct Deployment Target. To do so, select the target for the extension, find the Deployment Info section of the General tab, and change the Deployment Target to 10.0 (fig. 3).

Fig. 3: modify the Deployment Info of the extension's target by changing the Deployment Target to 10.0

4.3. Go to the Capabilities tab (fig. 4):

Fig. 4: Capabilities tab

There, enable Keychain Sharing (fig. 5):

Fig. 5: Keychain Sharing switch is located in Capabilities tab

Lastly, locate the Entitlements files. They are usually named Entitlements-Debug.plist and Entitlements-Release.plist and are located in a folder named as the project in the iOS project's directory. Open these files and copy the field keychain-access-groups from Entitlements-Debug.plist into Entitlements-Release.plist.

All done!

Plugin API

setBaseURL(options)

This is a method setting the base URL and managing the SSL certificate check. options is a dictionary with the following possible keys:

  • baseURL. A string with the base URL for all requests — a secure endpoint that is used to connect to a secure server.

  • publicKeyPins. An array of pins for checking the SSL certificate. A pin is a string from base64 encoded sha256 out of the SPKI part of the certificate.

  • overrideHost. A string containing a host. Override host in case the base URL is an IP address or the host doesn't match the one in the SSL certificate.

setupDecryption(success, fail)

This method handles encryption keys and the decryption process. It generates encryption keys, sends the Public Key to your backend, and adds the handler that deciphers messages on Android. The callback is either success or fail. The latter contains information about the error in two fields:

  • error, which is a native error object converted into a string and,

  • errorDescription, a string with error's description.

teardownDecryption(success, fail)

A method that disables Secure Push Notifications on the device. It deletes the Public Key on the device, sends a deletion request to your backend, and stops the Android decryption handler. The parameters are the same as the setupDecryption's: success indicates a successfully completed request, while fail indicates an error and contains information about it in two fields:

  • error, which is a native error object converted into a string and,

  • errorDescription, a string with error's description.

Send Encrypted Messages

To send an encrypted push notifications, you should make a /createMessage POST request to Secure Push Notifications software. Please see the full description of the API for details.