Message Exchange for Social Care and Health: certificate guidance

MESH client and MESH server application program interface (API) require certificates when connecting to the MESH server to send and receive messages to ensure safe and secure communication. MESH relies on mutual authentication for higher security (both ends check the other end has a valid certificate) as part of the log on process.

If you want to access MESH and do not already have access to the Spine, you'll need to request a certificate by using the Certificate Enrolment Tool. There are also instructions (below) on how to request a certificate manually if you cannot, or do not want to use the enrolment tool.

If you already have a Spine end-point registration certificate used for accessing Spine messaging interfaces, you may use this for accessing MESH via the HSCN/N3 connection without applying for another certificate. Please bear in mind that this will mean you're running two services from one certificate. More information in using a current end point registration certificate can be found below.

A MESH certificate will last for three years and it is the responsibility of the organisation to renew certificates to ensure connection to the service. If your certificate expires, you will no longer have access to MESH, with immediate effect.

Step 1

A new Certificate Enrolment Tool is being developed so please download a temporary replacement ZIP file and extract the newg2.bat.txt file to a folder on a PC that has Java installed.

Step 2

Remove the extra .txt from the filename. If you cannot see the .txt extension, ensure you have file name extensions ticked:

Step 3

Open a command prompt and use the CD command to change to that directory so that you can run the batch file from there.

C:\user\smith\Desktop\G2> newg2.bat

Step 4

When newg2.bat is executed, the batch script initially looks for the location of the java keytool command and, once found, will ask you to Press any key to continue.

You’ll be asked a series of questions which should be responded to as follows:

Local identifier: Enter the mailbox id which the MESH client will manage.

ODS code: Enter your ODS code.

Mailbox Type: Enter c for client.

You will be prompted for a keystore password. This password is defined locally and should comprise only of letters and numbers. Upper and lower case characters are acceptable but avoid special characters such as the '£' sign. Enter the password and ensure that this is reflected in the <KeyStorePassword> setting in the meshclient.cfg file.

Confirm with a y if you’re happy with what you’ve entered (or n to enter another password).

The batch script will show that the certificate will have a Subject Common Name of {mailbox id}.{ODS}.mesh-client.nhs.uk

Confirm with a y if you’re happy with that (or enter n to start again).

It will then create a new keystore and a Certificate Signing Request (CSR) file called mesh.csr before pausing.

Step 5

The CSR will look similar to the request shown below:

This needs to be emailed to the National Service Desk at [email protected]

In the body of the email, provide the:

• name
• company/organisation
• contact number
• MESH mailbox id(s) served by this certificate
• certificate common name (CN): identifier.ODS.mesh-client.nhs.uk
• reason for the certificate (such as 'New MESH client' or 'Current certificate has or is about to expire')

Underneath this, paste the contents of the CSR including the lines for BEGIN and END CERTIFICATE REQUEST.

Send, and wait for the DIR team to email the signed certificate to you.

Step 6

When you receive the signed certificate, create a file called mesh.crt and place the whole text of the cert (including the BEGIN and END CERTIFICATE rows) into that file and save it.

The mesh.crt file must be in the same location as the mesh.csr file before continuing with the batch script, which will then import all the required root and intermediate certificates into the keystore.

Step 7

You’ll be prompted to press any key to continue and the batch script will clean up the folder by deleting the temporary root and sub CA files before exiting.

Step 8

The keystore file is called MESH.keystore and needs to be copied into the MESH client’s KEYSTORE folder; this is normally a sub-directory of MESH-APP-HOME.

If you do not currently hold a Spine End Point Certificate (EPC) and do not wish to use our Certificate Enrolment Tool (information above), follow the instructions below to acquire a MESH-specific certificate.

Ensure you have a JVM version 1.7 or later installed on the server before beginning.

This certificate lasts for three years. It's the responsibility of the organisation to renew certificates to ensure MESH connection. If your certificate expires, you'll no longer have access to MESH, with immediate effect.

Step 1

Open the Command Prompt as an administrator (“Start”, search for “cmd”, right click on Command Prompt and select “Run as Administrator”). You should now see a command window and be able to use everything within the same directory.

Step 2

