smoa/docs/integrations/as4-gateway-integration.md

# 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