Server Architecture
Layered architecture design for security, scalability, and maintainability.
The fourbics Server follows a layered architecture designed for security, scalability, and maintainability.
Layer Overview
┌──────────────────────────────────────────────────────────────────────────────┐
│ Presentation Layer │
│ (HTTP Endpoints, XML Processing) │
├──────────────────────────────────────────────────────────────────────────────┤
│ Application Layer │
│ (Request Handlers, Business Logic, VEU) │
├──────────────────────────────────────────────────────────────────────────────┤
│ Domain Layer │
│ (Entities, Value Objects, Domain Services) │
├──────────────────────────────────────────────────────────────────────────────┤
│ Infrastructure Layer │
│ (Database, Crypto, External APIs, File Storage) │
└──────────────────────────────────────────────────────────────────────────────┘
Presentation Layer
HTTP Endpoint
The server exposes a single endpoint for all EBICS requests. All communication uses XML over HTTPS with TLS 1.2 or higher.
Request Processing Pipeline
┌──────────────────────────────────────────────────────────────────────────────┐
│ Request Pipeline │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. TLS Termination │
│ └─→ Verify client certificate (optional) │
│ │
│ 2. XML Parsing │
│ └─→ Parse request, extract header │
│ │
│ 3. Schema Validation │
│ └─→ Validate against EBICS XSD │
│ │
│ 4. Host Resolution │
│ └─→ Identify target host from HostID │
│ │
│ 5. Authentication │
│ └─→ Verify XML signature (X002) │
│ │
│ 6. Authorization │
│ └─→ Check subscriber permissions │
│ │
│ 7. Request Handling │
│ └─→ Route to specific handler │
│ │
│ 8. Response Generation │
│ └─→ Build and sign response │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Application Layer
Request Handlers
Each EBICS order type has a dedicated handler responsible for:
- Validating order-specific parameters
- Executing the business logic
- Generating the appropriate response
Handler Categories
| Category | Order Types | Purpose |
|---|---|---|
| Version | HEV | Protocol version discovery |
| Key Management | INI, HIA, HPB, H3K, PUB, HCA, HCS, SPR | Key exchange and management |
| Administrative | HAA, HPD, HKD, HTD, HAC | Information retrieval |
| Business | BTU, BTD, FUL, FDL | Order upload and download |
| VEU | HVU, HVZ, HVD, HVT, HVE, HVS | Distributed signatures |
Transaction Management
Multi-phase transactions are managed through a state machine:
┌──────────────────────────────────────────────────────────────────────────────┐
│ Transaction Lifecycle │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Upload Transaction: │
│ ┌──────────────┐ ┌──────────────┐ │
│ │Initialization│───>│ Data Transfer│ │
│ │ (Phase 1) │ │ (Phase 2) │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ Download Transaction: │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │Initialization│───>│ Data Transfer│───>│ Receipt │ │
│ │ (Phase 1) │ │ (Phase 2) │ │ (Phase 3) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Domain Layer
Core Concepts
The server manages these core domain concepts:
| Concept | Description |
|---|---|
| Host | An EBICS server identity with its own keys and configuration |
| Partner | A customer organization connected to a host |
| Subscriber | An individual user within a partner organization |
| Transaction | A multi-phase EBICS protocol exchange |
| Order | A business transaction (payment, statement, etc.) |
Subscriber States
| State | Description |
|---|---|
| NEW | Subscriber created, no keys received |
| PARTLY_INITIALISED | Some keys received (INI or HIA) |
| READY | All keys received and activated |
| BLOCKED | Temporarily or permanently blocked |
Signature Classes
| Class | Name | Can Execute Alone |
|---|---|---|
| E | Single Signature | Yes |
| A | First Signature | No - needs A or B |
| B | Second Signature | No - needs A |
| T | Transport Only | No - upload only |
Infrastructure Layer
Cryptographic Services
The server provides these cryptographic operations:
| Operation | Algorithm | Purpose |
|---|---|---|
| Signing | RSA-SHA256 | Sign responses (X002) |
| Verification | RSA-SHA256 | Verify request signatures |
| Encryption | AES-128-CBC + RSA | Encrypt response data |
| Decryption | AES-128-CBC + RSA | Decrypt request data |
| Hashing | SHA-256 | Key fingerprints, digests |
HSM Integration
For production environments, bank keys should be stored in Hardware Security Modules (HSM):
- Key generation within HSM
- Signing operations performed by HSM
- Private keys never leave HSM
- Support for common HSM vendors
Scalability
Horizontal Scaling
┌──────────────────────────────────────────────────────────────────────────────┐
│ Scaling Strategy │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Stateless Application Servers │
│ ├── No session state in application │
│ ├── Transaction state in shared storage │
│ └── Can scale horizontally │
│ │
│ Shared State │
│ ├── Database: Transaction state, subscriber data │
│ ├── Cache: Rate limiting, session data │
│ └── Queue: Async order processing │
│ │
│ Load Balancing │
│ ├── Round-robin for stateless requests │
│ └── Sticky sessions not required │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Performance Optimization
| Technique | Benefit |
|---|---|
| Connection Pooling | Reuse database connections |
| Response Caching | Cache static responses (HEV, HPD) |
| Async Processing | Queue large order processing |
| Compression | Reduce payload sizes |
Security Architecture
Defense in Depth
┌──────────────────────────────────────────────────────────────────────────────┐
│ Security Layers │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Layer 1: Network │
│ ├── Firewall rules │
│ ├── DDoS protection │
│ └── IP whitelisting (optional) │
│ │
│ Layer 2: Transport │
│ ├── TLS 1.2+ only │
│ ├── Strong cipher suites │
│ └── Certificate validation │
│ │
│ Layer 3: Application │
│ ├── XML signature verification │
│ ├── Request validation │
│ └── Rate limiting │
│ │
│ Layer 4: Data │
│ ├── Encryption at rest │
│ ├── Key management (HSM) │
│ └── Audit logging │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Audit Logging
All security-relevant events are logged:
- EBICS requests and responses
- Authentication successes and failures
- Key management operations
- Order processing events
- Administrative actions
Return Code Handling
The server returns standardized EBICS return codes:
| Code Range | Category | Examples |
|---|---|---|
| 000000 | Success | EBICS_OK |
| 011xxx | Download info | No more data available |
| 061xxx | Technical warnings | Recovery possible |
| 091xxx | Technical errors | Invalid signature |
| 09xxxx | Business errors | Unknown user, invalid order |
See Return Codes for the complete reference.