Bouncy Castle Providers
Bouncy Castle is a Java library that complements the default Java Cryptographic Extension (JCE),
and it provides more cipher suites and algorithms than the default JCE provided by Sun.
In addition to that,
Bouncy Castle has lots of utilities for reading arcane formats like PEM and ASN.1 that no sane person would want to rewrite themselves.
In Pulsar, security and crypto have dependencies on BouncyCastle Jars. For the detailed installing and configuring Bouncy Castle FIPS, see BC FIPS Documentation, especially the User Guides and Security Policy PDFs.
Bouncy Castle provides both FIPS and non-FIPS versions. But in a JVM, you can not include both of the 2 versions, and you need to exclude the current version before including the other.
In Pulsar, the security and crypto methods also depend on
Bouncy Castle, especially in mTLS authentication and Transport Encryption. This document contains the configuration between BouncyCastle FIPS(BC-FIPS) and non-FIPS(BC-non-FIPS) version while using Pulsar.
How BouncyCastle modules packaged in Pulsar
bouncy-castle module, We provide 2 sub modules:
bouncy-castle-bc(for non-FIPS versions) and
bouncy-castle-bcfips(for FIPS version), to package BC jars together to make the include and exclude of
Bouncy Castle easier.
To achieve this goal, we will need to package several
bouncy-castle jars together into
Each of the original bouncy-castle jars is related to security, so BouncyCastle dutifully supplies signed of each jar.
But when we do the re-package, Maven shade explodes the BouncyCastle jar file which puts the signatures into META-INF,
these signatures aren't valid for this new, uber-jar (signatures are only for the original BC jar).
Usually, You will meet error like
java.lang.SecurityException: Invalid signature file digest for Manifest main attributes.
You can exclude these signatures in the mvn pom file to avoid the above error.
But it can also lead to new, cryptic errors, e.g.
java.security.NoSuchAlgorithmException: PBEWithSHA256And256BitAES-CBC-BC SecretKeyFactory not available
By explicitly specifying where to find the algorithm like this:
It will get the real error:
java.security.NoSuchProviderException: JCE cannot authenticate the provider BC
So, we used a executable packer plugin that uses a jar-in-jar approach to preserve the BouncyCastle signature in a single, executable jar.
Include dependencies of BC-non-FIPS
bouncy-castle-bc, which is defined by
bouncy-castle/bc/pom.xml contains the needed non-FIPS jars for Pulsar, and packaged as a jar-in-jar(need to provide
By using this
bouncy-castle-bc module, you can easily include and exclude BouncyCastle non-FIPS jars.
Modules that include BC-non-FIPS module (
For Pulsar client, user need the bouncy-castle module, so
pulsar-client-original will include the
bouncy-castle-bc module, and have
<classifier>pkg</classifier> set to reference the
It is included as the following example:
bouncy-castle-bc already included in
pulsar-client-original has been included in a lot of other modules like
But for the above shaded jar and signatures reason, we should not package Pulsar's
bouncy-castle module into
pulsar-client-all other shaded modules directly, such as
So in the shaded modules, we will exclude the
bouncy-castle related jars are not shaded in these fat jars.
Module BC-FIPS (
bouncy-castle-bcfips, which is defined by
bouncy-castle/bcfips/pom.xml, contains the needed FIPS jars for Pulsar.
bouncy-castle-bcfips is also packaged as a
jar-in-jar package for easy include/exclude.
Exclude BC-non-FIPS and include BC-FIPS
If you want to switch from BC-non-FIPS to BC-FIPS version, Here is an example for
For more example, you can reference module