Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

Security guidance

Details of the API security model and supported protocols.

Secure connection negotiation

Provider Systems:

  • MUST only accept connections from the Spine Security Proxy (SSP)

  • MUST authenticate the SSP prior to responding to any requests using it’s client certificate

  • MUST only permit approved supported ciphers to be utilised

  • MUST only accept encrypted connections and drop connection attempts presented over insecure protocols

  • MUST only accept requests for it’s allocated ASID, as specified by the Ssp-To header, on it’s matching endpoint URL

  • MUST check that the Ssp-InteractionID value is consistent with the endpoint being requested

  • MUST check for the presence of all SSP headers

  • MUST check that an authorization bearer token in present and correctly formed

  • MAY authorise access to API endpoints through examining acceptable values in the JWT requested_scope claim

Security testing

Provider systems MUST as a minimum be tested against the OWASP top 10 web application vulnerabilities.

Provider systems SHOULD be tested for vulnerability to Denial of Service (DoS) and hardened against such attacks.

Secure Socket Layer (SSL), and Transport Layer Security (TLS) protocols

After consultation with the Infrastructure Security, Operational Security and Spine DDC teams the following SSL protocols MUST be supported.

  • TLSv1.2

Supported ciphers

After consultation with the Infrastructure Security, Operational Security and Spine DDC teams the following SSL protocols MUST be supported.

  • AESGCM+EECDH
  • AESGCM+EDH
  • AES256+EECDH
  • AES256+EDH

1Digitcert - SSL Support Enabling Perfect Forward Secrecy

Tomcat OpenSSL support using the APR/native provider

  • SSLCipherSuite = AESGCM+EECDH,AESGCM+EDH,AES256+EECDH,AES256+EDH
  • SSLHonorCipherOrder = true
  • SSLProtocol = TLSv1.2
  • SSLVerifyClient = require

Please see the Tomcat Config HTTP SSL Support webpage for more details.

Client certificates (TLSMA)

Provider and Consumer systems MUST only accept client certificates issued by the NHS Digital Deployment Issue and Resolution (DIR) team.

Provider and Consumer systems MUST only accept client certificates with a valid Spine ‘chain of trust’ (i.e. linked to the Spine SubCA and RootCA).

Provider and Consumer systems MUST only accept client certificates which have not expired or been revoked.

Provider and Consumer systems MUST check the FQDN presented in the client certificate is that of the Spine Security Proxy (SSP).

Response headers

Provider systems MUST ensure no sensitive data leaks into a browser cache by setting the following cache headers on all responses:

Cache-Control: no-store

Authorisation of access to endpoints

The primary purpose of the JWT claims is to enable cross organisation provenance information to be transmitted for auditing purposes.

Provider systems MAY choose to use the value of the requested_scope claim to authorise access to APIs. In this case, provider systems MUST apply authorisation logic to endpoints as follows:

Endpoint Acceptable values of requested_scope JWT claim
/Patient patient/*.[read/write]
/Organization organization/*.[read/write]
/Appointment patient/*.[read/write]
/Task organization/*.[read/write]
/Practitioner organization/*.[read/write]
/Location organization/*.[read/write]
/Slot organization/*.[read/write]

External Documents / Policy Documents

Name Author Version Updated
Approved Cryptographic Algorithms Good Practice Guidelines NHS Digital v4.0 July 2016
Warranted Environment Specification (WES) NHS Digital v3.2018 2018
Tags: development

All content is available under the Open Government Licence v3.0, except where otherwise stated