Skip to content

Commit 712a3b4

Browse files
cconloncconlon
committed
add Bouncy Castle Migration Guide
1 parent 26bdbb7 commit 712a3b4

13 files changed

Lines changed: 1532 additions & 1 deletion

File tree

‎BouncyCastle-Migration/Makefile‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
-include ../common/common.am
2+
.DEFAULT_GOAL := all
3+
all: pdf html
4+
5+
6+
SOURCES = chapter01.md \
7+
chapter02.md \
8+
chapter03.md \
9+
chapter04.md \
10+
chapter05.md \
11+
chapter06.md \
12+
chapter07.md \
13+
chapter08.md
14+
15+
PDF = BouncyCastle-wolfSSL-Migration-Guide.pdf
16+
17+
.PHONY: html-prep
18+
html-prep:
19+
20+
.PHONY: pdf-prep
21+
pdf-prep:

‎BouncyCastle-Migration/header.txt‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
% Bouncy Castle Migration Guide ![](logo.png)
2+
3+
---
4+
header-includes:
5+
# Blank pages on new sections
6+
- \usepackage{titlesec}
7+
- \newcommand{\sectionbreak}{\clearpage}
8+
# Fancy page headers
9+
- \usepackage{fancyhdr}
10+
- \pagestyle{fancy}
11+
- \fancyfoot[LO,RE]{COPYRIGHT \copyright 2026 wolfSSL Inc.}
12+
# Wrap long syntax highlighting code blocks
13+
- \usepackage{fvextra}
14+
- \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}}
15+
# Wrap long non-syntax highlighted code blocks
16+
- \usepackage{listings}
17+
- \let\verbatim\undefined
18+
- \let\verbatimend\undefined
19+
- \lstnewenvironment{verbatim}{\lstset{breaklines,basicstyle=\ttfamily}}{}
20+
subparagraph: yes
21+
---

‎BouncyCastle-Migration/mkdocs.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
site_name: Bouncy Castle Migration Guide
2+
site_url: https://wolfssl.com/
3+
docs_dir: build/html/
4+
site_dir: html/
5+
copyright: Copyright © 2026 wolfSSL Inc.
6+
nav:
7+
- "1. Introduction": index.md
8+
- "2. Overview of Differences": chapter02.md
9+
- "3. JCE Provider Migration": chapter03.md
10+
- "4. JSSE Provider Migration": chapter04.md
11+
- "5. BC Proprietary API Migration": chapter05.md
12+
- "6. FIPS 140-3 Considerations": chapter06.md
13+
- "7. Troubleshooting": chapter07.md
14+
- "8. Support": chapter08.md
15+
theme:
16+
name: null
17+
custom_dir: ../mkdocs-material/material
18+
language: en
19+
palette:
20+
primary: indigo
21+
accent: indigo
22+
font:
23+
text: Roboto
24+
code: Roboto Mono
25+
icon: "logo.png"
26+
logo: logo.png
27+
favicon: logo.png
28+
feature:
29+
tabs: true
30+
extra_css: [skin.css]
31+
extra:
32+
generator: false
33+
use_directory_urls: false

