Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Bruce

Quality Gate Status Security Rating Vulnerabilities Maven Central License

Bruce is an ergonomic, lightweight, pure Java wrapper around the Java Cryptography Architecture (JCA). It makes common cryptographic operations straightforward without adding any runtime dependencies beyond the JDK.

Features

  • Digital signatures — sign and verify data with RSA, DSA, ECDSA, and more
  • Symmetric encryption — AES-CBC, AES-GCM, DES, and other secret-key ciphers
  • Asymmetric encryption — RSA public/private-key encryption and decryption
  • Message digests — SHA-256, SHA-512, MD5, and any JCA-supported algorithm
  • Message Authentication Codes (MAC) — HmacSHA256, HmacSHA512, and more
  • Keystore management — load PKCS12/JKS keystores and serialize them to bytes, text, or files
  • Key generation — generate RSA/DSA/EC key pairs and symmetric keys on the fly
  • PEM support — read and write private keys, public keys, and certificates in PEM format
  • Multiple encodings — HEX, BASE64, URL-safe BASE64, and MIME BASE64
  • Pluggable providers — works with any JCA provider (e.g., Bouncy Castle)
  • Multi-key APIs — select a key by ID at call time for key-rotation scenarios
  • Type-safe algorithm enums — compile-time safety and IDE auto-completion for all algorithm names
  • Zero runtime dependencies — pure JDK, no extra JARs required at runtime

Requirements

  • Java 21 or later

Installation

Maven

<dependency>
    <groupId>com.mirkocaserta.bruce</groupId>
    <artifactId>bruce</artifactId>
    <version>2.1.0</version>
</dependency>

Gradle

implementation 'com.mirkocaserta.bruce:bruce:2.1.0'

Check Maven Central for the latest release version.

Quick Start

All operations are accessed through two static facades. Add these imports once at the top of your file:

import static com.mirkocaserta.bruce.Bruce.*;
import static com.mirkocaserta.bruce.Bruce.Encoding.*;
import static com.mirkocaserta.bruce.Keystores.*;

// Optional: import algorithm enums for type-safe algorithm selection
import com.mirkocaserta.bruce.DigestAlgorithm;
import com.mirkocaserta.bruce.MacAlgorithm;
import com.mirkocaserta.bruce.SignatureAlgorithm;
import com.mirkocaserta.bruce.SymmetricAlgorithm;
import com.mirkocaserta.bruce.SymmetricCipherAlgorithm;
import com.mirkocaserta.bruce.AsymmetricAlgorithm;

Usage Examples

Loading Keys from a Keystore

// Load a PKCS12 keystore from the classpath
KeyStore ks = keystore("classpath:keystore.p12", "password".toCharArray(), "PKCS12");

// Extract keys by alias
PrivateKey privateKey = privateKey(ks, "alice", "password".toCharArray());
PublicKey  publicKey  = publicKey(ks, "alice");

Keystores can be loaded from multiple sources:

PrefixExample
classpath:classpath:keystore.p12
file:file:/etc/ssl/keystore.p12
http://http://config-server/keystore.p12
https://https://config-server/keystore.p12

Keystore Serialization

KeyStore ks = keystore("classpath:keystore.p12", "password", "PKCS12");

// Serialize to raw bytes
byte[] raw = keystoreToBytes(ks, "password");

// Serialize and encode for text transport
String base64 = keystoreToString(ks, "password", BASE64);

// Persist directly to disk
keystoreToFile(ks, "password", Path.of("/tmp/keystore-copy.p12"));

Digital Signatures

KeyStore ks         = keystore("classpath:keystore.p12", "password", "PKCS12");
PrivateKey signKey  = privateKey(ks, "alice", "password");
PublicKey  verifyKey = publicKey(ks, "alice");

// Create a signer and a verifier (string-based)
Signer   signer   = signerBuilder().key(signKey).algorithm("SHA256withRSA").build();
Verifier verifier = verifierBuilder().key(verifyKey).algorithm("SHA256withRSA").build();

