Initial commit
This commit is contained in:
defiQUG
298
docs/integrations/as4-gateway-integration.md
Normal file
298
docs/integrations/as4-gateway-integration.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# AS4 Gateway Integration Documentation
|
||||
|
||||
**Version:** 1.0
|
||||
**Last Updated:** 2024-12-20
|
||||
**Status:** Draft - In Progress
|
||||
|
||||
---
|
||||
|
||||
## Integration Overview
|
||||
|
||||
### Purpose
|
||||
SMOA integrates with AS4 (Applicability Statement 4) gateway for secure, reliable inter-agency messaging per OASIS AS4 Profile 1.0.
|
||||
|
||||
### Integration Type
|
||||
- **Protocol:** AS4 (ebMS 3.0 profile)
|
||||
- **Message Format:** SOAP with WS-Security
|
||||
- **Transport:** HTTPS/TLS
|
||||
- **Authentication:** Certificate-based mutual authentication
|
||||
|
||||
### Integration Status
|
||||
- **Status:** Framework Complete
|
||||
- **Implementation:** Partial (full implementation pending Apache CXF integration)
|
||||
- **Testing:** Framework testing complete
|
||||
|
||||
---
|
||||
|
||||
## Integration Architecture
|
||||
|
||||
### AS4 Message Flow
|
||||
|
||||
```
|
||||
SMOA Application
|
||||
↓
|
||||
AS4 Service Layer (core:as4)
|
||||
↓
|
||||
AS4 Message Construction
|
||||
↓
|
||||
WS-Security Headers
|
||||
↓
|
||||
SOAP Envelope
|
||||
↓
|
||||
HTTPS/TLS Transport
|
||||
↓
|
||||
AS4 Gateway
|
||||
↓
|
||||
Partner System
|
||||
```
|
||||
|
||||
### Components
|
||||
|
||||
#### AS4 Service Layer
|
||||
- **Location:** `core/as4/src/main/java/com/smoa/core/as4/`
|
||||
- **Components:**
|
||||
- AS4MessageBuilder
|
||||
- AS4SecurityHandler
|
||||
- AS4ReliabilityHandler
|
||||
- AS4Service
|
||||
|
||||
#### Message Models
|
||||
- **AS4Message:** Complete AS4 message structure
|
||||
- **AS4Party:** Sender/receiver party information
|
||||
- **AS4Security:** WS-Security headers
|
||||
- **AS4Reliability:** WS-ReliableMessaging headers
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### AS4 Gateway Configuration
|
||||
|
||||
#### Endpoint Configuration
|
||||
```kotlin
|
||||
// AS4 gateway endpoint
|
||||
as4GatewayEndpoint = "https://as4-gateway.example.com/as4"
|
||||
as4GatewayCertificate = "gateway-cert.pem"
|
||||
```
|
||||
|
||||
#### Party Configuration
|
||||
```kotlin
|
||||
// SMOA party information
|
||||
smoaPartyId = "SMOA-001"
|
||||
smoaPartyName = "Secure Mobile Operations Application"
|
||||
smoaCertificate = "smoa-cert.pem"
|
||||
```
|
||||
|
||||
#### Security Configuration
|
||||
```kotlin
|
||||
// Security settings
|
||||
signatureAlgorithm = "RSA-SHA256"
|
||||
encryptionAlgorithm = "AES-256-GCM"
|
||||
certificateValidation = true
|
||||
mutualTLS = true
|
||||
```
|
||||
|
||||
### Partner Configuration
|
||||
|
||||
#### Partner Agreements (CPA)
|
||||
- **CPA Management:** Collaboration Protocol Agreement management
|
||||
- **Partner Registration:** Partner registration procedures
|
||||
- **Certificate Exchange:** Certificate exchange procedures
|
||||
- **Policy Configuration:** Policy configuration per partner
|
||||
|
||||
---
|
||||
|
||||
## Message Formats
|
||||
|
||||
### AS4 Message Structure
|
||||
|
||||
#### Message Envelope
|
||||
```xml
|
||||
<soap:Envelope>
|
||||
<soap:Header>
|
||||
<eb:Messaging>
|
||||
<eb:UserMessage>
|
||||
<eb:MessageInfo>
|
||||
<eb:MessageId>uuid:...</eb:MessageId>
|
||||
<eb:Timestamp>2024-12-20T12:00:00Z</eb:Timestamp>
|
||||
</eb:MessageInfo>
|
||||
<eb:PartyInfo>
|
||||
<eb:From>...</eb:From>
|
||||
<eb:To>...</eb:To>
|
||||
</eb:PartyInfo>
|
||||
<eb:CollaborationInfo>...</eb:CollaborationInfo>
|
||||
<eb:PayloadInfo>...</eb:PayloadInfo>
|
||||
</eb:UserMessage>
|
||||
</eb:Messaging>
|
||||
<wsse:Security>...</wsse:Security>
|
||||
<wsrm:Sequence>...</wsrm:Sequence>
|
||||
</soap:Header>
|
||||
<soap:Body>...</soap:Body>
|
||||
</soap:Envelope>
|
||||
```
|
||||
|
||||
### WS-Security Headers
|
||||
|
||||
#### XML Digital Signature
|
||||
- **Algorithm:** RSA-SHA256
|
||||
- **Canonicalization:** Exclusive XML Canonicalization
|
||||
- **Signature Location:** SOAP header
|
||||
- **Certificate:** X.509 certificate
|
||||
|
||||
#### XML Encryption
|
||||
- **Algorithm:** AES-256-GCM
|
||||
- **Key Transport:** RSA-OAEP
|
||||
- **Encryption Scope:** Message body
|
||||
- **Certificate:** Recipient certificate
|
||||
|
||||
### Message Payload
|
||||
|
||||
#### Payload Format
|
||||
- **Content Type:** Application-specific (XML, JSON, binary)
|
||||
- **Compression:** Optional compression
|
||||
- **Size Limits:** Per AS4 specification
|
||||
|
||||
---
|
||||
|
||||
## Message Operations
|
||||
|
||||
### Sending Messages
|
||||
|
||||
#### Send Message Procedure
|
||||
1. **Construct Message:** Build AS4 message
|
||||
2. **Add Security:** Add WS-Security headers
|
||||
3. **Add Reliability:** Add WS-ReliableMessaging headers
|
||||
4. **Sign Message:** Sign message with XMLDSig
|
||||
5. **Encrypt Message:** Encrypt message (if required)
|
||||
6. **Send Message:** Send via HTTPS
|
||||
7. **Wait for Receipt:** Wait for AS4 receipt
|
||||
8. **Verify Receipt:** Verify receipt signature
|
||||
|
||||
#### Message Sending Code
|
||||
```kotlin
|
||||
val message = AS4MessageBuilder()
|
||||
.setMessageId(UUID.randomUUID().toString())
|
||||
.setFrom(smoaParty)
|
||||
.setTo(partnerParty)
|
||||
.setPayload(payload)
|
||||
.build()
|
||||
|
||||
val signedMessage = as4SecurityHandler.sign(message, smoaCertificate)
|
||||
val encryptedMessage = as4SecurityHandler.encrypt(signedMessage, partnerCertificate)
|
||||
|
||||
val receipt = as4Service.sendMessage(encryptedMessage)
|
||||
```
|
||||
|
||||
### Receiving Messages
|
||||
|
||||
#### Receive Message Procedure
|
||||
1. **Receive Message:** Receive AS4 message
|
||||
2. **Verify Signature:** Verify XMLDSig signature
|
||||
3. **Decrypt Message:** Decrypt message (if encrypted)
|
||||
4. **Process Message:** Process message payload
|
||||
5. **Generate Receipt:** Generate AS4 receipt
|
||||
6. **Sign Receipt:** Sign receipt
|
||||
7. **Send Receipt:** Send receipt to sender
|
||||
|
||||
### Message Receipts
|
||||
|
||||
#### Receipt Generation
|
||||
- **Receipt Type:** AS4 non-repudiation receipt
|
||||
- **Receipt Content:** Message ID, timestamp, status
|
||||
- **Receipt Signature:** Digital signature on receipt
|
||||
- **Receipt Delivery:** Reliable delivery of receipt
|
||||
|
||||
### Error Handling
|
||||
|
||||
#### Error Signal Messages
|
||||
- **Error Types:** Processing errors, security errors, reliability errors
|
||||
- **Error Format:** AS4 error signal format
|
||||
- **Error Handling:** Error signal processing and response
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
### Authentication
|
||||
- **Mutual TLS:** Certificate-based mutual authentication
|
||||
- **Certificate Validation:** Full certificate chain validation
|
||||
- **Revocation Checking:** OCSP/CRL checking
|
||||
|
||||
### Message Security
|
||||
- **Digital Signatures:** XMLDSig on all messages
|
||||
- **Message Encryption:** XMLEnc for sensitive messages
|
||||
- **Non-Repudiation:** Receipt-based non-repudiation
|
||||
|
||||
### Key Management
|
||||
- **Certificate Storage:** Secure certificate storage
|
||||
- **Certificate Rotation:** Certificate rotation procedures
|
||||
- **Key Exchange:** Secure key exchange procedures
|
||||
|
||||
---
|
||||
|
||||
## Reliability
|
||||
|
||||
### WS-ReliableMessaging
|
||||
- **Message Ordering:** Guaranteed message ordering
|
||||
- **Duplicate Detection:** Automatic duplicate detection
|
||||
- **Acknowledgments:** Message acknowledgments
|
||||
- **Retry Logic:** Automatic retry on failure
|
||||
|
||||
### Pull Protocol
|
||||
- **Pull Support:** AS4 pull protocol support
|
||||
- **Polling:** Message polling procedures
|
||||
- **Message Retrieval:** Secure message retrieval
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Integration Testing
|
||||
- **Test Environment:** AS4 test gateway
|
||||
- **Test Messages:** Test message scenarios
|
||||
- **Test Certificates:** Test certificates
|
||||
- **Test Procedures:** Integration test procedures
|
||||
|
||||
### Test Scenarios
|
||||
- **Message Sending:** Test message sending
|
||||
- **Message Receiving:** Test message receiving
|
||||
- **Error Handling:** Test error scenarios
|
||||
- **Reliability:** Test reliable messaging
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Message Sending Failures
|
||||
- **Issue:** Messages not sending
|
||||
- **Diagnosis:** Check network, certificates, configuration
|
||||
- **Resolution:** Verify connectivity, certificates, configuration
|
||||
|
||||
#### Signature Verification Failures
|
||||
- **Issue:** Signature verification fails
|
||||
- **Diagnosis:** Check certificates, signature format
|
||||
- **Resolution:** Verify certificates, check signature format
|
||||
|
||||
#### Receipt Not Received
|
||||
- **Issue:** Receipt not received
|
||||
- **Diagnosis:** Check message delivery, receipt generation
|
||||
- **Resolution:** Verify message delivery, check receipt generation
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [OASIS AS4 Profile 1.0](https://docs.oasis-open.org/ebxml-msg/ebms/v3.0/profiles/AS4-profile/v1.0/)
|
||||
- [WS-Security Specification](https://docs.oasis-open.org/wss/v1.1/)
|
||||
- [WS-ReliableMessaging Specification](https://docs.oasis-open.org/ws-rx/wsrm/200702)
|
||||
- [Architecture Documentation](../architecture/ARCHITECTURE.md)
|
||||
|
||||
---
|
||||
|
||||
**Document Owner:** Integration Developer
|
||||
**Last Updated:** 2024-12-20
|
||||
**Status:** Draft - In Progress
|
||||
**Next Review:** 2024-12-27
|
||||
|
||||
Reference in New Issue
Block a user