Add open ssl and the jre7bin directory to the path (for the keytool). Do this by copying and pasting the following command into the command prompt:

PATH = %PATH%;C:\Program Files\GnuWin32\bin;C:\Program Files\Java\jre7\bin 

If working on a 64 bit system, either of these directories may in fact reside in Program Files (x86). If this is the case a simple substitution is required in the command from Program Files to Program Files (x86).

Step 3

The MESH-specific certificate for MESH clients will be based on the ODS code of the end system. It will follow the Identifier.ODScode.mesh-client.nhs.uk naming convention.

Take, for example, a MESH client at a care setting with example ODS code RRR01 and Identifier (in this case a mailbox ID) “RRR01HC”. The certificate CSR should contain a subject Common Name (CN) value of “rrr01hc.RRR01.mesh-client.nhs.uk”.

To generate the private key and create the Java Keystore, type the following command replacing <Common Name> with the name of the certificate based on the naming convention above:

keytool -genkey -alias meshclient -keyalg RSA -keysize 2048 -keystore c:\MESH-APP-HOME\KEYSTORE\MESH.keystore -dname "CN=<Common Name>"

Using the example above the command would look like this:-

keytool -genkey -alias meshclient -keyalg RSA -keysize 2048 -keystore c:\MESH-APP-HOME\KEYSTORE\MESH.keystore -dname “CN=server1.RRR01.mesh-client.nhs.uk”

The command will prompt for a Keystore password and password confirmation and password for the private key. Return can be selected here to use the same password as the Keystore.

Please use the same password throughout even when asked for a new password.

Step 4

To generate the certificate signing request (CSR) type the following command:

keytool -certreq -alias meshclient -keystore c:\MESH-APP-HOME\KEYSTORE\MESH.keystore -file c:\MESH-APP-HOME\KEYSTORE\mesh.csr

The command will prompt for the Keystore password. Enter it.

Step 5

Create an email addressed to National Service Desk and if the certificate is to be used with the MESH API, a copy of the API Conformance Certificate must also be attached.

In the body of the email provide the following information:

• Name
• Company/Organisation
• Contact Number
• The MESH mailbox id(s) served by this certificate
• The certificate Common Name (CN):  identifier.ODS.[api].mesh-client.nhs.uk
• Reason for the Certificate (such as, New MESH client, Current certificate has or is about to expire)

If this is for a new MESH client, please also quote the reference number given to you by the NSD when your mailbox was created.

If the above information is not supplied, the request may be rejected.

Underneath this, paste the contents of the c:\MESH-APP-HOME\KEYSTORE\mesh.csr file including the lines for BEGIN and END CERTIFICATE REQUEST.

Send the email.

Step 6

The DIR team will reply with the certificate.

Using notepad, save the certificate by pasting the certificate including “--- BEGIN CERTIFICATE---“ and “--- END CERTIFICATE---“ to the file c:\MESH-APPHOME\KEYSTORE\mesh.crt

Step 7

To download the Spine Root certificate, navigate to the NHS Certificate Services interface.

Right click the “view here” link beside the “View Root CA in Base-64 ASCII” and download the file as NHS_Root_Authority.txt rename this rootca.Pem and copy to the mesh keystore folder.

Save the certificate in the <MESH-APP-HOME>\keystore directory with the default name of rootca.pem

Step 8

To add the root certificate to the Keystore to create the Truststore, type the following command:

keytool -importcert -file c:\MESH-APP-HOME\KEYSTORE\rootca.pem -alias rootca -keystore c:\MESH-APP-HOME\KEYSTORE\MESH.keystore

The command will prompt for the keystore password and confirm you trust this certificate. Enter “yes” to trust the certificate.

Step 9

To download the Spine SubCA certificate, navigate to the NHS Certificate Services interface and right click the “view here” link beside the “View NHS Level 1C in Base-64 ASCII (PEM)” and download the file as NHS_Level_1C.txt rename this subca.Pem and copy to the mesh keystore folder.

Save the certificate in the <MESH-APP-HOME>\keystore directory with the default name of subca.pem.

Step 10

To add the SubCA certificate to the Keystore to create Truststore, type the following command:

