Initial Bouncy Castle Migration Guide

BouncyCastle-Migration/Makefile

@@ -0,0 +1,21 @@
+-include ../common/common.am
+.DEFAULT_GOAL := all
+all: pdf html
+
+
+SOURCES = chapter01.md \
+		  chapter02.md \
+		  chapter03.md \
+		  chapter04.md \
+		  chapter05.md \
+		  chapter06.md \
+		  chapter07.md \
+		  chapter08.md
+
+PDF  = BouncyCastle-wolfSSL-Migration-Guide.pdf
+
+.PHONY: html-prep
+html-prep:
+
+.PHONY: pdf-prep
+pdf-prep:

BouncyCastle-Migration/header.txt

@@ -0,0 +1,21 @@
+% Bouncy Castle Migration Guide  ![](logo.png)
+
+---
+header-includes:
+    # Blank pages on new sections
+    - \usepackage{titlesec}
+    - \newcommand{\sectionbreak}{\clearpage}
+    # Fancy page headers
+    - \usepackage{fancyhdr}
+    - \pagestyle{fancy}
+    - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2026 wolfSSL Inc.}
+    # Wrap long syntax highlighting code blocks
+    - \usepackage{fvextra}
+    - \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}}
+    # Wrap long non-syntax highlighted code blocks
+    - \usepackage{listings}
+    - \let\verbatim\undefined
+    - \let\verbatimend\undefined
+    - \lstnewenvironment{verbatim}{\lstset{breaklines,basicstyle=\ttfamily}}{}
+subparagraph: yes
+---

BouncyCastle-Migration/mkdocs.yml

@@ -0,0 +1,33 @@
+site_name: Bouncy Castle Migration Guide
+site_url: https://wolfssl.com/
+docs_dir: build/html/
+site_dir: html/
+copyright: Copyright © 2026 wolfSSL Inc.
+nav:
+    - "1. Introduction": index.md
+    - "2. Overview of Differences": chapter02.md
+    - "3. JCE Provider Migration": chapter03.md
+    - "4. JSSE Provider Migration": chapter04.md
+    - "5. BC Proprietary API Migration": chapter05.md
+    - "6. FIPS 140-3 Considerations": chapter06.md
+    - "7. Troubleshooting": chapter07.md
+    - "8. Support": chapter08.md
+theme:
+  name: null
+  custom_dir: ../mkdocs-material/material
+  language: en
+  palette:
+    primary: indigo
+    accent: indigo
+  font:
+    text: Roboto
+    code: Roboto Mono
+  icon: "logo.png"
+  logo: logo.png
+  favicon: logo.png
+  feature:
+    tabs: true
+extra_css: [skin.css]
+extra:
+    generator: false
+use_directory_urls: false

BouncyCastle-Migration/src/chapter01.md

