Botanj - Java Security Provider (JSP)

⚠️ Caution:
The code within this repository is currently in its early beta phase and has not been officially released. We would strongly advise against using it for production purposes until it reaches a stable, release-ready state.

Index

1. Introduction
2. Documentation
3. Building The Library
4. Supported Primitives
5. Using Botan JSP

Introduction

Botanj is a Java Security Provider (JSP) , which uses Botan to implements parts of the Java Cryptography Extension (JCE). This implementation is compatible with other JSPs (e.g. Bouncy Castle), thus enabling a smooth migration.

Botanj uses JNR-FFI for loading Botan native code.

Documentation

• JavaDoc API Reference

Comprehensive API documentation with detailed usage examples, architecture explanations, and implementation notes for all cryptographic operations.

Building The Library

• Install native Botan Library
• Install Apache Maven-3
• Install Java 17+ (tested with openjdk 17/21/24)
• Run tests: (Botan library path macOS example) mvn test -Dnative.lib.path=/opt/homebrew/opt/botan/lib

Supported Primitives

Ciphers, hashes, MACs, and checksums

• Authenticated cipher modes: EAX, OCB, GCM, SIV, CCM, (X)ChaCha20Poly1305
• Cipher modes: CTR, CBC, CFB, OFB
• Block ciphers: AES, DES/3DES
• Stream ciphers: (X)Salsa20, (X)ChaCha20
• Hash functions: SHA-1, SHA-2, SHA-3, MD4, MD5, RIPEMD-160, BLAKE2b
• Message Authentication codes: HMAC (SHA-1, SHA-2, SHA-3), CMAC, Poly1305, SipHash

Public Key Cryptography

• Not yet supported

Public Key Infrastructure

• Not yes supported

Transport Layer Security (TLS) Protocol (JSSE)

• Not yet supported

Using Botanj

• An example describing the procedure to compute a MessageDigest object:

final MessageDigest digest = MessageDigest.getInstance("blake2b-512", BotanProvider.NAME);
final byte[] output = digest.digest("hello world".getBytes());

• An example describing the procedure to compute a MAC object:

final SecretKeySpec key = new SecretKeySpec(key, "HMAC-SHA512");
final Mac mac = Mac.getInstance("HMAC-SHA512", BotanProvider.NAME);
mac.init(key);
final byte[] output = mac.doFinal("hello world".getBytes());

• An example describing the procedure to encrypt using AES-256/GCM:

final Cipher cipher = Cipher.getInstance("AES-256/GCM/NoPadding", BotanProvider.NAME);
// Never reuse the IV with the same key
cipher.init(Cipher.ENCRYPT_MODE, key, iv);
cipher.updateAAD(aad);
final byte[] output = cipher.doFinal("hello world".getBytes());

• An example describing the procedure to encrypt using AES-256/CBC/PKCS7:

final Cipher cipher = Cipher.getInstance("AES-256/CBC/PKCS7", BotanProvider.NAME);
cipher.init(Cipher.ENCRYPT_MODE, key, iv);
final byte[] output = cipher.doFinal("hello world".getBytes());

• An example describing the procedure to encrypt using ChaCha20:

final Cipher cipher = Cipher.getInstance("ChaCha20/None/NoPadding", BotanProvider.NAME);
// Never reuse the IV with the same key
cipher.init(Cipher.ENCRYPT_MODE, key, iv);
final byte[] output = cipher.doFinal("hello world".getBytes());

• An example describing the procedure to encrypt using ChaCha20-Poly1305 (AEAD):

final Cipher cipher = Cipher.getInstance("ChaCha20/Poly1305/NoPadding", BotanProvider.NAME);
// ChaCha20-Poly1305 uses 12-byte nonce, never reuse with the same key
final AeadParameterSpec params = new AeadParameterSpec(128, nonce); // 128-bit tag
cipher.init(Cipher.ENCRYPT_MODE, key, params);
cipher.updateAAD(aad); // Optional associated data
final byte[] output = cipher.doFinal("hello world".getBytes());

• An example describing the procedure to encrypt using XChaCha20-Poly1305 (AEAD):

final Cipher cipher = Cipher.getInstance("XChaCha20/Poly1305/NoPadding", BotanProvider.NAME);
// XChaCha20-Poly1305 uses 24-byte extended nonce for improved security
final AeadParameterSpec params = new AeadParameterSpec(128, nonce); // 128-bit tag
cipher.init(Cipher.ENCRYPT_MODE, key, params);
cipher.updateAAD(aad); // Optional associated data
final byte[] output = cipher.doFinal("hello world".getBytes());