The 3rd Party Sign-Up Form is a website the app shows to the end user when he taps the sign-up link on the app Login Screen. There, the end customer usually provides his contact details like name, address, phone number and email address, etc. After validation, the website creates an account and a subscriber in the sip:carrier via the API.

After successfully creating the account and the subscriber, this site needs to construct a specially crafted URL, which is sent back to the end customer via a side channel. Ideally, this channel would be an SMS if you want to verify the end customer’s mobile number, or an email if you want to check the email address.

The sip:phone app registers a URL schema handler for URLs starting with sipphone://. If you start such a link, the app performs a Base64 decoding of the string right after the sipphone:// prefix and then decrypts the resulting binary string via AES using the keys defined during the branding step. The resulting string is supposed to be

username=$user&server=$domain&password=$password.

Therefore, the 3rd Party Sign-Up Form needs to construct this string using the credentials defined while creating the subscriber via the sip:carrier API, then encrypt it via AES, and finally perform a Base64 encoding of the result.

	Up until and including version mr4.5.1 of the sip:carrier, the SIP login credentials are used here. Future versions will connect to the REST interface of the sip:carrier using the web credentials first and fetch the SIP credentials along with other settings from there.

An example Perl code performs encoding of such a string. The AES key and initialization vector ($key and $iv) are the standard values of the sip:phone app and should work until you specified other values during the branding process.

#!/usr/bin/perl -w
use strict;
use Crypt::Rijndael;
use MIME::Base64;
use URI::Escape;

my $key = 'iBmTdavJ8joPW3HO';
my $iv = 'tww21lQe6cmywrp3';

my $plain = do { local $/; <> };
# pkcs#5 padding to 16 bytes blocksize
my $pad = 16 - (length $plain) % 16;
$plain .= pack('C', $pad) x $pad;

my $cipher = Crypt::Rijndael->new(
        $key,
        Crypt::Rijndael::MODE_CBC()
);
$cipher->set_iv($iv);
my $crypted = $cipher->encrypt($plain);
# store b64-encoded string and print to STDOUT
my $b64 = encode_base64($crypted, '');
print $b64, "\n";
# print to STDOUT using URL escaping also
print uri_escape($b64), "\n";

This snippet takes a string from STDIN, encrypts it via AES, encodes it via Base64 and sends the result to STDOUT. It also writes the second line with the same string, but this time, the URL is escaped. To test it, you would run it as follows on a shell, granted it’s stored at /path/to/encrypt.pl.

echo -n 'username=testuser&server=example.org&password=testpass' \
  | /path/to/encrypt.pl

This command would result in the output strings CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI/Wv/VaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg== and CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI%2FWv%2FVaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg%3D%3D. The sip:phone can use the former string to automatically fill in the login form of the Login Screen if started via a Link like sipphone://CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI/Wv/VaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg==.

Here is the same code in PHP.

#!/usr/bin/php
<?php
$key = "iBmTdavJ8joPW3HO";
$iv = "tww21lQe6cmywrp3";

$clear = fgets(STDIN);
$cipher = fnEncrypt($clear, $key, $iv);

echo $cipher, "\n";
echo urlencode($cipher), "\n";

function fnEncrypt($clear, $key, $iv) {
        $pad = 16 - strlen($clear) % 16;
        $clear .= str_repeat(pack('C', $pad), $pad);
        return rtrim(base64_encode(mcrypt_encrypt(
                MCRYPT_RIJNDAEL_128, $key, $clear,
                MCRYPT_MODE_CBC, $iv)), "\0");
}
?>

Similar to the Perl code, you can call it like this:

echo -n 'username=testuser&server=example.org&password=testpass' \
  | /path/to/encrypt.php

However, a URL with the sipphone:// schema is not displayed as a link in an SMS or an Email client and thus can not be clicked by the end customer, so you need to make a detour via a regular http:// URL. To do so, you need a 3rd Party Launch Handler to trick the phone to open such a link.

Therefore, that the 3rd Party Sign-Up Form needs to return a link containing a URL pointing to the 3rd Party Launch Handler and pass the URL escaped string gathered above to the client via an SMS or an Email. Since it is the regular http:// link, it is clickable on the phone and can be launched from virtually any client (SMS, Email, etc.), which correctly renders an HTML link.

A possible SMS sent to the end customer (via the phone number entered in the sign-up from) could, therefore, look as follows (trying to stay below 140 chars).

http://example.org/p?c=CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI
%2FWv%2FVaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg%3D%3D to launch sipphone

An HTML Email could look like this:

Welcome to Example.org,
<a href="http://www.example.org/sipphone?c=CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI
%2FWv%2FVaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg%3D%3D">
click here
</a> to log in.

