Skip to content

Commit 0b4a878

Browse files
committed
Added ECDHwithSHA256HKDF, ECDHwithSHA384HKDF and ECDHwithSHA512HKDF key agreements, the ECDH counterparts of XDHwithSHA*HKDF; the EC KeyAgreement now passes a UserKeyingMaterialSpec salt to HKDF.
1 parent 7a73dbc commit 0b4a878

5 files changed

Lines changed: 141 additions & 3 deletions

File tree

‎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 BCJSSE provider adds an org.bouncycastle.jsse.BCSSLContext interface exposing extended functionality of its SSLContext, obtained with org.bouncycastle.jsse.util.ContextUtil.getBCSSLContext() by way of the new BCSSLSessionContext interface the context's session contexts implement. Its getDefaultParameters(boolean) and getSupportedParameters(boolean) return the context's default and supported parameters as a BCSSLParameters for either client or server mode, including the BC-specific properties, where SSLContext.getDefaultSSLParameters() and getSupportedSSLParameters() report client mode only and cannot carry those properties. A BCSSLContext describes the initialization of the SSLContext it was obtained from, and is not updated if the SSLContext is re-initialized.
8686

87+
- The provider adds ECDHwithSHA256HKDF, ECDHwithSHA384HKDF and ECDHwithSHA512HKDF KeyAgreement algorithms: ECDH followed by HKDF (RFC 5869), the counterparts for elliptic curve keys of the XDHwithSHA\*HKDF agreements used for the RFC 8418 dhSinglePass-stdDH-hkdf schemes. As with those, a UserKeyingMaterialSpec supplies the HKDF info and, optionally, its salt. They are registered by name only; the RFC 8418 scheme object identifiers remain registered to the XDH agreements.
88+
8789
### 2.1.4 Additional Notes
8890

8991
- 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.

‎prov/src/main/java/org/bouncycastle/jcajce/provider/asymmetric/EC.java‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,11 @@ public void configure(ConfigurableProvider provider)
157157
provider.addAlgorithm("KeyAgreement.ECDHWITHSHA512KDF", PREFIX + "KeyAgreementSpi$DHwithSHA512KDFAndSharedInfo", generalEcAttributes);
158158
provider.addAlgorithm("KeyAgreement.ECCDHWITHSHA512KDF", PREFIX + "KeyAgreementSpi$CDHwithSHA512KDFAndSharedInfo", generalEcAttributes);
159159

160+
// HKDF (RFC 5869) - by name only: the RFC 8418 dhSinglePass-stdDH-hkdf OIDs are registered to XDH in EdEC
161+
provider.addAlgorithm("KeyAgreement.ECDHWITHSHA256HKDF", PREFIX + "KeyAgreementSpi$DHwithSHA256HKDF", generalEcAttributes);
162+
provider.addAlgorithm("KeyAgreement.ECDHWITHSHA384HKDF", PREFIX + "KeyAgreementSpi$DHwithSHA384HKDF", generalEcAttributes);
163+
provider.addAlgorithm("KeyAgreement.ECDHWITHSHA512HKDF", PREFIX + "KeyAgreementSpi$DHwithSHA512HKDF", generalEcAttributes);
164+
160165
provider.addAlgorithm("KeyAgreement", X9ObjectIdentifiers.dhSinglePass_stdDH_sha1kdf_scheme, PREFIX + "KeyAgreementSpi$DHwithSHA1KDFAndSharedInfo", generalEcAttributes);
161166
provider.addAlgorithm("KeyAgreement", X9ObjectIdentifiers.dhSinglePass_cofactorDH_sha1kdf_scheme, PREFIX + "KeyAgreementSpi$CDHwithSHA1KDFAndSharedInfo", generalEcAttributes);
162167

‎prov/src/main/java/org/bouncycastle/jcajce/provider/asymmetric/ec/KeyAgreementSpi.java‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
import org.bouncycastle.crypto.agreement.ECMQVRawAgreement;
1818
import org.bouncycastle.crypto.agreement.kdf.ConcatenationKDFGenerator;
1919
import org.bouncycastle.crypto.digests.RIPEMD160Digest;
20+
import org.bouncycastle.crypto.generators.HKDFBytesGenerator;
2021
import org.bouncycastle.crypto.generators.KDF2BytesGenerator;
2122
import org.bouncycastle.crypto.params.ECDHUPrivateParameters;
2223
import org.bouncycastle.crypto.params.ECDHUPublicParameters;
@@ -175,6 +176,12 @@ protected void doInitFromKey(Key key, AlgorithmParameterSpec parameterSpec, Secu
175176
if (parameterSpec instanceof UserKeyingMaterialSpec)
176177
{
177178
checkKdfSalt((UserKeyingMaterialSpec)parameterSpec);
179+
// only an HKDF based agreement gets this far with a salt - checkKdfSalt refuses the rest
180+
ukmParametersSalt = ((UserKeyingMaterialSpec)parameterSpec).getSalt();
181+
}
182+
else
183+
{
184+
ukmParametersSalt = null;
178185
}
179186

180187
if (agreement instanceof ECMQVRawAgreement)
@@ -516,6 +523,38 @@ public CDHwithSHA512CKDF()
516523
}
517524
}
518525

