Secure Push Messaging

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

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

Plugin API Server API F.A.Q.

Secure Push Messaging Overview

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 your servers. All Public Keys are stored on a private server, accessible only from your side.

  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.

Setting Up The System

The Pushwoosh Secure Messaging Solution is made up of two applications. One handles the data storage, the other encrypts and sends messages.

  1. Install the first app on your server and make it publicly accessible. Your mobile app will communicate with it through the public network, collecting device data, such as Public Keys.

  2. Install the second app and make it accessible only through the private network. You’ll use it to send messages to your clients.

The installation process is fairly straight-forward. Launching the setup .exe file will open the Setup Wizard.

The Setup Wizard: overview.

Choose the directory, and the installation will start after a confirmation. The installation process consists of four points: 1. Copying the app into the chosen directory; 2. Adding default app launching values into the Windows registry. The registry key is HKCU\Software\Pushwoosh\Secure Push Device API or HKCU\Software\Pushwoosh\Secure Push Messaging, depending on the app; 3. The corresponding service is registered in the operating system; 4. The service is started.

Configure the Secure Push Messaging in Windows system registry. Use the following parameters (make sure to add missing ones, if any):

connection_string = "file:C:\\SecurePush\\database.db" # Full path to the database.
port = 9093 #application port
access_log = "access.log" # Relative or absolute path to access logs
error_log = "error.log"
log_level = "error" # log levels. Values: "info", "error". "Info" log level provides full information about every request made and its response; "error" writes down only error messages
default_message = "New info available" # the default text shown on the device should the decryption fail

Add And Use The Plugin

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

1. Add the plugin:

cordova plugin add PATH_TO_SECURE_PUSHES_PLUGIN

2. 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>

3. 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

3.4. 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. 3.5. 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

3.6. 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

Plugin consists of 2 modules:

Module 1: pushwoosh-cordova-plugin-alinma.PushwooshSecure

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.

  • 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 Messaging 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.

Module 2: pushwoosh-cordova-plugin-alinma.PushGeolocation

requestPermissions()

A method that requests location tracking permissions for the application. Can be used for requesting permissions manually.

startTrackingPushGeolocation(success, fail)

A method that starts tracking device's coordinates when the push is received. The callback is either success or fail.

stopTrackingPushGeolocation()

A method that is used to stop tracking device's geolocation.

popReceivedPushes(success, fail)

A method that retrieves the list of pushes with corresponding coordinates from the storage. The callback is either success or fail.

success callback with array of parameters that contains objects with following fields:

  • payload, push payload,

  • geolocation, contains the following fields: latitude, longitude, accuracy.

Note: after popReceivedPushes is called, all previous records are removed from the storage.

Send Encrypted Messages

To send an encrypted transactional message, you should make a message/create POST request to Secure Push Messaging software. Please see the full description of the API for details.