How to use the MESH Certificate Enrolment Tool

Transcription

1 Document filename: How to use the MESH Certificate Enrolment Tool Directorate / Programme Operations and Project Assurance Services Spine Services/ MESH Document Reference <insert> Project Manager Andrew Meyer Status Issued Owner Ash Raines Version 3.1 Author Stuart Baskerville Version issue date 08/08/2017 How to use the MESH Certificate Enrolment Tool

2 Document Management Revision History Version Date Summary of Changes /04/2016 Initial version /05/2016 Updated following review /05/2016 Issued /05/2016 Removed EPR certificate instructions to a separate document /05/2016 Updated following review /05/2016 Updated following review /05/2016 Issued /05/2016 Remove initial dialog prompt /05/2016 Issued /08/2107 Keystore Password revised text 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 What it stands for Application Programming Interface Common Name Certificate Signing Request Distinguished Encoding Rules Deployment Issue and Resolution Data Transfer Service Page 2 of 14

3 EPR HSCIC JVM Keystore MESH MOLES ODS OpenSSL PEM PKCS12 RA RATS RBAC RSA SSL End Point Registration Health and Social Care Information Centre Java Virtual Machine Repository for security certificates Messaging Exchange for Social Care and Heath 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, attachment), are considered to have passed out of control and should be checked for currency and validity. Page 3 of 14

4 Contents 1 Introduction Purpose of Document Background 5 2 Overview What is a certificate and how it is used in MESH? What certificate can be used by MESH? MESH client and MESH Server API 6 3 MESH client certificates How to set up MESH-specific certificates How to install the MESH certificate for the MESH client How to install the MESH certificate for the MESH Server API 13 4 Contact HSCIC 14 Page 4 of 14

5 1 Introduction 1.1 Purpose of Document The purpose of this document is to provide an explanation of how client certificates are used in the MESH system and how users request and install their MESH client certificate using the MESH Client Certificate Enrolment Tool. The intended audience for this document are installers that need to understand how MESH client certificates are requested. 1.1 Background The BT contract for provision of the DTS expires on 30 June 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 14

6 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: Spine End-Point Registration (EPR) Certificate - if services currently connect to the Spine Messaging interfaces using an EPR certificate, this certificate can o be used for connection by the MESH client. 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 here. 2.3 MESH client and MESH Server API If using the MESH Java client to send and receive messages, the certificate will need to be installed into a Keystore. A Java Keystore (JKS) is a repository of security certificates that are used by Java applications. If using the MESH Server API, the certificate will need to be installed where the calling application is able to use the certificate to establish a mutual authentication session with the MESH server. Page 6 of 14

7 3 MESH client certificates This section details how to request a MESH client certificate for use with the MESH client or MESH server API. 3.1 How to set up MESH-specific certificates For users that currently do not use an EPR certificate, a MESH client certificate will be required. A certificate request will need to be created for a certificate to be issued. MESH client certificates are issued by HSCIC s DIR team. HSCIC have produced a utility that will simplify the certificate request process and is available to download from the MESH website. The utility is Windows-based and creates the certificate request which is then ed to HSCIC. 3.2 How to install the MESH certificate for the MESH client Download the utility To request a MESH client certificate, the MESH certificate Enrolment Assistant needs to be downloaded from the MESH website. Download the zip file and extract it to your Desktop Install prerequisites The client is a single Windows executable file and requires the following to be installed in order to run: Microsoft.Net Framework version 4 or later available to download from Microsoft. JVM version 1.6 or later available to download from Oracle. Page 7 of 14

8 3.2.3 Run the MESH certificate Enrolment Assistant On running the utility, will display the following dialog: Figure 1 MESH certificate Enrolment Assistant initial screen. Step 1 requires the Common Name (CN) of the MESH client certificate to be entered. The MESH-specific certificate for MESH clients will be based on the Organisation Data Service (ODS) code of the end system. It will follow the optionallocalidentifier.odscode.mesh-client.nhs.uk naming convention. For example, for a MESH client at a care setting with example ODS code RRR01 and local Identifier Server1. MHS will be registered using "MHS Only" product called "MESH MHS" in ODS namespace X26xxx (pending from ODS team). The certificate CSR should contain a subject Common Name (CN) value of server1.rrr01.mesh-client.nhs.uk. If users do not know their ODS code, this can be found by on the HSCIC website. Please note an N3 connection is required to connect to the look up service. Enter the CN value as shown below by specifying the ODS code, Local Identifier and System Type of either Client for MESH client use or API if requesting a certificate to be used with a system using the MESH Server API. In the example below, the MESH client certificate is being requested with an ODS Code of X26001 (HSCICs ODS code) and NCMPC is the name of the server that will be running the MESH client. The local identifier will depend on the infrastructure running the MESH client or API. For example, this could be name of the datacentre the MESH system is running enabling the same certificate to be installed on multiple servers. The local identifier Page 8 of 14

