themis docs security security_eidas

eIDAS Qualified Electronic Signatures

Overview

ThemisDB implements eIDAS-compliant qualified electronic signatures (QES) by combining hardware-backed signing (HSM via PKCS#11) with cryptographic timestamps (RFC 3161 TSA). This provides legally binding signatures recognized across the EU.

What is eIDAS?

eIDAS (electronic IDentification, Authentication and trust Services) is the EU regulation (910/2014) establishing a framework for electronic signatures, seals, timestamps, and other trust services.

Qualified Electronic Signatures are the highest level of electronic signatures under eIDAS:

• Legally equivalent to handwritten signatures
• Require qualified certificates from QTSPs (Qualified Trust Service Providers)
• Must be created using hardware-backed Secure Signature Creation Devices (SSCD)
• Must include cryptographic timestamps to ensure long-term validity

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    ThemisDB PKI API                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌───────────────┐  ┌────────────────┐  ┌───────────────┐ │
│  │ HSMProvider   │  │ Timestamp      │  │ PkiApiHandler │ │
│  │ (PKCS#11)     │  │ Authority      │  │               │ │
│  │               │  │ (RFC 3161)     │  │ eIDAS Logic   │ │
│  └───────┬───────┘  └────────┬───────┘  └───────┬───────┘ │
│          │                   │                  │          │
└──────────┼───────────────────┼──────────────────┼──────────┘
           │                   │                  │
           ▼                   ▼                  ▼
  ┌─────────────────┐ ┌──────────────┐  ┌──────────────────┐
  │ Hardware HSM    │ │ FreeTSA /    │  │ HTTP REST API    │
  │ (SoftHSM2,      │ │ Enterprise   │  │                  │
  │  Luna, CloudHSM)│ │ TSA Server   │  │ /api/pki/eidas/* │
  └─────────────────┘ └──────────────┘  └──────────────────┘

Components

1. HSMProvider (PKCS#11)

Provides hardware-backed signing using industry-standard PKCS#11 interface:

Supported HSMs:

• SoftHSM2 (Development/Testing)
• Thales Luna (Production)
• AWS CloudHSM (Cloud Production)
• Utimaco SecurityServer (Production)
• YubiHSM 2 (Small deployments)

Key Features:

• Private keys never leave HSM
• FIPS 140-2 Level 2/3 compliance
• Multi-user PIN/passphrase protection
• Audit logging
• Key backup/recovery

See: HSM Integration Guide

2. TimestampAuthority (RFC 3161)

Provides cryptographic timestamps:

Supported TSA Services:

• FreeTSA (Free, public service)
• Enterprise TSA (e.g., Sectigo, DigiCert)
• Self-hosted TSA (OpenSSL based)

Key Features:

• SHA-256/384/512 hash algorithms
• Nonce generation for replay protection
• Certificate validation
• eIDAS timestamp validation
• Long-term timestamp verification

Timestamp Token Structure (ASN.1):

TimeStampToken ::= ContentInfo
  -- contentType is id-signedData
  -- content is SignedData containing TSTInfo

TSTInfo ::= SEQUENCE {
  version                 INTEGER,
  policy                  TSAPolicyId,
  messageImprint          MessageImprint,
  serialNumber            INTEGER,
  genTime                 GeneralizedTime,
  accuracy                Accuracy OPTIONAL,
  ordering                BOOLEAN DEFAULT FALSE,
  nonce                   INTEGER OPTIONAL,
  tsa                     GeneralName OPTIONAL,
  extensions              Extensions OPTIONAL
}

3. PkiApiHandler

Orchestrates eIDAS qualified signature workflows:

Endpoints:

• POST /api/pki/eidas/sign - Create qualified signature
• POST /api/pki/eidas/verify - Verify qualified signature
• POST /api/pki/hsm/sign - Direct HSM signing
• GET /api/pki/hsm/keys - List HSM keys
• POST /api/pki/timestamp - Get timestamp token
• POST /api/pki/timestamp/verify - Verify timestamp
• GET /api/pki/certificates - List certificates
• GET /api/pki/certificates/:id - Get certificate details
• GET /api/pki/status - Health check

API Usage

1. Create eIDAS Qualified Signature

Request:

curl -X POST http://localhost:8080/api/pki/eidas/sign \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "data_b64": "SGVsbG8sIFdvcmxkIQ=="
  }'

Response:

{
  "qualified_signature": {
    "signature_b64": "MEUCIQDx...",
    "algorithm": "ECDSA-SHA256",
    "key_id": "hsm-key-001",
    "cert_serial": "1A2B3C4D5E",
    "timestamp_token_b64": "MIIDfQYJKoZI...",
    "timestamp_utc": "2025-06-15T10:30:45Z",
    "format": "eIDAS-QES",
    "version": "1.0"
  },
  "timestamped": true
}

2. Verify eIDAS Qualified Signature

Request:

curl -X POST http://localhost:8080/api/pki/eidas/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "data_b64": "SGVsbG8sIFdvcmxkIQ==",
    "qualified_signature": {
      "signature_b64": "MEUCIQDx...",
      "algorithm": "ECDSA-SHA256",
      "timestamp_token_b64": "MIIDfQYJKoZI...",
      "format": "eIDAS-QES"
    }
  }'

Response:

{
  "valid": true,
  "signature_valid": true,
  "timestamp_valid": true,
  "format": "eIDAS-QES",
  "algorithm": "ECDSA-SHA256",
  "timestamp_utc": "2025-06-15T10:30:45Z"
}

3. Direct HSM Signing (Lower Level)

Request:

curl -X POST http://localhost:8080/api/pki/hsm/sign \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "data_b64": "SGVsbG8sIFdvcmxkIQ=="
  }'

Response:

{
  "signature_b64": "MEUCIQDx...",
  "algorithm": "ECDSA-SHA256",
  "key_id": "hsm-key-001",
  "cert_serial": "1A2B3C4D5E"
}

4. Get Cryptographic Timestamp

Request:

curl -X POST http://localhost:8080/api/pki/timestamp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "data_b64": "SGVsbG8sIFdvcmxkIQ=="
  }'

Response:

{
  "timestamp_token_b64": "MIIDfQYJKoZI...",
  "timestamp_utc": "2025-06-15T10:30:45Z",
  "serial_number": "1234567890"
}

5. List HSM Keys

Request:

curl -X GET http://localhost:8080/api/pki/hsm/keys \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "keys": [
    {
      "id": "hsm-key-001",
      "label": "production-signing-key",
      "type": "EC",
      "curve": "secp256r1",
      "certificate_serial": "1A2B3C4D5E"
    }
  ]
}

6. Check PKI System Status

Request:

curl -X GET http://localhost:8080/api/pki/status \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "signing_service": "available",
  "hsm": "available",
  "tsa": "available",
  "hsm_keys_count": 3,
  "hsm_status": "connected",
  "tsa_status": "configured",
  "overall": "healthy"
}

Configuration

Environment Variables

# HSM Configuration
export THEMIS_HSM_LIBRARY="/usr/lib/softhsm/libsofthsm2.so"
export THEMIS_HSM_SLOT="0"
export THEMIS_HSM_PIN="1234"
export THEMIS_HSM_KEY_LABEL="production-key"
export THEMIS_HSM_ALGORITHM="ECDSA-SHA256"

# TSA Configuration
export THEMIS_TSA_URL="https://freetsa.org/tsr"
export THEMIS_TSA_HASH_ALGORITHM="SHA256"
export THEMIS_TSA_CERT_REQ="true"
export THEMIS_TSA_TIMEOUT_SECONDS="30"

C++ API Configuration

#include "server/pki_api_handler.h"
#include "security/hsm_provider.h"
#include "security/timestamp_authority.h"
#include "security/signing.h"

// Configure HSM
security::HSMConfig hsm_config;
hsm_config.library_path = "/usr/lib/softhsm/libsofthsm2.so";
hsm_config.slot_id = 0;
hsm_config.pin = "1234";
hsm_config.key_label = "production-key";
hsm_config.signature_algorithm = "ECDSA-SHA256";

auto hsm_provider = std::make_shared<security::HSMProvider>(hsm_config);
hsm_provider->initialize();

// Configure TSA
security::TSAConfig tsa_config;
tsa_config.url = "https://freetsa.org/tsr";
tsa_config.hash_algorithm = "SHA256";
tsa_config.cert_req = true;
tsa_config.timeout_seconds = 30;

auto tsa = std::make_shared<security::TimestampAuthority>(tsa_config);

// Create signing service
auto signing_service = std::make_shared<SigningService>();

// Create PKI API Handler with all components
auto pki_handler = std::make_shared<server::PkiApiHandler>(
    signing_service,
    hsm_provider,
    tsa
);

eIDAS Compliance Requirements

For Qualified Electronic Signatures (QES)

To meet eIDAS requirements, you need:

1. Qualified Trust Service Provider (QTSP)

• Obtain qualified certificates from an eIDAS-accredited QTSP
• Examples: D-Trust, SwissSign, DigiCert (EU operations)
• Certificate must be marked as "qualified" in X.509 extensions

2. Secure Signature Creation Device (SSCD)

• Use hardware HSM meeting Common Criteria EAL 4+ or FIPS 140-2 Level 3
• Examples: Thales Luna, Utimaco SecurityServer, AWS CloudHSM
• Private keys must be generated and stored in HSM (never exported)

3. Qualified Timestamp

• Use timestamp authority recognized under eIDAS
• Timestamp must use qualified certificates
• Required for long-term signature validity (Art. 32 eIDAS)

4. Certificate Chain Validation

• Implement full X.509 chain validation
• Check CRL/OCSP revocation status
• Validate against EU Trusted List (EUTL)

5. Long-Term Validation (LTV)

• Archive signature data including:
  • Original document
  • Qualified signature
  • Certificate chain
  • Timestamp tokens
  • Revocation information (CRL/OCSP responses)
• Maintain archives for legal retention periods (typically 10-30 years)

eIDAS Signature Formats

ThemisDB currently implements CAdES-like qualified signatures:

Components:

{
  "signature_b64": "...",           // Digital signature (PKCS#1 or ECDSA)
  "algorithm": "ECDSA-SHA256",       // Signature algorithm
  "key_id": "hsm-key-001",           // HSM key identifier
  "cert_serial": "1A2B3C4D5E",       // Certificate serial number
  "timestamp_token_b64": "...",      // RFC 3161 timestamp token
  "timestamp_utc": "2025-06-15...",  // Human-readable timestamp
  "format": "eIDAS-QES",             // Format identifier
  "version": "1.0"                   // Schema version
}

Future Enhancements:

• Full CAdES-BES, CAdES-T, CAdES-X, CAdES-A support
• XAdES (XML Advanced Electronic Signatures)
• PAdES (PDF Advanced Electronic Signatures)
• Integration with EU Trusted Lists

Production Deployment

1. Hardware HSM Setup

Thales Luna Example:

# Initialize Luna HSM
lunacm
> slot set -slot 0
> partition init -label "production"
> partition changePw -oldpw default -newpw <strong-password>

# Generate qualified key pair
cmu generatekeypair -modulusBits=2048 \
    -keyType=RSA \
    -sign=1 \
    -verify=1 \
    -label="production-signing-key"

# Configure ThemisDB
export THEMIS_HSM_LIBRARY="/usr/safenet/lunaclient/lib/libCryptoki2_64.so"
export THEMIS_HSM_SLOT="0"
export THEMIS_HSM_PIN="<strong-password>"
export THEMIS_HSM_KEY_LABEL="production-signing-key"

2. Enterprise TSA Configuration

DigiCert TSA Example:

export THEMIS_TSA_URL="https://timestamp.digicert.com"
export THEMIS_TSA_HASH_ALGORITHM="SHA256"
export THEMIS_TSA_CERT_REQ="true"
export THEMIS_TSA_TIMEOUT_SECONDS="30"

3. Certificate Management

Obtain Qualified Certificate from QTSP:

# Generate CSR (Certificate Signing Request) in HSM
pkcs11-tool --module /usr/lib/libCryptoki2_64.so \
    --slot 0 \
    --login \
    --pin <hsm-pin> \
    --keypairgen \
    --key-type RSA:2048 \
    --label production-key \
    --id 01

# Export public key for CSR
pkcs11-tool --module /usr/lib/libCryptoki2_64.so \
    --slot 0 \
    --read-object \
    --type pubkey \
    --id 01 \
    -o public.der

# Create CSR with OpenSSL
openssl req -new -engine pkcs11 \
    -keyform engine \
    -key slot_0-id_01 \
    -out request.csr \
    -subj "/C=DE/O=YourOrg/CN=production.example.com"

# Submit CSR to QTSP and import signed certificate

4. Security Hardening

HSM Security:

• Use strong PINs/passphrases (min 16 characters)
• Enable multi-factor authentication (MFA) for HSM access
• Implement M-of-N key ceremony for critical keys
• Regular HSM firmware updates
• Physical security controls for HSM hardware

Network Security:

• TLS 1.3 for all API communications
• Mutual TLS (mTLS) for production deployments
• HSM network segmentation (separate VLAN)
• Firewall rules restricting HSM access

Operational Security:

• Implement audit logging for all signing operations
• Monitor HSM health and capacity
• Backup HSM keys using secure key wrapping
• Test disaster recovery procedures
• Regular security audits

Performance Considerations

Typical Latencies

• HSM Signing: 10-50ms (depends on HSM model)
• TSA Timestamp: 100-500ms (network latency)
• Total eIDAS Sign: 150-600ms
• Verification: 50-200ms

Optimization Strategies

1. HSM Connection Pooling:

// Reuse HSM sessions
hsm_provider->initialize();  // Once at startup
// Multiple sign operations reuse the same session

2. Timestamp Batching:

// For high-volume scenarios, batch timestamp requests
std::vector<std::vector<uint8_t>> signatures;
// ... collect signatures ...
auto batch_timestamp = tsa->batchGetTimestamps(signatures);

3. Async Processing:

// Offload timestamp requests to background thread
std::future<TimestampToken> ts_future = std::async(
    std::launch::async,
    [&tsa, signature]() { return tsa->getTimestamp(signature); }
);

Troubleshooting

HSM Issues

Problem: HSM_CKR_PIN_INCORRECT

# Check PIN
softhsm2-util --show-slots

# Reset PIN (SoftHSM2)
softhsm2-util --init-token \
    --slot 0 \
    --label "test-token" \
    --so-pin 1234 \
    --pin 5678

Problem: HSM_CKR_SESSION_HANDLE_INVALID

// Reinitialize HSM connection
hsm_provider->initialize();

TSA Issues

Problem: Timestamp request timeout

# Test TSA connectivity
curl -I https://freetsa.org/tsr
# Increase timeout
export THEMIS_TSA_TIMEOUT_SECONDS="60"

Problem: Invalid timestamp token

# Verify TSA certificate chain
openssl ts -verify \
    -in timestamp.tsr \
    -data data.bin \
    -CAfile tsa-ca-chain.pem

Testing

Unit Tests

# Build tests
cd /workspaces/ThemisDB/build
cmake --build . --target test_hsm_provider
cmake --build . --target test_timestamp_authority
cmake --build . --target test_pki_api_handler

# Run tests
./test_hsm_provider
./test_timestamp_authority
./test_pki_api_handler

Integration Tests

# Test eIDAS signature workflow
curl -X POST http://localhost:8080/api/pki/eidas/sign \
  -H "Content-Type: application/json" \
  -d '{"data_b64": "VGVzdCBEYXRh"}' \
  | jq . > signature.json

curl -X POST http://localhost:8080/api/pki/eidas/verify \
  -H "Content-Type: application/json" \
  -d "{\"data_b64\": \"VGVzdCBEYXRh\", \"qualified_signature\": $(cat signature.json | jq .qualified_signature)}" \
  | jq .

Legal Considerations

Disclaimer: This documentation provides technical implementation guidance. Legal compliance requires consultation with qualified legal counsel and accredited trust service providers.

Key Legal Requirements:

• Obtain qualified certificates from eIDAS-accredited QTSPs
• Use certified SSCD (hardware HSM)
• Implement certificate chain validation
• Archive signatures with long-term validation data
• Comply with GDPR for signature metadata
• Meet industry-specific regulations (e.g., eIDAS Art. 25 for healthcare)

Liability: The signature creator is responsible for:

• Protecting HSM credentials
• Verifying signer identity
• Ensuring consent to sign
• Proper key lifecycle management

References

Standards

• eIDAS Regulation: EU 910/2014
• ETSI EN 319 102-1: Electronic Signatures and Infrastructures (ESI); Procedures for Creation and Validation of AdES Digital Signatures
• ETSI EN 319 122-1: CAdES (CMS Advanced Electronic Signatures)
• RFC 3161: Time-Stamp Protocol (TSP)
• RFC 5652: Cryptographic Message Syntax (CMS)
• FIPS 140-2: Security Requirements for Cryptographic Modules

Resources

• EU Trusted Lists: https://eidas.ec.europa.eu/efda/tl-browser/
• FreeTSA: https://freetsa.org/
• OASIS DSS: https://www.oasis-open.org/committees/dss/
• ThemisDB HSM Integration: hsm_integration.md

QTSPs (Qualified Trust Service Providers)

• D-Trust (Germany): https://www.d-trust.net/
• SwissSign (Switzerland): https://www.swisssign.com/
• Agencia de Tecnología y Certificación Electrónica (Spain): https://www.sede.fnmt.gob.es/
• Actalis (Italy): https://www.actalis.com/

Support

For technical questions or implementation support:

• GitHub Issues: https://github.com/yourusername/ThemisDB/issues
• Email: [email protected]
• Documentation: https://docs.themisdb.example.com

---

ThemisDB PKI/eIDAS Implementation
Version 1.0 - June 2025