d-bis/smoa
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
smoa/docs/integrations/as4-gateway-integration.md
defiQUG 97f75e144f Initial commit
2025-12-26 10:48:33 -08:00

7.6 KiB
Raw Permalink Blame History

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

// AS4 gateway endpoint
as4GatewayEndpoint = "https://as4-gateway.example.com/as4"
as4GatewayCertificate = "gateway-cert.pem"

Party Configuration

// SMOA party information
smoaPartyId = "SMOA-001"
smoaPartyName = "Secure Mobile Operations Application"
smoaCertificate = "smoa-cert.pem"

Security Configuration

// 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

<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

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

Document Owner: Integration Developer
Last Updated: 2024-12-20
Status: Draft - In Progress
Next Review: 2024-12-27

Reference in New Issue View Git Blame Copy Permalink