Because careless or malicious services could potentially annoy UP.Link subscribers with notifications, the UP.Link Server provides the following controls on notifications:
The certificate required to send notifications to the secure port (usually called a server certificate) can only be used to issue notifications from a specific domain. The certificate Common-Name stores the subdomain and domain names of the host sending the notifications and ensures that malicious services cannot misrepresent themselves and send spurious notifications (for more information, see Chapter 6, Security).
To send secure notifications, you need to add the following two steps to the beginning of the general steps outlined in How to send notifications on page 84.
To send secure notifications, you must request and install a server certificate from a Certificate Authority approved by the UP.Link Server provider. To request a certificate on Windows, use the UP.SDK CertMaker utility. To use CertMaker, choose Start>Programs>UP.SDK 4.0>CertMaker Tool. Then choose Certificate>Create Request and follow the instructions.
To request a certificate on UNIX, use the sdk_installdir/bin/upcerreq utility. For more information on upcerreq, invoke it with the -h option or see the UP.SDK Tools and APIs Guide.
CertMaker and upcerreq generate a public-private key pair and a Certificate Signing Request (CSR). You copy and paste this CSR into the WWW-based certificate request form provided by the Certificate Authority. The Certificate Authority returns an email response containing a certificate, which you should save and install as described in the next step.
To install a certificate on Windows, use CertMaker again. Choose Certificate>Install Certificate and follow the instructions.
To install a certificate on UNIX, use the sdk_installdir/bin/upcerins utility. For more information on upcerins, invoke it with the -h option or see the UP.SDK Tools and APIs Guide.
CertMaker and upcerins use the certificate email and the private key file to create an output certificate (.pem) file. You'll use the .pem file when you call UP.SDK tools and APIs to send secure notifications.
Verisign currently provides information and instructions for obtaining certificates at the following URL:
http://digitalid.verisign.com/server/trial/index.html
Before you request a real certificate, you should request a free test certificate. You can use the test certificate to prototype and test your application. Verisign provides information about test certificates at the following URL:
http://digitalid.verisign.com/test_server_ids.html
Test certificates are typically issued immediately on request. However, they are valid only for a short time (normally two weeks from when they are issued).
After you display one of the Web pages listed above, select Phone.com in the Server Software Vendor scroll list. The Web site will provide you with all the necessary instructions. It includes a form into which you paste the CSR that you created in the steps in the previous section.
If you use Verisign's Web form to request a certificate, after you have completed the certificate request, you will be prompted to install the certificate in your browser. Although you might want to do it anyway, this step is not required for you to use the certificate for notifications.
Instead of using a Web form to request a certificate, you can email the CSR directly to Verisign. The email address for a test certificate is:
The UP.SDK notification APIs let you issue either secure or non-secure notifications. When you issue a secure notification, the default mode is "secure-preferred." In this mode, the APIs first attempt to connect to the UP.Link Server secure port; if the secure port is not available, they attempt to connect to the non-secure port.
The following table lists notification modes and the types of connections the APIs will establish with different UP.Link Server ports enabled:
Secure-preferred mode is the only mode that guarantees notification delivery. However, you should not use it for information that requires security. The following table summarizes the recommended uses for each notification mode:
| Notification mode | Use |
|---|---|
Applications for which it is important to work on every UP.Link Server, regardless of security (most applications) | |
In general, you do not need to worry about notification port numbers because the UP.SDK APIs issue notifications to the appropriate ports by default. The following table lists the default UP.Link Server notification ports:
| Port | Description |
|---|---|
|
4445
| Internet Assigned Number Authority (IANA) assigned port for non-secure notifications |
|
3356
|
The following section describes some common problems with secure notifications.
If you send a secure notification with an invalid URL for your certificate (for example, if the notification URL is http://mycompany.com but the Common-Name for your certificate is ntfn.www.mycompany.com), the following can happen:
400 HTTP error code--no failover to the non-secure port will occur. This is because a valid secure connection can be established, but the URL is invalid.