Requirements¶

A requirement in this technical design is a testable demand on what GBO builds, or on the interfaces between GBO and other parties. It follows from the design (GO, PSA, FR-DvTP), or the GBO team derived it from building the demo. Each requirement states where it comes from.

The arc42 sections explain the design, and the architecture decisions record the choices. A requirement states the need that a section or a decision serves. Each arc42 page and each ADR ends with a traceability footer. The footer lists the requirements that the page explains or depends on. The traceability pages link requirements to findings, open questions, and demo increments.

When something is a requirement¶

A REQ-NN counts as a requirement only with these four properties:

Testable: MUST, MAY, or MUST NOT, with a result that you can observe.
Sourced: it names the passage in the design that it follows from. For a requirement derived from the demo, the source is the principle or capability that it serves, with one sentence about the reason.
Addressed: it is addressed to a component that GBO delivers, or to an interface agreement (see Addressee).
A need: it describes the need and does not describe the chosen solution.

The test for a derived requirement is one question: which principle or capability breaks without this requirement? If there is no answer, it is no requirement.

What is not a requirement¶

Three levels of items are no requirements, and each level lands in its own place:

Level	Example	Where it lands
Demo glue	mocks, seeds, provisioning, the fake DigiD	nowhere
Implementation detail	a switch, a design pattern, a library	in the code
Design decision	never cache the status, or keep keys for at most five minutes	an ADR, or a note on the requirement that it serves

Need or decision: ask can another solution meet the same need? If yes, the need is the requirement, and the chosen solution is a design decision.

When a design decision becomes an ADR: a design decision becomes an ADR only if all three conditions apply:

There were real alternatives.
Going back is expensive (an interface, a data model, or another party).
Someone outside the team must know about it or agree to it.

If not, the decision is a note "design choice" on the requirement that it serves. Related choices go into one ADR. The ADRs are in Architecture decisions.

Entry format¶

Each requirement entry has this format:

## REQ-NN — Title as a statement {#req-nn}

> The [component] MUST [testable demand].

| Case | Outcome |        (optional: what must hold, with the deny reason)
|---|---|

- **Source**: design — PSA S04, FR-34 criterion 1
             or: derived — serves PSA S01: why, in one sentence
- **Addressee**: GBO-delivered component | interface agreement | guideline for bronhouders
- **Evidence**: demo issue or PR, with a permalink to the test or the code;
               or: not built — issue
- **Related**: links only (REQ, F, Q, ADR)
- **Notes**: only what a builder needs; an open point as a link to the Q
- **Status**: draft | ready for review | approved | covered | withdrawn

The fields have these rules:

Source: the value is design if the design already states or sharpens the requirement. The value is derived if the requirement comes from the demo. PSA and GO links go to the published site. FR-DvTP criteria are named without a link until the FRs are public. The archived reference architecture (v0.6.2) is no longer a source. The PSA passage replaces it.
Evidence: the place where the demo tests the requirement: an issue or PR in gbo-demo, and a permalink to the test or the code. Later, test tags with coverage from CI will replace this field.
Related: only references that work as links.
Notes: limits, design choices, and open points. No history: the page describes the design as it is.

Status¶

An entry has one of these statuses:

Status	Meaning
draft	written by the analysis team
ready for review	meets this norm
approved	accepted in the review with the tech lead
covered	a test shows the requirement
withdrawn	an approved requirement that no longer applies. It stays, with the reason and the successor, because others can refer to it
candidate	a connection condition (AV) that is proposed and not set

If a requirement was never approved and no longer holds, the GBO team removes it and does not withdraw it. Nobody uses its number again. For more information, see Removed numbers.

Addressee: a MUST is only about what GBO builds¶

The system is federative (Q-02), and P-10 puts the bronhouder in control. So a requirement that prescribes how a bronhouder configures its own PDP, PAP, or policy engine is no requirement. Nobody can enforce it in practice. Each requirement names its addressee:

GBO-delivered component: software that GBO builds and delivers as a generic component or reference implementation. A MUST applies, because it is a demand on an artifact of GBO itself. Delivery does not mean operation: most of these components run at the source (behind the Inway: PEP and PDP, adapters, request mappers, gateways). The requirement binds the GBO build. It does not limit the freedom of a source to choose something else.
Interface agreement: behavior at the outside that every participant must deliver, because it follows from system or legal demands. For example, you can trace which policy version a decision used. A MUST applies, but only to the observable result. It never applies to the internal configuration or the product.
Guideline for bronhouders: the internal configuration at a source. At most SHOULD, with the reason, or a selection criterion for a product.

