spdx / spdx/cryptographic-algorithm-list

operationMode extended form

Open
#82 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
No language data
Stars
8
Forks
4
No merged PRs in 30d

Description

Background

The Cryptography Group decided to go for the "short form" of describing the operationMode parameter first, and later on, based on community request, evaluate the possibility to add the "extended form" of describing the operationMode on any specific algorithm.

The "extended form" is already described in a proposal so a significant part of the required work to add this more detailed way to describe the operationMode of any specific algorithm is already done.

Rationale

The Cryptography Group is not sure about the need for the "extended form" in the List. If there is any use case that justifies it, then it should be considered. For now, #80 and #81 describe the needs at this point.

Description

In addition to the current way to describe the operationMode of an algorithm, there is a second way we have identified and described. We call that additional way to describe the operationMode "extended form", vs the current way which is called "short form".

This is the way we would introduce the "extended form" into the docs/crypto-algorithms-list-properties-parameters-description.md

`### parameterName

  • Description: The set of valid values depends on the algorithm's cryptoClass / cryptoSubClass. Each parameter have a different structure so their description is specific to each one of them
  • Cardinality: [0..*]
  • Values:
    • Enumeration: "operationMode", "padding", "paddingScheme", "digestFunction", "variant", "construction", "pseudorandomFunction", "group", "curve", "pointCompression", "polynomial", "underlyingCipher"
    • Numeric: "nonceLength", "ivLength", "tagLength", "keyLength", "outputLength", "saltLength", "modulusLength", "pPrimeLength", "qPrimeLength", "publicExponent", "iterations", "memoryCost", "parallelism", "costFactor", "rounds", "dropBytes"
operationMode
Qualifiers (extended form)

An algorithm entry can describe operationMode in two ways.

  • Short form: only the operationMode value is given, using one of the values listed above. This states which mode applies, with no further detail.
  • Extended form: the operationMode value is given together with one or more qualifiers. The qualifiers add the length or scheme detail that applies to that specific algorithm and mode, such as the nonce length, the IV length, the tag length, or the padding scheme in use.

The extended form is used when the group wants to record the exact configuration used with a mode, not only the mode name. Each qualifier is described below.

The extended form is a list. Each list item is a mapping that starts with its own operationMode key, plus whichever qualifiers apply to that specific mode. A plain YAML mapping cannot repeat the same key twice at the same level, so each mode's qualifiers must live inside its own list item rather than all being written flat under a single shared operationMode: key.

operationMode:
  - operationMode: 'GCM'
    nonceLength: '96'
    tagLength: '128'
  - operationMode: 'CBC'
    padding: 'PKCS7'
  - operationMode: 'CTR'

Modes with no qualifiers (like CTR above) are listed with just their operationMode key and nothing else.

nonceLength
  • Description: nonce length
  • Cardinality: [0..1]
  • Values: one of these options, or a combination of them, are valid
    • '', where is an integer, provided in bits, as a quoted string.
    • ['','', ... ''], where , , ... are different integers, provided in bits, and in ascendant order.
    • {min: '', max: ''}, where is the minimum integer, and is the maximum integer of the range, both provided in bits.
ivLength
  • Description: initialization vector length
  • Cardinality: [0..1]
  • Values: one of these options, or a combination of them, are valid
    • '', where is an integer, provided in bits, as a quoted string.
    • ['','', ... ''], where , , ... are different integers, provided in bits, and in ascendant order.
    • {min: '', max: ''}, where is the minimum integer, and is the maximum integer of the range, both provided in bits.
tagLength
  • Description: authentication tag length
  • Cardinality: [0..1]
  • Values: one of these options, or a combination of them, are valid
    • '', where is an integer, provided in bits, as a quoted string.
    • ['','', ... ''], where , , ... are different integers, provided in bits, and in ascendant order.
    • {min: '', max: ''}, where is the minimum integer, and is the maximum integer of the range, both provided in bits.
padding
  • Description: the padding scheme used to handle a plaintext length that is not a multiple of the block size, for block-cipher modes such as CBC. This is distinct from paddingScheme, which applies to public-key primitives (e.g. RSA-OAEP, RSA-PSS) and covers a different, non-overlapping set of values.
  • Cardinality: [0..1]
  • Values: a single string (padding scheme id), or an array of strings if more than one padding scheme is valid for that mode entry`

Examples of algorithms described through this "extended form" are

# rc5.yaml (extended form, when the padded variant needs to be distinguished) parameters: operationMode: - operationMode: 'ECB' - operationMode: 'CBC' padding: 'PKCS5' - operationMode: 'CTS' keyLength: {min: '0', max: '2040'}

and

parameters: operationMode: - operationMode: 'GCM' nonceLength: '96' tagLength: '128' - operationMode: 'CBC' padding: 'PKCS7' - operationMode: 'CTR'

Actions

  • The Cryptography Group decides to incorporate the operationMode "extended form" description into the List
  • Re-evaluate the current "extended form" description and create a proposal, including several algorithms
  • Discussion and approval within the Cryptography Group of the proposal
  • Create the corresponding PR
    • One for the description file
    • One for the affected algorithms
  • Approve the PRs

DoD

  • Link to the MoM where the Cryptography Group decides to incorporate the "extended form"
  • Link to the proposal
  • Link to PRs
  • Link to the approved description and affected algorithms

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with docs/crypto-algorithms-list-properties-parameters-description.md and review the proposal and Cryptography Group decision referenced by the issue. Confirm the extended-form description and affected algorithm entries, then track the documentation and algorithm PRs; done means the MoM, proposal, approved description, affected algorithms, and PRs are linked.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown, yaml
Domain
cryptography, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.