operationMode extended form

[toscalix]

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

• Description: the mode of operation under which a block cipher is applied to data. Modes are standardised constructions that compose the cipher's primitive transformation into a complete encryption scheme over arbitrary-length input.
  • GCM: Galois/Counter Mode
    • NIST SP 800-38D: https://csrc.nist.gov/pubs/sp/800/38/d/final
  • CCM: Counter with CBC-MAC
    • NIST SP 800-38C: https://csrc.nist.gov/pubs/sp/800/38/c/upd1/final
  • CBC: Cipher Block Chaining
    • NIST SP 800-38A: https://csrc.nist.gov/pubs/sp/800/38/a/final
  • CTR: Counter Mode
    • NIST SP 800-38A: https://csrc.nist.gov/pubs/sp/800/38/a/final
  • OFB: Output Feedback Mode
    • NIST SP 800-38A: https://csrc.nist.gov/pubs/sp/800/38/a/final
  • CFB: Cipher Feedback Mode
    • CFB1: NIST SP 800-38A (s = 1 bit): https://csrc.nist.gov/pubs/sp/800/38/a/final
    • CFB8: NIST SP 800-38A (s = 8 bits): https://csrc.nist.gov/pubs/sp/800/38/a/final
    • CFB128: NIST SP 800-38A (s = 128 bits): https://csrc.nist.gov/pubs/sp/800/38/a/final
  • XTS: XEX-based Tweaked Cipher Mode with ciphertext stealing
    • NIST SP 800-38E: https://csrc.nist.gov/pubs/sp/800/38/e/final
  • SIV: Synthetic Initialization Vector
    • RFC 5297: https://datatracker.ietf.org/doc/html/rfc5297
  • GCM-SIV: GCM with Synthetic IV
    • RFC 8452: https://datatracker.ietf.org/doc/html/rfc8452
  • EAX: Encrypt-then-Authenticate-then-Translate Mode
    • ISO/IEC 19772; Bellare, Rogaway, Wagner (FSE 2004): https://web.cs.ucdavis.edu/~rogaway/papers/eax.pdf
  • OCB: Offset Codebook Mode
    • OCB2: ISO/IEC 19772:2009: https://www.iso.org/standard/46345.html
    • OCB3: RFC 7253: https://datatracker.ietf.org/doc/html/rfc7253
  • CTS: Ciphertext Stealing
    • CBC-CS1: NIST SP 800-38A Addendum: https://csrc.nist.gov/pubs/sp/800/38/a/add/final
    • CBC-CS2: NIST SP 800-38A Addendum: https://csrc.nist.gov/pubs/sp/800/38/a/add/final
    • CBC-CS3: NIST SP 800-38A Addendum: https://csrc.nist.gov/pubs/sp/800/38/a/add/final
  • CWC: Carter-Wegman Counter Mode
    • Kohno, Viega, Whiting (FSE 2004): https://eprint.iacr.org/2003/106
  • IAPM: Integrity-Aware Parallelizable Mode
    • Jutla (EUROCRYPT 2001): https://eprint.iacr.org/2000/039
  • LRW: Liskov-Rivest-Wagner Mode
    • Liskov, Rivest, Wagner (CRYPTO 2002): https://people.csail.mit.edu/rivest/pubs/LRW02.pdf
  • XEX: XOR-Encrypt-XOR Mode
    • Rogaway (ASIACRYPT 2004): https://www.cs.ucdavis.edu/~rogaway/papers/offsets.pdf
  • CMC: CBC-Mask-CBC Mode
    • Halevi, Rogaway (CRYPTO 2003): https://eprint.iacr.org/2003/148
  • EME: Encrypt-Mix-Encrypt Mode
    • Halevi, Rogaway (CT-RSA 2004): https://eprint.iacr.org/2003/147
  • HCTR2: Length-Preserving Encryption with HCTR2
    • Crowley, Huckleberry, Biggers (IACR ePrint 2021/1441): https://eprint.iacr.org/2021/1441
  • CMAC: Cipher-based MAC
    • NIST SP 800-38B: https://csrc.nist.gov/pubs/sp/800/38/b/upd1/final
  • GMAC: Galois MAC
    • NIST SP 800-38D: https://csrc.nist.gov/pubs/sp/800/38/d/final
  • PMAC: Parallelizable MAC
    • Black, Rogaway (EUROCRYPT 2002): https://www.cs.ucdavis.edu/~rogaway/papers/pmac.pdf
  • PCBC: Propagating CBC
    • No formal standard; used in Kerberos v4 (see RFC 1510, historical): https://www.rfc-editor.org/info/rfc1510/
  • IGE: Infinite Garble Extension
    • No formal standard; first described by Campbell (1978); used in Telegram MTProto: https://core.telegram.org/mtproto/description. Check Ben Laurie description on openSSL-IGE https://www.links.org/files/openssl-ige.pdf
  • ECB: Electronic Codebook
    • NIST SP 800-38A: https://csrc.nist.gov/pubs/sp/800/38/a/final
  • FF1: Format-Preserving Encryption method 1
    • NIST SP 800-38G: https://csrc.nist.gov/pubs/sp/800/38/g/upd1/final
  • FF3: Format-Preserving Encryption method 3 (original)
    • NIST SP 800-38G (withdrawn 2016, superseded by FF3-1-draft after Durak-Vaudenay attack): https://csrc.nist.gov/pubs/sp/800/38/g/final
  • FF3-1: Format-Preserving Encryption method 3, revised
    • NIST SP 800-38G Revision 1 (draft): https://csrc.nist.gov/pubs/sp/800/38/g/r1/2pd
  • Wrap: Key Wrap
    • KW: NIST SP 800-38F: https://csrc.nist.gov/pubs/sp/800/38/f/final
    • KWP: NIST SP 800-38F: https://csrc.nist.gov/pubs/sp/800/38/f/final
    • TKW: NIST SP 800-38F (TDEA-based, legacy applications): https://csrc.nist.gov/pubs/sp/800/38/f/final
  • XCBC_MAC: XCBC Message Authentication Code (Black, Rogaway, CRYPTO 2000)
    • XCBC_MAC: full-length construction: https://www.cs.ucdavis.edu/~rogaway/papers/3k.pdf
    • XCBC_MAC_96: truncated to 96 bits, RFC 3566: https://datatracker.ietf.org/doc/html/rfc3566
• Applicability: determines which security service the construction provides (confidentiality only, authenticated encryption, AEAD, or key wrapping) and what auxiliary inputs the scheme requires (initialisation vector, nonce, authentication tag, padding). A given mode is only meaningful for a block cipher of a compatible block size.
• Cardinality: [1..*]
• Values: "GCM", "CCM", "CBC", "CTR", "OFB", "CFB", "CFB1", "CFB8", "CFB128", "XTS", "SIV", "GCM-SIV", "EAX", "OCB", "OCB2", "OCB3", "CTS", "CBC-CS1", "CBC-CS2", "CBC-CS3", "CWC", "IAPM", "LRW", "XEX", "CMC", "EME", "HCTR2", "CMAC", "GMAC", "PMAC", "PCBC", "IGE", "ECB", "FF1", "FF3", "FF3-1", "Wrap", "KW", "KWP", "TKW", "XCBC_MAC", "XCBC_MAC_96"

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