// Or use the type-safe enum alternative:
Signer   signer2   = signerBuilder().key(signKey).algorithm(SignatureAlgorithm.SHA256_WITH_RSA).build();
Verifier verifier2 = verifierBuilder().key(verifyKey).algorithm(SignatureAlgorithm.SHA256_WITH_RSA).build();

// Sign
Bytes message   = Bytes.from("Hello, Bob!");
Bytes signature = signer.sign(message);

// Encode signature for transport
String b64Signature = signature.encode(BASE64);

// Verify (decode first, then verify)
Bytes sigFromB64 = Bytes.from(b64Signature, BASE64);
boolean valid    = verifier.verify(message, sigFromB64);

Message Digest (Hashing)

// String-based or enum-based algorithm selection
Digester sha256 = digestBuilder().algorithm("SHA-256").build();
Digester sha256e = digestBuilder().algorithm(DigestAlgorithm.SHA_256).build(); // equivalent
Digester sha512 = digestBuilder().algorithm("SHA-512").build();

Bytes hash    = sha256.digest(Bytes.from("Hello, World!"));
String hexHash = hash.encode(HEX);    // "dffd6021bb2bd5b0af676290809ec3a5..."
String b64Hash = hash.encode(BASE64); // "/fVgIbsr1v..."

// File hashing is streamed in chunks (does not load the full file in memory)
Bytes fileHashFromPath = sha256.digest(Path.of("/var/log/app.log"));
Bytes fileHashFromFile = sha256.digest(new File("/var/log/app.log"));

Symmetric Encryption (AES)

// Generate a random AES key
byte[] keyBytes = symmetricKey("AES");
byte[] ivBytes  = new byte[16];
new SecureRandom().nextBytes(ivBytes);

// Build encryptor and decryptor (string-based)
SymmetricEncryptor encryptor = cipherBuilder()
    .key(keyBytes)
    .algorithms("AES", "AES/CBC/PKCS5Padding")
    .buildSymmetricEncryptor();

SymmetricDecryptor decryptor = cipherBuilder()
    .key(keyBytes)
    .algorithms("AES", "AES/CBC/PKCS5Padding")
    .buildSymmetricDecryptor();

// Or use type-safe enums:
SymmetricEncryptor encryptor2 = cipherBuilder()
    .key(keyBytes)
    .algorithms(SymmetricAlgorithm.AES, SymmetricCipherAlgorithm.AES_CBC_PKCS5)
    .buildSymmetricEncryptor();

Bytes iv         = Bytes.from(ivBytes);
Bytes cipherText = encryptor.encrypt(iv, Bytes.from("Secret message"));
Bytes plainText  = decryptor.decrypt(iv, cipherText);

// Encode for storage/transport
String encoded = cipherText.encode(BASE64);

Asymmetric Encryption (RSA)

// Generate an RSA key pair
KeyPair keyPair = keyPair("RSA", 2048);

AsymmetricEncryptor encryptor = cipherBuilder()
    .key(keyPair.getPublic())
    .algorithm("RSA/ECB/PKCS1Padding")
    .buildAsymmetricEncryptor();

AsymmetricDecryptor decryptor = cipherBuilder()
    .key(keyPair.getPrivate())
    .algorithm("RSA/ECB/PKCS1Padding")
    .buildAsymmetricDecryptor();

Bytes cipherText = encryptor.encrypt(Bytes.from("Top secret"));
Bytes plainText  = decryptor.decrypt(cipherText);

Message Authentication Code (MAC)

// Load a secret key from a keystore
KeyStore ks  = keystore("classpath:keystore.p12", "password");
Key secretKey = secretKey(ks, "hmac-key", "password");

Mac mac = macBuilder()
    .key(secretKey)
    .algorithm("HmacSHA256")
    .build();

Bytes data = Bytes.from("Authenticate me");
Bytes tag  = mac.sign(data);
String hexTag = tag.encode(HEX);

PEM Support

// Read keys from PEM strings
PrivateKey privKey = privateKeyFromPem("""
    -----BEGIN PRIVATE KEY-----
    MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7...
    -----END PRIVATE KEY-----
    """, "RSA");

