Package net.randombit.botan

Class BotanProvider

java.lang.Object
java.util.Dictionary<K,V>
java.util.Hashtable<Object,Object>
java.util.Properties
java.security.Provider
net.randombit.botan.BotanProvider
All Implemented Interfaces:
Serializable, Cloneable, Map<Object,Object>
public final class BotanProvider extends Provider
Java Security Provider implementation that provides cryptographic algorithms using the Botan native library.

This provider integrates the Botan cryptography library into the Java Cryptography Architecture (JCA), making Botan's high-performance native implementations available through standard JCA APIs. All cryptographic operations are delegated to the native Botan library via JNR-FFI.

Installation and Usage

The provider can be registered statically in the security properties file or dynamically at runtime:

Static Registration (java.security file)

 security.provider.N=net.randombit.botan.BotanProvider

Dynamic Registration


 // Add as highest priority provider
 Security.insertProviderAt(new BotanProvider(), 1);

 // Or add at lowest priority
 Security.addProvider(new BotanProvider());

Using Algorithms from This Provider


 // Explicitly request from Botan provider
 MessageDigest sha256 = MessageDigest.getInstance("SHA-256", "Botan");
 Mac hmac = Mac.getInstance("HmacSHA256", "Botan");
 Cipher aes = Cipher.getInstance("AES/GCM/NoPadding", "Botan");

 // Or use provider object
 MessageDigest sha256 = MessageDigest.getInstance("SHA-256", new BotanProvider());

Supported Algorithms

Message Digests (Hash Functions)

  • MD Family: MD4, MD5 (deprecated for security)
  • SHA-1: SHA-1 (deprecated for security)
  • SHA-2 Family: SHA-224, SHA-256, SHA-384, SHA-512
  • SHA-3 Family: SHA3-224, SHA3-256, SHA3-384, SHA3-512
  • Keccak: KECCAK-224, KECCAK-256, KECCAK-384, KECCAK-512
  • BLAKE2b: BLAKE2B-160, BLAKE2B-256, BLAKE2B-384, BLAKE2B-512
  • RIPEMD: RIPEMD-160

Message Authentication Codes (MACs)

  • HMAC: HMAC-MD5, HMAC-RIPEMD160, HMAC-SHA1, HMAC-SHA224, HMAC-SHA256, HMAC-SHA384, HMAC-SHA512
  • CMAC: CMAC (AES-based cipher MAC)
  • Poly1305: Poly1305
  • SipHash: SipHash (SipHash-2-4)

Symmetric Ciphers

AES (Advanced Encryption Standard):

  • Block modes: AES/CBC, AES/CFB
  • Stream modes: AES/CTR/NoPadding, AES/OFB/NoPadding
  • AEAD modes: AES/GCM, AES/CCM, AES/SIV, AES/EAX, AES/OCB

DES (Data Encryption Standard):

  • Block modes: DES/CBC, DES/CFB
  • Stream modes: DES/CTR/NoPadding, DES/OFB/NoPadding

Triple DES (3DES/DESede):

  • Block modes: DESede/CBC, DESede/CFB (also aliased as 3DES and TripleDES)
  • Stream modes: DESede/CTR/NoPadding, DESede/OFB/NoPadding

Stream Ciphers:

  • Salsa20/None/NoPadding, XSalsa20/None/NoPadding
  • ChaCha20/None/NoPadding, XChaCha20/None/NoPadding

Padding Schemes for Block Ciphers

Block cipher modes (CBC, CFB) support the following padding schemes:

  • PKCS7 - PKCS#7 padding (most common, recommended)
  • PKCS5 - PKCS#5 padding (equivalent to PKCS7 for 8-byte blocks)
  • X9.23 - ANSI X9.23 padding
  • OneAndZeros - ISO/IEC 7816-4 padding
  • ESP - ESP padding (RFC 4303)
  • NoPadding - No padding (plaintext must be multiple of block size)

Example: Cipher.getInstance("AES/CBC/PKCS7", "Botan")

Algorithm Aliases

This provider supports multiple aliases for convenience and compatibility:

  • SHA-256 can also be accessed as "SHA256"
  • HmacSHA256 is an alias for "HMAC-SHA256"
  • AESCMAC is an alias for "CMAC"
  • 3DES/CBC and TripleDES/CBC are aliases for "DESede/CBC"
  • OID aliases are supported for standard algorithms (e.g., "2.16.840.1.101.3.4.2.1" for SHA-256)

Usage Examples

Computing a Hash


 Security.addProvider(new BotanProvider());

 MessageDigest sha256 = MessageDigest.getInstance("SHA-256", "Botan");
 sha256.update("Hello, World!".getBytes());
 byte[] hash = sha256.digest();

HMAC Authentication


 Mac hmac = Mac.getInstance("HmacSHA256", "Botan");
 SecretKeySpec key = new SecretKeySpec(keyBytes, "HmacSHA256");
 hmac.init(key);
 hmac.update(message);
 byte[] mac = hmac.doFinal();

AES Encryption with GCM (AEAD)


 Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "Botan");
 SecretKeySpec key = new SecretKeySpec(keyBytes, "AES");
 GCMParameterSpec params = new GCMParameterSpec(128, nonceBytes);

 cipher.init(Cipher.ENCRYPT_MODE, key, params);
 cipher.updateAAD(additionalData);
 byte[] ciphertext = cipher.doFinal(plaintext);

ChaCha20 Stream Cipher


 Cipher cipher = Cipher.getInstance("ChaCha20/None/NoPadding", "Botan");
 SecretKeySpec key = new SecretKeySpec(keyBytes, "ChaCha20");
 IvParameterSpec nonce = new IvParameterSpec(nonceBytes);

 cipher.init(Cipher.ENCRYPT_MODE, key, nonce);
 byte[] ciphertext = cipher.doFinal(plaintext);

Provider Information

Provider name: "Botan"

Provider info: "Botan Java Security Provider"

Version: Determined by the native Botan library version (accessible via getVersionStr())

Native Library Requirements

This provider requires the Botan 3.x native library to be installed and accessible:

  • Library name: botan-3 (libbotan-3.so on Linux, libbotan-3.dylib on macOS, botan-3.dll on Windows)
  • Minimum version: Botan 3.0.0
  • Installation: Via system package manager or built from source
  • Path configuration: Library must be in system library path or specified via java.library.path

If the native library cannot be loaded, the provider will throw an exception during construction.

Compatibility

This provider is designed to be compatible with other JCE providers:

  • Can be used alongside SunJCE, BouncyCastle, and other providers
  • Follows standard JCA naming conventions and APIs
  • Supports OID-based algorithm requests for interoperability
  • Algorithm implementations produce compatible outputs with standard implementations

Implementation Notes

  • Performance: Algorithms delegate to native Botan library for optimal performance
  • Resource Management: Uses Java Cleaner API for automatic native resource cleanup
  • Thread Safety: The provider itself is thread-safe, but individual cipher/digest instances are not
  • Immutability: The provider is final and cannot be extended
  • Initialization: Provider checks native library availability during construction
Since:
0.1.0
Author:
Yasser Aziza
See Also: