Skip to content

Commit 07ce709

Browse files
committed
ParametersWithUKM now nests outside ParametersWithRandom: GOST28147WrapEngine, CryptoProWrapEngine and ECVKOAgreement accept it, the wrap engines still accept the earlier order, and the provider's GOST 28147 key wrap ciphers build it.
1 parent 0a65497 commit 07ce709

9 files changed

Lines changed: 184 additions & 14 deletions

File tree

‎core/src/main/java/org/bouncycastle/crypto/agreement/ECVKOAgreement.java‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
import org.bouncycastle.crypto.params.ECDomainParameters;
99
import org.bouncycastle.crypto.params.ECPrivateKeyParameters;
1010
import org.bouncycastle.crypto.params.ECPublicKeyParameters;
11+
import org.bouncycastle.crypto.params.ParametersWithRandom;
1112
import org.bouncycastle.crypto.params.ParametersWithUKM;
1213
import org.bouncycastle.math.ec.ECAlgorithms;
1314
import org.bouncycastle.math.ec.ECPoint;
@@ -32,7 +33,13 @@ public void init(CipherParameters key)
3233
{
3334
ParametersWithUKM p = (ParametersWithUKM)key;
3435

35-
this.key = (ECPrivateKeyParameters)p.getParameters();
36+
CipherParameters kParam = p.getParameters();
37+
if (kParam instanceof ParametersWithRandom)
38+
{
39+
kParam = ((ParametersWithRandom)kParam).getParameters();
40+
}
41+
42+
this.key = (ECPrivateKeyParameters)kParam;
3643
this.ukm = new BigInteger(1, Arrays.reverse(p.getUKM()));
3744

3845
CryptoServicesRegistrar.checkConstraints(Utils.getDefaultProperties("ECVKO", this.key));

‎core/src/main/java/org/bouncycastle/crypto/engines/CryptoProWrapEngine.java‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,17 +23,22 @@ public void init(boolean forWrapping, CipherParameters param)
2323
ParametersWithUKM pU = (ParametersWithUKM)param;
2424
byte[] sBox = null;
2525

26+
CipherParameters inner = pU.getParameters();
27+
if (inner instanceof ParametersWithRandom)
28+
{
29+
inner = ((ParametersWithRandom)inner).getParameters();
30+
}
2631

2732
KeyParameter kParam;
2833

29-
if (pU.getParameters() instanceof ParametersWithSBox)
34+
if (inner instanceof ParametersWithSBox)
3035
{
31-
kParam = (KeyParameter)((ParametersWithSBox)pU.getParameters()).getParameters();
32-
sBox = ((ParametersWithSBox)pU.getParameters()).getSBox();
36+
kParam = (KeyParameter)((ParametersWithSBox)inner).getParameters();
37+
sBox = ((ParametersWithSBox)inner).getSBox();
3338
}
3439
else
3540
{
36-
kParam = (KeyParameter)pU.getParameters();
41+
kParam = (KeyParameter)inner;
3742
}
3843

3944
kParam = new KeyParameter(cryptoProDiversify(kParam.getKey(), pU.getUKM(), sBox));

‎core/src/main/java/org/bouncycastle/crypto/engines/GOST28147WrapEngine.java‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,15 @@ public void init(boolean forWrapping, CipherParameters param)
2525

2626
ParametersWithUKM pU = (ParametersWithUKM)param;
2727

28-
cipher.init(forWrapping, pU.getParameters());
28+
CipherParameters kParam = pU.getParameters();
29+
if (kParam instanceof ParametersWithRandom)
30+
{
31+
kParam = ((ParametersWithRandom)kParam).getParameters();
32+
}
33+
34+
cipher.init(forWrapping, kParam);
2935

30-
mac.init(new ParametersWithIV(pU.getParameters(), pU.getUKM()));
36+
mac.init(new ParametersWithIV(kParam, pU.getUKM()));
3137
}
3238

3339
public String getAlgorithmName()

‎core/src/main/java/org/bouncycastle/crypto/params/ParametersWithUKM.java‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,13 @@
22

33
import org.bouncycastle.crypto.CipherParameters;
44

