====== 3.4 Troubleshooting ======

Troubleshooting for common issues with the PQ cryptography infrastructure.

----

===== Quick Diagnostics =====

Run these commands to check system status:

<code bash>
# 1. OpenSSL version
openssl version
# Expected: OpenSSL 3.6.0 or higher

# 2. PQ algorithms available?
openssl list -signature-algorithms | grep -i "ml-dsa"
openssl list -kem-algorithms | grep -i "ml-kem"

# 3. Provider active?
openssl list -providers

# 4. .NET Runtime
dotnet --list-runtimes | grep "NETCore.App 8"
</code>

----

===== OpenSSL Errors =====

==== libcrypto not found ====

**Symptom:**
<code>
Unable to load DLL 'libcrypto-3-x64.dll'
</code>

**Diagnosis:**
<code bash>
# Windows - search for DLL
where libcrypto-3-x64.dll

# Linux - search for shared library
ldconfig -p | grep libcrypto

# macOS - search for dylib
ls /usr/local/lib/libcrypto*
</code>

**Solution Windows (PowerShell as Administrator):**
<code powershell>
# Check PATH
$env:PATH -split ";" | Select-String "OpenSSL"

# Extend PATH (if not present)
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files\OpenSSL\bin", "Machine")

# Or set OPENSSL_PATH
[Environment]::SetEnvironmentVariable("OPENSSL_PATH", "C:\Program Files\OpenSSL\bin", "Machine")
</code>

**Solution Linux:**
<code bash>
# Update ldconfig
echo "/usr/local/openssl/lib64" | sudo tee /etc/ld.so.conf.d/openssl.conf
sudo ldconfig

# Verify
ldconfig -p | grep libcrypto
</code>

----

==== OpenSSL version too old ====

**Symptom:**
<code>
OpenSSL version 3.6.0+ required for ML-DSA
</code>

**Diagnosis:**
<code bash>
# Full version and build info
openssl version -a

# Find installed versions (Linux)
find /usr -name "openssl" -type f 2>/dev/null

# Find installed versions (Windows)
where /r C:\ openssl.exe 2>nul
</code>

**Solution:**
Upgrade to OpenSSL 3.6.0+ → [[.:installation|Installation]]

----

==== PQ algorithms not available ====

**Symptom:**
<code bash>
openssl list -signature-algorithms | grep -i "ml-dsa"
# No output
</code>

**Diagnosis:**
<code bash>
# Check provider status
openssl list -providers

# All available signature algorithms
openssl list -signature-algorithms

# All available KEM algorithms
openssl list -kem-algorithms
</code>

**Possible causes:**
  * OpenSSL < 3.6.0 (ML-DSA/ML-KEM only from 3.6)
  * Provider not loaded
  * Custom build without PQ support

----

===== Certificate Errors =====

==== Display certificate details ====

<code bash>
# Analyze certificate in PEM format
openssl x509 -in cert.pem -text -noout

# Check signature algorithm
openssl x509 -in cert.pem -text -noout | grep "Signature Algorithm"

# Expected for PQ certificates:
# Signature Algorithm: ML-DSA-65 or ML-DSA-87

# Public key details
openssl x509 -in cert.pem -pubkey -noout | openssl pkey -pubin -text -noout
</code>

==== Verify certificate chain ====

<code bash>
# Simple verification
openssl verify -CAfile root-ca.crt -untrusted intermediate.crt server.crt

# Verbose with error details
openssl verify -verbose -CAfile root-ca.crt -untrusted intermediate.crt server.crt

# Expected output on success:
# server.crt: OK
</code>

**Common verification errors:**

^  Error  ^  Meaning  ^  Solution  ^
| ''unable to get local issuer certificate'' | CA certificate missing | Add Root/Intermediate CA |
| ''certificate has expired'' | Certificate expired | Renew certificate |
| ''certificate signature failure'' | Signature invalid | Certificate corrupted/tampered |
| ''self signed certificate in chain'' | Self-signed not trusted | Add Root CA to trust store |

