NHS Mail SMS Gateway How to guide

 

IMPORTANT NEWS

NHS have advised all Trusts across the UK that the SMS service available with NHS mail will be discontinued as from 31st March 2015

Overview

NHS Mail allows SMS messages to be sent by connecting to their SMS gateway. NHS Mail support the following connection methods including:

• SMTP on port 25 (supported by Swivel)

Prerequisites

NHS Mail Account

Swivel 3.x

Mobile Phone on which to receive SMS text messages

Create and Configure the NHS Mail transport

Create the NHS Mail Transport

On the Swivel Administration console select Transport/General, then click on New Entry

Configuring one or more NHS Mail transports for Swivel 3.x

On the Swivel Administration Console Transport/General screen, for the entry created above enter the following parameters:

Identifier: NHS Mail

Class: Default: com.swiveltechnologies.pinsafe.server.transport.NHSMailTransport

Strings per message: Default: 1, the number of security strings that are sent.

Strings Repository Group: choose a group where security strings are sent to

Alert repository group: choose a group where Alert messages are sent to

Destination attribute: phone

Click apply to save the settings. For further information see: Transport Configuration

Configuring the NHS Mail details for Swivel 3. x

Mail server/host: send.nhs.net

Port: 587

Connection Timeout (s): 20

Account username: username for NHS Mail account

Domain suffix: @sms.nhs.net

Account password: Password for the NHS Mail account

Authentication Required: Yes

Enable debug: No, unless indicated by Swivelsecure support

Expected Results

The Swivel log should indicate when a message is sent it is added to the message queue and then sent to the SMS gateway:

Troubleshooting

Try sending a security string or alert and check the Swivel log.

Also see SMS messages are not being sent

Error messages

Sending via NHS Sendmail failed to 01234567890. javax.mail.MessagingException: Can't send command to SMTP host; nested exception is: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

This error has been seen due to an upgrade of the SSL certificate on the NHS Mail gateway. The first time the certificate was altered was on 14th October at 3.30pm.

You will need to obtain the latest NHS Mail certificate and upload it to the Java trusted certificates store on the Swivel appliance. The steps to do this are as follows:

• If you do not have a copy of the NHS mail certificate, you can find it here.

• Use WinSCP or Webmin to upload the NHSMail.cer file to the /backups/upload directory on the appliance. See the WinSCP How To Guide for help with using WinSCP.

• Connect to the Swivel appliance using PuTTY and get to the command line via the Advanced Menu. For help with using PuTTY, see the PuTTY How To Guide. Enter the following commands:

cd /usr/java/default/lib/security

cp cacerts cacerts.bak

keytool -importcert -keystore cacerts -alias NHSMail -file /backups/upload/NHSMail.cer

These commands, switch to the directory containing the java root store, make a backup copy of the certificates store, and then import the NHSMail certificate as a trusted root certificate.

On the final command, you will be asked for the password for the keystore which is "changeit". It will display the certificate, and then ask you to confirm you want to trust it (type "yes").

If you are installing an update to an existing certificate, and you get an error on the last command that the alias NHSMail already exists, use the following command to delete the old NHSMail:

keytool -delete -keystore cacerts -alias NHSMail

Then re-try the last command.

• Finally, restart Tomcat. This will register the modified certificate store.

If anything goes wrong at this point, you can revert to the backup copy of the certificate store and restart Tomcat.

• If there is more than one appliance, you will need to perform this task on the other appliances where the NHS Mail transport will be used, this includes other nodes in a High Availability pair.