docs(baseline-requirements.md): Add reference to RFC2119

docs/baseline-requirements.md

@@ -32,43 +32,54 @@ SPDX-License-Identifier: Apache-2.0
 
 # Preamble / Scope
 
-This document lays out the requirements for open-source products that should become part of openDesk.
+This document lays out the requirements for open-source products that should become part of openDesk (called "component" in the following).
 
-As this is a comprehensive set of requirements most new components will not adhere to all of them.
+As this is a comprehensive set of requirements, most new components will not adhere to all of them.
 
-This document can be used to assess the status and possible gaps for a component which might itself be the basis for a decision if a component should be integrated into openDesk by working on closing the identified gaps.
+This document can be used to assess the status and possible gaps for a component, which might itself be the basis for a decision if the component should be integrated into openDesk by working on closing the identified gaps.
 
 > [!note]
 > Even an already integrated application might not adhere to all aspects of the documented requirements yet.
 > Closing the gaps for existing applications therefore is an openDesk priority.
 
+> [!note]
+> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
+>      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
+>      "OPTIONAL" in this document are to be interpreted as described in
+>      [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+
+
 # Software bill of materials (SBOMs)
 
-openDesk is looking into options for in-depth SBOM creation first for container images and later for source code. It is still expected by the suppliers to provide artifact and source code SBOMs in a standardized manner, ideally in the openCode preferred [SPDX 2.2.1](https://spdx.org/rdf/ontology/spdx-2-2-1/) format.
+
+[ToDo: align this with ironDesk requirements]
+
+openDesk is looking into options for in-depth SBOM creation first for container images and later for source code. Components MUST provide artifact and source code SBOMs in a standardized manner, ideally in the openCode preferred [SPDX 2.2.1](https://spdx.org/rdf/ontology/spdx-2-2-1/) format.
 
 **Reference:** https://gitlab.opencode.de/bmi/opendesk/deployment/SBOM/-/tree/main/sboms/0.5.74
 
 ## Artifact SBOMs
 
-There are various free tools like [syft](https://github.com/anchore/syft) available to generate SBOMs for container images. It is expected that this kind of artifact SBOMs is provided (and signed) for all containers delivered to be integrated into openDesk.
+There are various free tools like [syft](https://github.com/anchore/syft) available to generate SBOMs for container images. Components MUST provide cryptographically signed artifact SBOMs for all container images delivered to be integrated into openDesk.
 
 **Reference:** As part of [openDesk's standard CI](https://gitlab.opencode.de/bmi/opendesk/tooling/gitlab-config) a container image SBOM is derived from the container's content and gets signed. Both artifacts (SBOM and signature) are placed next to the image in the related registry ([e.g.](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images/semantic-release/container_registry/827)).
 
 ## Source code SBOMs
 
-Today's software development platforms like GitLab or GitHub provide dependency list/graph features that are the basis for your source code SBOMs. These features are usually based on analysis of language-specific package manager dependency definition files. As part of a supplier's software development process, it is expected that source code SBOMs are at least created on the level of the already defined software dependencies within the source code tree of the component.
+Today's software development platforms like GitLab or GitHub provide dependency list/graph features that are the basis for your source code SBOMs. These features are usually based on analysis of language-specific package manager dependency definition files. As part of a component supplier's software development process, it is expected that source code SBOMs are at least created on the level of the already defined software dependencies within the source code tree of the component.
 
 **Reference:** Currently we do not have source code SBOMs in place.
 
 # License compliance
 
-All parts of openDesk Community Edition must be open source with source code (also) published or at least publishable on openCode.
+All parts of openDesk Community Edition MUST be open source (ToDo: add reference to definition). Source code MUST BE published or MUST BE publishable on openCode.
 
 openCode provides some boundaries when it comes to open source license compliance openDesk has to adhere to:
 
 - The components must be published under a license listed in the [openCode license allow list](https://opencode.de/de/wissen/rechtssichere-nutzung/open-source-lizenzen).
 - Delivered artifacts (container images) must contain only components licensed under the aforementioned allow list. A container must not contain any artifact using a license from the [openCode license block list](https://opencode.de/de/wissen/rechtssichere-nutzung/open-source-lizenzen#3.-Negativliste-aller-nicht-freigegebenen-Lizenzen).
 
+[ToDo: we should make this a markdown?]
 Deviations from the above requirements must be documented in the openDesk license deviation report.
 
 **Reference:** https://gitlab.opencode.de/bmi/opendesk/deployment/SBOM/-/blob/main/sboms/openDesk%20Deviation%20Report-0.5.74.md
@@ -77,6 +88,8 @@ Deviations from the above requirements must be documented in the openDesk licens
 
 ZenDiS plans to provide secured key storage as a service on openCode.
 
+[ToDo: update to v1.2?]
+
 openDesk is going to implement [SLSA v1.0](https://slsa.dev/spec/v1.0/).
 
 The minimum requirement for all of openDesk's functional components is that all component artifacts (i.e. container images, Helm charts) are signed and their signature can be verified based on the ZenDiS-provided secure key store.
@@ -87,6 +100,8 @@ The minimum requirement for all of openDesk's functional components is that all
 
 Note: openDesk is operated as a Kubernetes (K8s) workload.
 
+[ToDo: shouldn't we link to these as well: IG BvC, DVS, Pod Security Standards]
+
 openDesk applications should adhere to best practices for K8s application/container design. While there are dozens of documents about these best practices please use them as references:
 - https://cloud.google.com/architecture/best-practices-for-building-containers
 - https://cloud.google.com/architecture/best-practices-for-operating-containers
@@ -113,6 +128,8 @@ You will find below some of the most common best practice requirements, some of
 
 # Security
 
+[ToDo: shouldn't we move this up to container arch. basics?]
+
 openDesk should be compliant with the "Deutsche Verwaltungscloud Strategie" (DVS). While this is a moving target it references some already established standards like the BSI's [IT-Grundschutz](https://www.bsi.bund.de/DE/Themen/Unternehmen-und-Organisationen/Standards-und-Zertifizierung/IT-Grundschutz/IT-Grundschutz-Kompendium/it-grundschutz-kompendium_node.html) and [C5](https://www.bsi.bund.de/DE/Themen/Unternehmen-und-Organisationen/Informationen-und-Empfehlungen/Empfehlungen-nach-Angriffszielen/Cloud-Computing/Kriterienkatalog-C5/C5_AktuelleVersion/C5_AktuelleVersion_node.html). These standards address hundreds of requirements which are published at the given links. So here's just a summary to understand the approach of the broadest requirements from IT-Grundschutz.
 
 **Reference:** [Deutsche Verwaltungscloud-Strategie – Rahmenwerk der Zielarchitektur](https://www.cio.bund.de/SharedDocs/downloads/Webs/CIO/DE/cio-bund/steuerung-it-bund/beschluesse_cio-board/2023_11_Beschluss_CIO_Board_DVS_Rahmenwerk_Anlage.pdf)
@@ -141,7 +158,7 @@ We are aware that IT-Grundschutz is a complex topic and are working towards a st
 
 # Accessibility
 
-Accessibility is a key requirement for software that is being used in the public sector. Therefore the products of the suppliers are expected to adhere to the relevant standards.
+Accessibility is a key requirement for software that is being used in the public sector. Therefore the products of the suppliers MUST adhere to the relevant standards.
 
 Please find more context about the topic on the [website of the German CIO](https://www.cio.bund.de/Webs/CIO/DE/digitaler-wandel/it-barrierefreiheit/vorgaben-und-richtlinien/vorgaben-und-richtlinien-node.html) followed by a more detailed look at the actual accessibility standard [WCAG 2.1](https://www.barrierefreiheit-dienstekonsolidierung.bund.de/Webs/PB/DE/gesetze-und-richtlinien/wcag/wcag-artikel.html).
 
@@ -155,7 +172,7 @@ Each vendor must provide a certificate that their product - or the parts of the
 
 # Data protection
 
-Each component must be able to operate according to the [EU's General Data Protection Regulation (GDPR)](https://gdpr.eu/). This requires some key messages to be answered when it comes to personal data[^1]:
+Each component MUST be able to operate according to the [EU's General Data Protection Regulation (GDPR)](https://gdpr.eu/). This requires some key messages to be answered when it comes to personal data[^1]:
 
 - Who are the affected data subjects?
 - What personal data (attributes) from the subjects is being processed?
@@ -201,15 +218,15 @@ Applications can access the IAM's LDAP to access all data necessary for managing
 
 ### Push: Provisioning
 
-Some applications require active provisioning of the centrally maintained IAM data. As the actual provisioning is part of the openDesk provisioning framework it is necessary to define the ULC flow regarding its different states to get a matching provisioning connector implemented. This is done collaboratively between the supplier and openDesk product management.
+Some applications require active provisioning of the centrally maintained IAM data. As the actual provisioning is part of the openDesk provisioning framework, it is necessary to define the ULC flow regarding its different states to get a matching provisioning connector implemented. This is done collaboratively between the supplier and openDesk product management.
 
 **Reference:** New applications will make use of the [provisioning framework](https://gitlab.opencode.de/bmi/opendesk/component-code/crossfunctional/univention/ums-provisioning-api). At the moment to only active (push) provisioned component is OX AppSuite fed by the [OX-connector](https://github.com/univention/ox-connector/tree/ucs5.0).
 
 ## Authentication
 
-The central IdP ensures the single sign-on and logout workflows. As standard openDesk uses [Open ID Connect](https://openid.net/). It can be configured to provide additional user information from the IAM when required by a component.
+The central IdP ensures the single sign-on and logout workflows. openDesk consistently uses [Open ID Connect](https://openid.net/). It can be configured to provide additional user information from the IAM if required by a component.
 
-Minimum requirements regarding the OIDC support in an application besides the actual login flow:
+The following configuration is REQUIRED regarding the OIDC support in a component, besides the actual login flow:
 
 - Back-channel logout: [OIDC Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html) must be supported by the components unless there is a significant reason why it technically cannot be supported, in that case [OIDC Front-Channel Logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html) is the alternative.
 - IdP Session Refresh: Ensure that your application regularly checks the IdP session for its validity and invalidates the local session when there is no longer an IdP session.
@@ -218,10 +235,12 @@ Minimum requirements regarding the OIDC support in an application besides the ac
 
 ## Top bar
 
-The top bar of all applications should provide a common UX.
+The top bar of all applications SHOULD provide a common UX.
 
 ### Look and feel
 
+[ToDo: make req. clear according to RFC2119]
+
 The current status is subject to review, but the basics will most likely stay the same. Ensure that the top bar can be customized (or adheres to a given openDesk standard) in various settings:
 
 - Size (height) of the bar.
@@ -236,9 +255,11 @@ The current status is subject to review, but the basics will most likely stay th
 
 ### Central navigation
 
-From the top bar, the user can access the central navigation. A menu that gets its contents from the portal, rending the categories and (sub-)applications available to the logged-in user.
+[ToDo: make req. clear according to RFC2119]
 
-When implementing the central navigation into an application there are two options to access the user's data from the portal:
+From the top bar, the user can access the central navigation: A menu that gets its contents from the portal components, rendering the categories and (sub-)applications available to the logged-in user.
+
+When implementing the central navigation into an application, there are two options to access the user's data from the portal:
 
 - Frontend-based: Issuing an IFrame-based silent login against the intercom service (ICS) to get a session with the ICS, followed by a request for the JSON containing the user's central navigation contents through the ICS.
 - Backend-based: Requesting the JSON using a backend call to the portal providing the user's name and a shared secret.
@@ -247,7 +268,7 @@ When implementing the central navigation into an application there are two optio
 
 ## Functional administration
 
-While applications usually support technical and functional administration the technical part should be in the responsibility of the operator and is usually done at (re)deployment time. Therefore the administrative tasks within an application should be limited to functional administration.
+While applications usually support technical and functional administration, the technical part SHOULD be in the responsibility of the operator and is usually done at (re)deployment time. Therefore, the administrative tasks within an application should be limited to functional administration.
 
 Example for "technical administration":
 - Configuring the SMTP relay for an application to send out emails.
@@ -259,17 +280,17 @@ Example of "functional administration":
 
 ## Theming
 
-Theming should be controlled with the deployment and affect all components that support branding options.
+Theming MUST be controlled with the deployment and affect all components that support branding options.
 
 **Reference:** https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/issues/27
 
 ## Central user profile
 
-The user profile is maintained centrally, therefore the applications should make use of that central data and not allow local editing of the data within the application except for data that is required by the application and cannot be provided by the central IAM.
+The user profile is maintained centrally, therefore the components SHOULD make use of that central data and not allow local editing of the data within the application, except for data that is required by the component and that cannot be provided by the central IAM.
 
-The data can still be rendered but must not be tampered with in any way within an openDesk application outside of the IAM, as it would either cause inconsistent data within the platform or the changed data being overwritten, which is at least unexpected by the user.
+The data can still be rendered but MUST NOT be tampered with in any way within an openDesk application outside of the IAM, as it would either cause inconsistent data within openDesk or the changed data being overwritten, which is at least unexpected behaviour from the user's perspective.
 
-The user's preferred language and theme (light/dark) are also selected in the IAM's portal and the setting should be respected in all applications.
+The user's preferred language and theme (light/dark) are also selected in the IAM's portal and the setting SHOULD be respected in all components.
 
 **Reference:** No reference yet.