From 5e9fad04f49752629a6ae012adbbf3ab0da1c1ec Mon Sep 17 00:00:00 2001 From: toscalix Date: Wed, 25 Mar 2026 13:13:07 +0000 Subject: [PATCH 1/3] adding the process to add or remove algorithms to contributing.md --- CONTRIBUTING.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 248d216..5c6e785 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,9 +20,90 @@ name: SPDX Cryptographic Algorithm List Example cryptoClass: Symmetric-Key-Algorithm/Encoding commonkeySize: ['256', '512'] specifiedkeySize: {min: '128', max: '256'} +reference: + - https://doi.org/10.17487/RFC2144 + - https://tnlandforms.us/cs594-cns96/cast.pdf ``` --- +## Inclusion and Removal of Cryptographic Algorithms + +This section describes the process by which algorithms are added to, deprecated in, or removed from SPDX CryptAlg. It covers how proposals are submitted, how the Cryptography Group evaluates and decides on them, and what is required before a change reaches a pull request and is merged. + +The criteria the Cryptography Group uses to decide whether an algorithm is eligible for inclusion, deprecation, or removal are maintained separately in the [Cryptographic Algorithm Inclusion and Removal Criteria](docs/cryptographic-algorithm-inclusion-removal-criteria.md) document. This section does not reproduce those criteria; it describes the process that applies once a proposal has been submitted. + +### Proposing a New Algorithm + +#### Step 1 — Open a GitHub issue + +Every proposal for a new algorithm must begin with a GitHub issue in the [working repository](https://github.com/spdx/cryptographic-algorithm-list). A pull request must never be the first step. The issue is where the proposal is described, discussed, and allowed to mature before any formal review takes place. + +The issue must include, at minimum, the mandatory attributes: + +- The proposed SPDX CryptAlg identifier (`id`) for the algorithm. +- The full name of the algorithm. +- The proposed `cryptoClass` and subclass. +- A brief justification explaining why the algorithm meets the inclusion criteria, with reference to the relevant key or additional factors described in the [Cryptographic Algorithm Inclusion and Removal Criteria](docs/cryptographic-algorithm-inclusion-removal-criteria.md) document. +- At least one reference to a stable, publicly accessible specification, standard, or authoritative technical document describing the algorithm. + +Proposals that do not include these elements may be put on hold until the missing information is provided. + +#### Step 2 — Community discussion + +Once the issue is open, it is discussed asynchronously through comments and, where needed, synchronously in Cryptography Group meetings. Any conclusions or agreements reached in meetings are recorded in the issue. The issue remains open until the group has reached sufficient consensus on whether the algorithm is suitable for inclusion and, if so, on the content of its entry. + +The Release Coordinator or any group member may label the issue to reflect its current status in the process (for example, `under-review`, `agreed`, or `more-info-needed`). + +There is no fixed timeline for this discussion phase. Proposals that are straightforward and clearly meet the inclusion criteria may move quickly. Proposals that raise questions — about categorisation, key sizes, the right identifier, or the relationship to an algorithm already on the list — will take longer. The quality of the final entry matters more than speed. + +#### Step 3 — Open a pull request + +A pull request may only be opened once the Cryptography Group has reached sufficient consensus in the issue that: +- The algorithm is suitable for inclusion. +- The proposed identifier, cryptoClass, and other properties are agreed upon. + +The pull request must include a `.yaml` file for the algorithm, stored in the `yaml/` folder of the working repository, and named `.yaml` where `` is the agreed SPDX CryptAlg identifier. The file must conform to the schema defined in the working repository and must include, at minimum, all mandatory properties as defined in the [properties description file](docs/crypto-algorithms-list-properties-description.md). Submitters are strongly encouraged to also include optional properties, in particular `oid` and `reference`, where these are known. + +The pull request description must reference the issue where the proposal was discussed. + +Submissions that do not conform to the schema, or where the corresponding issue has not reached consensus, will not be merged. + +#### Step 4 — Review and merge + +The pull request is reviewed by the Cryptography Group following the standard review process. At least one group member other than the author must approve the pull request before it can be merged. The Release Coordinator, or any group member with merge rights, may merge the pull request once the review conditions are satisfied. + +Once merged, the algorithm entry will be included in the next scheduled release, provided it is merged before the data freeze date defined in section 3.1. + +### Proposing a Correction to an Existing Entry + +Corrections to existing algorithm entries — for example, fixing an incorrect `cryptoClass`, updating a key size, or adding a missing `oid` or `reference` — follow a lighter version of the same process. + +A GitHub issue must still be opened before a pull request, unless the correction is clearly trivial (for example, fixing a typo in the `name` field). For corrections that affect the meaning or categorisation of an entry, the issue allows the group to verify the proposed change before it is submitted for review. The pull request must reference the issue and include a plain-language description of what was changed and why. + +### Proposing Deprecation or Removal of an Algorithm + +#### Deprecation + +Deprecation is the standard response when an algorithm on the list is no longer recommended for use in new SPDX documents — for example, because it has been superseded, withdrawn by a standardisation body, or found to be cryptographically weak. Deprecation retains the entry on the list with its identifier intact, ensuring backward compatibility for existing documents and downstream tools. + +A proposal to deprecate an algorithm follows the same issue-first process described in section 6.1. The issue must explain the reason for the deprecation and, where applicable, identify the superseding algorithm or standard. Once the group reaches consensus, a pull request is opened to update the algorithm's `.yaml` file with the appropriate deprecation markers. + +#### Removal + +Removal is reserved for the specific cases described in the [Cryptographic Algorithm Inclusion and Removal Criteria](docs/cryptographic-algorithm-inclusion-removal-criteria.md) document. Because removal can break downstream tools and eliminates traceability, it requires a higher level of scrutiny than deprecation. + +A proposal to remove an algorithm must be submitted as a GitHub issue. The issue must: +- Identify the algorithm by its SPDX CryptAlg identifier. +- State clearly the reason for removal, with reference to the removal criteria. +- Describe the potential impact on downstream tools and SPDX documents that may have referenced the identifier. + +The Cryptography Group must reach explicit agreement — not merely the absence of objection — before a removal is approved. This agreement must be recorded in the issue. The pull request that carries out the removal must reference the issue and include a description of the impact and any migration guidance for downstream consumers. + +Removal must be documented in the release notes of the release in which it occurs, including the removed identifier, the reason, and guidance for any downstream tools that may have referenced it. +--- + +## About the List + * All the properties are described on the SPDX Cryptographic Algorithms List [properties description file](https://github.com/spdx/cryptographic-algorithm-list/blob/main/crypto-algorithms-list-properties-description.md). * All the algorithms from the SPDX Cryptographic Algorithm List are included in the [yaml folder](https://github.com/spdx/cryptographic-algorithm-list/tree/main/yaml). * For each algorithm you will find a .yaml file, with the name .yaml , where is the SPDX identifier for the corresponding cryptographic algorithm From 136ff27537441a402d4959bdff375227d557b25b Mon Sep 17 00:00:00 2001 From: toscalix Date: Wed, 25 Mar 2026 17:44:18 +0000 Subject: [PATCH 2/3] modified contributing.md to remove the concept of deprecation --- CONTRIBUTING.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5c6e785..3ad6fd7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,9 +28,9 @@ reference: ## Inclusion and Removal of Cryptographic Algorithms -This section describes the process by which algorithms are added to, deprecated in, or removed from SPDX CryptAlg. It covers how proposals are submitted, how the Cryptography Group evaluates and decides on them, and what is required before a change reaches a pull request and is merged. +This section describes the process by which algorithms are added to or removed from SPDX CryptAlg. It covers how proposals are submitted, how the Cryptography Group evaluates and decides on them, and what is required before a change reaches a pull request and is merged. -The criteria the Cryptography Group uses to decide whether an algorithm is eligible for inclusion, deprecation, or removal are maintained separately in the [Cryptographic Algorithm Inclusion and Removal Criteria](docs/cryptographic-algorithm-inclusion-removal-criteria.md) document. This section does not reproduce those criteria; it describes the process that applies once a proposal has been submitted. +The criteria the Cryptography Group uses to decide whether an algorithm is eligible for inclusion or removal are maintained separately in the [Cryptographic Algorithm Inclusion and Removal Criteria](docs/cryptographic-algorithm-inclusion-removal-criteria.md) document. This section does not reproduce those criteria; it describes the process that applies once a proposal has been submitted. ### Proposing a New Algorithm @@ -38,12 +38,14 @@ The criteria the Cryptography Group uses to decide whether an algorithm is eligi Every proposal for a new algorithm must begin with a GitHub issue in the [working repository](https://github.com/spdx/cryptographic-algorithm-list). A pull request must never be the first step. The issue is where the proposal is described, discussed, and allowed to mature before any formal review takes place. -The issue must include, at minimum, the mandatory attributes: +The issue must include, at minimum: - The proposed SPDX CryptAlg identifier (`id`) for the algorithm. - The full name of the algorithm. - The proposed `cryptoClass` and subclass. -- A brief justification explaining why the algorithm meets the inclusion criteria, with reference to the relevant key or additional factors described in the [Cryptographic Algorithm Inclusion and Removal Criteria](docs/cryptographic-algorithm-inclusion-removal-criteria.md) document. +- A brief justification explaining: + - why the algorithm meets the inclusion criteria, with reference to the relevant key additional factors described in the [Cryptographic Algorithm Inclusion and Removal Criteria](docs/cryptographic-algorithm-inclusion-removal-criteria.md) document. + - if the proposal is related to or the result of decisions, modifications or updates on algorithms approved within standardization bodies or pushed by the algorithm authors - At least one reference to a stable, publicly accessible specification, standard, or authoritative technical document describing the algorithm. Proposals that do not include these elements may be put on hold until the missing information is provided. @@ -52,7 +54,7 @@ Proposals that do not include these elements may be put on hold until the missin Once the issue is open, it is discussed asynchronously through comments and, where needed, synchronously in Cryptography Group meetings. Any conclusions or agreements reached in meetings are recorded in the issue. The issue remains open until the group has reached sufficient consensus on whether the algorithm is suitable for inclusion and, if so, on the content of its entry. -The Release Coordinator or any group member may label the issue to reflect its current status in the process (for example, `under-review`, `agreed`, or `more-info-needed`). +The issue should reflect its current status in the process on every step. There is no fixed timeline for this discussion phase. Proposals that are straightforward and clearly meet the inclusion criteria may move quickly. Proposals that raise questions — about categorisation, key sizes, the right identifier, or the relationship to an algorithm already on the list — will take longer. The quality of the final entry matters more than speed. @@ -60,9 +62,9 @@ There is no fixed timeline for this discussion phase. Proposals that are straigh A pull request may only be opened once the Cryptography Group has reached sufficient consensus in the issue that: - The algorithm is suitable for inclusion. -- The proposed identifier, cryptoClass, and other properties are agreed upon. +- The proposed identifier, full name, cryptoClass, and other properties are agreed upon. -The pull request must include a `.yaml` file for the algorithm, stored in the `yaml/` folder of the working repository, and named `.yaml` where `` is the agreed SPDX CryptAlg identifier. The file must conform to the schema defined in the working repository and must include, at minimum, all mandatory properties as defined in the [properties description file](docs/crypto-algorithms-list-properties-description.md). Submitters are strongly encouraged to also include optional properties, in particular `oid` and `reference`, where these are known. +The pull request must include a `.yaml` file for the algorithm, stored in the `yaml/` folder of the working repository, and named `.yaml` where `` is the agreed SPDX CryptAlg identifier. The file must conform to the schema defined in the working repository and must include, at minimum, all mandatory properties as defined in the [properties description file](docs/crypto-algorithms-list-properties-description.md). Submitters are strongly encouraged to also include optional properties where these are known. The pull request description must reference the issue where the proposal was discussed. @@ -70,36 +72,34 @@ Submissions that do not conform to the schema, or where the corresponding issue #### Step 4 — Review and merge -The pull request is reviewed by the Cryptography Group following the standard review process. At least one group member other than the author must approve the pull request before it can be merged. The Release Coordinator, or any group member with merge rights, may merge the pull request once the review conditions are satisfied. +The pull request is reviewed by the Cryptography Group following the standard review process. At least one group member other than the author must approve the pull request before it can be merged. Any group member with merge rights may merge the pull request once the review conditions are satisfied. -Once merged, the algorithm entry will be included in the next scheduled release, provided it is merged before the data freeze date defined in section 3.1. +Once merged, the algorithm entry will be included in the next scheduled release, provided it is merged before the data freeze date defined in section 3.1 of the [release process](/DOCS/spdx-cyptographic-algorithm-list-release-process.md]. ### Proposing a Correction to an Existing Entry -Corrections to existing algorithm entries — for example, fixing an incorrect `cryptoClass`, updating a key size, or adding a missing `oid` or `reference` — follow a lighter version of the same process. +Corrections to existing algorithm entries — for example, fixing an incorrect `cryptoClass`, updating a key size, or adding a missing value to any property — follow a lighter version of the same process. A GitHub issue must still be opened before a pull request, unless the correction is clearly trivial (for example, fixing a typo in the `name` field). For corrections that affect the meaning or categorisation of an entry, the issue allows the group to verify the proposed change before it is submitted for review. The pull request must reference the issue and include a plain-language description of what was changed and why. ### Proposing Deprecation or Removal of an Algorithm -#### Deprecation - -Deprecation is the standard response when an algorithm on the list is no longer recommended for use in new SPDX documents — for example, because it has been superseded, withdrawn by a standardisation body, or found to be cryptographically weak. Deprecation retains the entry on the list with its identifier intact, ensuring backward compatibility for existing documents and downstream tools. - -A proposal to deprecate an algorithm follows the same issue-first process described in section 6.1. The issue must explain the reason for the deprecation and, where applicable, identify the superseding algorithm or standard. Once the group reaches consensus, a pull request is opened to update the algorithm's `.yaml` file with the appropriate deprecation markers. - -#### Removal - -Removal is reserved for the specific cases described in the [Cryptographic Algorithm Inclusion and Removal Criteria](docs/cryptographic-algorithm-inclusion-removal-criteria.md) document. Because removal can break downstream tools and eliminates traceability, it requires a higher level of scrutiny than deprecation. +Removal is reserved for the specific cases described in the [Cryptographic Algorithm Inclusion and Removal Criteria](docs/cryptographic-algorithm-inclusion-removal-criteria.md) document. Because removal can break downstream tools and eliminates traceability, it requires a higher level of scrutiny than other changes to the list. A proposal to remove an algorithm must be submitted as a GitHub issue. The issue must: + - Identify the algorithm by its SPDX CryptAlg identifier. - State clearly the reason for removal, with reference to the removal criteria. -- Describe the potential impact on downstream tools and SPDX documents that may have referenced the identifier. +- Describe the potential impact on downstream tools and SPDX documents that may have referenced the identifier, if known. The Cryptography Group must reach explicit agreement — not merely the absence of objection — before a removal is approved. This agreement must be recorded in the issue. The pull request that carries out the removal must reference the issue and include a description of the impact and any migration guidance for downstream consumers. Removal must be documented in the release notes of the release in which it occurs, including the removed identifier, the reason, and guidance for any downstream tools that may have referenced it. + +## Relationship Between the Proposal Process and the Release Cycle + +The proposal process described in this section — issue, discussion, consensus, pull request, review, merge — is independent of the release cadence. An algorithm entry may be proposed and discussed at any time. What the release cadence governs is when a merged change becomes part of a published release: any pull request merged before the data freeze date defined in section 3.1 of the [release process](/DOCS/spdx-cyptographic-algorithm-list-release-process.md] will be included in that month's release. Pull requests merged after the freeze will be included in the following release, except in those extraordinary cases described in the release process. + --- ## About the List From 6f0119dc8d64b69139cd0d00a5598e226bffb795 Mon Sep 17 00:00:00 2001 From: toscalix Date: Wed, 25 Mar 2026 19:55:08 +0000 Subject: [PATCH 3/3] the word deprecation removed from a title --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ad6fd7..bd5ba07 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,7 +82,7 @@ Corrections to existing algorithm entries — for example, fixing an incorrect ` A GitHub issue must still be opened before a pull request, unless the correction is clearly trivial (for example, fixing a typo in the `name` field). For corrections that affect the meaning or categorisation of an entry, the issue allows the group to verify the proposed change before it is submitted for review. The pull request must reference the issue and include a plain-language description of what was changed and why. -### Proposing Deprecation or Removal of an Algorithm +### Proposing Removal of an Algorithm Removal is reserved for the specific cases described in the [Cryptographic Algorithm Inclusion and Removal Criteria](docs/cryptographic-algorithm-inclusion-removal-criteria.md) document. Because removal can break downstream tools and eliminates traceability, it requires a higher level of scrutiny than other changes to the list.