keytool -importcert -file c:\MESH-APP-HOME\KEYSTORE\subca.pem -alias subca -keystore c:\MESH-APP-HOME\KEYSTORE\mesh.keystore

The command will prompt for the keystore password and confirm you trust this certificate. Enter “yes” to trust the certificate.

Step 11

To add the MESH client certificate to the Keystore, type the following command:

keytool -importcert -trustcacerts -alias meshclient -file c:\MESH-APP-HOME\KEYSTORE\mesh.crt –keystore c:\MESH-APP-HOME\KEYSTORE\MESH.keystore

The command will prompt for the keystore password and confirm you trust this certificate.

Enter “yes” to trust the certificate.

Step 12

To verify the keystore contents, type the following command and enter the password:

keytool.exe -list -keystore c:\MESH-APP-HOME\KEYSTORE\MESH.keystore
Enter keystore password:

Try the same command again but press enter instead of entering the password.

The command should list the three certificates added to the keystore, if not the keystore won't work:

Keystore type: JKS
Keystore provider: SUN
Your keystore contains 3 entries
rootca, 03-May-2016, trustedCertEntry,
Certificate fingerprint (SHA1):
EC:7A:3B:3C:B7:95:EC:E9:56:C5:A7:BE:C4:20:4A:29:8F:EB:23:6C
subca, 03-May-2016, trustedCertEntry,
Certificate fingerprint (SHA1):
B0:1F:20:80:4D:DB:F5:84:E4:47:77:87:3D:1C:83:40:0C:25:6B:C3
meshclient, 03-May-2016, PrivateKeyEntry,
Certificate fingerprint (SHA1):
04:47:30:E9:67:EA:D9:F0:87:F5:AA:2C:E7:5D:CC:4C:4C:5B:93:9C

Step 13

You now have your certificate to access MESH. To continue MESH installation, please refer back to our MESH client installation guidance.

For MESH API users only

Your installation of the MESH certificate, onto systems that utilise the MESH Server API, depends on how your system is configured. This is why we recommend you have technical support for this type of MESH access.

The certificate request process is a subset of the steps performed to the process to request a MESH client certificate detailed above.

To generate the private key and the CSR to submit the National Service Desk, follow the steps above. Ensure you use a slightly different Common Name naming convention for API use: Identifier.ODScode.api.mesh-client.nhs.uk.

Your ODS code is a unique code given to all health and social care services. If not already known, it may be found via the ODS portal which requires HSCN/N3 access.

The identifier is client specific and will not be verified as part of the MESH client authentication. If this mailbox is in addition to the original mailbox on installation, we advise to check with the MESH client installer if they have a preference.

The returned email from the DIR team will comprise the certificate in PEM format. This can then be installed in the client application.

Depending on how the client system authenticates to the MESH server, the Root CA and Sub CA certificates may also need to be installed in the client application. These can be downloaded from the NHS Certificate Service website.

If the private key for the certificate is required, this can be exported from the Keystore using the following command, where the <password> is a password for the private key file:

keytool -importkeystore -srckeystore c:\MESH-APP-HOME\
KEYSTORE\MESH.keystore -destkeystore keystore.p12 -deststoretype PKCS12 -srcalias meshclient

The command will prompt for the password for the output file and the Keystore password.

The format of the private key can be converted to PEM format using the openssl command:

openssl pkcs12 -in keystore.p12 -nokeys -out cert.pem

and to export the unencrypted private key:

openssl pkcs12 -in keystore.p12 -nodes -nocerts -out key.pem

This section is for those who already have a Spine End-Point Registration (EPR) certificate.

You will have an EPR certificate if you use services that currently connect to the Spine Messaging interfaces using an EPR certificate. This certificate can also be used to connect to MESH client.

These steps assume that the EPR certificate and private key is available from the DIR team using the Spine SubCA .

Step 1: Install prerequisites

You must first:

• download OpenSSL for Windows from the Source Forge website (currently version 1.0.2j) 
• install Open SSL for Windows
• select Destination Location (C:\Program Files\GnuWin32)
• select Components: Only the binaries are required
• check your windows installation for msvcrt.dll and msvcp60.dll. These should be stored in C:\WINDOWS\system32 if downloaded from the Microsoft website.