----

===== Key Store Errors =====

==== PQ key not found ====

**Symptom:**
<code>
PQ private key not found for certificate thumbprint: ABC123...
</code>

**Diagnosis:**

**Windows (PowerShell):**
<code powershell>
# PQ key store path
$pqKeyStore = "$env:LOCALAPPDATA\WvdS.Crypto\PqKeys"

# Check existence
Test-Path $pqKeyStore

# List contents
Get-ChildItem $pqKeyStore -ErrorAction SilentlyContinue

# Check permissions
Get-Acl $pqKeyStore | Format-List
</code>

**Linux:**
<code bash>
# PQ key store path
PQ_KEYSTORE=~/.local/share/wvds-crypto/pqkeys

# Check existence
ls -la $PQ_KEYSTORE

# Check permissions (should be 700)
stat $PQ_KEYSTORE
</code>

**Solution:**
  - Restore from backup
  - If no backup: Re-create certificate with new key pair

----

===== FIPS Mode Errors =====

==== FIPS Provider not active ====

**Diagnosis:**
<code bash>
# List providers
openssl list -providers

# Should contain:
#   fips
#     name: OpenSSL FIPS Provider
#     status: active
</code>

**Solution:**
Enable FIPS Provider in ''openssl.cnf'' → [[.:konfiguration#fips-modus_openssl|FIPS Configuration]]

----

==== Algorithm not FIPS-compliant ====

**Symptom:**
<code>
error:0308010C:digital envelope routines::unsupported
</code>

**Cause:** Algorithm not permitted in FIPS mode.

**FIPS 140-3 approved algorithms:**

^  Type  ^  Approved  ^  Not Approved  ^
| Signature | ML-DSA-44/65/87, RSA >=2048, ECDSA | Ed25519, Ed448 |
| KEM | ML-KEM-512/768/1024 | X25519, X448 |
| Hash | SHA-256, SHA-384, SHA-512 | MD5, SHA-1 |
| Cipher | AES-GCM | ChaCha20 |

----

===== Network Diagnostics =====

==== Test TLS connection ====

<code bash>
# TLS handshake and certificate check
openssl s_client -connect server.example.com:443 -showcerts

# With specific CA bundle
openssl s_client -connect server.example.com:443 -CAfile /path/to/ca-bundle.crt

# Force TLS 1.3
openssl s_client -connect server.example.com:443 -tls1_3
</code>

==== Retrieve certificate from server ====

<code bash>
# Download and save certificate
openssl s_client -connect server.example.com:443 < /dev/null 2>/dev/null | \
    openssl x509 -outform PEM > server.crt

# Analyze certificate
openssl x509 -in server.crt -text -noout
</code>

----

===== Log Analysis =====

==== OpenSSL error codes ====

<code bash>
# Look up error code
openssl errstr 0308010C

# Show all recent errors (if in debug mode)
openssl errstr
</code>

==== Check Windows Event Log ====

<code powershell>
# Cryptography-related events
Get-EventLog -LogName Application -Source "*Crypto*" -Newest 20

# .NET Runtime errors
Get-EventLog -LogName Application -Source ".NET Runtime" -Newest 10 -EntryType Error
</code>

==== Check Linux Syslog ====

<code bash>
# OpenSSL-related entries
journalctl | grep -i openssl | tail -20

# .NET Runtime errors
journalctl | grep -i dotnet | tail -20
</code>

----

===== Further Reading =====

  * [[.:installation|Installation]] – Correct setup
  * [[.:konfiguration|Configuration]] – FIPS mode, paths
  * [[.:betrieb|Operations]] – Health checks, certificates

----
//Wolfgang van der Stille @ EMSR DATA d.o.o. - Post-Quantum Cryptography Professional//

{{tag>troubleshooting errors diagnostics openssl}}