Three other namespaces hold what is not a requirement on GBO:

RL-NN: guidelines for bronhouders, on Policy management. Matrix and findings can refer to them like a requirement, without the suggestion that they are one. Each guideline has a promotion rule: the open question that must be answered before it can become a requirement.
AV-NN: candidate connection conditions, obligations for other participants, on Connection conditions.
BSNK-NN: preconditions that BSNk PP, an external facility, imposes on GBO, on BSNk preconditions.

If you write a requirement, do two checks:

Does the MUST sentence name a product or an implementation form that GBO does not deliver? If so, reword the sentence to the role (PAP, PDP, management API), and change the addressee. The use of a product in the demo is a demo choice. It belongs in the evidence.
Does the requirement assume that GBO runs something? That is almost never certain. It is open which facilities are really central (Q-10, Q-02). The demo runs everything in one stack, and that proves nothing about it. Write the requirement on the artifact or on the interface.

Organization of the pages¶

Topic pages are grouped by channel, as in the building block view: GBO Basis (needed for every channel), DvTP, and EUDI. A requirement that belongs to one channel only is on a topic page of that channel. If a requirement moves to another page, its number does not change.

All requirements¶

Every live number is in one of the following tables. The channel is GBO Basis (needed for every channel), DvTP, or EUDI. The source is design if the design already states the requirement, and derived if it comes from building the demo.

Requirements (REQ)¶

These requirements apply to GBO-delivered components and interface agreements:

