Package org.bouncycastle.crypto.params

Classes for parameter objects for ciphers and generators.

Several parameter types in this package are wrappers: each carries one extra value and a getParameters() link to the CipherParameters it decorates, so a caller supplies a nested chain ending in a key. The wrappers are ParametersWithContext, ParametersWithID, ParametersWithRandom, ParametersWithUKM, ParametersWithIV, ParametersWithSBox and ParametersWithSalt.

There is no enforced nesting order, but the implementations share a de facto one. A component unwraps only the wrapper it consumes and passes the remainder down, so a wrapper sits outside everything consumed further down the stack. Outermost first, the order used throughout the lightweight API and by the JCE provider when it builds these chains is:

  • ParametersWithContext or ParametersWithID - a signature context string (ML-DSA, SLH-DSA and similar) or a signer identity (SM2, SM9), consumed by the signer.
  • ParametersWithRandom - consumed by the outermost component that needs randomness: a signer, an asymmetric encoding, a wrap engine, or a padded buffered cipher. Block cipher modes and stream ciphers do not unwrap it, so it must not be nested inside an IV.
  • ParametersWithUKM - the user keying material of the GOST 28147 wrap engines.
  • ParametersWithIV - the IV or nonce, consumed by the cipher mode, stream cipher or MAC.
  • ParametersWithSBox - the GOST 28147 S-box, consumed by the engine and so placed directly around the key.
  • the key itself: KeyParameter or an AsymmetricKeyParameter.
So, for example, a GOST 28147 CBC cipher takes IV(SBox(key)), a padded CBC cipher takes Random(IV(key)), and an ML-DSA signer takes Context(Random(privateKey)).

ParametersWithSalt is used only by ISO9796d2PSSSigner, which accepts it as an alternative to ParametersWithRandom rather than nested with it. A few GOST classes (GOST28147Mac in particular) accept their wrappers in any order; most implementations do not, and a chain nested against the order above is usually rejected with an IllegalArgumentException or a ClassCastException. AEADParameters is a self-contained alternative to ParametersWithIV for AEAD modes and combines key, nonce, tag length and associated data without nesting.