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.

It is important not to add them both as a dependency since they are not compatible

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:

  1. "bouncy-castle" - forces connector to first try to use bouncy-castle-adapter  module
  2. "bouncy-castle-fips" - forces connector to first try to use bouncy-castle-fips-adapter  module
  3. 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


Note that only approved mode provides full FIPS compliance

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 create X509CertificateBC class (i.e. a class with the same name with BC postfix) passing your original X509Certificate as a parameter to the constructor, and then use this created wrapper as a parameter for PdfSigner#SignDetached method.
  • If you are using bouncy-castle-fips-adapter dependency, then you should create X509CertificateBCFips class passing your actual X509Certificate as a parameter, and then use this created wrapper as a parameter for PdfSigner#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());
}