ID	Title	Channel	Topic page	Source (design/derived)	Status
REQ-04	The source delivers only after a positive decision by its PDP	GBO Basis	Authorization	design	ready for review
REQ-06	A denial carries a machine-readable reason: coarse for the consumer, full for the operator	GBO Basis	Authorization	design	ready for review
REQ-08	Source access delivers only the fields that the request selects	GBO Basis	Data minimization	design	ready for review
REQ-10	Consent covers a whole data set, and the citizen does not pick fields within a set	DvTP	Consent (DvTP)	design	ready for review
REQ-11	A GBO component fetches source data from the source for each request and does not store it	GBO Basis	Data minimization	design	ready for review
REQ-12	A consent is bound to one consumer, one service, and a named data scope	DvTP	Consent (DvTP)	design	draft
REQ-14	After revocation, the chain denies every later request on that consent	DvTP	Consent (DvTP)	design	ready for review
REQ-17	The PDP decides on every field that the source runs, and denies an uncertain field list	GBO Basis	Query enforcement	design	ready for review
REQ-18	The PDP decides on facts that it established itself, and never on what the consumer declares	GBO Basis	Authorization	design	ready for review
REQ-19	A consent has a finite validity, and after that the PDP denies	DvTP	Consent lifecycle	design	ready for review
REQ-20	In the consent path the consumer gets no BSN in the proof or in the response	DvTP	Pseudonymization	design	draft
REQ-21	The source converts the value from the proof itself, only after a positive decision and without a central party	DvTP	Pseudonymization	design	ready for review
REQ-23	The consent register (toestemmingsregister) gets no BSN, not even temporarily	DvTP	Consent roles	design	draft
REQ-24	The citizen identity comes from the authentication service assertion at the required assurance level and not from client input	DvTP	Consent roles	design	ready for review
REQ-32	Audit records are protected, complete, and stored apart from operational logs	GBO Basis	Decision audit	design	ready for review
REQ-37	A consent request names the consumer, the service, the requested data sets, and the return address	DvTP	Consent initiation	design	draft
REQ-38	A logged-in citizen can view consents with status and revoke them	DvTP	Citizen access	design	draft
REQ-39	Only the consent backend can create, query, and revoke the consents of a citizen in the register	DvTP	Citizen access	design	draft
REQ-40	A citizen sees and revokes only their own consents	DvTP	Citizen access	design	draft
REQ-42	The authorization request follows an open PEP-PDP profile, and the PEP passes the request on unchanged	GBO Basis	Authorization	design	ready for review
REQ-44	A channel adapter translates protocol, and the decision on source data lies with the PDP of the source	GBO Basis	Authorization	derived	ready for review
REQ-45	The source is queried only about the citizen from a verified PID disclosure	EUDI	EUDI issuance	design	draft
REQ-46	Every channel that calls a source on behalf of an external party does so through FSC, with a valid certificate	GBO Basis	Identity and trust	design	ready for review
REQ-48	Every rule checks actor and scope itself, and a request passes only if no check denies	GBO Basis	Authorization	design	ready for review
REQ-55	One trace ID per request across the whole chain, and the transaction ID can be linked to it	GBO Basis	Observability	design	ready for review
REQ-57	An attestation about someone other than the requester follows an agreed relation from the verified requester	EUDI	EUDI issuance	derived	draft
REQ-58	Every bronhouder has its own certificate set for issuance, and missing material fails	EUDI	EUDI issuance	design	ready for review
REQ-59	The decision record names the policy version that decided	GBO Basis	Decision audit	design	ready for review
REQ-60	Logging contains no BSN that the processing does not need	GBO Basis	Decision audit	design	ready for review
REQ-61	Admission comes from a register and not from decision policy	GBO Basis	Admission and contracts	design	ready for review
REQ-62	The admission decision on a contract is its own rule set, separate from request policy	GBO Basis	Admission and contracts	design	ready for review
REQ-63	An automated refusal of a contract proposal is recoverable	GBO Basis	Admission and contracts	derived	draft
REQ-64	A GBO component works only with the service description the source publishes itself, after validation	GBO Basis	Source metadata	design	ready for review
REQ-65	Only an explicit management action takes a source into use, and a valid contract is not enough	GBO Basis	Source metadata	design	ready for review
REQ-66	Source metadata fails closed per source, ages within bounds, and can be rolled back	GBO Basis	Source metadata	design	ready for review
REQ-67	The legal identity of a bronhouder comes from its certificate and not from configuration	GBO Basis	Identity and trust	design	draft
REQ-68	The PDP decides only on a consent whose origin, binding, and current status it establishes itself	DvTP	Consent (DvTP)	design	draft
REQ-69	The consent register stores the polymorphic values under its own reference and no encrypted values per party	DvTP	Pseudonymization	design	ready for review
REQ-71	Every authorization decision is in an ADL-conformant decision record, and that record is the audit source	GBO Basis	Decision audit	design	ready for review
REQ-72	A GBO component that processes personal data writes an LDV log record for each processing at its controller	GBO Basis	Processing logging	design	ready for review
REQ-74	The authorization regime follows from the evidence a request carries	GBO Basis	Authorization	derived	ready for review
REQ-75	Consent status is available within a set propagation time, availability, and latency	DvTP	Consent (DvTP)	design	draft
REQ-76	The register gives consent status only to an authenticated, authorized PDP, over FSC, and records who asked	DvTP	Consent (DvTP)	design	draft
REQ-77	An attestation gets the validity and revocation policy of the bronhouder	EUDI	EUDI issuance	design	draft
REQ-78	Issuance issues nested claims, with selective disclosure per element as the schema prescribes	EUDI	EUDI issuance	design	draft
REQ-79	Under a consent the subject comes only from the proof	DvTP	Pseudonymization	derived	ready for review
REQ-80	The proof carries a value per party that only that party can read, and the recipient checks that the value is meant for it	DvTP	Pseudonymization	design	ready for review
REQ-81	Only the component that enforces the decision reaches the source gateway	DvTP	Pseudonymization	derived	ready for review
REQ-82	When consent is given, the consent facility (toestemmingsvoorziening) knows the OIN, the key version, and the BSN authorization of each source	DvTP	Pseudonymization	derived	draft
REQ-83	Every ASIP verification result is sealed	EUDI	Authentic Source Interface	design	ready for review
REQ-84	`Unknown` only means the source has no (complete) value	EUDI	Authentic Source Interface	design	ready for review
REQ-85	The verify response contains no value from the source	EUDI	Authentic Source Interface	derived	draft
REQ-86	The access token carries the citizen's identification data and the means used to identify him	EUDI	Authentic Source Interface	design	ready for review
REQ-87	The ASIP takes the citizen only from a valid token bound to the QTSP that covers the operation	EUDI	Authentic Source Interface	design	ready for review
REQ-88	Only a QTSP with the `QEAA_Provider` right in the register becomes a client	EUDI	Authentic Source Interface	design	ready for review
REQ-89	The right of a registered client is re-checked periodically	EUDI	Authentic Source Interface	design	ready for review
REQ-90	The citizen approves the request by logging in, or refuses	EUDI	Authentic Source Interface	design	ready for review
REQ-91	The citizen sees who asks what at which source before logging in	EUDI	Authentic Source Interface	design	ready for review
REQ-92	The ASIP asks the source only for the fields of the requested attributes	EUDI	Authentic Source Interface	derived	ready for review
REQ-93	A chain that does not answer is an error, not `Unknown`	EUDI	Authentic Source Interface	derived	ready for review
REQ-94	Every ASI response names the one authentic source responsible for it	EUDI	Authentic Source Interface	design	ready for review
REQ-95	An access token is valid only for the source the citizen saw	EUDI	Authentic Source Interface	derived	ready for review
REQ-97	Every rule names the FSC services it applies to	GBO Basis	Authorization	derived	ready for review
REQ-99	The ASIP provides a discovery record for each attribute and data service, with a path to endpoint, contract, and authorization server	EUDI	Authentic Source Interface	design	draft
REQ-100	A data service contract names its authorization-server metadata at the location RFC 8414 prescribes	EUDI	Authentic Source Interface	design	draft
REQ-101	A retrieve for which the source lacks a requested attribute is not found and gives no partial result	EUDI	Authentic Source Interface	design	ready for review
REQ-102	The authorization server identifies the citizen with the EUDI wallet through OpenID4VP and asks only the PID attributes in its registration	EUDI	Authentic Source Interface	design	ready for review
REQ-103	An authorization can be bound to the requested attributes, and the ASIP then processes only those attributes	EUDI	Authentic Source Interface	design	draft
REQ-106	An integrator acts only with a registered mandate, and the consent binds the represented party	DvTP	Consent (DvTP)	design	ready for review
REQ-107	Consent can be given only after confirmation that the citizen saw the information	DvTP	Consent (DvTP)	design	ready for review
REQ-108	The citizen can export the overview of consents	DvTP	Citizen access	design	ready for review
REQ-109	Revocation is possible only for a valid consent	DvTP	Citizen access	design	ready for review
REQ-110	A suspended or departed consumer gets no more data, even with a valid consent	GBO Basis	Admission and contracts	design	draft
REQ-111	What the citizen sees about the consumer, and the return address, come from the registration and not from the request	DvTP	Consent initiation	design	ready for review
REQ-112	The ASIP offers the clause 6.1 interface	EUDI	Authentic Source Interface	design	draft
REQ-113	Fuzzy matching only on free text, with documented rules	EUDI	Authentic Source Interface	design	draft
REQ-114	A request on behalf of another person gets 501	EUDI	Authentic Source Interface	design	draft
REQ-115	The ASIP verifies attribute fragments	EUDI	Authentic Source Interface	design	draft
REQ-116	An attestation contains only what the source answered, per its mapping, and an answer that does not fit gives no attestation	EUDI	EUDI issuance	design	draft
REQ-117	Before choosing, the citizen sees in plain language who asks what, for what, and for how long	DvTP	Consent (DvTP)	design	draft
REQ-118	If a service excludes delegation, an authorized representative cannot give consent for it	DvTP	Consent (DvTP)	design	draft
REQ-119	After every outcome the citizen returns to the consumer with that outcome	DvTP	Consent initiation	design	draft
REQ-120	For every consent and after every revocation, the portal points the citizen to their rights at the consumer	DvTP	Citizen access	design	draft
REQ-121	Screen, initiation check, and reference policy follow the same data-set description	DvTP	Consent (DvTP)	design	draft
REQ-122	The citizen gets a confirmation of their choice	DvTP	Consent (DvTP)	design	draft
REQ-123	Every change to an admission, mandate, or activation is traceable	GBO Basis	Admission and contracts	design	draft
REQ-124	For every attestation, the versions of the mapping, the source schema, and the attestation schema are traceable	EUDI	EUDI issuance	design	draft

