Setting Up ebMS 2.0 Partnerships

Partnership ID

Description

The unique identifier of an ebMS 2.0 partnership in local Hermes.

The value of this field has no restriction but it is RECOMMENDED to be unique between sender and recipient.

This field is mandatory and its maximum length is 255.

CPA ID

Description

The Collaboration Protocol Agreement (CPA) ID is a string that identifies the parameters governing the exchange of messages between the parties. The recipient of a message must be able to resolve the CPA ID to an individual set of parameters, taking into account the sender of the message.

Simply put, it is an arbitary and mandatory string that can be used to identify both sender and recipient.

See [OASIS ebXML Messaging Service Spec v2.0] for details.

Service

Description In Hermes, this mandatory parameter is used for mapping a partnership between sender and recipient.

Action

Description This identifies a process within a Service that processes the ebMS message. Action must be unique within the Service in which it is defined. The value of the Action element is specified by the designer of the Service. This field is mandatory and its maximum length is 255 characters.

Disabled

Description

This boolean option indicates whether the partnership is disabled or not.

Disabled partnership do not deliver/receive any outgoing/incoming messages.

Options [ true = disabled ], [ false = enabled ]

Transport Endpoint

Description

The endpoint URL of the receiving messaging gateway.

If the receiving messaging gateway is Hermes and HTTP/HTTPS is the transport protocol, the endpoint URL is formatted as http://<RECIPIENT_HOST>:<PORT>/corvus/httpd/ebms/inbound. The recipient should set this field to http://<SENDER_HOST>:<PORT>/corvus/httpd/ebms/inbound in order to send acknowledgements upon request.

Otherwise, if the recipient host is an SMTP gateway, the endpoint URL is formatted as mailto:<EMAIL ADDRESS>.

This field is mandatory and the format must be an HTTP/HTTPS URL or EMAIL ADDRESS.

Hostname Verified in SSL?

Description

This boolean flag indicates whether HTTP SSL/TLS protocol is used to verify the recipient hostname.

This is relevant only if HTTPS transport protocol is used in Transport Endpoint

Options [ true = hostname verified using SSL , false = no verification using SSL ]

Sync Reply Mode

Description

Indicates whether the receiver should reply to incoming ebMS messages using the same HTTP/HTTPS connection that the sender is using for delivery.

This parameter is only applicable to send partnerships using HTTP/HTTPS transport protocol.

Options [ mshSignalsOnly = synchronous reply ], [ none = asynchronous reply ]

Synchronous reply

ebMS message acknowledgement is included in the HTTP/SOAP response.

_images/ebms-send-sync.png

Asynchronous reply

ebMS message acknowledgement will be delivered through another HTTP/SOAP connection from the recipient to the sender.

_images/ebms-send-async.png

Acknowledgement Requested

Description

Indicates whether the sender has requested the recipient to reply with an ebMS acknowledgement. An acknowledgement is a type of ebMS message which has an <acknowledgement> element.

For interoperability of this feature, both sender and recipient must enable it. Otherwise, the recipient will return a negative acknowledgement.

How the acknowledgement is sent depends on the value of Sync Reply Mode. If it is enabled, the acknowledgement will be sent immediately using the same HTTP connection as the received message. Otherwise, if the recipient is using Hermes, the acknowledgement will be placed in an outgoing queue until it is delivered to the sender.

It is RECOMMENDED to set this parameter to always for reliable messaging.

Options [ always = acknowledgement requested ], [ none = acknowledgement is not requested ]

Acknowledgement Signed Requested

Description

Indicates whether the recipient must sign the ebMS acknowledgement digitally using their private key before delivering it to the sender.

For interoperability of this feature, both sender and recipient must enable it. Otherwise, the recipient will return a negative acknowledgement.

The format of the private key should be in PKCS12 and the created signatures should conform to W3C XML Signatures Specification [XMLDsig].

The send partnership must set Acknowledgement Requested to always for this feature to run properly.

The recipient is required to provide a Certificate for Verification so the signature in the acknowledgement can be verified.

Dependencies

[ Acknowledgement Requested = always ],

[ Certificate For Verification REQUIRED ]

Options

[ true = acknowledgement must be digitally signed ],

[ false = acknolwedgment must not be digitally signed ]

Duplicate Elimination

Description

Indicates whether the recipient will ignore duplicate messages.

For interoperability of this feature, both sender and recipient must enable it. Otherwise, the recipient will return a negative acknowledgement.

Options

[ always = ignores duplicate messages ],

[ never = receives duplicate messages ]

Message Order

Description

Indicates whether the recipient must receive ebMS messages in the same sequence that they were sent.

For interoperability of this feature, both sender and recipient must enable it. Otherwise, the recipient will return a negative acknowledgement.

Dependencies

[ Sync Reply Mode = none ],

[ Acknowledgement Requested = always ],

[ Duplicate Elimination = always ]

Options

[ Guaranteed = recipient receives ebMS messages in sending order ],

[ NotGuaranteed = recipient receives ebMS message with best effort behavior ]

Signing Required?

Description

Indicates whether the sender must sign ebMS messages digitally using their private key.

For interoperability of this feature, both sender and recipient must enable this. Otherwise, the recipient will return a negative acknowledgement.

The format of the private key should be in PKCS12 and the created signature should conform to W3C XML Signatures Specification [XMLDsig]. For details of signing message, please refer to Sign and Verify Message.

Options

[ true = outgoing ebMS messages must be digitally signed ],

[ false = outgoing ebMS messages are not required to be digitally signed ]

Encryption Required? (Mail Only)

Description

Indicates whether the sender must encrypt ebMS messages using the recipient’s public certificate defined in Certificate For Encryption.

This is only applicable when using SMTP protocol for Transport Endpoint.

The encryption method is based on S/MIME standard.

Dependencies

[ Transport Endpoint = using SMTP protocol ],

[ Sync Reply Mode = none ],

[ Certificate For Encryption REQUIRED ]

Options

[ true = outgoing ebMS messages must be encrypted ],

[ false = outgoing ebMS messages are not required to be encrypted ]

Certificate For Encryption

Description

The certificate file for encrypting outgoing ebMS messages using SMTP protocol by using the public key generated by the recipient.

The recipient should use the keystore in the ebMS plugin to export the public certificate for the sender. ebMS default keystore location: <HERMES2_HOME>/plugins/corvus-ebms/security

The certificate must be in X.509 format. See Encryption Required? (Mail Only) for details.

Maximum Retries

Description

The maximum number of retries allowed for the sender to attempt delivering an ebMS message.

Hermes tries to deliver the ebMS message under the features of reliable messaging until exceeding the maximum number of retries.

There will be a time interval between each attempt, which is defined in Retry Interval (ms).

It is recommended that the value of this field be between 1-10.

Dependencies [ Acknowledgement Requested = always ]

Retry Interval (ms)

Description

The time interval (milleseconds) between each consecutive attempt to deliver an ebMS message.

It is recommended that the value of this field be between 30000-300000.

Dependencies [ Acknowledgement Requested = always ]

Certificate For Verification

Description

The certificate (.cer) file for verifying incoming digitally signed ebMS message by using the public key generated by sender.

The sender should use the keystore in the ebMS plugin to export the public certificate for the recipient. ebMS default keystore location: <HERMES2_HOME>/plugins/corvus-ebms/security

The keystore must be in PKCS12 format.

See Signing Required? for details.