API Bites — Data Confidentiality, Integrity and Non-Repudiation
An excursion from the parent article API Bites — Tactics to Secure Sensitive APIs
Data Confidentiality, Integrity and Non-Repudiation
Occasionally, regulatory controls or controls-by-agreement will dictate special handling of data to ensure Data Confidentiality, Integrity and/or Non-Repudiation. These measures come with a significant maintenance burden and should be employed to meet a validated, documented data security requirement only.
There are a number of technologies that might be applied, and often various methods of implementation. A coherent and consistent enterprise approach can mitigate a potentially considerable maintenance burden.
The following tactics are provided as examples only — enterprise technology and tactical guidance will depend on a number of factors including tech stack, current practice and expertise, and specific mandatory data handling requirements.
Signed Payload
An enterprise API Gateway can be configured to support the Javascript Object Signing and Encryption (JOSE) framework and JSON Web Signature (JWS) validation.
To support data integrity and Non-Repudiation above and beyond TLS, the business service and/or the API Gateway can provide JWS Detached Content payload signing. The JWS Detached Content mechanism controls header length, allows delegation of verification to an API gateway, and may be applied to one class of clients (e.g. external) and not others (e.g. internal).
OpenAPI support for describing a signature requirement is limited. When a JWS signature is required, a mandatory ‘x-jws-signature’ header and an API description must clearly describe the requirement in the API specification.
The JWS compact serialization string
A JWS is a string composed of three components separated by ‘.’
base64UrlEncode(Header) + ‘.’ + base64UrlEncode(Payload) + ‘.’ + base64UrlEncode(JSONWebSignature)JWS Header
The header “alg” value describes the digital signature or message authentication code (MAC) applied to the Payload, the “kid” Key Identifier should describe the certificate Subject Key Identifier (SKI), and the “cty” describes the content type of the payload. e.g.
{“kid”:”signKey”,”alg”:”RS512",”cty”:”application/json”}Payload
The payload is a body of the message.
JSONWebSignature
A JSON Web Signature is a string composed of two components separated by ‘.’ hashed with a shared secret, e.g.
RSASHA512( base64UrlEncode(header) + “.” +base64UrlEncode(payload), secret)Detached Content JWS
To produce a Detached Content JWS, replace the middle part (base64UrlEncoded payload) with a (zero-length) empty string, and insert the result into a ‘x-jws-signature’ HTTP header. E.g.
x-jws-signature: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..t3VhQ7QsILDuVHNFSMI-Fb2FoT7fuzalpS5AH8A9c0Validation of the signature involves base64UrlEncoding the message payload, re-inserting into the middle of the JWS, and validating the reconstituted JWS.
Encrypted Payload
Content encryption adds little value over a direct call to an API Gateway over an encrypted HTTPS connection. The primary use-case of content encryption is to ensure confidentiality of data from end-to-end, through intermediate platforms such as API Gateways that may otherwise allow for the capture, logging or inspection of data in transit.
There will occasionally be a requirement to encrypt payload content to protect the confidentiality of protected data exchanged with one or more trusted external clients. Be aware that content encryption may have ramifications for performance, audit, message tracking, data retention and troubleshooting.
Consider using JSON Web Encryption (JWE) JSON Serialization (JWE-JS) Syntax to encrypt JSON content. JWE-JS encrypted content may be fully described in the API specification, and documents with a content-type of ‘application/jose+json’ may be validated as properly formatted JWE-JS encrypted data by the API gateway.
JSON Web Encryption — JSON Serialization
JSON serialization syntax is optimized for more than one recipient, meaning that single payload is accessible to multiple authorized parties. Below is an example of JWE encrypted content with an encrypted key for only 1 recipient.
{
"protected" : "eyJlbmMiOiJBMTI4R0NNIiwiY3R5IjoidGV4dC9wbGFpbiIsImFsZyI6IkExMjhLVyJ9",
"recipients": [{
"encrypted_key": "iq1vJBpOHKRkMDoY2GTakWE6M_uPGVsh"
"header": {
"alg": "RSA1_5",
"kid": "recipient1@example1.gov.au"
}
}
],
"iv":"SUpOEf-7Q1tT0JV_",
"ciphertext": "ajm2Q-OpPXCr7-MHXicknb1lsxLdXxK_yLds0KuhJzfWK
04SjdxQeSw2L9mu3a_k1C55kCQ_3xlkcVKC5yr__Is48VOoK0k63_QRM
9tBURMFqLByJ8vOYQX0oJW4VUHJLmGhF-tVQWB7Kz8mr8zeE7txF0MSa
P6ga7-siYxStR7_G07Thd1jh-zGT0wxM5g-VRORtq0K6AXpLlwEqRp7p
kt2zRM0ZAXqSpe1O6FJ7FHLDyEFnD-zDIZukLp",
"tag":"DkW2pZCd7lhR0KqIGQ69-A"
}}A Convention for the Description and Discovery of Encrypted APIs
OpenAPI 3.0 support for describing an encryption requirement is limited. If there is no requirement to publish the underlying API specification, or if obfuscation is required, then JSON schemas may be exchanged directly with known parties, and the API modelled as a generic JWE-JS payload in the API specification under the media type ‘application/jose+json’.
If you intend the API to be discoverable, the API specification should describe the unencrypted data under the RequestBody and Responses keywords, defined under the media type ‘application/jose+json’ (indicating the JWS-JS requirement). The API description must clearly describe the encryption requirement.
Where the encryption requirement is described this way in the API specification, and JWE-encoded HTTP requests and responses use the content type ‘application/jose+json’, the API Gateway is able to validate against the JWE-JS schema, rather than the business API.
Wrap-up
Data Confidentiality, Integrity and Non-Repudiation measures come with a significant maintenance burden and should be employed to meet a validated, documented data security requirement only. Consider discoverability and self-service, performance, traceability and audit, and the role of API gateways in mediating and securing signed and encrypted APIs.