Guidelines for bronhouders (RL)¶

The guidelines apply to the internal configuration of a bronhouder, and each guideline has a promotion rule:

ID	Title	Channel	Topic page	Source (design/derived)	Status
RL-01	Deliver policy as a versioned bundle instead of baking it into the PDP	GBO Basis	Policy management	design	ready for review
RL-02	Authorize the management API with its own policy set and deny on an empty store	GBO Basis	Policy management	derived	ready for review
RL-03	Separate writing from publishing, and publish with a non-personal, short-lived identity	GBO Basis	Policy management	design	ready for review
RL-04	Withdraw policy instead of deleting it, and reconcile the deployed set with version control	GBO Basis	Policy management	design	ready for review
RL-05	Validate a bundle before activation, and fall back visibly to the last valid set	GBO Basis	Policy management	design	ready for review

Candidate connection conditions (AV)¶

The candidates are obligations for other participants, and each entry names the obliged party:

ID	Title	Channel	Topic page	Source (design/derived)	Status
AV-01	Consumer sends trace context and records the transaction ID	DvTP	Connection conditions	—	candidate
AV-02	Consumer records its processing according to LDV	DvTP	Connection conditions	—	candidate
AV-03	Consumer uses the consent facility and BSNk PP	DvTP	Connection conditions	—	candidate
AV-04	Consumer has its own FSC peer with PKIoverheid certificate and OIN	DvTP	Connection conditions	—	candidate
AV-05	Consumer sends the consent proof unchanged	DvTP	Connection conditions	—	candidate
AV-06	Integrator is admitted separately and acts as processor	DvTP	Connection conditions	—	candidate
AV-07	Bronhouder publishes a machine-readable description for each data service	GBO Basis	Connection conditions	—	candidate
AV-08	Bronhouder without its own endpoint provably agrees with a taken-over description	EUDI	Connection conditions	—	candidate
AV-09	Bronhouder keeps decryption keys of an older version while proofs for that version are valid	DvTP	Connection conditions	—	candidate
AV-10	Bronhouder logs every living data subject of a relation attestation	EUDI	Connection conditions	—	candidate
AV-11	Bronhouder tests its view for relation attestations	EUDI	Connection conditions	—	candidate
AV-12	Bronhouder as provider has a public validity and revocation policy	EUDI	Connection conditions	—	candidate
AV-13	Bronhouder gives the instruction to revoke an attestation	EUDI	Connection conditions	—	candidate
AV-14	Consumer has registered contact details for GDPR rights	DvTP	Connection conditions	—	candidate
AV-15	Consumer declares an equivalent alternative at admission	DvTP	Connection conditions	—	candidate

