Skip navigation links
Bouncy Castle Cryptography Library 1.87

Package org.bouncycastle.crypto.params

Classes for parameter objects for ciphers and generators.

See: Description

Package org.bouncycastle.crypto.params Description

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:

So, for example, a GOST 28147 CBC cipher takes IV(SBox(key)), a padded CBC cipher takes Random(IV(key)), an ML-DSA signer takes Context(Random(privateKey)), and a GOST 28147 wrap engine takes UKM(Random(SBox(key))). The GOST 28147 wrap engines also still accept the earlier Random(UKM(SBox(key))).

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.

Rejecting other nestings is intended. New code should accept the order above and nothing else. Accepting an alternative order is a compatibility measure, and is justified only where existing callers are known to build it, as with the earlier Random(UKM(..)) of the GOST 28147 wrap engines. An alternative added speculatively becomes a second form that every caller, wrapper and port then has to keep supporting.

Skip navigation links
Bouncy Castle Cryptography Library 1.87