5+
/**
6+
* Wrapper class for parameters which include User Keying Material (UKM).
7+
* <p>
8+
* Combined with a {@link ParametersWithRandom}, this goes on the outside:
9+
* {@code ParametersWithUKM(ParametersWithRandom(key))}. The UKM is consumed by the wrap engine or key
10+
* agreement, and anything inside it is passed on.
11+
*/
512
public class ParametersWithUKM
613
implements CipherParameters
714
{

‎core/src/main/java/org/bouncycastle/crypto/params/package-info.java‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,13 @@
1717
* <em>outside</em> everything consumed further down the stack. Outermost first, the order used
1818
* throughout the lightweight API and by the JCE provider when it builds these chains is:
1919
* <ul>
20-
* <li>{@code ParametersWithContext} or {@code ParametersWithID} - a signature context string
21-
* (ML-DSA, SLH-DSA and similar) or a signer identity (SM2, SM9), consumed by the signer.</li>
20+
* <li>{@code ParametersWithContext}, {@code ParametersWithID} or {@code ParametersWithUKM} - a
21+
* signature context string (ML-DSA, SLH-DSA and similar), a signer identity (SM2, SM9), or the
22+
* user keying material of the GOST 28147 wrap engines and the VKO key agreement, consumed by the
23+
* signer, wrap engine or agreement.</li>
2224
* <li>{@code ParametersWithRandom} - consumed by the outermost component that needs randomness:
2325
* a signer, an asymmetric encoding, a wrap engine, or a padded buffered cipher. Block cipher
2426
* modes and stream ciphers do not unwrap it, so it must not be nested inside an IV.</li>
25-
* <li>{@code ParametersWithUKM} - the user keying material of the GOST 28147 wrap engines.</li>
2627
* <li>{@code ParametersWithIV} - the IV or nonce, consumed by the cipher mode, stream cipher or
2728
* MAC.</li>
2829
* <li>{@code ParametersWithSBox} - the GOST 28147 S-box, consumed by the engine and so placed
@@ -31,7 +32,9 @@
3132
* {@link org.bouncycastle.crypto.params.AsymmetricKeyParameter}.</li>
3233
* </ul>
3334
* So, for example, a GOST 28147 CBC cipher takes {@code IV(SBox(key))}, a padded CBC cipher takes
34-
* {@code Random(IV(key))}, and an ML-DSA signer takes {@code Context(Random(privateKey))}.
35+
* {@code Random(IV(key))}, an ML-DSA signer takes {@code Context(Random(privateKey))}, and a
36+
* GOST 28147 wrap engine takes {@code UKM(Random(SBox(key)))}. The GOST 28147 wrap engines also
37+
* still accept the earlier {@code Random(UKM(SBox(key)))}.
3538
* <p>
3639
* {@code ParametersWithSalt} is used only by
3740
* {@link org.bouncycastle.crypto.signers.ISO9796d2PSSSigner}, which accepts it as an alternative
@@ -42,5 +45,11 @@
4245
* {@link org.bouncycastle.crypto.params.AEADParameters} is a self-contained alternative to
4346
* {@code ParametersWithIV} for AEAD modes and combines key, nonce, tag length and associated data
4447
* without nesting.
48+
* <p>
49+
* Rejecting other nestings is intended. New code should accept the order above and nothing else.
50+
* Accepting an alternative order is a compatibility measure, and is justified only where existing
51+
* callers are known to build it, as with the earlier {@code Random(UKM(..))} of the GOST 28147 wrap
52+
* engines. An alternative added speculatively becomes a second form that every caller, wrapper and
53+
* port then has to keep supporting.
4554
*/
4655
package org.bouncycastle.crypto.params;

‎core/src/test/java/org/bouncycastle/crypto/test/RegressionTest.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,7 @@ public class RegressionTest
158158
new SM2KeyExchangeTest(),
159159
new SM2SignerTest(),
160160
new ShortWrapCipherTextTest(),
161+
new UKMParametersNestingTest(),
161162
new SM4Test(),
162163
new SM9KEMTest(),
163164
new SM9EngineTest(),
Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
package org.bouncycastle.crypto.test;
2+
3+
import java.security.SecureRandom;
4+
5+
import org.bouncycastle.asn1.cryptopro.ECGOST3410NamedCurves;
6+
import org.bouncycastle.crypto.AsymmetricCipherKeyPair;
7+
import org.bouncycastle.crypto.CipherParameters;
8+
import org.bouncycastle.crypto.Wrapper;
9+
import org.bouncycastle.crypto.agreement.ECVKOAgreement;
10+
import org.bouncycastle.crypto.digests.GOST3411_2012_256Digest;
11+
import org.bouncycastle.crypto.engines.CryptoProWrapEngine;
12+
import org.bouncycastle.crypto.engines.GOST28147Engine;
13+
import org.bouncycastle.crypto.engines.GOST28147WrapEngine;
14+
import org.bouncycastle.crypto.generators.ECKeyPairGenerator;
15+
import org.bouncycastle.crypto.params.ECDomainParameters;
16+
import org.bouncycastle.crypto.params.ECKeyGenerationParameters;
17+
import org.bouncycastle.crypto.params.KeyParameter;
18+
import org.bouncycastle.crypto.params.ParametersWithRandom;
19+
import org.bouncycastle.crypto.params.ParametersWithSBox;
20+
import org.bouncycastle.crypto.params.ParametersWithUKM;
21+
import org.bouncycastle.util.Arrays;
22+
import org.bouncycastle.util.encoders.Hex;
23+
import org.bouncycastle.util.test.SimpleTest;
24+
25+
/**
26+
* {@link ParametersWithUKM} goes outside {@link ParametersWithRandom} (see the
27+
* {@code org.bouncycastle.crypto.params} package documentation). Every UKM consumer must accept that
28+
* nesting with the same result as no random at all, and the GOST 28147 wrap engines must also still
29+
* accept the earlier {@code Random(UKM(..))}.
30+
*/
31+
public class UKMParametersNestingTest
32+
extends SimpleTest
33+
{
34+
private static final SecureRandom RANDOM = new SecureRandom();
35+
36+
private static final byte[] KEK = Hex.decode("8b2f3a41c6d5e7091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f7081");
37+
private static final byte[] CEK = Hex.decode("0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20");
38+
private static final byte[] UKM = Hex.decode("1d80603c8544c727");
39+
40+
public String getName()
41+
{
42+
return "UKMParametersNesting";
43+
}
44+
45+
public void performTest()
46+
throws Exception
47+
{
48+
wrapTest("GOST28147Wrap", new GOST28147WrapEngine(), null);
49+
wrapTest("GOST28147Wrap/SBox", new GOST28147WrapEngine(), GOST28147Engine.getSBox("E-A"));
50+
wrapTest("CryptoProWrap/SBox", new CryptoProWrapEngine(), GOST28147Engine.getSBox("E-A"));
51+
52+
vkoTest();
53+
}
54+
55+
private void wrapTest(String label, Wrapper wrapper, byte[] sBox)
56+
throws Exception
57+
{
58+
byte[] expected = null;
59+
60+
for (int i = 0; i < 3; ++i)
61+
{
62+
wrapper.init(true, createWrapParameters(i, sBox));
63+
byte[] wrapped = wrapper.wrap(CEK, 0, CEK.length);
64+
if (expected == null)
65+
{
66+
expected = wrapped;
67+
}
68+
isTrue(label + " wrap differs for nesting " + i, areEqual(expected, wrapped));
69+
70+
wrapper.init(false, createWrapParameters(i, sBox));
71+
byte[] unwrapped = wrapper.unwrap(expected, 0, expected.length);
72+
isTrue(label + " unwrap differs for nesting " + i, areEqual(CEK, unwrapped));
73+
}
74+
}
75+
76+
/*
77+
* A fresh key each time: CryptoProWrapEngine diversifies the KeyParameter's bytes in place.
78+
*/
79+
private static CipherParameters createWrapParameters(int nesting, byte[] sBox)
80+
{
81+
CipherParameters key = new KeyParameter(Arrays.clone(KEK));
82+
if (sBox != null)
83+
{
84+
key = new ParametersWithSBox(key, sBox);
85+
}
86+
87+
switch (nesting)
88+
{
89+
case 0:
90+
return new ParametersWithUKM(key, UKM);
91+
case 1:
92+
return new ParametersWithUKM(new ParametersWithRandom(key, RANDOM), UKM);
93+
case 2:
94+
return new ParametersWithRandom(new ParametersWithUKM(key, UKM), RANDOM);
95+
default:
96+
throw new IllegalArgumentException("nesting");
97+
}
98+
}
99+
100+
private void vkoTest()
101+
{
102+
ECDomainParameters domain = new ECDomainParameters(
103+
ECGOST3410NamedCurves.getByNameX9("Tc26-Gost-3410-12-256-paramSetA"));
104+
105+
ECKeyPairGenerator kpGen = new ECKeyPairGenerator();
106+
kpGen.init(new ECKeyGenerationParameters(domain, RANDOM));
107+
108+
AsymmetricCipherKeyPair kpA = kpGen.generateKeyPair();
109+
AsymmetricCipherKeyPair kpB = kpGen.generateKeyPair();
110+
111+
ECVKOAgreement agreeA = new ECVKOAgreement(new GOST3411_2012_256Digest());
112+
agreeA.init(new ParametersWithUKM(kpA.getPrivate(), UKM));
113+
byte[] expected = agreeA.calculateAgreement(kpB.getPublic());
114+
115+
agreeA.init(new ParametersWithUKM(new ParametersWithRandom(kpA.getPrivate(), RANDOM), UKM));
116+
isTrue("VKO agreement differs for UKM(Random(key))", areEqual(expected, agreeA.calculateAgreement(kpB.getPublic())));
117+
118+
ECVKOAgreement agreeB = new ECVKOAgreement(new GOST3411_2012_256Digest());
119+
agreeB.init(new ParametersWithUKM(new ParametersWithRandom(kpB.getPrivate(), RANDOM), UKM));
120+
isTrue("VKO peer agreement differs for UKM(Random(key))", areEqual(expected, agreeB.calculateAgreement(kpA.getPublic())));
121+
}
122+
123+
public static void main(String[] args)
124+
{
125+
runTest(new UKMParametersNestingTest());
126+
}
127+
}

‎docs/releasenotes.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,8 @@ Date: 2026, TBD
8484

8585
- The sources and javadoc jars of the Ant-built distributions (jdk14, jdk15to18 and jdk13) no longer carry test material. Each module's javadoc target copies the package documentation it needs - org/bouncycastle/<area>/**/*.html - back into the module source directory that has already been compiled from, and zip-src zips that directory afterwards, so every test package's package.html arrived in the sources jar by that route; javadoc-util additionally copied org/bouncycastle/asn1/isismtt/**/*.java, which put test classes into the bcutil javadoc as generated pages, and javadoc-pg deliberately copied the gpg and bcpg test sources in order to document them. Separately the source copies excluded test material only one directory deep and only for *.java, because Ant reads ** as an any-depth wildcard just where it is a whole path segment, so anything nested further or with another extension - the PEM certificate fixtures under org/bouncycastle/est/test/san corrected in 1.86, and an ICAO master list under org/bouncycastle/asn1/icao/test - went through. The source and javadoc copies of every module now exclude test directories at any depth, and javadoc-pg no longer documents the test packages. org.bouncycastle.util.test is unaffected and still ships in the bcprov binary, sources and javadoc jars, as it does from the Gradle build: it is the SimpleTest framework the light-weight API's own test classes are written against, not test material of the distribution. No binary changes - the classes and resources of every Ant-built jar are identical to those of the 1.86 release - and the Gradle-built jdk18on artifacts never carried any of this.
8686

87+
- ParametersWithUKM now nests outside ParametersWithRandom in the light-weight API, alongside ParametersWithContext and ParametersWithID, as the org.bouncycastle.crypto.params package documentation now describes. GOST28147WrapEngine, CryptoProWrapEngine and ECVKOAgreement accept ParametersWithUKM(ParametersWithRandom(key)); the two wrap engines also still accept the earlier ParametersWithRandom(ParametersWithUKM(key)), and the provider's GOST 28147 key wrap ciphers now build the new form. A ParametersWithUKM with no random inside is unaffected.
88+
8789
<a id="r1rv86"></a>
8890

8991
### 2.2.1 Version

‎prov/src/main/java/org/bouncycastle/jcajce/provider/symmetric/util/BaseWrapCipher.java‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -221,16 +221,16 @@ else if (k.getParam() != null)
221221
param = new ParametersWithIV(param, iv);
222222
}
223223

224+
GOST28147WrapParameterSpec gostSpec = null;
224225
if (params instanceof GOST28147WrapParameterSpec)
225226
{
226-
GOST28147WrapParameterSpec spec = (GOST28147WrapParameterSpec) params;
227+
gostSpec = (GOST28147WrapParameterSpec) params;
227228

228-
byte[] sBox = spec.getSBox();
229+
byte[] sBox = gostSpec.getSBox();
229230
if (sBox != null)
230231
{
231232
param = new ParametersWithSBox(param, sBox);
232233
}
233-
param = new ParametersWithUKM(param, spec.getUKM());
234234
}
235235

236236
if (param instanceof KeyParameter && ivSize != 0)
@@ -248,6 +248,12 @@ else if (k.getParam() != null)
248248
param = new ParametersWithRandom(param, random);
249249
}
250250

251+
// the UKM goes outside the random (see org.bouncycastle.crypto.params)
252+
if (gostSpec != null)
253+
{
254+
param = new ParametersWithUKM(param, gostSpec.getUKM());
255+
}
256+
251257
try
252258
{
253259
switch (opmode)

0 commit comments

Comments
 (0)