BSNk PP preconditions (BSNK)¶

BSNk PP imposes these preconditions on GBO, and they have no status of their own:

ID	Title	Channel	Topic page	Source (design/derived)	Status
BSNK-01	Only a recognized party can activate and transform	DvTP	BSNk preconditions	—	—
BSNK-02	Activation needs the BSN and check data	DvTP	BSNk preconditions	—	—
BSNK-03	A PI belongs to the requester and nobody else	DvTP	BSNk preconditions	—	—
BSNK-04	Transformation is possible only while the citizen is logged in	DvTP	BSNk preconditions	—	—
BSNK-05	At most four recipients per request	DvTP	BSNk preconditions	—	—
BSNK-06	The BSN Authorization List sets BSN or pseudonym	DvTP	BSNk preconditions	—	—
BSNK-07	The recipient is an OIN	DvTP	BSNk preconditions	—	—
BSNK-08	An encrypted value belongs to one key version	DvTP	BSNk preconditions	—	—
BSNK-09	The recipient gets its keys through an Access Service or Key Requester	DvTP	BSNk preconditions	—	—
BSNK-10	The party that activates has the inspection duty	DvTP	BSNk preconditions	—	—
BSNK-11	The interfaces are SOAP with PKIoverheid	DvTP	BSNk preconditions	—	—

Removed numbers¶

If a requirement was never approved and no longer holds, the GBO team removes it. Nobody uses its number again. Topic pages list their own removed numbers with the reason. Each removed number has a disposition and, where one exists, a successor:

Number	Disposition	Successor
REQ-01	removed	—
REQ-02	merged into	REQ-61
REQ-03	removed	—
REQ-05	merged into	REQ-48
REQ-07	removed	—
REQ-09	merged into	REQ-17
REQ-13	removed	REQ-68, REQ-18
REQ-15	merged into	REQ-79
REQ-16	merged into	REQ-55
REQ-22	removed	pending Q-49
REQ-25	removed	REQ-79, REQ-17
REQ-26	removed	REQ-79, REQ-17
REQ-27	removed	REQ-79, REQ-17
REQ-28	merged into	REQ-55
REQ-29	merged into	REQ-60
REQ-30	never used	—
REQ-31	merged into	REQ-71
REQ-33	removed	—
REQ-34	removed	—
REQ-35	merged into	REQ-40
REQ-36	removed	—
REQ-41	merged into	REQ-14
REQ-43	removed	—
REQ-47	removed	—
REQ-49	removed	—
REQ-50	merged into	REQ-18
REQ-51	removed	REQ-44, REQ-64
REQ-52	removed	a design decision, not a requirement (see F-35)
REQ-53	removed	REQ-20, REQ-21 (and F-30, F-37)
REQ-54	merged into	REQ-55
REQ-56	removed	REQ-74 (partly)
REQ-70	removed	—
REQ-73	removed	AV-01
REQ-96	merged into	REQ-91
REQ-98	removed	REQ-48, REQ-74, REQ-97, REQ-79, REQ-17
REQ-104	removed	REQ-88 (a duty of the QTSP under ETSI and eIDAS)
REQ-105	removed	REQ-88 (a duty of the QTSP under ETSI and eIDAS)