Step 2: Configure a command window (cmd)

Open a cmd window as an administrator, right click cmd and select “run as” and select administrator. 

You should now see a cmd window and be able to use everything within the same directory. It is necessary to add openssl and the jre7bin directory to the path (for the keytool). Do this by issuing the following command.

PATH = %PATH%;C:\Program Files\GnuWin32\bin;C:\Program Files\Java\jre7\bin 

If working on a 64 bit system, either of these directories may reside in Program Files (x86). If this is the case a simple substitution is required in the command from Program Files to Program Files (x86).

Now everything can be done within a single working directory.

Step 3: Convert file EPR private key to PEM format

Your EPR certificate should be in PEM format. Depending on how the EPR certificate was requested, it may not be in this format.  An example private key in PEM format is:

Use the openssl command to convert to the correct format. Below is an example of a command to convert an Rivest-Shamir-Adleman (RSA) cryptosystem key to PEM format:

openssl rsa -in .\ssh\id_rsa -outform pem > id_rsa.pem

openssl x509 -inform der -in certificate.cer -out certificate.pem 

Step 4: Create the Java Keystore

Ensure your private key and certificate are in the file mykey.pem in PEM format. Copy these files into the <MESH-APP-HOME>/ keystore directory.

Type the following command to create the Keystore:

openssl pkcs12 -export -in mycert.pem -inkey mycert.pem > MyCert.p12

This command may prompt for a password. A password must be specified as this will be required by the MESH client to access the Keystore later.

The .p12 file can then be used to create a Keystore using the keytool command below:

keytool -importkeystore -srckeystore MyCert.p12 -destkeystore
MESH.keystore -srcstoretype pkcs12

The keystore command will prompt for destination keystore password (used by the MESH client) and may prompt for the source keystore password of the private key if defined. You now have a keystore named MESH.keystore containing the certificate/key you need.

Step 5: Download the Spine SubCA certificate

Visit the NHS Certificate Services interface 

Click the "Install New SubCA cert (PEM format)" link from the menu (left panel).

Save the certificate in the <MESH-APP-HOME>/keystore directory with the default name of subca.pem

Step 6: Add the subca certificate to the Keystore

To add the root certificate to the Keystore to create Truststore you'll need to use the keytool command:

keytool -importcert -file subca.pem -alias subca -keystore MESH.keystore

Step 7: Download the Spine Root certificate

Visit the NHS Certificate Services interface

Click the "Install RootCA cert (PEM format)" link from the menu (left panel).

Save the certificate in the <MESH-APP-HOME>/keystore directory with the default name of rootca.pem.

Step 8: Add the root certificate to the Keystore

Create Truststore by adding the root certificate to the Keystore. Use the command: 

keytool -import -file rootca.pem -alias rootca -keystore MESH.keystore

The Keystore creation is complete and can now be used with the MESH client.

Step 9: Verify installation

To verify that both certificates have been added to the Keystore, the following command should be run. The command will prompt for the Keystore password specified above:

keystore –list –keystore MESH.keystore

The output should confirm two entries, the EPR and root certificates. The output should be similar to that shown below:

>keytool -list -keystore mesh.jks
Enter keystore password:
Keystore type: JKS
Keystore provider: SUN
Your keystore contains 3 entries
rootca, 03-May-2016, trustedCertEntry,
Certificate fingerprint (SHA1):
EC:7A:3B:3C:B7:95:EC:E9:56:C5:A7:BE:C4:20:4A:29:8F:EB:23:6C
subca, 03-May-2016, trustedCertEntry,
Certificate fingerprint (SHA1):
B0:1F:20:80:4D:DB:F5:84:E4:47:77:87:3D:1C:83:40:0C:25:6B:C3
mesh, 03-May-2016, PrivateKeyEntry,
Certificate fingerprint (SHA1):
04:47:30:E9:67:EA:D9:F0:87:F5:AA:2C:E7:5D:CC:4C:4C:5B:93:9C

You now have your certificate to access MESH. To continue MESH installation, please refer back to our MESH client installation guidance.