Configuring custom AS4 conformance policies

By configuring a custom AS4 conformance policy you can define such parameters as security, error and receipt handling, and notifications.

Before you begin

You also can import a conformance policy as a resource from another installation of AS4 Microservice. For more information, see ../reference/as4/meg_resource_commands.html.

About this task

A custom conformance policy contains all the processing mode (p-mode) parameters that are specified in the individual predefined conformance policies. You can define a custom conformance policy based on the agreement with your trading partner.

To configure a custom AS4 conformance policy, complete the following steps:

Procedure

  1. Log in to AS4 Microservice. You must have Master Account Administrator permissions to configure a custom AS4 conformance policy.
  2. Click Exchanges > Conformance Policies
  3. On the Conformance Policies page, click New.
  4. To use a predefined conformance policy and create a new custom conformance policy, select the predefined conformance policy that you want to use.
  5. Optional: On the detailed view page for that conformance policy, click Copy.
  6. On the New Conformance Policy page, specify values for the fields listed in the following table.

    The conformance policy configuration includes the following settings:

    Bundling

    You can bundle error messages and receipts of previous transactions related to the same trading partner with a current exchange.

    Security
    You can encrypt transmitted messages by using the combination of an encryption algorithm and key strength, the security reference type, and a key transport algorithm. You can also secure a message that is transmitted with the help of a certificate and related parameters. Additionally, you can authenticate the users who are involved in the message exchange. Security configuration includes Encryption, Signing, and Message Layer Authentication settings. Encryption includes algorithm settings for asymmetrical and symmetrical encryption of inbound and outbound messages.
    Important: AES 128 GCM encryption is requested for data at rest when using IBM Integration Bus.
    Signing includes signature settings for outbound and inbound messages. Message Layer Authentication includes enabling user authentication and specifying the type and mode of user authentication.
    Reliability

    Reliability is the ability of the message service handler to resend a message if receipt is not received, detect and eliminate duplicate messages, and deliver a message reliably based on the WS-Reliable Message settings.

    Error Handling

    Error handling includes the settings for reporting ebMS errors to a trading partner.

    Notifications

    Notifications includes settings for notifying the business application about the status of a message that was sent or received.

    File Size Optimization

    Includes Compression and Split and join settings for a message.

    Associated Organization
    Click Select and select the owner organization.
    Name

    Type a unique name for the custom AS4 conformance policy.

    Description

    Optional: Type a description for the custom AS4 conformance policy.

    Bundle receipts and error messages

    Optional: To enable piggy backing of receipts and error messages along with other user message or signal messages, select the Bundle receipts and error messages check box.

    Enable encryption

    Optional: To enable the encryption of messages in an exchange, select the Enable Encryption check box.

    Tip: For successful encryption enabled transactions, both a visibility event (ENCRYPTION_PROCESSING) and an auditable event (SECURITY_PROCESSING) are emitted for monitoring purposes.
    Remember: To use encryption with an AS4 conformance policy, the appropriate Java Cryptography Extension (JCE) policy must be installed with AS4 Microservice. For more information about installing a JCE policy, see ../security/as4/meg_securing_jcepolicyoverview.html.
    Algorithm

    If you select Enable Encryption, you must select an algorithm and key strength combination for encryption.

    Each algorithm is combined with a key strength. You can select an Advanced Encryption Standard (AES) algorithm in CBC mode with a key strength of 128 bits (AES_128), an AES algorithm in GCM mode with a key strength of 128 bits (AES_128 GCM), an AES algorithm with a key strength of 256 bits (AES_256), or a Triple Data Encryption (Triple DES) algorithm with a key strength of 168 bits (TRIPLE_DES_168).

    Security reference type

    If you select Enable Encryption, you must select a security reference type for encryption. The security reference specifies the token type.

    You can select a binary security token (BINARY_SECURITY_TOKEN_SINGLE_CERT), an X.509 key identifier (X509_KEY_IDENTIFIER), an issuer and serial number (ISSUERNAME_AND_SERIALNUMBER), or a subject key identifier (SKI_ KEY_IDENTIFIER).

    Key transport algorithm

    If you select Enable Encryption, you must select a Key transport algorithm. The key transport algorithm is used to decrypt encrypted symmetric keys.

    You can select an RSA algorithm (RSA-1_5), or an RSA-OAEP algorithm (RSA-OAEP-MGF1P) for key transport encryption.

    Enable decryption

    Optional: To enable the decryption of messages in an exchange, select the Enable Decryption check box.

    Certificate alias (decryption)

    If you select Enable Decryption, you must select a Certificate alias. The certificate alias is used to decrypt the message after it is transmitted to your trading partner.

    Outbound exchanges use X.509 certificate to sign the data

    Optional: To enable the signing of a message with an X.509 certificate in an outbound exchange, select the Outbound exchanges use X.509 certificate to sign the data check box.

    Ensure that you share the public part of the certificate that is used for signing with the trading partner.

    Certificate alias (signing)

    If you select Outbound exchanges use X.509 certificate to sign the data, you must select the certificate alias that must be used for signing outbound messages.

    To add a certificate alias, click Add certificate. Ensure that the Signing/Signature verification option is enabled for the certificate.

    Key identifier
    Optional: Select the key identifier for the certificate that is used for the transaction:
    • Binary Security Token
    • Binary Security Token with Chain
    • Issuer Name and Serial Number
    • Subject Key Identifier
    • Thumbprint Identifier
    Inbound exchanges require signed messages

    Optional: To specify that inbound messages must be signed, select the Inbound exchanges require signed messages check box.

    If the Inbound exchanges require signed messages option is enabled, ensure that the required certificate (of the trading partner) with appropriate usage (signing and signature verification) is available in your system.

    You must select the appropriate certificate when configuring connection settings for the inbound push request and outbound pull response in an exchange profile.

    If the Inbound exchanges require signed messages option is enabled and the required certificate is not available in the system, the inbound message or response is not processed. Based on the conformance policy configuration, an appropriate error message is sent to the sender and notification is sent to the business application.

    Signature hash
    Optional: Select the hash algorithm that is used for signing the messages. The available options are as follows:
    • MD5
    • SHA1
    • SHA256
    • SHA384
    • SHA512
    Important: Do not use the MD5 or SHA1 signature hashes.
    Enable user authentication checking

    Optional: To enable user authentication, select the Enable user authentication checking check box.

    If user authentication checking is enabled, the user name and password (or password digest) that you and your partner agreed on must be available in the request sent to or received from the trading partner.

    Authenticate with
    Optional: If you enable user authentication checking, you must specify one of the following authentication types to authenticate a user:
    • User name token
    • X.509 certificate
    User name token
    Optional: To authenticate a user with a user name and password, select the User name token check box. You must also select the password type that can be sent in the request. The available options are as follows:

    • Password digest - A digest of the password is sent (outbound flow) or received (inbound flow). A password digest is a Base64 encoded, SHA-2 hash value of the UTF8 encoded password text. For more security, the nonce (a random value that is created and included in the user name token), creation time (the time when the nonce was created), and the password are digested using the SHA-2 hash algorithm and then Base64 encoded.

    • Plain text - The password is sent (outbound flow) or received (inbound flow) as plain text.

    X.509 certificate

    Optional: To authenticate a user with an X.509 certificate, select the X.509 certificate.

    If this option is selected, you must select the required certificate when configuring an exchange profile.

    Authenticate via
    Optional: If you enable user authentication checking, you must specify the mode through which user can be authenticated. The options are:
    • User exit
    • System default
    User exit

    Optional: Select User exit to enable user authentication through a user exit. If you select User exit, the X.509 certificate or user name token that are available in an external database (outside AS4 Microservice) are used. A custom code is used to access the external database.

    System default

    Optional: Select System default to enable user authentication through system default. If you select System default, the X.509 certificate and user name token that are available in the Identity component of AS4 Microservice are used.

    Require receipt

    Optional: Select the Require receipt check box to send or receive a receipt for the message that is sent to the trading partner or received from the trading partner.

    Based on the nature of exchange, specify whether you want to receive or send the receipt synchronously or asynchronously. Select one of the following options:

    • Synchronously - Select Synchronously to receive or send the receipt on the same HTTP or HTTPS connection. You can select this option if AS4 Microservice is awaiting a receipt from the trading partner or if the trading partner is waiting for a receipt from AS4 Microservice for further processing. For example, a two-way synchronous exchange.

      If you have specified synchronous receipt in the conformance policy, and configured a two-way push pull exchange profile using the conformance policy, synchronous receipt is sent or received for the push part of the exchange, and asynchronous receipt for the pull part of the exchange. As piggybacking is not supported for two-way push pull message exchange, this functionality is useful for trading partners who do not host an HTTP or HTTPS server, or for trading partners who are using an AS4 client. If synchronous receipt is selected, the split and join option is disabled in the conformance policy. When you select synchronous receipts, you can specify values for interval for receipts and resending the message, for the pull part of the exchange.

    • Asynchronously - Select Asynchronously to receive the receipt on a separate HTTP or HTTPS connection. Select this option if it is not required for AS4 Microservice to receive a receipt immediately from a trading partner. If you select asynchronous receipt and associate the conformance policy with a two-way push pull exchange profile,the receipts are sent and received asynchronously for both push and pull parts of the message exchange.

    Interval for receipts

    Optional: Specify the time that AS4 Microservice must wait to receive a receipt.

    If resending of message is configured, the message is resent after the time specified in the Interval for receipts.

    For one-way pull or two-way push pull exchanges, the message in the pull destination is purged after a pull request is honored (if receipt is not configured) or after a receipt is received (if receipt is configured). However, if Require receipts is selected and a receipt is not received after the time specified in the Interval for receipts field, the message that was pulled earlier is made available in the pull destination. The trading partner can send another pull request to pull the message. The number of pull requests and the interval is based on the values specified in the Number of retries and Interval for receipts fields.

    Enable resending of messages if receipt not received

    Optional: To resend messages if a receipt is not received, select the Enable resending of messages if receipt not received check box.

    If you have selected synchronous option for receipts, the Enable resending of messages if receipt not received option is disabled. In a synchronous message exchange pattern, the sending message service handler (MSH) receives a receipt or an error on the same connection. In either case, the sending MSH does not resend a message.

    Number of retries

    Optional: Specify the number of times AS4 Microservice must resend a message in the Number of retries field.

    Minimum value for number of retries is 1.

    Maximum value for number of retries is 100.

    Detect duplicate messages

    Optional: Select the Detect duplicate messages check box to detect duplicate messages.

    Duplicate detection is the ability of AS4 Microservice to detect duplicate messages based on the MessageId parameter of the message that is received.

    Eliminate duplicate messages

    Optional: To eliminate duplicate messages, select the Eliminate duplicate messages check box.

    If elimination is configured, duplicate messages are not sent to the business application and are deleted from AS4 Microservice.

    If elimination is not configured, duplicate messages are sent to the business application after ebMS processing and security processing.

    Enable delivery assurance via WS-ReliableMessaging

    To enable web services reliability messaging, select the Enable delivery assurance via WS-ReliableMessaging check box.

    Report ebMS errors
    To specify whether ebMS processing errors must be reported to the trading partner, synchronously or asynchronously, select one of the following options:

    • Synchronously (default selection) - Errors are reported to the trading partner on the same HTTP or HTTPS connection. Synchronous error reporting is used for synchronous message exchange patterns. If you have specified sending error messages synchronously in the conformance policy, and configured a two-way push pull exchange profile using the conformance policy, error messages are sent or received synchronously for the push part of the exchange, and asynchronously for the pull part of the exchange. As piggybacking is not supported for two-way push pull message exchange, this functionality is useful for trading partners who do not host an HTTP or HTTPS server, or for trading partners who are using AS4 client.

    • Asynchronously - Errors are reported on a different connection. Asynchronous error reporting is used for asynchronous message exchange patterns. If you select asynchronous error messages and associate the conformance policy with a two-way push pull exchange profile,the error messages are sent and received asynchronously for both push and pull parts of the message exchange.

    Notify message producer

    Optional: To notify the business application about the status of a message that was submitted or received, select the Notify message producer check box. Select the messaging destination where the notification must be sent. You might choose to send the notification to the default notification destination also.

    Restriction: For outbound messages, if an error occurs before trading partner look-up, a notification is sent to the default notification destination and not to the notification destination that you selected.
    Split and join
    Optional: Whether to split a message before sending it to the trading partner. Possible values are:
    • Unchecked (default) - do not split messages
    • Checked - Split the messages

    The split and join feature enables you to split large messages (payload and attachments) into fragments before sending them to a trading partner. Splitting large messages allows you to address problems such as, delay in transfer of large messages or limitations of the network resources.

    Split files larger than

    Required if splitting is enabled. Specify the threshold size for splitting a message. A message that is larger than the threshold size is split before sending. The units are specified in KB or MB (default).

    Default value is 10 MB.

    Maximum fragment size

    Required if splitting is enabled. Specify the fragment size. The source message is split into the specified size. The units are specified in KB or MB (default).

    Default value is 10 MB.

    Join timeout

    Required if splitting is enabled. In an inbound flow, the join timeout specifies the time interval for which AS4 Microservice waits for the second and subsequent fragments after receiving the first fragment. The units are specified in MIN and HOUR.

    If the second and subsequent fragments are not received within the timeout interval, AS4 Microservice fails the transaction and sends appropriate error message and notification to the trading partner and the business application.

    Default value is 60 MIN.

    Write source message to storage

    Optional. If splitting is enabled, you can specify whether to write the source message to storage.

    If this option is enabled, the source message before splitting and the source message that is formed after joining the fragments is written to storage. You might want to write the source message to storage for auditing reasons.

    Non-repudiation of receipts

    Optional: Select Non-repudiation of receipts to send the source message digest along with the receipt.

    If split and join is enabled, non-repudiation of receipts is applicable regardless of whether the source message is signed or unsigned. For exchanges where split and join is not enabled, non-repudiation information (digest of the source message) is included in the receipt only if the source message is signed.

    You must also select the algorithm to calculate the message digest.

    Compression (GZIP)
    Optional: Whether to compress the attachments before sending the message. This compression is the AS4 compression. Possible values are:
    • Unchecked (default) - do not compress messages
    • Checked - compress messages

    Only the EBHandler system default conformance policy has the compression option enabled by default. The threshold is 1 MB and Compression level is MEDIUM.

    Compress files larger than

    Required if Compression is selected. This value is the threshold for compressing files. The units are specified in KB or MB. This value is an integer 0 - 2147483647. Specifying zero (0) for this parameter means that all file are compressed. Select the unit of measurement from the list (either KB or MB).

    Only the EBHandler system default conformance policy has the compression option enabled by default. The threshold is 1 MB and Compression level is MEDIUM.

    Compression level
    Required if Compression is checked. This value is the amount of compression that is done to the message. Possible values are:
    • HIGH
    • MEDIUM
    • LOW

    Only the EBHandler system default conformance policy has the compression option enabled by default. The threshold is 1 MB and Compression level is MEDIUM.

  7. Click Save to save the AS4 custom conformance policy. The AS4 custom conformance policy is automatically deployed when you save the configuration.