PublicKey pubKey = publicKeyFromPem("""
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu7...
    -----END PUBLIC KEY-----
    """, "RSA");

// Convert keys back to PEM
String privatePem = keyToPem(privKey);
String publicPem  = keyToPem(pubKey);

Key Generation

// Generate key pairs
KeyPair rsaKeyPair = keyPair("RSA", 2048);
KeyPair ecKeyPair  = keyPair("EC", 256);
KeyPair dsaKeyPair = keyPair("DSA", 2048);

// Generate symmetric keys
byte[] aesKey    = symmetricKey("AES");
String b64AesKey = symmetricKey("AES", BASE64); // encoded for storage

Multi-Key APIs

Bruce supports selecting a key by ID at runtime, which is useful for key-rotation scenarios:

Map<String, PrivateKey> privateKeys = Map.of(
    "key-2023", privateKey(ks, "alice-2023", "password"),
    "key-2024", privateKey(ks, "alice-2024", "password")
);

SignerByKey signer = signerBuilder()
    .keys(privateKeys)
    .algorithm("SHA256withRSA")
    .buildByKey();

// Select the key to use at call time
Bytes signature = signer.sign("key-2024", Bytes.from("Hello"));

Type-Safe Algorithm Enums

All builder methods that accept a raw algorithm string also accept a type-safe enum constant. This provides compile-time validation and IDE auto-completion as an alternative to remembering JCA algorithm name strings.

// DigestAlgorithm
digestBuilder().algorithm(DigestAlgorithm.SHA_256).build();

// MacAlgorithm
macBuilder().key(key).algorithm(MacAlgorithm.HMAC_SHA_256).build();

// SignatureAlgorithm
signerBuilder().key(privateKey).algorithm(SignatureAlgorithm.SHA256_WITH_RSA).build();
verifierBuilder().key(publicKey).algorithm(SignatureAlgorithm.SHA256_WITH_RSA).build();

// SymmetricAlgorithm + SymmetricCipherAlgorithm
cipherBuilder()
    .key(keyBytes)
    .algorithms(SymmetricAlgorithm.AES, SymmetricCipherAlgorithm.AES_CBC_PKCS5)
    .buildSymmetricEncryptor();

// AsymmetricAlgorithm
cipherBuilder()
    .key(publicKey)
    .algorithm(AsymmetricAlgorithm.RSA_ECB_PKCS1)
    .buildAsymmetricEncryptor();

All enum types implement the AlgorithmId interface, which exposes the underlying JCA name via algorithmName(). The string-based overloads remain fully supported for custom or provider-specific algorithms not covered by the built-in enums.

Using a Custom Provider

// Use Bouncy Castle for extended algorithm support
Security.addProvider(new BouncyCastleProvider());

Digester digester = digestBuilder()
    .algorithm("BLAKE2b-256")
    .provider("BC")
    .build();

The Bytes Type

Bytes is Bruce’s universal currency type. It wraps a raw byte array and provides convenient conversions:

// Construction
Bytes b1 = Bytes.from(new byte[]{1, 2, 3});       // raw bytes
Bytes b2 = Bytes.from("Hello");                    // UTF-8 text
Bytes b3 = Bytes.from("cafebabe", HEX);            // decode HEX
Bytes b4 = Bytes.from("c2lnbg==", BASE64);         // decode BASE64
Bytes b5 = Bytes.from(Path.of("secret.bin"));      // file contents
Bytes b6 = Bytes.fromPem("-----BEGIN ...");        // PEM-encoded DER

// Consumption
byte[] raw   = b2.asBytes();
String hex   = b2.encode(HEX);
String b64   = b2.encode(BASE64);
String text  = b2.asString();       // UTF-8
int    len   = b2.length();
boolean empty = b2.isEmpty();

Building from Source

git clone https://github.com/mcaserta/bruce.git
cd bruce
./gradlew build

Run tests:

./gradlew test

Generate Javadoc:

./gradlew javadoc

Contributing

Contributions are welcome. See CONTRIBUTING.md for the issue and pull request workflow.

License

Bruce is released under the Apache License, Version 2.0.