526+
// ECDH with HKDF (RFC 5869): the ECDH counterpart of edec's XDHwithSHA256HKDF, which serves the
527+
// RFC 8418 dhSinglePass-stdDH-hkdf-sha256-scheme for X25519/X448. The UserKeyingMaterialSpec
528+
// carries the HKDF info and, optionally, its salt.
529+
public static class DHwithSHA256HKDF
530+
extends KeyAgreementSpi
531+
{
532+
public DHwithSHA256HKDF()
533+
{
534+
super("ECDHwithSHA256HKDF", new ECDHRawAgreement(), new HKDFBytesGenerator(DigestFactory.createSHA256()));
535+
}
536+
}
537+
538+
// ECDH with HKDF (RFC 5869): the ECDH counterpart of edec's XDHwithSHA384HKDF.
539+
public static class DHwithSHA384HKDF
540+
extends KeyAgreementSpi
541+
{
542+
public DHwithSHA384HKDF()
543+
{
544+
super("ECDHwithSHA384HKDF", new ECDHRawAgreement(), new HKDFBytesGenerator(DigestFactory.createSHA384()));
545+
}
546+
}
547+
548+
// ECDH with HKDF (RFC 5869): the ECDH counterpart of edec's XDHwithSHA512HKDF.
549+
public static class DHwithSHA512HKDF
550+
extends KeyAgreementSpi
551+
{
552+
public DHwithSHA512HKDF()
553+
{
554+
super("ECDHwithSHA512HKDF", new ECDHRawAgreement(), new HKDFBytesGenerator(DigestFactory.createSHA512()));
555+
}
556+
}
557+
519558
public static class MQVwithSHA1CKDF
520559
extends KeyAgreementSpi
521560
{

‎prov/src/test/java/org/bouncycastle/jce/provider/test/DHTest.java‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,13 @@
4040

4141
import org.bouncycastle.asn1.ASN1ObjectIdentifier;
4242
import org.bouncycastle.asn1.pkcs.PKCSObjectIdentifiers;
43+
import org.bouncycastle.crypto.Digest;
4344
import org.bouncycastle.crypto.agreement.DHStandardGroups;
45+
import org.bouncycastle.crypto.digests.SHA256Digest;
46+
import org.bouncycastle.crypto.digests.SHA384Digest;
47+
import org.bouncycastle.crypto.digests.SHA512Digest;
48+
import org.bouncycastle.crypto.generators.HKDFBytesGenerator;
49+
import org.bouncycastle.crypto.params.HKDFParameters;
4450
import org.bouncycastle.internal.asn1.bsi.BSIObjectIdentifiers;
4551
import org.bouncycastle.jcajce.provider.config.ConfigurableProvider;
4652
import org.bouncycastle.jcajce.spec.DHDomainParameterSpec;
@@ -1634,6 +1640,91 @@ public void performTest()
16341640
testMinSpecValue();
16351641
testGenerateUsingStandardGroup();
16361642
testHybridValueParameterSpec();
1643+
1644+
testECDHwithHKDF("ECDHwithSHA256HKDF", new SHA256Digest(), "secp256r1");
1645+
testECDHwithHKDF("ECDHwithSHA384HKDF", new SHA384Digest(), "secp384r1");
1646+
testECDHwithHKDF("ECDHwithSHA512HKDF", new SHA512Digest(), "secp521r1");
1647+
}
1648+
1649+
/**
1650+
* The ECDH HKDF agreements against an independent derivation: the shared secret from plain ECDH,
1651+
* then RFC 5869 HKDF taking the UserKeyingMaterialSpec's keying material as info and its salt, when
1652+
* present, as salt. Run with no spec, with keying material only, and with keying material and a
1653+
* salt, since a salt the agreement dropped would still agree with the other side.
1654+
*/
1655+
private void testECDHwithHKDF(String algorithm, Digest digest, String curveName)
1656+
throws Exception
1657+
{
1658+
KeyPairGenerator g = KeyPairGenerator.getInstance("EC", "BC");
1659+
1660+
g.initialize(ECNamedCurveTable.getParameterSpec(curveName));
1661+
1662+
KeyPair aKeyPair = g.generateKeyPair();
1663+
KeyPair bKeyPair = g.generateKeyPair();
1664+
1665+
KeyAgreement rawAgree = KeyAgreement.getInstance("ECDH", "BC");
1666+
1667+
rawAgree.init(aKeyPair.getPrivate());
1668+
rawAgree.doPhase(bKeyPair.getPublic(), true);
1669+
1670+
byte[] z = rawAgree.generateSecret();
1671+
byte[] info = Hex.decode("000102030405060708090a0b0c0d0e0f");
1672+
byte[] salt = Hex.decode("beeffeed");
1673+
1674+
byte[] noSpec = checkECDHwithHKDF(algorithm, aKeyPair, bKeyPair, null, hkdf(digest, z, null, null));
1675+
byte[] unsalted = checkECDHwithHKDF(algorithm, aKeyPair, bKeyPair, new UserKeyingMaterialSpec(info),
1676+
hkdf(digest, z, null, info));
1677+
byte[] salted = checkECDHwithHKDF(algorithm, aKeyPair, bKeyPair, new UserKeyingMaterialSpec(info, salt),
1678+
hkdf(digest, z, salt, info));
1679+
1680+
isTrue(algorithm + " ignored the HKDF info", !Arrays.areEqual(noSpec, unsalted));
1681+
isTrue(algorithm + " ignored the HKDF salt", !Arrays.areEqual(unsalted, salted));
1682+
}
1683+
1684+
private byte[] checkECDHwithHKDF(String algorithm, KeyPair aKeyPair, KeyPair bKeyPair,
1685+
UserKeyingMaterialSpec spec, byte[] expected)
1686+
throws Exception
1687+
{
1688+
byte[] aKey = agreeECDHwithHKDF(algorithm, aKeyPair.getPrivate(), bKeyPair.getPublic(), spec);
1689+
byte[] bKey = agreeECDHwithHKDF(algorithm, bKeyPair.getPrivate(), aKeyPair.getPublic(), spec);
1690+
1691+
isTrue(algorithm + " 2-way test failed", Arrays.areEqual(aKey, bKey));
1692+
isTrue(algorithm + " key does not match HKDF over the ECDH shared secret", Arrays.areEqual(expected, aKey));
1693+
1694+
return aKey;
1695+
}
1696+
1697+
private byte[] agreeECDHwithHKDF(String algorithm, PrivateKey privKey, PublicKey pubKey,
1698+
UserKeyingMaterialSpec spec)
1699+
throws Exception
1700+
{
1701+
KeyAgreement agreement = KeyAgreement.getInstance(algorithm, "BC");
1702+
1703+
if (spec == null)
1704+
{
1705+
agreement.init(privKey);
1706+
}
1707+
else
1708+
{
1709+
agreement.init(privKey, spec);
1710+
}
1711+
1712+
agreement.doPhase(pubKey, true);
1713+
1714+
return agreement.generateSecret("AES[256]").getEncoded();
1715+
}
1716+
1717+
private static byte[] hkdf(Digest digest, byte[] ikm, byte[] salt, byte[] info)
1718+
{
1719+
HKDFBytesGenerator kdf = new HKDFBytesGenerator(digest);
1720+
1721+
kdf.init(new HKDFParameters(ikm, salt, info));
1722+
1723+
byte[] key = new byte[32];
1724+
1725+
kdf.generateBytes(key, 0, key.length);
1726+
1727+
return key;
16371728
}
16381729

