Bouncy Castle changes
Overview
In the scope of the 8.0.0 release, we've introduced several major breaking changes in the way we handle bouncy-castle dependencies. Now we no longer use org.bouncycastle
dependencies directly in our kernel
and sign
modules. Instead, all the necessary bouncy-castle related classes are grouped into two new modules: bouncy-castle-adapter
and bouncy-castle-fips-adapter
.
One of these modules is required to be in a classpath for the correct usage of cryptographic and signatures-related logic of our kernel
and sign
modules, but by default they are not added as a dependency in order to provide the ability to choose one of them from the customer's side.
Basically, this means that in order to use any other iText product (except several products which will be mentioned later) together with cryptographic or signatures-related logic either bouncy-castle-adapter
or bouncy-castle-fips-adapter
module shall be added as a dependency. Otherwise, a special log message will be sent.
Android version limitations
Android artifacts directly depend on vanilla BouncyCastle and don't support switching to BouncyCastle FIPS.
The whole idea behind adding the possibility to depend on BouncyCastle-FIPS in iText Core is that this build of Bouncy-Castle is FIPS-certified, i.e. adheres to FIPS standard as confirmed by a certification process.
Status of known vulnerability CVE-2022-45146 for FIPS Java API before 1.0.2.4
The whole idea behind adding the possibility to depend on BouncyCastle-FIPS in iText Core is that this build of Bouncy-Castle is FIPS-certified, i.e. adheres to FIPS standard as confirmed by certification process.
So, there are two reasons why iText Core keeps 1.0.2.3 dependency as the default one:
1) The only available version with the fix, 1.0.2.4, is not FIPS-certified (see https://www.bouncycastle.org/latest_releases.html#1.0.2.4-NONCERT )
2) BC-FIPS 1.0.2.3 is specifically certified against JRE 1.7, JRE 1.8, and JRE 1.11 (see https://www.bouncycastle.org/fips_java_roadmap.html ).
So, the expectation is that a user would want to opt-in to BC-FIPS dependency only with BC-FIPS 1.0.2.3 version and only for java8 or java11, while CVE-2022-45146 is only relevant to java13+.
It's also possible to switch to 1.0.2.4 by explicitly specifying this version in maven pom file.
The inside of bouncy-castle adapters
Java
com.itextpdf:bouncy-castle-adapter
maven module encapsulates bouncy-castle related classes for these two maven dependencies:
org.bouncycastle:bcpkix-jdk15on
org.bouncycastle:bcprov-jdk15on
com.itextpdf:bouncy-castle-fips-adapter
maven module encapsulates bouncy-castle related classes for these two maven dependencies:
org.bouncycastle:bcpkix-fips
org.bouncycastle:bc-fips
.NET
itext7.bouncy-castle-adapter
nuget package encapsulates bouncy-castle related classes for this nuget dependency:
Portable.BouncyCastle
itext7.bouncy-castle-fips-adapter
nuget package encapsulates bouncy-castle related classes for these two assemblies (dlls taken from https://www.bouncycastle.org/fips-csharp/):
bc-fips-1.0.1.1
bcpkix-fips-1.0.1
Since those two dll files are not signed, we can't use them with .NET Framework and therefore the only supported target framework for bouncy-castle-fips-adapter
project is netstandard2.0
.
Ways to specify adapter
The idea of using adapters relies on the fact that only one adapter will be used in order to generate bouncy-castle related wrappers. The choose of adapter happens in separated module bouncy-castle-connector
. If for some reason both bouncy-castle-adapter
and bouncy-castle-fips-adapter
dependency added, there are still ways to specify which one need to be used.
First of all, connector modules searches for the special system or environment variable called ITEXT_BOUNCY_CASTLE_FACTORY_NAME
. There are three possible values here:
- "bouncy-castle" - forces connector to first try to use
bouncy-castle-adapter
module - "bouncy-castle-fips" - forces connector to first try to use
bouncy-castle-fips-adapter
module - anything else - ignored
However, related dependency still shall be added in order to successfully use related module.
Bouncy-castle-fips-adapter module operating modes
Bouncy-castle-fips-adapter
module can be operated in two modes:
- General mode
- Approved mode
General mode is enabled by default. There are several ways to enable approved mode.
Java:
- Call
CryptoServicesRegistrar#setApprovedOnlyMode(true)
method - Pass "
org.bouncycastle.fips.approved_only=true
" VM parameter to your build configuration
.NET:
- Call
CryptoServicesRegistrar#SetApprovedOnlyMode(true)
method - Pass environment or system variable
ITEXT_DOTNET_BOUNCY_CASTLE_FIPS_MODE
with "approved_mode
" value
Ones approved mode is enabled, you can't go back to the general mode. Also this operating mode is thread local, i.e. it needs to be explicitly set per each thread.
Several algorithms are not available in the approved mode (such as MD5
for example). You will receive a corresponding log message if an algorithm is not FIPS compliant and therefore cannot be used in approved mode.
API usage
In the scope of this changes also several public API methods definitions changed. Right now we use special interfaces instead of org.bouncycastle
classes in our API as a parameter or return values. In case when you need to work with such interfaces to either create them from actual org.bouncycastle
values or retrieve actual value, you should access classes from either bouncy-castle-adapter
or bouncy-castle-fips-adapter
directly and either call the constructor to create an instance and pass it as a parameter or call the corresponding getter method to retrieve the actual value. Let's take a more precise look at one of the examples.
Let's say you need to create IX509Certificate
interface in order to pass it as a parameter to PdfSigner#SignDetached
method. Assuming you already have X509Certificate
object. Here there are two cases:
- If you are using
bouncy-castle-adapter
dependency, then you should createX509CertificateBC
class (i.e. a class with the same name withBC
postfix) passing your originalX509Certificate
as a parameter to the constructor, and then use this created wrapper as a parameter forPdfSigner#SignDetached
method. - If you are using
bouncy-castle-fips-adapter
dependency, then you should createX509CertificateBCFips
class passing your actualX509Certificate
as a parameter, and then use this created wrapper as a parameter forPdfSigner#SignDetached
method.
Correspondingly, if you for example need to retrieve actual X509Certificate
object from either X509CertificateBC
or X509CertificateBCFips
, you should call GetCertificate
method.
This workflow is valid for each wrapper from bouncy-castle-adapter
and bouncy-castle-fips-adapter
modules, with the respect of names.
Let's take a look at the code.
.NET
before:
ICipherParameters pk = pk12.GetKey(alias).Key; X509CertificateEntry[] ce = pk12.GetCertificateChain(alias); X509Certificate[] chain = new X509Certificate[ce.Length]; for (int k = 0; k < ce.Length; ++k) { chain[k] = ce[k].Certificate; } PdfReader reader = new PdfReader(src); PdfSigner signer = new PdfSigner(reader, new FileStream(dest, FileMode.Create), new StampingProperties().UseAppendMode()); // Set signer options signer.SetFieldName(name); signer.SetCertificationLevel(PdfSigner.CERTIFIED_FORM_FILLING); IExternalSignature pks = new PrivateKeySignature(pk, DigestAlgorithms.SHA256); // Sign the document using the detached mode, CMS or CAdES equivalent. signer.SignDetached(pks, chain, null, null, null, 0, PdfSigner.CryptoStandard.CMS);
after:
ICipherParameters pk = pk12.GetKey(alias).Key; X509CertificateEntry[] ce = pk12.GetCertificateChain(alias); IX509Certificate[] chain = new IX509Certificate[ce.Length]; for (int k = 0; k < ce.Length; ++k) { chain[k] = new X509CertificateBC(ce[k].Certificate); } PdfReader reader = new PdfReader(src); PdfSigner signer = new PdfSigner(reader, new FileStream(dest, FileMode.Create), new StampingProperties().UseAppendMode()); // Set signer options signer.SetFieldName(name); signer.SetCertificationLevel(PdfSigner.CERTIFIED_FORM_FILLING); IExternalSignature pks = new PrivateKeySignature(new PrivateKeyBC(pk), DigestAlgorithms.SHA256); // Sign the document using the detached mode, CMS or CAdES equivalent. signer.SignDetached(pks, chain, null, null, null, 0, PdfSigner.CryptoStandard.CMS);
Java
before:
if (TimestampConstants.UNDEFINED_TIMESTAMP_DATE != pkcs7.getTimeStampDate()) { System.out.println("TimeStamp: " + date_format.format(pkcs7.getTimeStampDate().getTime())); TSTInfo ts = pkcs7.getTimeStampToken(); System.out.println("TimeStamp service: " + ts.getTimeStampInfo().getTsa()); System.out.println("Timestamp verified? " + pkcs7.verifyTimestampImprint()); }
after:
if (TimestampConstants.UNDEFINED_TIMESTAMP_DATE != pkcs7.getTimeStampDate()) { System.out.println("TimeStamp: " + date_format.format(pkcs7.getTimeStampDate().getTime())); TSTInfo ts = ((TSTInfoBC) pkcs7.getTimeStampTokenInfo()).getTstInfo(); System.out.println("TimeStamp service: " + ts.getTsa()); System.out.println("Timestamp verified? " + pkcs7.verifyTimestampImprint()); }