@@ -0,0 +1,44 @@
+# Introduction
+
+This guide provides instructions and reference material for developers migrating
+Java applications from the Bouncy Castle JCE provider and/or JSSE provider to
+wolfSSL's wolfJCE and wolfJSSE providers. wolfJCE and wolfJSSE are backed by
+the wolfCrypt native cryptography library, which includes FIPS 140-3 validated
+options for applications requiring certified cryptography.
+
+## Audience
+
+This guide is intended for Java developers and architects who currently use
+Bouncy Castle for cryptographic operations (JCE) and/or TLS (JSSE) and are
+evaluating or planning a migration to wolfJCE and/or wolfJSSE.
+
+## Why Migrate?
+
+Common reasons for migrating from Bouncy Castle to wolfJCE/wolfJSSE include:
+
+- **FIPS 140-3 compliance** - wolfCrypt has FIPS 140-3 validated cryptographic
+  modules, providing certified cryptography underneath the JCE and JSSE layers.
+- **Performance** - wolfCrypt is written in C and can leverage hardware
+  cryptography acceleration, offering performance advantages over pure-Java
+  implementations.
+- **Reduced footprint** - wolfCrypt's native implementation can offer a smaller
+  overall footprint compared to Bouncy Castle in resource-constrained
+  environments.
+- **Commercial support** - wolfSSL Inc. provides commercial support, maintenance,
+  and consulting services.
+
+## Scope
+
+This guide covers migration of:
+
+- **JCE Provider** - Cryptographic operations including ciphers, message digests,
+  MACs, signatures, key generation, key agreement, and KeyStore implementations
+  (Bouncy Castle JCE Provider to wolfJCE).
+- **JSSE Provider** - TLS/SSL connections including SSLContext, SSLSocket,
+  SSLServerSocket, SSLEngine, TrustManager, and KeyManager implementations
+  (Bouncy Castle JSSE Provider to wolfJSSE).
+
+For detailed reference on each product, see the
+[wolfCrypt JCE Provider and JNI Manual](https://www.wolfssl.com/documentation/manuals/wolfcrypt-jni-jce/)
+and the
+[wolfSSL JNI and wolfJSSE Manual](https://www.wolfssl.com/documentation/manuals/wolfssljni/).

BouncyCastle-Migration/src/chapter02.md

@@ -0,0 +1,65 @@
+# Overview of Differences
+
+This chapter provides a high-level comparison between Bouncy Castle and the
+wolfSSL Java providers (wolfJCE and wolfJSSE) to help frame the migration effort.
+
+## Architecture Comparison
+
+### Bouncy Castle
+
+Bouncy Castle is a pure-Java cryptographic library that includes both a
+lightweight crypto API and standard JCE/JSSE provider implementations. All
+cryptographic operations are implemented in Java.
+
+### wolfJCE / wolfJSSE
+
+wolfJCE and wolfJSSE are JNI-based providers that wrap the native wolfCrypt and
+wolfSSL C libraries, respectively. Cryptographic operations are performed in
+native code, with Java providing the JCE/JSSE interface layer.
+
+## Provider Registration
+
+Both Bouncy Castle and wolfJCE/wolfJSSE follow the standard Java Security
+architecture for provider registration. The primary difference is in the
+provider class names and the requirement to load native libraries for wolfSSL
+providers.
+
+### Bouncy Castle Provider Registration
+
+```java
+import org.bouncycastle.jce.provider.BouncyCastleProvider;
+import org.bouncycastle.jsse.provider.BouncyCastleJsseProvider;
+
+Security.addProvider(new BouncyCastleProvider());
+Security.addProvider(new BouncyCastleJsseProvider());
+```
+
+### wolfJCE / wolfJSSE Provider Registration
+
+```java
+import com.wolfssl.provider.jce.WolfCryptProvider;
+import com.wolfssl.provider.jsse.WolfSSLProvider;
+
+Security.addProvider(new WolfCryptProvider());
+Security.addProvider(new WolfSSLProvider());
+```
+
+## Supported Algorithms
+
+wolfJCE and wolfJSSE support a focused set of algorithms commonly required
+for modern applications and FIPS 140-3 compliance. While Bouncy Castle supports
+a very wide range of algorithms including many legacy and niche options,
+wolfJCE/wolfJSSE focus on widely-used, standards-based algorithms.
+
+Consult the following manuals for the current list of supported algorithms
+and classes:
+
+- [wolfJCE Supported Algorithms and Classes](https://www.wolfssl.com/documentation/manuals/wolfcrypt-jni-jce/chapter06.html)
+- [wolfJSSE Supported Algorithms and Classes](https://www.wolfssl.com/documentation/manuals/wolfssljni/chapter06.html)
+
+## KeyStore Comparison
+
+For FIPS 140-3 deployments, WKS is the recommended KeyStore type since all
+of its internal cryptographic operations use FIPS-approved algorithms from the
+wolfCrypt FIPS module. See Chapter 3 for KeyStore migration details.
+