16391730
/**

‎prov/src/test/java/org/bouncycastle/jce/provider/test/KeyAgreementInitParametersTest.java‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ public void performTest()
8181

8282
checkAcceptsSalt("X25519withSHA256HKDF", xKey);
8383
checkAcceptsSalt("XDHwithSHA256HKDF", xKey);
84+
checkAcceptsSalt("ECDHwithSHA256HKDF", ecKey);
8485

8586
checkNoUkm(ecKey, xKey);
8687
}
@@ -269,9 +270,9 @@ private void checkVKODefaultUKM(KeyPair kp)
269270
private void checkUKMReachesTheKDF(KeyPair ecKey, KeyPair xKey)
270271
throws Exception
271272
{
272-
String[] algorithms = new String[]{ "ECDHwithSHA256KDF", "ECCDHwithSHA256KDF", "X25519withSHA256KDF",
273-
"X25519withSHA256HKDF" };
274-
KeyPair[] keys = new KeyPair[]{ ecKey, ecKey, xKey, xKey };
273+
String[] algorithms = new String[]{ "ECDHwithSHA256KDF", "ECCDHwithSHA256KDF", "ECDHwithSHA256HKDF",
274+
"X25519withSHA256KDF", "X25519withSHA256HKDF" };
275+
KeyPair[] keys = new KeyPair[]{ ecKey, ecKey, ecKey, xKey, xKey };
275276

276277
for (int i = 0; i != algorithms.length; i++)
277278
{

0 commit comments

Comments
 (0)