Bandwidth Branded Site for 9-1-1 Services

Follow

Molly Katolas

Updated

Overview

The branded site is a URL redirect initiated from the customer’s portal in order to update a 9-1-1 record. This is accomplished by configuring the branded site information on the dashboard, on the customer administration interface, and again on the customer’s website platform as seen in the diagram below.

 

 

A shared HMAC key performs authentication for the branded website. This key will be set up via your dashboard administrative web portal. Under Emergency > Configure the branded website configuration module will be found. Here, the key type will need to be selected in the “Key Type” field, then press “Generate New Keys”, as shown here.

Once this is clicked, the keys fields will be populated with new HMAC keys determined by the key type preferred (default is MD5).

Success/Failure URL Setup

Success and failure URLs are set up so that when the end user makes the 9-1-1 update in the branded site, the URL will redirect the end user and indicate whether or not the update was valid and accepted. Bandwidth has provided a success and failure URL below to assist with testing this feature.

Test Success URL: http://brandedwebsite.dashcs.com/success.html

Test Failure URL: http://brandedwebsite.dashcs.com/failure.html

After a user successfully performs an update, they will return to the URL provided in the configuration module using the success URL. Returning via this URL means no error occurred and the user decided to return. Any user-defined data (xd) passed in when redirected to the branded site will be returned via querystring, in a parameter named xd (extra data).

When an error occurs inside the branded site, the user will be directed back to the website provided in the failure URL. In addition to user-defined extra data (xd) in the querystring, there will be a reason parameter. The possible error codes are listed below. It is recommended that upon receiving an error, the end user would contact the customer’s internal methods for assistance to resolve the failure. Once reported internally, please contact the Bandwidth team for additional assistance if needed to resolve the address issue.

Error Codes

An example of the error URL would be:

http://brandedwebsite.dashcs.com/failure.html?xd=&reason=101

Valid values for the return reason are:

Error Value Meaning
000 No reason. Contact Bandwidth support for branded website assistance.
001 Unknown reason. Contact Bandwidth support for branded website assistance.
100 General Failure. Contact Bandwidth Support for branded website assistance.
101 Authentication error. Contact Bandwidth Support for branded website assistance.
102 Update failure. A problem occurred while updating the address.
200 Address validation problem. A subscriber could not enter a postal-validated address. 
 
Logo and CSS Setup

Customization of the branded website is accomplished via changing the logo file and CSS (cascading style sheet) of the webpage to match that of an internal customer portal. Once customization is complete, the changes can be configured under the “Logo URL” and “CSS URL” sections in the branded website configuration module in the dashboard.

URL Generator

The branded website URL generator is provided to assist you in setting up the branded website. This URL generator utilizes the settings defined above to generate a URL for testing against. This is extremely helpful in locating any discrepancies between the URL redirect generated from the customer end, and the URL generated on the Bandwidth end. Furthermore, it allows for testing the redirect to ensure the site is responding. To test using the URL generator, simply click on the “Branded Site URL Generator” link in the dashboard on the branded site configuration module. Clicking this link will provide the URL generator screen. On this screen, a telephone number will need to be inserted, and the HMAC key will need to be selected and verified to be correct. Once finished, click “Update”.

This will return the proper generated URL based on the branded site settings, as shown below. To test the feature all the way through, simply click on the generated link or open it in a new browser window. The branded site that has been customized using all of the aforementioned methods should appear and allow a 9-1-1 address update to occur.

To verify further that the address was accepted and provisioned in the dashboard, simply search for the TN in the dashboard under Emergency > Endpoints. Enter the TN in the search box, and click “Search”. The properly provisioned endpoint should appear in a list. Click on the endpoint to view the endpoint in full, and look to verify any minor discrepancies in provisioning, such as date or CID which are the most common errors.

Customer Platform Redirect Configuration

In order for the branded site to fully function, the URL redirect must originate from the customer web portal. As Bandwidth cannot authenticate the end subscriber via the URL redirect, we rely on the customer to authenticate the user and tie that user to their telephone number before allowing them to update a 9-1-1 address. From the customer web portal, instruct the end user to click on the “Update my 9-1-1 address” link, which will initiate the redirect on the end user side and allow them to update the address information associated with the telephone number.

Values

In order to create the URL redirect, the following values are required and must be populated then HASHed to provide security to the customer’s 9-1-1 information.

Subscriber Telephone Number

Name: tn
Value: The telephone number of the subscriber as a 10-digit number with no additional characters.

Date

Name: date
Value: The current date and time, expressed in UTC. The format is “yyyyMMddHHmm”:

 
yyyy =

