1.7 Confidentiality and Integrity

REQUIRED

All communications to or from an API must be over TLS 1.2 or higher. Other versions of TLS and SSL should be disabled. This provides a recognised level of confidentiality that covers all communications between all components.

The consuming application must validate the TLS certificate chain when making requests to protected resources, including checking the Certificate Revocation List (CRL).

1.7.2 Token Audience and State Parameters (Integrity)

Token security is particularly important to OAuth implementations; the reasons and mitigations are explained below.

1.7.2.1 Audience Information (Draft)

Because Bearer Tokens are not aligned to any one client, they are open to reuse and misuse. To help prevent misuse of the OAuth Bearer token (Access Token) the Audience Information draft profile links the token to a specific Resource Server and scope. To do this, it defines a new ‘audience’ header which is used by the client to indicate what Resource Server (or Servers) it wants to access.

The client request has the required Resource Server identified in the new ‘audience’ field. The Resource Server receives the request and gets the Authorisation server to validate it and return an access token to the client with that audience as part of the token’s scope.

1.7.2.2 State

State is also a parameter that can be used during the authorisation grant stage to provide a level of security to address possible man-in-the-middle attacks. The state parameter is a string of random letters and numbers that is sent to the Authorisation Server by the client when requesting an authorisation code. It is sent back to the client with the Authorisation Code and should be verified by the client application to confirm the authenticity of the response i.e. it came from the authorisation server to which the request was sent.

Note: State is used to provide a level of integrity when using the standard format of bearer tokens. The confidence in the level of integrity can be increased in JWT tokens are used for bearer tokens. (See Integrity sections below).

1.7.3 Content Encryption (Confidentiality)

If content needs only to be visible to specific consumer end points, use encryption. However, if content only needs to be guaranteed untampered and/or from a specific source (e.g. provider) then use content signing. Content encryption enables all or part of a JSON payload to be readable only by the target consumer(s). This is useful where the content being carried by the API is sensitive, and the API request or response transits multiple stopping points. Whilst TLS protects the payload in transit, it only applies to each point to point connection between components (e.g. mobile app to API gateway). If transit components are not totally under the provider’s control, it can be worthwhile performing body encryption. E.g. it may be sensible to encrypt credit card details passed between consumer and provider backend systems.

It is also worth considering how much protection the information needs whilst at rest (e.g. information received from consuming applications, caches) and whether some content should be stored encrypted.

Encryption is only worthwhile implementing when data sensitivity or data protection requirements drive it, as encryption is computationally intensive. It also makes it more difficult for protection mechanisms, such as API gateways, to validate and transform API content. When only the integrity of the content passed needs to be ensured, consider using Content Signing (section 1.7.4) instead.

There are many existing ways of encrypting message content, built into code libraries and development tools. It is Required that any content encryption adhere to the standard algorithms laid out in NZISM (HMAC Algorithms).

1.7.4 Content Signing (Integrity)

Content signing is used to assure content integrity and proof of authorship. It can apply to the whole body of the JSON message or specific elements of that content e.g. credit card details. There are many approaches to content signing and the most appropriate approach is requirements-dependent. Standard signing algorithms exist within coding libraries, and JWT has a body which can contain verifiable (signed) JSON fields. API Gateways can also be configured to sign content objects in transit, if provided with an appropriate private key.

Signing has less of a computational overhead than encryption, but can still affect performance, so it is advisable that it be used only when and where needed.

For APIs, this is a developing area: there are standards currently under development to address content signing:

  • Message Authentication Code - OAuth 2.0 Message Authentication Code (MAC) Tokens (draft)
  • Proof of Possession - OAuth 2.0 Proof-of-Possession (PoP) Security Architecture (draft)

It is Recommended that where Bearer Tokens are used, they should be signed using JSON Web Tokens (JWT) as defined in:

  • JSON Web Token (JWT) RFC 7519
  • JSON Web Signature (JWS) RFC 7515
  • JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants RFC 7523

1.7.5 Non Repudiation (Integrity)

Non repudiation covers the means to ensure that a consumer cannot deny making a request and, similarly, a provider cannot claim they did not send a response. To aid non-repudiation for APIs, it is important to ensure credentials are not shared between consumers and to perform comprehensive logging of API request/responses.

Digital signatures are useful for not just guaranteeing authenticity and integrity, but also supporting non-repudiation.

Page last updated: 18/12/2016