How to use an EPR certificate with the MESH client

Document filename: How to use an EPR certificate with the MESH client Directorate / Programme Operations and Assurance Services Project Spine Services/ MESH Document Reference <insert> Project Manager Andrew Meyer Status Issued Owner Ash Raines Version 2.0 Author Stuart Baskerville Version issue date 05/05/2016 How to use an EPR certificate with the MESH client

Document Management Revision History Version Date Summary of Changes 0.1 27/04/2016 Initial version. 0.2 03/05/2016 Updated following review. 1.0 03/05/2016 Issued 1.1 05/05/2016 Updated to remove MESH client certificate sections 2.0 05/05/2016 Issued Reviewers This document must be reviewed by the following people: Reviewer name Title / Responsibility Date Version Simon Richards DTS Service Owner Marta Raper Kathryn Common Spine2 Project Manager Senior Communications Officer Approved by This document must be approved by the following people: Name Signature Title Date Version Ash Raines Glossary of Terms Term / Abbreviation API CN CSR DER DIR DTS EPR HSCIC JVM Keystore MESH What it stands for Application Programming Interface Common Name Certificate Signing Request Distinguished Encoding Rules Deployment Issue and Resolution Data Transfer Service End Point Registration Health and Social Care Information Centre Java Virtual Machine Repository for security certificates Messaging Exchange for Social Care and Heath Page 2 of 13

MOLES ODS OpenSSL PEM PKCS12 RA RATS RBAC RSA SSL MESH Online Enquiry Service Organisation Data Service Open source implementation of SSL Privacy Enhanced Mail Public-Key Cryptography Standards defined for transporting private keys and certificates Registration Authority Registration and Tracking Service Role-Based Access Control Rivest-Shamir-Adleman cryptosystem Secure Socket Layer - standard for establishing an encrypted link between a web server and a client Document Control: The controlled copy of this document is maintained in the HSCIC corporate network. Any copies of this document held outside of that area, in whatever format (e.g. paper, email attachment), are considered to have passed out of control and should be checked for currency and validity. Page 3 of 13

Contents 1 Introduction 5 1.1 Purpose of Document 5 1.1 Background 5 2 Overview 6 2.1 What is a certificate and how it is used in MESH? 6 2.2 What certificate can be used by MESH? 6 3 Spine end-point certificates 7 3.1 How to install the EPR certificate for the MESH client 7 3.2 How to install the EPR certificate for the MESH API 11 4 Contact HSCIC 12 5 Appendix A list of commands to create the MESH Keystore from an EPR certificate 13 Page 4 of 13

1 Introduction 1.1 Purpose of Document The purpose of this document provides an explanation of how client certificates are used in the MESH system and how users use an existing End Point Registration (EPR) certificate and install in their MESH client installation. For users wishing to request a new MESH client certificate, please refer to the MESH Client Certificates Manual Steps document for details. The intended audience for this document is DTS installers and users to assist in transition from DTS to MESH. 1.1 Background The BT contract for provision of the DTS expires on 30 June 2016. The Health and Social Care Information Centre (HSCIC) has developed a replacement for DTS which will be an inhouse managed service. This transition enabled HSCIC to introduce a number of service improvements and deliver cost savings. In January 2016 we transitioned the DTS Central Service from BT to the HSCIC MESH Service. This means that the service is now operated and managed by the HSCIC. The transition will also enable the new service to adapt to emerging user requirements in a more flexible and efficient manner. Page 5 of 13

2 Overview The DTS client uses a single certificate on all client installations to connect to the central service so it can send and receive messages. This requirement has remained unchanged following the migration to the MESH central service. However, to improve security levels to meet the current Spine Core security requirements, all MESH clients and MESH Server API installations will require a specific local certificate. This is because the new MESH client/mesh Server API rely on mutual authentication for higher security (both ends check that the other end has a valid certificate) as part of the logon process. 2.1 What is a certificate and how it is used in MESH? Digital certificates are a means by which consumers and businesses can use the security applications of Public Key Infrastructure (PKI). PKI comprises of technology that enables secure e-commerce and internet based communication. The MESH client uses the certificate when connecting to the MESH server to send and receive messages. At a later date, the certificate will also be used by the MESH server to enhance mailbox authentication by checking the certificate used is associated with that mailbox. 2.2 What certificate can be used by MESH? The MESH system will allow two types of certificate to be used: New MESH client certificate - for users that currently do not use an EPR certificate, a MESH-specific certificate will be required. These will be issued by the HSCIC s Deployment Issue and Resolution (DIR) team. Details of how to contact the team is available on the HSCIC website. Spine End-Point Registration (EPR) Certificate - if services currently connect to the Spine Messaging interfaces using an EPR certificate, this certificate can also be used for connection by the MESH client. Page 6 of 13

3 Spine end-point certificates If services currently connect to the Spine Messaging interfaces using an EPR certificate, this certificate can also be used for connection by the MESH client. 3.1 How to install the EPR certificate for the MESH client These steps assume that the EPR certificate and private key is available from the DIR team using the Spine SubCA. To create the Keystore, it is necessary to generate a PKCS12 database consisting of the private key and this certificate. The following steps should be performed to generate the PKCS12 database: 3.1.1 Install prerequisites The following prerequisites need to be performed: Download OpenSSL for Windows from the Source Forge website (currently version 0.9.8h) 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. 3.1.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 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). Now everything can be done within a single working directory. 3.1.3 Convert file EPR private key to PEM format Depending on how the EPR certificate was requested, it may not be in PEM format. An example private key in PEM format is shown below: -----BEGIN ENCRYPTED PRIVATE KEY----- MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDg MBQGCCqGSIb3DQMHBAgD1kGN4ZslJgSCBMi1xk9jhlPxPc 9g73NQbtqZwI+9X5OhpSg/2ALxlCCjbqvzgSu8gfFZ4yo+ AX0R+meOaudPTBxoSgCCM51poFgaqt4l6VlTN4FRpj+c/Wc blk948uada/bwvmzjxfy4tztah0cuqlaldoqbzu8twe7wd Page 7 of 13

