Content Encryption (Confidentiality)

If content needs only to be visible to specific consumer endpoints, use encryption. However, if content only needs to be guaranteed untampered and/or from a specific source (e.g. the bank) 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 bank’s control, it can be worthwhile performing body encryption.

E.g. it may be sensible to encrypt credit card details passed between consumer and bank’s 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 adheres to the standard HMAC algorithms.

Nonrepudiation covers the means to ensure that a consumer cannot deny making a request and, similarly, the API provider cannot claim it 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.