‎BouncyCastle-Migration/src/chapter01.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Introduction
2+
3+
This guide provides instructions and reference material for developers migrating
4+
Java applications from the Bouncy Castle JCE provider and/or JSSE provider to
5+
wolfSSL's wolfJCE and wolfJSSE providers. wolfJCE and wolfJSSE are backed by
6+
the wolfCrypt native cryptography library, which includes FIPS 140-3 validated
7+
options for applications requiring certified cryptography.
8+
9+
## Audience
10+
11+
This guide is intended for Java developers and architects who currently use
12+
Bouncy Castle for cryptographic operations (JCE) and/or TLS (JSSE) and are
13+
evaluating or planning a migration to wolfJCE and/or wolfJSSE.
14+
15+
## Why Migrate?
16+
17+
Common reasons for migrating from Bouncy Castle to wolfJCE/wolfJSSE include:
18+
19+
- **FIPS 140-3 compliance** - wolfCrypt has FIPS 140-3 validated cryptographic
20+
modules, providing certified cryptography underneath the JCE and JSSE layers.
21+
- **Performance** - wolfCrypt is written in C and can leverage hardware
22+
cryptography acceleration, offering performance advantages over pure-Java
23+
implementations.
24+
- **Reduced footprint** - wolfCrypt's native implementation can offer a smaller
25+
overall footprint compared to Bouncy Castle in resource-constrained
26+
environments.
27+
- **Commercial support** - wolfSSL Inc. provides commercial support, maintenance,
28+
and consulting services.
29+
30+
## Scope
31+
32+
This guide covers migration of:
33+
34+
- **JCE Provider** - Cryptographic operations including ciphers, message digests,
35+
MACs, signatures, key generation, key agreement, and KeyStore implementations
36+
(Bouncy Castle JCE Provider to wolfJCE).
37+
- **JSSE Provider** - TLS/SSL connections including SSLContext, SSLSocket,
38+
SSLServerSocket, SSLEngine, TrustManager, and KeyManager implementations
39+
(Bouncy Castle JSSE Provider to wolfJSSE).
40+
41+
For detailed reference on each product, see the
42+
[wolfCrypt JCE Provider and JNI Manual](https://www.wolfssl.com/documentation/manuals/wolfcrypt-jni-jce/)
43+
and the
44+
[wolfSSL JNI and wolfJSSE Manual](https://www.wolfssl.com/documentation/manuals/wolfssljni/).

‎BouncyCastle-Migration/src/chapter02.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Overview of Differences
2+
3+
This chapter provides a high-level comparison between Bouncy Castle and the
4+
wolfSSL Java providers (wolfJCE and wolfJSSE) to help frame the migration effort.
5+
6+
## Architecture Comparison
7+
8+
### Bouncy Castle
9+
10+
Bouncy Castle is a pure-Java cryptographic library that includes both a
11+
lightweight crypto API and standard JCE/JSSE provider implementations. All
12+
cryptographic operations are implemented in Java.
13+
14+
### wolfJCE / wolfJSSE
15+
16+
wolfJCE and wolfJSSE are JNI-based providers that wrap the native wolfCrypt and
17+
wolfSSL C libraries, respectively. Cryptographic operations are performed in
18+
native code, with Java providing the JCE/JSSE interface layer.
19+
20+
## Provider Registration
21+
22+
Both Bouncy Castle and wolfJCE/wolfJSSE follow the standard Java Security
23+
architecture for provider registration. The primary difference is in the
24+
provider class names and the requirement to load native libraries for wolfSSL
25+
providers.
26+
27+
### Bouncy Castle Provider Registration
28+
29+
```java
30+
import org.bouncycastle.jce.provider.BouncyCastleProvider;
31+
import org.bouncycastle.jsse.provider.BouncyCastleJsseProvider;
32+
33+
Security.addProvider(new BouncyCastleProvider());
34+
Security.addProvider(new BouncyCastleJsseProvider());
35+
```
36+
37+
### wolfJCE / wolfJSSE Provider Registration
38+
39+
```java
40+
import com.wolfssl.provider.jce.WolfCryptProvider;
41+
import com.wolfssl.provider.jsse.WolfSSLProvider;
42+
43+
Security.addProvider(new WolfCryptProvider());
44+
Security.addProvider(new WolfSSLProvider());
45+
```
46+
47+
## Supported Algorithms
48+
49+
wolfJCE and wolfJSSE support a focused set of algorithms commonly required
50+
for modern applications and FIPS 140-3 compliance. While Bouncy Castle supports
51+
a very wide range of algorithms including many legacy and niche options,
52+
wolfJCE/wolfJSSE focus on widely-used, standards-based algorithms.
53+
54+
Consult the following manuals for the current list of supported algorithms
55+
and classes:
56+
57+
- [wolfJCE Supported Algorithms and Classes](https://www.wolfssl.com/documentation/manuals/wolfcrypt-jni-jce/chapter06.html)
58+
- [wolfJSSE Supported Algorithms and Classes](https://www.wolfssl.com/documentation/manuals/wolfssljni/chapter06.html)
59+
60+
## KeyStore Comparison
61+
62+
For FIPS 140-3 deployments, WKS is the recommended KeyStore type since all
63+
of its internal cryptographic operations use FIPS-approved algorithms from the
64+
wolfCrypt FIPS module. See Chapter 3 for KeyStore migration details.
65+

0 commit comments

Comments
 (0)