Getting Started

Installation Guide

Maven Dependency

<dependency>
   <groupId>net.glassless</groupId>
   <artifactId>glassless-provider</artifactId>
   <version>{project-version}</version>
</dependency>

Gradle Dependency

Groovy DSL

implementation 'net.glassless:glassless-provider:{project-version}'

Kotlin DSL

implementation("net.glassless:glassless-provider:{project-version}")

JVM Arguments

The provider requires native access permissions: 

java --enable-native-access=ALL-UNNAMED -jar your-app.jar

Or set in JAVA_TOOL_OPTIONS:

export JAVA_TOOL_OPTIONS="--enable-native-access=ALL-UNNAMED"

Registering the Provider

Programmatic Registration

import java.security.Security;
import net.glassless.provider.GlaSSLessProvider;

// Option 1: Add provider programmatically
Security.addProvider(new GlaSSLessProvider());

// Option 2: Insert at highest priority
Security.insertProviderAt(new GlaSSLessProvider(), 1);

System-wide Configuration

For system-wide installation, add GlaSSLess to the java.security file located at $JAVA_HOME/conf/security/java.security.

Finding the Configuration File
# Find java.security location
java -XshowSettings:all 2>&1 | grep java.home
# Then look in: <java.home>/conf/security/java.security
Adding the Provider

Providers are listed with numeric priorities (lower numbers = higher priority): 

# Existing providers (example)
security.provider.1=SUN
security.provider.2=SunRsaSign
security.provider.3=SunEC
security.provider.4=SunJSSE
security.provider.5=SunJCE
# ... other providers

# Add GlaSSLess
security.provider.13=net.glassless.provider.GlaSSLessProvider

Best Practices

Provider Priority Positioning

Position Use Case Recommendation
Low priority (e.g., 13) Explicit use only

Use getInstance("ALG", PROVIDER_NAME) to select
Mid priority (e.g., 5-6) Preferred for specific algorithms GlaSSLess used when JDK doesn't provide algorithm
High priority (e.g., 1-2) Default for all operations All crypto uses GlaSSLess unless unavailable

Recommended: Low Priority with Explicit Selection

For most applications, add GlaSSLess at low priority and explicitly request it when needed: 

# Add GlaSSLess at low priority
security.provider.13=net.glassless.provider.GlaSSLessProvider
// Explicitly request GlaSSLess for performance-critical operations
KeyPairGenerator kpg = KeyPairGenerator.getInstance("EC", PROVIDER_NAME);
Signature sig = Signature.getInstance("Ed25519", PROVIDER_NAME);

This approach:

  • Maintains JDK behavior by default

  • Allows selective use of GlaSSLess where beneficial

  • Avoids unexpected behavior changes

High Priority for OpenSSL-First Strategy

If you want all cryptographic operations to use OpenSSL by default: 

# Insert GlaSSLess at high priority
security.provider.1=net.glassless.provider.GlaSSLessProvider
security.provider.2=SUN
security.provider.3=SunRsaSign
# ... remaining providers renumbered
WARNING
 High priority positioning changes default behavior for all applications using this JVM. Test thoroughly before deploying.

Hybrid Mode Configuration

Hybrid mode allows GlaSSLess to delegate certain algorithms to the JDK provider for better performance. JDK's HotSpot intrinsics significantly outperform OpenSSL via FFM for some operations:

  • SHA-256/SHA-512 (small data <1KB): JDK is ~4-6x faster

  • HMAC-SHA256/SHA512 (small data <1KB): JDK is ~4-8x faster

  • SecureRandom (small buffers <64B): JDK is ~2x faster

  • ML-KEM operations: JDK is ~1.7-2.5x faster

To enable hybrid mode: 

# Enable hybrid mode (delegates selected algorithms to JDK)
glassless.hybrid.enabled=true

Or via system property: 

java -Dglassless.hybrid.enabled=true --enable-native-access=ALL-UNNAMED -jar your-app.jar
Default Delegated Algorithms

When hybrid mode is enabled, the following algorithms are delegated to the JDK provider:

Service Type Algorithms
MessageDigest SHA-256, SHA-512
Mac HmacSHA256, HmacSHA512
SecureRandom NativePRNG, DRBG
KEM ML-KEM, ML-KEM-512, ML-KEM-768, ML-KEM-1024
KeyPairGenerator ML-KEM, ML-KEM-512, ML-KEM-768, ML-KEM-1024
Custom Algorithm Lists

Override the default delegated algorithms per service type: 

# Custom algorithm lists (comma-separated)
glassless.hybrid.delegate.MessageDigest=SHA-256,SHA-512,SHA-384
glassless.hybrid.delegate.Mac=HmacSHA256,HmacSHA512,HmacSHA384
glassless.hybrid.delegate.SecureRandom=NativePRNG
glassless.hybrid.delegate.KEM=ML-KEM-768
glassless.hybrid.delegate.KeyPairGenerator=ML-KEM-768
Hybrid Mode and FIPS
IMPORTANT
 Hybrid mode is automatically disabled when FIPS mode is active. FIPS compliance requires using the FIPS-validated OpenSSL implementation for all cryptographic operations.

FIPS Mode Considerations

When OpenSSL is in FIPS mode, GlaSSLess automatically excludes non-approved algorithms. For FIPS-compliant deployments: 

# Place GlaSSLess at high priority to ensure FIPS-approved algorithms are used
security.provider.1=net.glassless.provider.GlaSSLessProvider
security.provider.2=SunJSSE
# ... other providers

TLS/SSL Configuration

For TLS connections to use GlaSSLess algorithms, ensure the provider is available before SunJSSE:

security.provider.1=net.glassless.provider.GlaSSLessProvider
security.provider.2=SunJSSE
# ... remaining providers

The JSSE implementation will automatically use GlaSSLess for underlying cryptographic operations.

Security Properties File Override

Instead of modifying the system java.security, create a custom properties file:

# custom-security.properties
security.provider.1=net.glassless.provider.GlaSSLessProvider
security.provider.2=SUN
# ... etc

Then specify it at runtime: 

java -Djava.security.properties=/path/to/custom-security.properties \
     --enable-native-access=ALL-UNNAMED \
     -jar your-app.jar

Module Path Configuration

When using the module path, ensure GlaSSLess is accessible: 

java --module-path /path/to/glassless-provider.jar \
     --add-modules net.glassless.provider \
     --enable-native-access=net.glassless.provider \
     -jar your-app.jar

Command-Line Tool

Display provider information: 

java --enable-native-access=ALL-UNNAMED -jar glassless-provider-{project-version}.jar

# Verbose mode (list all algorithms)
java --enable-native-access=ALL-UNNAMED -jar glassless-provider-{project-version}.jar --verbose