That way, you can do both: verify the contact details of the end customer, and send the end customer the login credentials in a secure manner.

The URL http://www.example.org/sipphone mentioned above can be any simple script, and its sole purpose is to send back a 301 Moved Permanently or 302 Moved Temporarily with a Location: sipphone://xxxxxxxxxxxx header to tell the phone to open this link via the sip:phone app. The xxxxxxxxxxxx is the plain (non-URL-escaped) string generated by the above script.

An example CGI script performing this task follows.

#!/usr/bin/perl -w
use strict;
use CGI;

my $q = CGI->new;
my $c = $q->param('c');
print CGI::redirect("sipphone://$c");

The script simply takes the URL parameter c from the URL http://www.example.org/sipphone?c=CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI%2FWv%2FVaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg%3D%3D crafted above and puts its content into a Location header using the sipphone:// schema, and finally sends a 301 Moved Permanently back to the phone.

The phone follows the redirect by opening the URL using the sip:phone app, which in turn decrypts the content and fills in the login form.

	Future versions of the sip:carrier will be shipped with this launch handler integrated into the system. Up until and including the version mr4.5.1, this script needs to be installed on any webserver manually.

If the mobile push functionality is enabled and there are no devices registered for a subscriber, the call-flow looks as follows.

Figure B.2. Mobile Push Workflow

In the case of a time-out (no registration notification within a particular time), the application server rejects the call request with an error.

Follow this checklist to make sure you’ve completed all the steps. If you miss anything, the service may not work as expected.

A trusted SSL certificate is required, and we suggest obtaining it before starting the configuration.

The mobile application uses respective iOS/Android libraries to establish a secure TLS connection with certain sip:carrier services, such as SIP/XMPP/pushd(https). A signed SSL certificate is required to guarantee the security of this connection.

Any Certificate Authority (CA) such as Verisign and others can provide you with the required trusted SSL certificate (a certificate and the key files) which you will use in the configuration below.

Below is a brief instruction on how to create an Apple account and enable the Push Notification Service in it. You may need to perform additional steps depending on your project.

	You may only create an Apple account (step 1 below) and enroll into the Apple Developer Program (step 2 below) and Sipwise developers will do the rest. Still, you can perform all the steps by yourself.

cd ~/Desktop
openssl x509 -in aps.cer -inform der -out PushChatCert.pem
openssl pkcs12 -in PushChatCert.p12 -out PushCertificate.pem -nodes –clcerts
openssl pkcs12 -nocerts -out PushChatKey.pem -in PushChatKey.p12

You can use Google Cloud Messaging (GCM) to send push notifications to your subscribers with Android-based mobile devices. Google Cloud Messaging is a free service that acts as an intermediary between the NGCP and devices of your subscribers. Google’s Cloud Connection Server (CCS), a part of GCP, manages the persistent connections with mobile devices to deliver your push notifications.

While communicating with CCS, the NGCP identifies itself using an API key. To get it, follow the steps below.

Please, provide Sipwise developers with the following files and information so that they can make beta builds and submit the application to the App Store:

For the Android application, provide the following:

ngcpcfg apply 'enabled the backup feature.'
ngcpcfg push all

Check that your NS and A DNS records are correctly configured.

Let’s consider the following example: * the load-balancers have the lb01a.example.com and the lb01b.example.com names * the shared name is lb01.example.com and the shared IP address is 1.1.1.1 * the service name is voipservice.example.com

The following DNS records must be present:

Add at least one record for each service: xmpp-server, xmpp-client, sips.

A regular SRV record has the following form:

_service._proto.name. TTL class SRV priority weight port target

Here are examples of the SRV records:

_xmpp-server._tcp.voipservice.example.com. 18000 IN SRV 10 50 5269 voipservice.example.com.
_xmpp-client._tcp.voipservice.example.com. 18000 IN SRV 10 50 5222 voipservice.example.com.
_sips._tcp.voipservice.example.com. 18000 IN SRV 10 100 5061 voipservice.example.com.

You can always check whether the required SRV records are configured by executing the following commands:

dig SRV _xmpp-client._tcp.voipservice.example.net
dig SRV _xmpp-server._tcp.voipservice.example.net
dig SRV _sips._tcp.voipservice.example.net

We strongly suggest that the clocks of all the nodes within the platform are synchronized. To ensure this, check that the NTP service is correctly configured on all your sip:carrier servers and works reliably. Execute the following command for quick test of time synchronization:

ntpq –p

If the current node synchronizes with an NTP server, this server will be marked by the star (*) symbol.

It can be enabled for a domain or separate subscribers in the Admin Panel.

To enable the service for a domain:

Perform tests when the application is available:

Make sure that the subscribers can start using your services in the easiest possible way.