Installation Issues
Symptoms
openssl list -providers does not show the Qudo provider. PQC algorithms are unavailable.
Root Cause
The provider binary is not in the correct ossl-modules directory, or the architecture (x86_64 vs arm64) does not match your system.
Resolution
# 1. Find the correct modules directory openssl version -m # Look for MODULESDIR # 2. Verify architecture matches file /path/to/qudofipsprovider.so uname -m # 3. Copy to the correct location sudo cp qudofipsprovider.so $(openssl version -m | grep -o '"[^"]*"' | tr -d '"')/
Validation
openssl list -providers | grep -i qudo
Symptoms
Error: error loading shared library or cannot open shared object file when OpenSSL tries to load the provider.
Root Cause
The provider depends on OpenSSL 3.x's libcrypto, which is either not installed or not in the library path.
Resolution
# Check dependencies (Linux) ldd /usr/lib/ossl-modules/qudofipsprovider.so # Check dependencies (macOS) otool -L /opt/homebrew/lib/ossl-modules/qudofipsprovider.dylib # Install OpenSSL 3.x if missing # Ubuntu/Debian: sudo apt install libssl3 openssl # RHEL/Fedora: sudo dnf install openssl openssl-libs # macOS: brew install openssl@3
Validation
openssl version # Should show 3.x openssl list -providers
Symptoms
Permission denied when copying the provider to ossl-modules or when OpenSSL tries to load it.
Root Cause
The modules directory is owned by root, or the provider file has incorrect permissions.
Resolution
# Copy with sudo sudo cp qudofipsprovider.so /usr/lib/ossl-modules/ # Set correct permissions (readable by all, writable by owner) sudo chmod 644 /usr/lib/ossl-modules/qudofipsprovider.so # Verify ls -la /usr/lib/ossl-modules/qudofipsprovider.so # Should show: -rw-r--r--
Validation
openssl list -providers
Symptoms
Provider fails to load silently, or openssl version shows 1.x or LibreSSL.
Root Cause
The Qudo provider requires OpenSSL 3.0 or later. Older versions (1.1.x) and LibreSSL do not support the provider API.
Resolution
# Check current version openssl version # Upgrade on Ubuntu/Debian (22.04+) sudo apt update && sudo apt install openssl libssl3 # Upgrade on RHEL 9 / Fedora sudo dnf install openssl # macOS (system ships LibreSSL, use Homebrew) brew install openssl@3 echo 'export PATH="/opt/homebrew/opt/openssl@3/bin:$PATH"' >> ~/.zshrc source ~/.zshrc
Validation
openssl version # Must show: OpenSSL 3.x.x
Configuration Issues
Symptoms
You edited openssl.cnf but openssl list -providers still doesn't show the Qudo provider.
Root Cause
OpenSSL is reading a different config file than the one you edited, or OPENSSL_CONF is overriding the default path.
Resolution
# Find which config file OpenSSL is actually using openssl version -d # Shows: OPENSSLDIR: "/path/to/ssl" # Config is at: /path/to/ssl/openssl.cnf # Override explicitly export OPENSSL_CONF=/path/to/your/openssl.cnf openssl list -providers # Or set permanently echo 'export OPENSSL_CONF=/etc/ssl/openssl.cnf' >> ~/.bashrc
Validation
OPENSSL_CONF=/your/path/openssl.cnf openssl list -providers
Symptoms
Error: Provider module not found or provider listed but not activated.
Root Cause
The module = path in openssl.cnf does not match the actual file location.
Resolution
# Find the actual provider location find / -name "qudofipsprovider*" 2>/dev/null # Update openssl.cnf with the correct path # [qudo_sect] # activate = 1 # module = /actual/path/to/qudofipsprovider.so # Alternative: set OPENSSL_MODULES environment variable export OPENSSL_MODULES=/path/to/directory/containing/provider/
Validation
openssl list -providers -verbose
Symptoms
Provider works from CLI but not from your application (Java, Python, Node.js, etc.).
Root Cause
Your application's environment does not inherit shell environment variables like OPENSSL_MODULES or OPENSSL_CONF.
Resolution
# Set for the current session export OPENSSL_MODULES=/usr/lib/ossl-modules export OPENSSL_CONF=/etc/ssl/openssl.cnf # For Java applications java -Djava.library.path=/usr/lib/ossl-modules -jar your-app.jar # For systemd services, add to unit file: # [Service] # Environment="OPENSSL_MODULES=/usr/lib/ossl-modules" # Environment="OPENSSL_CONF=/etc/ssl/openssl.cnf" # For Docker containers # ENV OPENSSL_MODULES=/usr/lib/ossl-modules # ENV OPENSSL_CONF=/etc/ssl/openssl.cnf
Validation
echo $OPENSSL_MODULES echo $OPENSSL_CONF openssl list -providers
Runtime Issues
Symptoms
SSL_ERROR_HANDSHAKE_FAILURE or no shared group when connecting to a PQC-enabled server.
Root Cause
Client or server does not have X25519MLKEM768 configured in the supported groups, or the Qudo provider is not loaded on one side.
Resolution
# Test TLS with PQC groups explicitly openssl s_client -connect localhost:443 \ -groups X25519MLKEM768:X25519:P-384 # Check server configuration (NGINX) # ssl_ecdh_curves X25519MLKEM768:X25519:P-384; # Check if provider is loaded on the server openssl list -providers # Run on server # Fallback: add classical groups for compatibility # ssl_ecdh_curves X25519MLKEM768:X25519:P-384:P-256;
Validation
openssl s_client -connect localhost:443 -groups X25519MLKEM768 2>&1 | grep "Server Temp Key" # Should show: X25519MLKEM768
Symptoms
unsupported algorithm or unable to verify signature when verifying ML-DSA signed certificates.
Root Cause
The verifying system does not have the Qudo provider loaded, so it doesn't recognize ML-DSA signatures.
Resolution
# Ensure Qudo provider is loaded on the verifying system openssl list -providers # Verify certificate with provider openssl verify -CAfile ca-chain.crt server.crt # Inspect certificate to see signing algorithm openssl x509 -in server.crt -text -noout | grep "Signature Algorithm"
Validation
openssl verify -CAfile ca-chain.crt server.crt # Expected: server.crt: OK
Symptoms
First PQC operation takes noticeably longer than subsequent ones. Application startup is slower with the provider loaded.
Root Cause
Provider initialization includes self-tests (FIPS requirement). This is a one-time cost per process startup.
Resolution
# This is expected behavior for FIPS providers. # The first operation includes provider self-test overhead. # Subsequent operations run at full speed. # Benchmark to confirm steady-state performance: # Use the PQC benchmark tool at /benchmark # Or run manually: openssl speed -seconds 3 -provider qudo mldsa65
Validation
Use the PQC Benchmark tool to measure steady-state performance on your hardware.
Debugging Help
When to Use
When provider loading fails silently or TLS connections fail without clear error messages.
Commands
# Enable trace output for provider loading OSSL_TRACE=PROVIDER openssl list -providers 2>&1 # Enable trace for TLS connections OSSL_TRACE=TLS openssl s_client -connect localhost:443 2>&1 # Full debug output for s_client openssl s_client -connect localhost:443 -debug -msg # Trace multiple categories OSSL_TRACE=PROVIDER,TLS,INIT openssl list -providers 2>&1
Commands
# List all loaded providers with details openssl list -providers -verbose # List all available signature algorithms openssl list -signature-algorithms # List all available KEM algorithms openssl list -kem-algorithms # List all public key algorithms openssl list -public-key-algorithms # Filter for PQC algorithms only openssl list -signature-algorithms | grep -E "ML-DSA|SLH-DSA" openssl list -kem-algorithms | grep -E "ML-KEM"
When to Use
When filing a support ticket or requesting help. Include this output for faster resolution.
Commands
# Collect all diagnostic info echo "=== System ===" uname -a echo "=== OpenSSL Version ===" openssl version -a echo "=== OpenSSL Config ===" openssl version -d echo "=== Providers ===" openssl list -providers -verbose echo "=== PQC Signature Algorithms ===" openssl list -signature-algorithms | grep -E "ML-DSA|SLH-DSA" echo "=== PQC KEM Algorithms ===" openssl list -kem-algorithms | grep -E "ML-KEM" echo "=== Provider Binary ===" ls -la /usr/lib/ossl-modules/qudofips* 2>/dev/null ls -la /opt/homebrew/lib/ossl-modules/qudofips* 2>/dev/null echo "=== Environment ===" echo "OPENSSL_CONF=$OPENSSL_CONF" echo "OPENSSL_MODULES=$OPENSSL_MODULES"
Send this output to support@zenv.ai along with a description of your issue.