Skip to content

Commit e3c879a

Browse files
TimvdLippeTimvdLippe
authored
Voeg signing en encryption modules toe als normatief (#276)
Hiermee worden ze officieel vastgesteld als normatieve modules voor alle REST API's. Op dit moment zijn ze enkel normatief binnen het REST API profiel van Digikoppeling. De modules zijn al vastgesteld bij het kennisplatform en als onderdeel van Digikoppeling, maar niet als losstaande documenten.
1 parent 71dcb42 commit e3c879a

3 files changed

Lines changed: 109 additions & 5 deletions

File tree

‎js/config.mjs‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { processRuleBlocks } from "https://logius-standaarden.github.io/publicatie/respec/plugins/adr.mjs";
22
import { loadRespecWithConfiguration } from "https://logius-standaarden.github.io/publicatie/respec/organisation-config.mjs";
3+
import { generateMermaidFigures } from "https://logius-standaarden.github.io/publicatie/respec/plugins/mermaid.mjs";
34

45
async function initializeHighlightJSYaml() {
56
//this is the function you call in 'preProcess', to load the highlighter
@@ -103,5 +104,24 @@ loadRespecWithConfiguration({
103104
pluralize: true,
104105

105106
preProcess: [initializeHighlightJSYaml, fetchSpectralConfiguration],
106-
postProcess: [highlightSpectralCode, (config, document, utils) => processRuleBlocks(config, document, utils, spectralConfiguration)],
107+
postProcess: [generateMermaidFigures, highlightSpectralCode, (config, document, utils) => processRuleBlocks(config, document, utils, spectralConfiguration)],
108+
109+
localBiblio: {
110+
"ADR-encryption": {
111+
authors: ["P. Haasnoot"],
112+
href: "https://logius-standaarden.github.io/API-mod-encryption/",
113+
publisher: "Logius",
114+
title: "API Design Rules Module: Encryption",
115+
// TODO: verwijder voor publicatie
116+
status: "Draft",
117+
},
118+
"ADR-signing": {
119+
authors: ["P. Haasnoot"],
120+
href: "https://logius-standaarden.github.io/API-mod-signing/",
121+
publisher: "Logius",
122+
title: "API Design Rules Module: Signing",
123+
// TODO: verwijder voor publicatie
124+
status: "Draft",
125+
},
126+
}
107127
});

‎media/signing-in-combination-with-encryption.mermaid‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
graph TD;
2+
Request--"JSON(payload)"-->SignA;
3+
SignA--"JWE(JWS(JSON(payload)))"-->SignB;
4+
SignB--"JSON(payload)"-->Proc;
5+
Proc--"JSON(payload)"-->SignC;
6+
SignC--"JWS(JWE(JSON(payload)))"-->SignD;
7+
SignD--"JSON(payload)"-->Response;
8+
9+
10+
direction TB
11+
subgraph Service Provider
12+
direction TB
13+
SignB("Decrypt with Provider private key</br
14+
-----------------------</br>
15+
Verify signature with Requester public key")
16+
Proc(Process Request)
17+
SignC("Sign with Provider private key </br>
18+
-----------------------</br>
19+
Encrypt with Requester public key")
20+
21+
end
22+
subgraph Service Requester
23+
direction TB
24+
Request:::sc
25+
SignA("Sign with Requester private key</br>
26+
-----------------------</br>
27+
Encrypt with Provider public key")
28+
SignD("Decrypt with Requester private key </br>
29+
-----------------------</br>
30+
Verify signature with Provider public key")
31+
classDef sc fill:#f96
32+
Response:::sc
33+
end

‎sections/designRules.md‎

Lines changed: 55 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -927,16 +927,17 @@ Services (potentially) including script code (e.g. JavaScript) in their response
927927

928928
* Ensure the intended Content-Type headers are sent in the response, matching the body content, e.g. `application/json` and not `application/javascript`.
929929

930-
## Geospatial
930+
## Normative modules
931931

932-
Geospatial data refers to information that is associated with a physical location on Earth, often expressed by its 2D/3D coordinates.
932+
The following modules are normative for all REST API's.
933933

934-
<div class="rule" id="/core/geospatial" data-type="functional">
934+
<div class="rule" id="/core/modules/geospatial" data-type="functional">
935935
<p class="rulelab">Apply the geospatial module for geospatial data</p>
936936
<dl>
937937
<dt>Statement</dt>
938938
<dd>
939-
The [[[ADR-GEO]]] version 1.0.x MUST be applied when providing geospatial data or functionality.
939+
<p>The [[[ADR-GEO]]] version 1.0.x MUST be applied when providing geospatial data or functionality.
940+
<p class="note">Geospatial data refers to information that is associated with a physical location on Earth, often expressed by its 2D/3D coordinates.
940941
</dd>
941942
<dt>Rationale</dt>
942943
<dd>
@@ -949,3 +950,53 @@ Geospatial data refers to information that is associated with a physical locatio
949950
</dd>
950951
</dl>
951952
</div>
953+
954+
<div class="rule" id="/core/modules/signing" data-type="functional">
955+
<p class="rulelab">Apply the signing module for signing payloads</p>
956+
<dl>
957+
<dt>Statement</dt>
958+
<dd>
959+
<p>The [[[ADR-signing]]] version 1.0.x MUST be applied when signing payloads.
960+
<p class="note">This rule does not dictate signing.
961+
Instead, it only applies in situations where there is a need for assurance of end to end message integrity and authenticity between client application and server application.
962+
In those situations, [[[ADR-signing]]] specifies how to sign.
963+
</dd>
964+
<dt>Rationale</dt>
965+
<dd>
966+
The [[[ADR-signing]]] formalizes as set of rules regarding:
967+
<ol>
968+
<li>How to sign data in request and response payloads.</li>
969+
<li>Which header to specify the signature.</li>
970+
</ol>
971+
</dd>
972+
</dl>
973+
</div>
974+
975+
<div class="rule" id="/core/modules/encryption" data-type="functional">
976+
<p class="rulelab">Apply the encryption module for encrypting payloads</p>
977+
<dl>
978+
<dt>Statement</dt>
979+
<dd>
980+
<p>The [[[ADR-encryption]]] version 1.0.x MUST be applied when encrypting payloads.
981+
<p class="note">This rule does not dictate encryption.
982+
Instead, it only applies in situations where there is a need for end to end message payload confidentiality between client application and server application.
983+
In those situations, [[[ADR-encryption]]] specifies how to encrypt.
984+
</dd>
985+
<dt>Rationale</dt>
986+
<dd>
987+
The [[[ADR-encryption]]] formalizes as set of rules regarding:
988+
<ol>
989+
<li>How to encrypt data in request and response payloads.</li>
990+
<li>The flow of operations between client and server.</li>
991+
</ol>
992+
</dd>
993+
</dl>
994+
</div>
995+
996+
If both the signing and encryption modules apply, use the following flow of operations:
997+
998+
<figure>
999+
<div class="mermaid" data-figure-name="signing-in-combination-with-encryption.mermaid">
1000+
</div>
1001+
<figcaption>Signing in combination with encryption</figcaption>
1002+
</figure>

0 commit comments

Comments
 (0)