Bouncy Castle Java

bctls-klog is a specialized Bouncy Castle TLS API designed for RFC 9850 (SSLKEYLOGFILE) key logging. It allows you to report TLS connection secrets so that packet captures (e.g., from Wireshark) can be decrypted for analysis.

CRITICAL WARNING: DO NOT USE IN PRODUCTION. RFC 9850 specifies that this mechanism MUST NOT be used in production systems. Anyone with access to these secrets can decrypt the associated traffic. Treat the bctls-klog JAR as a security risk that can expose every TLS connection made by the JVM.

The project is organized into several functional modules:

• core: Provides all lightweight API functionality.
• prov: Provides JCA/JCE provider functionality.
• util: Contains shared code, primarily ASN.1 classes for the PKIX module.
• pkix: Handles X.509 certificate generation and APIs for standards relying on ASN.1 (CMS, TSP, PKCS#12, OCSP, CRMF, and CMP).
• mail: Provides an S/MIME API built on top of CMS.
• pg: Supports OpenPGP.
• tls: Provides a general TLS API and JSSE Provider.

Warning for JCE users: If you are using a JDK version that already includes a JCE install (JDK 1.4+), do not include the jce/src/main/java directory as a source file, as it will clash with the JCE API provided by your JDK.

The project uses Allman braces and 4-space indentation (no tabs). Brace placement is machine-enforced via the Gradle checkstyle plugin.

Brace Rules:

• Left Curly ({): Must be on its own new line (option="nl"). This applies to classes, methods, control structures (if, for, while, try, switch), and lambda bodies.
• Right Curly (}): Must be alone on its own line (option="alone").

Validation: Run the following command to check for violations locally before pushing:

./gradlew checkstyleMain

Violations will result in a build failure in CI.

Canonical example and demo code is located in the misc/ module, not within the primary Gradle modules (like core, prov, or pg).

Key locations:

• misc/src/main/java/org/bouncycastle/{asn1,crypto,jcajce,openpgp,pqc/crypto}/examples/

Important Notes:

• The misc module is a non-publishing module; its code is compiled and tested via ./gradlew :misc:build to ensure it remains compatible with the library, but it is not included in the published bc* JARs or Maven distributions.
• If you are looking for examples of non-standard JCE aliases (e.g., Cipher.ECIESwithSHA256andAES-ECB), check the misc/ directory. Bouncy Castle typically does not register these non-standard aliases, so the examples demonstrate how to construct them locally using the lightweight API.

To perform a full build, signing, and testing cycle for the JDK 1.4 distribution, follow these steps. Note that JRE 1.4 requires providers to be signed, or they will fail with a "provider BC may not be signed by a trusted party" error.

Important: Always sign the jars after build-test because the test process may re-jar components and wipe existing signatures.

Note on cleaning: The staging tree build/jdk1.4 and artifact trees are never cleaned by the build script. If you change excludes, delete overlays, or rename files, you must manually run rm -rf build before rebuilding to prevent stale sources from compiling.

To use the lightweight crypto API and the JCA/JCE providers, add the bcprov-jdk18on artifact to your pom.xml. This is the most common starting point and is required by all other Bouncy Castle modules.

Note: The -jdk18on suffix indicates support for JDK 1.8 and newer. Do not use the older -jdk15on artifacts as they are end-of-life.

<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk18on</artifactId>
    <version>1.84</version>
</dependency>

The JDK 1.3 build layers overlays in this order: base src/main/java $\rightarrow$ src/main/jdk1.4 (overwrite) $\rightarrow$ src/main/jdk1.3 (overwrite).

Crucial Rule: When creating a new JDK 1.3 overlay for a class, do not base it on src/main/java. Instead, base it on the existing JDK 1.4 overlay if one exists. Basing it on the base source re-introduces Java 5/1.4 APIs (like ConcurrentHashMap or Logger) that the 1.4 overlay had already removed, which will break the 1.3 build.

To prevent leaking internal engine implementations into the published API, keep <Alg>Engine classes package-private. Instead of testing the engine directly, drive Known Answer Tests (KATs) through the public <Alg>KeyPairGenerator or <Alg>Signer using deterministic randomness.

Recommended Randomness Tools:

• org.bouncycastle.util.test.FixedSecureRandom(bytes): Use for single-shot tests requiring a specific seed.
• org.bouncycastle.pqc.crypto.test.NISTSecureRandom(seed, personalization): Use for NIST CTR-DRBG upstream KAT generators. A single instance can be reused across key generation and signing calls to reproduce reference implementation vectors byte-for-byte.

Pattern: If you cannot demote an engine to package-private because tests depend on it, rewrite the tests to use the public API with NISTSecureRandom first, then demote the engine.

Bouncy Castle modules (like prov, pkix, pg, tls) use Multi-Release JARs to provide version-specific implementations.

Source Structure

• src/main/java: Base sources (compiled with --release 8).
• src/main/jdk1.9, src/main/jdk1.11, src/main/jdk1.15, src/main/jdk17, src/main/jdk25: Version-specific overlays.
• src/main/j2me, src/main/jdk1.1 ... src/main/ext-jdk1.9: Legacy Ant distributions (not managed by Gradle).

Critical Warning: Testing Overlays

Standard tests in src/test/java do not execute the code in MR-jar overlays. If you modify a class that has a version-specific twin (e.g., in src/main/jdk1.11), you must manually add a test in the corresponding test directory (e.g., src/test/jdk1.11) and register it in the matching AllTests11 suite to ensure the overlay behavior is correct.