four-digit year

MM = two-digit month, from 01-12
dd = two-digit day of the month, from 00-32
HH = two-digit hour, from 00-23
mm =  two-digit minute, from 00-59

The date ensures that a URL cannot be used outside of a certain window of time (+/- 10 minutes of the current UTC time). This protects against an attacker retrieving a URL from the browser’s history, for example.


Company ID

Name: cid
Value: The Bandwidth assigned company ID (usually a 5-digit number). This can be retrieved on the dashboard from the main account screen when you first log in, or at the bottom of the page next to the customer name.

Key Number

Name: kn

Value: Key number, either 0 or 1, specifies the key to be used. Multiple keys are allowed in the database so as to make routing easier.

Authentication Value

Name: auth
Value: The HMAC generated has in Base64. This has is computed by using the supported HMAC algorithm. The plaintext-to-hash is the TN as 10 ASCII characters + the datetime. For instance, the HMAC for the TN 5557654321 at 3:40pm UTC on July 28, 2008, would be computed as “5557654321200807281540.”

*Note: The ‘date’ and ‘tn’ used when calculating the HMAC must be the same as passed in the date and tn parameters of the querystring.

Base URL

The base part of the URL will be: https://e911update.dashcs.com/dash-board/UpdateMyAddress.action

URL Configuration Example

Given the following information:
Key: 0x635329736E495B3867557C2A5D7D5054
Key number: 0
Company Id: 1000
Current UTC Date & Time: 200901200054 (12:54am, January 20, 2009) Telephone Number: 9876543210
HMAC Algorithm: HMAC-MD5

Expressed as Base64, the hash is: ZU8aB+YmMHRDend6U+asdA==

To put this into a URL, it must be encoded using the following replacements:

Replacing With
+ %2b
/ %2f
= %3d

The new hash would be: ZU8aB%2BYmMHRDend6U%2BasdA%3D%3D

The complete URL would be (one line):

https://e911update.dashcs.com/dash- board/UpdateMyAddress.action?tn=9876543210&date=200901200054&cid=1000&kn=0&a uth=ZU8aB%2BYmMHRDend6U%2BasdA%3D%3D

Once this URL is generated, the end user will be redirected to the branded site to begin updating the address. Below is a screenshot of this address update screen with a sample logo and CSS in place.

Sample Code

PHP is the most frequently requested sample code and is shown below.

<?php
function computeHash($tn, $date, $Key)

{

$auth=hash_hmac("md5",$tn.$date,$Key, TRUE);

return $auth;

}

function createQueryString($tn, $key, $companyId, $keyNumber)

 

{

echo "TN : "; echo $tn;

echo "<br>\n\n"; echo "<br>\n\n";

echo "Key : "; echo $key; echo "<br>\n\n";
echo "<br>\n\n";

echo "CompanyId : "; echo $companyId; echo "<br>\n\n";
echo "<br>\n\n";

echo "Key Number : "; echo $keyNumber; echo "<br>\n\n";
echo "<br>\n\n";

$format = "tn=%s&date=%s&cid=%s&kn=%d&auth=%s"; $date = gmdate('YmdHi');
//$date = "200601201149";
echo "Current Date : " . $date;

echo "<br>\n\n"; echo "<br>\n\n";

$auth = computeHash($tn, $date, $key);

echo "Plaintext to hash on : " . $tn.$date; echo "<br>\n\n";
echo "<br>\n\n";

echo "The hash is as hex : " . bin2hex($auth); echo "<br>\n\n";
echo "<br>\n\n";

echo "The hash is as binary : " . $auth; echo "<br>\n\n";
echo "<br>\n\n";

$auth=base64_encode($auth);
echo "The hash base 64 is : " . $auth; echo "<br>\n\n";
echo "<br>\n\n";

$auth=urlencode($auth);

echo "The hash Url enconded is : " . $auth;

echo "<br>\n\n";

echo "<br>\n\n";

$queryString = sprintf($format,$tn,$date,$companyId,$keyNumber,$auth); return $queryString;

}

function createUrl($tn, $key, $companyId, $keyNumber)

{

$baseUrl="http:// e911update.dashcs.com/dash-board/UpdateMyAddress.action?";

return $baseUrl.createQueryString($tn, $key, $companyId, $keyNumber);

}

// Call the function

$testUrl = createUrl("3035551244","].,uWYmv{!5;.~h|","501","0"); echo $testUrl;

echo "<br>\n\n<br>\n\n<a href=\"" . $testUrl . "\">" . $testUrl . "</a>"; //header("Location: $testUrl");

 

Article is closed for comments.