PKCS#12 Key Generation Iteration Configuration

Starting with Bouncy Castle 1.86, the iteration count used for the password-based encryption of PKCS#12 keystore keys can be configured via the system property:

org.bouncycastle.pkcs12.store_it_count

How the iteration count works

When Bouncy Castle writes a PKCS#12 keystore, it protects the private keys and certificates with password-based encryption (PBE). The iteration count controls how many times the key derivation function (PBKDF1-style SHA-256) is applied. A higher count increases the work an attacker must do to brute-force the password, but also increases the time a legitimate load or store operation takes.

Recommended iteration count values

Production

org.bouncycastle.pkcs12.store_it_count=600_000

Bouncy Castle's built-in default is 600,000, aligned with the OWASP recommendation for PBKDF2-HMAC-SHA256.

A keystore written at this count can always be read back, since the read-side cap (org.bouncycastle.pkcs12.max_it_count) defaults to 5,000,000.

Testing and CI

org.bouncycastle.pkcs12.store_it_count=4096

4,096 is the value Bouncy Castle's own Gradle build and Ant harnesses set via -Dorg.bouncycastle.pkcs12.store_it_count=4096. At 600,000 iterations, a test suite that creates dozens of PKCS#12 keystores adds significant wall time; 4,096 reduces that to a negligible cost. Use this value only in tests, keystores written at this count offer virtually no brute-force resistance.

Configure iteration count

WildFly

Add the system property to the file standalone.xml:

<system-properties>
        ...
        <property name="org.bouncycastle.pkcs12.store_it_count" value="4096"/>
</system-properties>

Alternatively, using the JBoss CLI:

/opt/wildfly/bin/jboss-cli.sh --connect '/system-property=org.bouncycastle.pkcs12.store_it_count:add(value="4096")'

Other Java applications

The property can also be set as a JVM argument when starting the Java process:

-Dorg.bouncycastle.pkcs12.store_it_count=4096