Cryptography
Detailed explanation of cryptographic operations, key management, and security measures in the fourbics Client.
This document provides a comprehensive overview of the cryptographic operations implemented in the fourbics Client, including key generation, signing, encryption, and security measures.
Key Types
EBICS requires three distinct RSA key pairs per user:
┌──────────────────────────────────────────────────────────────────────────────┐
│ EBICS KEY TYPES │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ SIGNATURE KEY (A005/A006) │ │
│ │ ───────────────────────── │ │
│ │ Purpose: Authorizes order data (Electronic Signature / EU) │ │
│ │ Algorithm: RSA with SHA-256 │ │
│ │ Padding: PKCS#1 v1.5 (A005) or RSASSA-PSS (A006) │ │
│ │ Used for: Signing payment files, statements, etc. │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ AUTHENTICATION KEY (X002) │ │
│ │ ──────────────────────── │ │
│ │ Purpose: Authenticates EBICS messages (XML-DSig) │ │
│ │ Algorithm: RSA with SHA-256 │ │
│ │ Padding: PKCS#1 v1.5 │ │
│ │ Used for: Signing request headers, proving identity │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ ENCRYPTION KEY (E002) │ │
│ │ ───────────────────── │ │
│ │ Purpose: Key transport (encrypts/decrypts AES keys) │ │
│ │ Algorithm: RSA PKCS#1 v1.5 │ │
│ │ Used for: Encrypting transaction keys for secure data exchange │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Key Generation
RSA Key Parameters
| Parameter | Value | Notes |
|---|---|---|
| Key Size | 2048-4096 bits | Minimum 2048 per EBICS spec |
| Default | 2048 bits | Configurable |
| Algorithm | RSA | OpenSSL implementation |
| Format | PEM | Standard format for storage |
Generation Process
┌──────────────────────────────────────────────────────────────────────────────┐
│ KEY GENERATION PROCESS │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. GENERATE RSA KEY PAIR │
│ • Create RSA key with specified bit length (2048-4096) │
│ • Extract public and private key components │
│ │
│ 2. EXTRACT COMPONENTS │
│ • Public key (PEM format) │
│ • Private key (PEM format) │
│ • Modulus (n) - Base64 encoded for EBICS transmission │
│ • Exponent (e) - Base64 encoded for EBICS transmission │
│ │
│ 3. CALCULATE PUBLIC KEY HASH │
│ • Format: SHA-256(exponent_hex + " " + modulus_hex) │
│ • Result: Base64 encoded hash for verification │
│ │
│ 4. ENCRYPT PRIVATE KEY │
│ • Private key encrypted at rest using AES-256-GCM │
│ • Never stored in plaintext │
│ │
│ 5. STORE SECURELY │
│ • Public key: Stored in plaintext (safe to expose) │
│ • Private key: Encrypted storage only │
│ • Hash: For verification during initialization │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Signature Algorithms
A005 - PKCS#1 v1.5 (Legacy)
Used with H003/H004 protocol versions:
┌──────────────────────────────────────────────────────────────────────────────┐
│ A005 SIGNATURE (PKCS#1 v1.5) │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Input: Order Data (compressed) │
│ │
│ Step 1: Hash │
│ digest = SHA-256(compressed_order_data) │
│ │
│ Step 2: Sign │
│ signature = RSA_PKCS1_Sign(digest, private_key) │
│ Uses PKCS#1 v1.5 padding (deterministic) │
│ │
│ Output: signature (binary), digest (binary) │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
A006 - RSASSA-PSS (Recommended)
Used with H005/H006 protocol versions:
┌──────────────────────────────────────────────────────────────────────────────┐
│ A006 SIGNATURE (RSASSA-PSS) │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Input: Order Data (compressed) │
│ │
│ Step 1: Hash │
│ digest = SHA-256(compressed_order_data) │
│ │
│ Step 2: Sign with PSS Padding │
│ signature = RSA_PSS_Sign(digest, private_key) │
│ │
│ PSS Parameters: │
│ • Hash: SHA-256 │
│ • MGF Hash: SHA-256 │
│ • Salt Length: 32 bytes (equals hash length) │
│ │
│ Output: signature (binary), digest (binary) │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Why A006 is Preferred
| Aspect | A005 (PKCS#1 v1.5) | A006 (RSASSA-PSS) |
|---|---|---|
| Security | Vulnerable to certain attacks | Provably secure |
| Padding | Deterministic | Randomized (salt) |
| Standard | Legacy | Modern (PKCS#1 v2.1) |
| Recommendation | Backwards compatibility | New implementations |
Authentication Signature (X002)
XML-DSig signature for message authentication:
┌──────────────────────────────────────────────────────────────────────────────┐
│ AUTHENTICATION SIGNATURE (X002) │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. SELECT AUTHENTICATED ELEMENTS │
│ XPath: //*[@authenticate='true'] │
│ Includes: header, DataEncryptionInfo, SignatureData, ReturnCode │
│ │
│ 2. CANONICALIZE (C14N) │
│ Algorithm: http://www.w3.org/TR/2001/REC-xml-c14n-20010315 │
│ • Remove XML declaration │
│ • Normalize whitespace │
│ • Sort attributes alphabetically │
│ • Normalize namespace declarations │
│ │
│ 3. HASH (SHA-256) │
│ digest = SHA-256(canonicalized_xml) │
│ DigestValue = Base64(digest) │
│ │
│ 4. BUILD SignedInfo │
│ Contains CanonicalizationMethod, SignatureMethod, Reference │
│ │
│ 5. SIGN SignedInfo │
│ canonicalized_signed_info = C14N(SignedInfo) │
│ signature = RSA-SHA256(canonicalized_signed_info, auth_key) │
│ SignatureValue = Base64(signature) │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Encryption (E002)
EBICS uses hybrid encryption: symmetric encryption for data, asymmetric for key transport.
┌──────────────────────────────────────────────────────────────────────────────┐
│ E002 HYBRID ENCRYPTION │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ENCRYPTION (Client → Bank) │
│ ───────────────────────── │
│ │
│ 1. Generate Transaction Key │
│ • Random 128-bit key for AES-128 │
│ │
│ 2. Encrypt Order Data (AES-128-CBC) │
│ • IV: Zero IV per EBICS specification │
│ • Padding: PKCS#7 │
│ • Result: Encrypted order data │
│ │
│ 3. Encrypt Transaction Key (RSA) │
│ • Algorithm: RSA PKCS#1 v1.5 │
│ • Key: Bank's E002 public key │
│ • Result: Encrypted transaction key │
│ │
│ 4. Output │
│ • OrderData: Base64(encrypted_data) │
│ • TransactionKey: Base64(encrypted_key) │
│ │
│ ────────────────────────────────────────────────────────────────────────────│
│ │
│ DECRYPTION (Bank → Client) │
│ ───────────────────────── │
│ │
│ 1. Decrypt Transaction Key │
│ • Use client's E002 private key │
│ • Recover AES-128 transaction key │
│ │
│ 2. Decrypt Order Data │
│ • Extract IV from first 16 bytes │
│ • Decrypt with recovered transaction key │
│ • Remove PKCS#7 padding │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Encryption Parameters
| Parameter | Value |
|---|---|
| Symmetric Algorithm | AES-128-CBC |
| Key Size | 128 bits (16 bytes) |
| IV | Zero IV for encryption, extracted for decryption |
| Padding | PKCS#7 |
| Asymmetric Algorithm | RSA PKCS#1 v1.5 |
| Key Transport | Bank's E002 public key |
Compression
Order data is compressed before encryption using DEFLATE (RFC 1951):
┌──────────────────────────────────────────────────────────────────────────────┐
│ COMPRESSION (DEFLATE) │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ COMPRESS (before encryption) │
│ • Algorithm: DEFLATE (raw, no gzip header) │
│ • Compression level: Maximum (9) │
│ │
│ DECOMPRESS (after decryption) │
│ • Reverse DEFLATE to recover original data │
│ │
│ Typical compression ratios for XML: 70-90% reduction │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Hash Operations
SHA-256 is used exclusively for all hash operations:
| Purpose | Input | Output |
|---|---|---|
| Order Data Digest | Compressed order data | 32 bytes (binary) |
| Public Key Hash | "exponent_hex modulus_hex" | Base64 encoded |
| XML-DSig Digest | Canonicalized XML | Base64 encoded |
| Bank Key Verification | Key components | Base64 encoded |
Key Storage & Protection
At Rest
- Public keys: Stored in plaintext (safe to expose)
- Private keys: Always encrypted using AES-256-GCM
- Key hashes: Stored for verification purposes
- Modulus/Exponent: Stored for EBICS transmission
In Memory
- Rate limiting: Maximum decryption attempts per minute per user
- Lockout: Temporary lockout after rate limit exceeded
- Audit logging: Every key access logged with user, purpose, timestamp
- No caching: Keys decrypted on-demand, not cached in memory
Key Lifecycle
┌──────────────────────────────────────────────────────────────────────────────┐
│ KEY LIFECYCLE │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ │
│ │ PENDING │ │
│ │(generated) │
│ └────┬────┘ │
│ │ submit to bank (INI/HIA) │
│ ▼ │
│ ┌───────────┐ │
│ │ SUBMITTED │ │
│ │(at bank) │ │
│ └─────┬─────┘ │
│ │ bank activates │
│ ▼ │
│ ┌────────┐ │
│ │ ACTIVE │ │
│ │(in use)│ │
│ └───┬────┘ │
│ ┌────────────┼────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ EXPIRED │ │ REVOKED │ │ ROTATED │ │
│ │(time) │ │(manual) │ │(replaced) │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ Key Rotation Orders: │
│ • PUB: Update signature key only │
│ • HCA: Update authentication + encryption keys │
│ • HCS: Update all three keys │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Certificate Support
The client supports X.509 certificates for H3K initialization:
┌──────────────────────────────────────────────────────────────────────────────┐
│ CERTIFICATE SUPPORT │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ H3K INITIALIZATION (Certificate-Based) │
│ ────────────────────────────────────── │
│ • All three keys initialized with CA-issued certificates │
│ • Eliminates need for INI/HIA letters │
│ • Certificates embedded in H3K request │
│ │
│ CERTIFICATE VALIDATION │
│ ───────────────────────── │
│ • Check if CA-signed (not self-signed) │
│ • Extract and validate certificate chain │
│ • Verify validity period (not expired, not yet valid) │
│ • Full H3K validation before submission │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Complete Data Flow
┌──────────────────────────────────────────────────────────────────────────────┐
│ UPLOAD ORDER DATA FLOW │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Original Order Data (e.g., pain.001 XML) │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 1. COMPRESS │ DEFLATE (RFC 1951) │
│ │ │ ~70-90% size reduction │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 2. HASH │ SHA-256(compressed_data) │
│ │ │ → order_data_digest │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 3. SIGN │ RSA-SHA256 with signature key │
│ │ (A005/A006) │ → electronic_signature (EU) │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 4. ENCRYPT │ AES-128-CBC with random transaction key │
│ │ (AES-128) │ → encrypted_order_data │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 5. ENCRYPT KEY │ RSA PKCS#1 with bank's E002 key │
│ │ (RSA E002) │ → encrypted_transaction_key │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 6. AUTH SIGN │ XML-DSig with authentication key │
│ │ (X002) │ → AuthSignature element │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ EBICS Request ready for transmission │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Security Summary
| Aspect | Implementation |
|---|---|
| Key Size | RSA 2048-4096 bits |
| Hash Algorithm | SHA-256 exclusively |
| Symmetric Encryption | AES-128-CBC |
| Signature (Modern) | RSASSA-PSS (A006) |
| Signature (Legacy) | PKCS#1 v1.5 (A005) |
| Key Storage | AES-256-GCM encryption at rest |
| Key Access | Rate-limited, audit-logged |
| Transport | TLS 1.2+ required |
Next Steps
- Data Model - Entity relationships
- Protocol Details - Message structures
- Return Codes - Error handling