H0ga/iLNvWYexG7FHLRiq5hTj0g9mUPEbeTXuPtOkTEb/0 GEs= -----END ENCRYPTED PRIVATE KEY----- Figure 1 Private Key in PEM format To convert to the correct format the openssl command should be used. Below is an example of a command to convert an RSA (Rivest-Shamir-Adleman) cryptosystem key to PEM format: openssl rsa -in.\ssh\id_rsa -outform pem > id_rsa.pem 3.1.4 Convert file EPR certificate to PEM format Depending on how the EPR certificate was requested, it may not be in PEM format. An example certificate in PEM format is shown below: -----BEGIN CERTIFICATE----- MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDg MBQGCCqGSIb3DQMHBAgD1kGN4ZslJgSCBMi1xk9jhlPxPc 9g73NQbtqZwI+9X5OhpSg/2ALxlCCjbqvzgSu8gfFZ4yo+ AX0R+meOaudPTBxoSgCCM51poFgaqt4l6VlTN4FRpj+c/Wc blk948uada/bwvmzjxfy4tztah0cuqlaldoqbzu8twe7wd H0ga/iLNvWYexG7FHLRiq5hTj0g9mUPEbeTXuPtOkTEb/0 GEs= -----END CERTIFICATE ----- Figure 2 Certificate in PEM format To convert to the correct format the openssl command should be used. Below is an example of a command to convert an RSA key to pem format: openssl x509 -inform der -in certificate.cer -out certificate.pem 3.1.5 Create the Java Keystore Assuming the private key is in the file mykey.pem in PEM format. The certificate is in mycert.pem, which is also in PEM format. Copy these files into the <MESH-APP- HOME>/keystore directory. Type the following command to create the Keystore. This command prompts for a password. A password must be specified as this will be required by the MESH client to access the Keystore: openssl pkcs12 -export -in mycert.pem -inkey mycert.pem > MyCert.p12 The openssl command may prompt for a password if the private key was created with a password. This is used 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. Page 8 of 13

3.1.6 Download the Spine SubCA certificate Navigate to the NHS Certificate Services interface https://portal.national.ncrs.nhs.uk/esw/ Click the Install New SubCA cert (PEM format) link from the menu (left panel). Figure 3 Download the rootca.der (ESW) Save the certificate in the <MESH-APP-HOME>/keystore directory with the default name of subca.pem 3.1.7 Add the subca certificate to the Keystore To add the root certificate to the Keystore to create Truststore, the keytool command is used: keytool -importcert -file subca.pem -alias subca -keystore MESH.keystore 3.1.8 Download the Spine Root certificate Navigate to the NHS Certificate Services interface https://portal.national.ncrs.nhs.uk/esw/ Click the Install RootCA cert (PEM format) link from the menu (left panel). Page 9 of 13

Figure 4 Download the rootca.der (ESW) Save the certificate in the <MESH-APP-HOME>/keystore directory with the default name of rootca.pem 3.1.9 Add the root certificate to the Keystore To add the root certificate to the Keystore to create Truststore, the keytool command is used: keytool -import -file rootca.pem -alias rootca -keystore MESH.keystore The Keystore creation is complete and can now be used with the MESH client. 3.1.10 Step 4 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 Page 10 of 13

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 The Keystore can now be used by the MESH client. To configure the MESH client, copy the MESH.keystore to the <MESH-APP-HOME>/keystore folder in the MESH client installation. Next the meshclient.cfg file will need to be updated to use the MESH Keystore. The following values will need to be updated: KeyStorePath KeyStorePassword This location is for the MESH keystore file e.g. C:\MESH-APP-HOME\KEYSTORE\mesh.keystore This is the Keystore password supplied with the user account details If using the MESH client on a non-windows based server, the above process can be used and the MESH.keystore copied to the server and configured in the same way. 3.2 How to install the EPR certificate for the MESH API If using the MESH Server API to connect to the MESH service, the EPR certificate should be installed into the client software so that a mutual authentication session can be established with the MESH server. This installation will vary depending on how the client software is configured. Page 11 of 13

4 Contact HSCIC For further information a dedicated MESH page has been created on the HSCIC website at: http://systems.hscic.gov.uk/ddc/mesh. If users have specific question related to MESH please contact the National Service Desk. Page 12 of 13

5 Appendix A list of commands to create the MESH Keystore from an EPR certificate Here is the list of commands to create the MESH keystore: openssl rsa -in.\ssh\id_rsa -outform pem > id_rsa.pem openssl x509 -inform der -in certificate.cer -out certificate.pem openssl pkcs12 -export -in mycert.pem -inkey mycert.pem > MyCert.p12 keytool -importkeystore -srckeystore MyCert.p12 -destkeystore MESH.keystore -srcstoretype pkcs12 Download the SubCA - https://portal.national.ncrs.nhs.uk/esw/certs/subca.pem.txt to c:\mesh-app-home\keystore\subca.pem keytool -importcert -file subca.pem -alias subca -keystore mesh.keystore Download the RootCA - https://portal.national.ncrs.nhs.uk/esw/certs/rootca.pem.txt and save the contents to c:\mesh-app-home\keystore\rootca.pem keytool -importcert -file rootca.pem -alias rootca -keystore mesh.keystore To confirm contents of the keystore keytool.exe -list -keystore c:\mesh-app-home\keystore\mesh.keystore Page 13 of 13