9 is client specific and will not be verified as part of the MESH client or MESH Server API authentication. Select the Generate button to create the Certificate Signing Request (CSR) Figure 2 MESH certificate Enrolment Assistant CSR Generation. The CSR is written to the Computer s paste buffer as well as a text file called csr.txt on the user s Desktop. The CSR will look similar to the request shown below: -----BEGIN CERTIFICATE REQUEST----- MIICgTCCAWkCAQAwPjE8MDoGA1UEAwwzU2VydmVyMS5SUlIwMS5tZXNoLWNsaWVu dc5uahmudwsubwvzac1jbgllbnqubmhzlnvrmiibijanbgkqhkig9w0baqefaaoc AQ8AMIIBCgKCAQEA6Svg4Jr2/k3JNnj7K543SGZhEdUYZS1mllX6OcTJTlotX6h5 P5JpPcHxx5S26DylZGuSttOmmqPPcD9znTdJg9JawIkiVfGv/OBbIVF0knMLs0Sl 106/qpvH8UJz1SO18J5Q8XNOgk2nnzM1heeMiCqOqngrSlE91wngR261hySq+//T r+obkeuc8sath5fumd3e8+z7ar488ig2drzoi/qdulbkmxihyd/pcpkasfeisghx vjetftuobpi/n+tc/+68ayhgbhtfjrxhvb0dcxo78zdpqqwy/zuosy2gpgarr5o0 SurA1Z90B2+Q2muoRIH7m7Kg2mPJAgwTdiEDWwIDAQABMA0GCSqGSIb3DQEBBQUA A4IBAQDXxRSyry/7Qprp1EOuirtK51CXEFzBg6obcGtS01e9Qe7EMU1LzAZVDGwJ osvnminy5j7u/8hy6zgqdb+7o5eupvi70fgn0vz/mmwnyj1t5vjzbjvwl9hthatj EoI4mut6BtIdEsW/xrpxeRwbXXB6ugDplJSuogmq/GKZGzXFJVJmz5b9UBZWLry0 +tyokedwo7+ulawtuum/fbcvh7ceay/pyoupzymfyh8k2ghtmswxohgrpoqcspol 83ptawgSbIqTcf15MZ1Q5mPDAO6qe2Jry+OqoHptwB1skAZTm9Ck9cF/CM9cTqOY ciboavbeljioj+mxewvk0ox3cnmf -----END CERTIFICATE REQUEST----- Figure 3 MESH certificate Enrolment Assistant CSR. This CSR needs to be ed to the DIR team at dir@hscic.gov.uk in the body of the as shown below. Page 9 of 14

10 To verify the identity of the requesting organisation, the subject field needs to include the Name of the Organisation and a MESH/DTS Mailbox name in the following format: Organisation: <Organisation Name>, Mailbox: <Mailbox name>. The screenshot below shows the CSR from HSCIC which have the MESH/DTS mailbox of dtshixhc. NOTE: If this information is not supplied with the CSR, the request will be rejected and the certificate will not be issued. Figure 4 MESH certificate Enrolment Assistant CSR The DIR team will reply with the certificate as shown below: Page 10 of 14

11 Figure 5 MESH certificate Enrolment Assistant Certificate Response To create the Java Keystore, the certificate including the BEGIN CERTIFICATE and --- END CERTIFICATE --- should be pasted into the MESH certificate Enrolment Assistant as shown below: Page 11 of 14

12 Figure 6 MESH Certificate Enrolment Assistant Create KeyStore The password for the Keystore also needs to be entered. This password will be used to open the Keystore by the MESH client and will need to be added to the MESH client configuration. This password is defined locally and should comprise only alpha numeric characters. Upper and lower case characters are acceptable but special characters such as the sign should be avoided. Select the Build Keystore button and the MESH client certificate together with the Spine Root CA and SubCA certificates will be added to the Keystore. The Keystore will be written to the user s Desktop called MESH.keystore. The MESH Certificate Enrolment Assistant will display an expiry date for the certificate. The MESH certificates are valid for three years and will need to be renewed before the current certificate expires to maintain connectivity to MESH. Figure 7 MESH Certificate Enrolment Assistant Create Keystore Finally, the utility will confirm the Keystore has been created successfully and stored in the user s Desktop: Page 12 of 14

13 Figure 8 MESH Certificate Enrolment Assistant Create Keystore Configure the MESH client 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 entered into the Enrolment Assistant 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.3 How to install the MESH certificate for the MESH Server API If you are using the MESH Server API to connect to the MESH service, the same process detailed in section above can be followed. The differences to this process are: The Common Name of the certificate must comply to the following naming convention with the additional api in the name: The MESH-specific certificate for MESH APIs will be based on the ODS code of the end system. It will follow the optionallocalidentifier.odscode.api.mesh-client.nhs.uk naming convention. For example, for a MESH client at a care setting with example ODS code RRR01 and local Identifier Server1. MHS will be registered using "MHS Only" product called "MESH MHS" in ODS namespace X26xxx (pending from ODS team). The certificate CSR should contain a subject CN value of server1.rrr01.api.mesh-client.nhs.uk. Unless using a Java Keystore, once the certificate is sent by the DIR team, this can then 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 13 of 14

14 4 Contact HSCIC For further information a dedicated MESH page has been created on the HSCIC website at: If users have specific question related to MESH please contact the National Service Desk. Page 14 of 14