ADR-HTTP Payload encryption

Kennisplatform API's Standard
Candidate version

This version:
https://docs.geostandaarden.nl/api/cv-hr-API-Strategie-mod-encryption-20240417/
Latest published version:
https://docs.geostandaarden.nl/api/API-Strategie-mod-encryption/
Latest editor's draft:
https://geonovum.github.io/KP-APIs/API-strategie-modules/encryption/
Editor:
Peter Haasnoot (Logius)
Author:
KPAPI (KPAPI)
Participate:
GitHub Geonovum/KP-APIs
File an issue
Commit history
Pull requests

This document is licensed under Logo Creative Commons Attribution 4.0 International Public License
Creative Commons Attribution 4.0 International Public License

Abstract

This ADR Module contains the requirements for ADR REST-API encryption based on JWE

Status of This Document

This is a proposed version approved by the technical commitee. Comments regarding this document may be shared through GitHub: https://github.com/Geonovum/KP-APIs/issues

1. ADR-HTTP Payload encryption

1.1 Introduction

This module specifies the use of JWE for HTTP payload encryption.

Use Cases

This module is applicable when there is a need for end to end message payload confidentiality between client application and server application. In a complex IT landscape the path between client and server can go over several intermediary components/systems in which case end to end confidentiality can be especially relevant. (In this case TLS is terminated in each step on the path and does not protect the http-message in transport fully end to end). A specific example is when there is confidential data that is processed and routed by an intermediary organization which is not allowed to access the contents of the message.

1.2 Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. The interpretation should only be applied when the terms appear in all capital letters.

1.3 JWE encryption

For encryption JSON Web Encryption (JWE) is used as defined in [RFC7516];

1.3.1 Basic JWE proces flow

The basic flow for encryption using JWE is :

Service Requester
Service Provider
JSON(payload)
JWE(JSON(payload))
JSON(payload)
JSON(payload)
JWE(JSON(payload))
JSON(payload)
Request
Encrypt with Provider public key
Decrypt with Requester private key
Response
Decrypt with Provider private key
Process Request
Encrypt with Requester public key
Figure 1 Encryption

  • 1 Service Requester encrypts payload using Service Provider public encryption key:

  • 2 Service Provider decrypts the request using the corresponding Service Provider private encryption key.

  • 3 Service Provider performs the request and then generates an encrypted response;

  • 4 Service Requester decrypts response using Requester private key

1.3.2 Parameters and requirements

The following specific requirements MUST be met:

  • The request is sent to Service Provider with the content-type: application/jose+json.

  • An encrypted request needs to pass application/jose+json as the value for the Content-Type and Accept headers:

Content-Type: application/jose+json
Accept: application/jose+json

  • When the encrypted request uses an unsupported algorithm, the Service Provider rejects the request with a 400 HTTP response.

  • Use for encryption the public key from the X.509 certificate of the other party

  • Use the following parameters in the JWE protected header:

alg : "RSA-OAEP", 
enc : "A256GCM",
typ : "JWE"
  • JWE compact serialization format is used

1.4 Cryptographic Algorithms

The following algorithms are used

As defined in [rfc7518]

1.5 Encryption in combination with signing

The following diagram shows the order in which encryption & signing must be applied when encryption is used in combination with signing

Service Requester
Service Provider
JSON(payload)
JWE(JWS(JSON(payload)))
JSON(payload)
JSON(payload)
JWS(JWE(JSON(payload)))
JSON(payload)
Request
Sign with Requester private key

    -----------------------

    Encrypt with Provider public key
Decrypt with Requester private key 

    -----------------------

    Verify signature with Provider public key
Response
Decrypt with Provider private key
 
    -----------------------

    Verify signature with Requester public key
Process Request
Sign with Provider private key 

    -----------------------

    Encrypt with Requester public key
Figure 2 Signing & Encryption

A. Tooling

A.1 JWT, JWS, JWE, JWK, and JWA Implementations

Libraries implementing JWT and the JOSE specs JWS, JWE, JWK, and JWA are listed here.

https://openid.net/developers/jwt-jws-jwe-jwk-and-jwa-implementations/

B. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, NOT RECOMMENDED, OPTIONAL, RECOMMENDED, REQUIRED, SHALL, SHALL NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

C. References

C.1 Normative references

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC7516]
JSON Web Encryption (JWE). M. Jones; J. Hildebrand. IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7516
[rfc7518]
JSON Web Algorithms (JWA). M. Jones. IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7518
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
Kennisplatform API's Standard - Candidate version