Details of the API security model and supported protocols

Secure connection negotiation

Provider systems:

• SHALL only accept connections from the Spine Secure Proxy (SSP)

• SHALL authenticate the SSP prior to responding to any requests using its client certificate

• SHALL only permit approved supported ciphers to be utilised

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

• SHALL only accept requests for its allocated address space identifier (ASID), as specified by the Ssp-To header on its matching endpoint URL

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

• SHALL check for the presence of all SSP headers

• SHALL check that an authorization bearer token is present and correctly formed

• MAY authorise access to API endpoints through examining acceptable values in the JSON Web Tokens (JWT) requested_scope claim

• SHALL risk-manage the security of the endpoints of the Transport Layer Security (TLS) communications, so as to prevent inappropriate risks (for example, audit logging of the GET parameters into an unprotected audit log)

Security testing

Provider systems SHALL 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 protocol guidance have been agreed:

• suppliers SHALL use TLS1.2 with mutual authentication enabled for all message interactions
• suppliers SHALL NOT use TLS1.0, TLS1.1, SSLv2 and SSLv3

Supported ciphers

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

Important: The list of supported ciphers is ordered by preference (that is, the first item being the most preferred).

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

Note: Galois/Counter Mode (GCM) suites are preferred as these are resistant to timing attacks¹.

Important: A Java Runtime Environment 8 (or above) and/or an up to date version of OpenSSL is required to support the GCM cipher suites.

¹Digitcert - SSL Support Enabling Perfect Forward Secrecy

Tomcat OpenSSL support using the Apache Portable Runtime (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 web page for more details.

Client certificates (TLS/mutual authentication (MA))

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

Provider and consumer systems SHALL only accept client certificates with a valid Spine ‘chain of trust’ (that is, linked to the Spine SubCA and RootCA).

Provider and consumer systems SHALL only accept client certificates which have not expired or been revoked.

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

Response headers

Provider systems SHALL 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 SHALL 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]
/Practitioner	organization/*.[read/write]
/Location	organization/*.[read/write]
/Slot	organization/*.[read/write]
/DocumentReference	patient/*.[read/write]
/Binary	patient/*.[read/write]

External policy documents

Name	Author	Version	Updated
Approved Cryptographic Algorithms Good Practice Guidelines	NHS Digital	v4.0	July 2016
Warranted Environment Specification (WES)	NHS Digital	v1.0	June 2015