/n software Adapters for BizTalk

Questions / Feedback?

AS2 Configuration

The adapter accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the adapter, access to these internal properties is provided through the Other property.

AS2 Configuration Settings

AcceptAnySignerCert:   Used to accept trust any signing certificate unconditionally.

If AcceptAnySignerCert is set to true, the adapter will accept any signer certificate for the incoming signature. Use of this setting in production is discouraged, as failing to authenticate the sender poses a security risk.

ChunkSize:   Specifies the chunk size in bytes when using chunked encoding.

This is only applicable when UseChunkedEncoding is true. This setting specifies the chunk size in bytes to be used when posting data. The default value is 16384.

LogDebug:   Whether to log debug data.

This setting specifies whether to log debug data. When set to True the adapter will create additional files in the LogDirectory. The default value is False.

When sending, files with extensions ".input", ".sign", ".compress", and ".encrypt" may be created. When receiving, files with extensions ".input", ".verify", ".decompress", and ".decrypt" may be created.

MDNDeliveryOption:   A URL indicating how the receipt is to be delivered.

The default mode of operation is for the receipt to be returned synchronously within the HTTP reply. By specifying a valid URL, the user may request asynchronous delivery instead. The URL indicates the destination for the reply, and may use any appropriate protocol, such as "mailto", "http", or "https".

If this is set to an empty string (default), the receipt will be returned synchronously, and will be processed automatically by the adapter. Clients requesting asynchronous delivery should provide their own processing for reading receipts. This is applicable to the send adapter only.

OAEPMGF1HashAlgorithm:   The MGF1 hash algorithm used when encrypting a key.

When UseOAEP is True, this algorithm specifies the MGF1 hash algorithm used for the encryption key by RSA OAEP. Possible values are:

  • "SHA1"
  • "SHA224"
  • "SHA256" (default)
  • "SHA384"
  • "SHA512"

Note: An empty string value indicates that the algorithm specified by OAEPRSAHashAlgorithm is used as the RSA hash algorithm as well.

OAEPParams:   The hex encoded OAEP parameters to be used when encrypting a key.

This setting is optional and should only be specified if OAEP parameters need to be explicitly set. The value specified should be a hex string. By default this setting is unspecified.

OAEPRSAHashAlgorithm:   The RSA hash algorithm used when encrypting a key.

When UseOAEP is True, this algorithm specifies the RSA hash algorithm used for the encryption key. This may differ from the hash algorithm used to sign the AS4 message content. Possible values are:

  • "SHA1"
  • "SHA224"
  • "SHA256" (default)
  • "SHA384"
  • "SHA512"
OtherHeaders:   Other headers as determined by the user.

The headers must be of the format "header: value" as described in the HTTP specifications. Header lines should be separated by CRLF ("\r\n"). Use this property with caution. If this property contains invalid headers, HTTP requests may fail. This property is useful for extending the functionality of the adapter beyond what is provided. This is applicable to the transmitter adapter only.

SignatureAlgorithm:   Signature algorithm to be used in outgoing messages.

The Signature Algorithm can be set to indicate the preferred signing algorithm. Possible values are:

  • sha1
  • md5
  • sha-224
  • sha-256 (default)
  • sha-384
  • sha-512
The default value is "sha1". MDNOptions will need to be updated to reflect the selected algorithm if the MDN receipt is to be signed with the same algorithm. For example:
 signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, sha-256
 
This is applicable to the send adapter only.

SMTPFrom:   The senders address for asynchronous MDN delivery.

If an asynchronous MDN is requested to be sent over SMTP this specifies the sender. This is applicable to the receive adapter only.

SMTPServer:   The SMTP server for asynchronous MDN delivery.

If an asynchronous MDN is requested to be sent over SMTP this specifies the server. This is applicable to the receive adapter only.

SMTPSubject:   The SMTP message subject for asynchronous MDN delivery.

If an asynchronous MDN is requested to be sent over SMTP this specifies the subject. This is applicable to the receive adapter only.

UseChunkedEncoding:   Whether to chunk outgoing posts.

When sending, this setting controls whether data is chunked. Chunking allows data to be streamed as it is available instead of preparing the entire message first. It is recommended to set this to True if sending very large files. The default value is False.

UseOAEP:   Whether to use Optimal Asymmetric Encryption Padding (OAEP) when encrypting the key with RSA.

If set to true, OAEP will be used when encrypting the key. By default this value is False and the component will use PKCS1. Only applicable when sending AS2 messages. The following optional settings apply when this is set to True:

UsePSS:   Whether to use RSA-PSS when signing.

If set to true, RSA-PSS will be used when signing messages. The default value is False. Note that the certificate used to sign does not itself need to be signed with RSA-PSS; any valid RSA certificate may be used with this setting.

SSL Configuration Settings

ReuseSSLSession:   Determines if the SSL session is reused.

If set to true, the adapter will reuse the context if and only if the following criteria are met:

  • The target host name is the same.
  • The system cache entry has not expired (default timeout is 10 hours).
  • The application process that calls the function is the same.
  • The logon session is the same.
  • The instance of the adapter is the same.

SSLCipherStrength:   The minimum cipher strength used for bulk encryption.

This minimum cipher strength largely dependent on the security modules installed on the system. If the cipher strength specified is not supported, an error will be returned when connections are initiated.

Please note that this setting contains the minimum cipher strength requested from the security library.

Use this setting with caution. Requesting a lower cipher strength than necessary could potentially cause serious security vulnerabilities in your application.

SSLEnabledCipherSuites:   The cipher suite to be used in an SSL negotiation.

The enabled cipher suites to be used in SSL negotiation.

By default, the enabled cipher suites will include all available ciphers ("*").

The special value "*" means that the adapter will pick all of the supported cipher suites. If SSLEnabledCipherSuites is set to any other value, only the specified cipher suites will be considered.

Multiple cipher suites are separated by semicolons.

Example values when UseInternalSecurityAPI is False (default):

// The "Other" property could contain ONE of the following lines:
SSLEnabledCipherSuites=*
SSLEnabledCipherSuites=CALG_AES_256
SSLEnabledCipherSuites=CALG_AES_256;CALG_3DES
Possible values when UseInternalSecurityAPI is False (default) include:
  • CALG_3DES
  • CALG_3DES_112
  • CALG_AES
  • CALG_AES_128
  • CALG_AES_192
  • CALG_AES_256
  • CALG_AGREEDKEY_ANY
  • CALG_CYLINK_MEK
  • CALG_DES
  • CALG_DESX
  • CALG_DH_EPHEM
  • CALG_DH_SF
  • CALG_DSS_SIGN
  • CALG_ECDH
  • CALG_ECDH_EPHEM
  • CALG_ECDSA
  • CALG_ECMQV
  • CALG_HASH_REPLACE_OWF
  • CALG_HUGHES_MD5
  • CALG_HMAC
  • CALG_KEA_KEYX
  • CALG_MAC
  • CALG_MD2
  • CALG_MD4
  • CALG_MD5
  • CALG_NO_SIGN
  • CALG_OID_INFO_CNG_ONLY
  • CALG_OID_INFO_PARAMETERS
  • CALG_PCT1_MASTER
  • CALG_RC2
  • CALG_RC4
  • CALG_RC5
  • CALG_RSA_KEYX
  • CALG_RSA_SIGN
  • CALG_SCHANNEL_ENC_KEY
  • CALG_SCHANNEL_MAC_KEY
  • CALG_SCHANNEL_MASTER_HASH
  • CALG_SEAL
  • CALG_SHA
  • CALG_SHA1
  • CALG_SHA_256
  • CALG_SHA_384
  • CALG_SHA_512
  • CALG_SKIPJACK
  • CALG_SSL2_MASTER
  • CALG_SSL3_MASTER
  • CALG_SSL3_SHAMD5
  • CALG_TEK
  • CALG_TLS1_MASTER
  • CALG_TLS1PRF
Example values when UseInternalSecurityAPI is True:
// The "Other" property could contain ONE of the following lines:
SSLEnabledCipherSuites=*
SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA
SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA;TLS_DH_ANON_WITH_AES_128_CBC_SHA
Possible values when UseInternalSecurityAPI is True include:
  • TLS_DHE_DSS_WITH_AES_128_GCM_SHA256
  • TLS_DHE_DSS_WITH_AES_256_GCM_SHA384
  • TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
  • TLS_DHE_DSS_WITH_DES_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
  • TLS_DHE_RSA_WITH_DES_CBC_SHA
  • TLS_RSA_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_128_GCM_SHA256
  • TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_256_CBC_SHA256
  • TLS_RSA_WITH_DES_CBC_SHA
  • TLS_RSA_WITH_RC4_128_MD5
  • TLS_RSA_WITH_RC4_128_SHA

If SSLEnabledProtocols is configured to use TLS 1.3 the following values are supported:

  • TLS_AES_128_GCM_SHA256
  • TLS_AES_256_GCM_SHA384

SSLEnabledCipherSuites is used together with SSLCipherStrength.

SSLEnabledProtocols:   Used to enable/disable the supported security protocols.

Used to enable/disable the supported security protocols.

Not all supported protocols are enabled by default (the value of this setting is 4032). If you want more granular control over the enabled protocols, you can set this property to the binary 'OR' of one or more of the following values:

TLS1.312288 (Hex 3000) (Experimental)
TLS1.23072 (Hex C00) (Default)
TLS1.1768 (Hex 300) (Default)
TLS1 192 (Hex C0) (Default)
SSL3 48 (Hex 30)
SSL2 12 (Hex 0C)

Note: TLS 1.1 and TLS1.2 support are only available starting with Windows 7.

Note: Enabling TLS 1.3 will automatically set UseInternalSecurityAPI to True.

SSLIncludeCertChain:   Whether the entire certificate chain is included in the SSLServerAuthentication event.

This setting specifies whether the transport log contains the full certificate chain. By default this value is False and only the leaf certificate will be present.

If set to True all certificates returned by the server will be present in the transport log. This includes the leaf certificate, any intermediate certificate, and the root certificate.

Note: When UseInternalSecurityAPI is set to True this value is automatically set to True. This is needed for proper validation when using the internal provider.

SSLSecurityFlags:   Flags that control certificate verification.

The following flags are defined (specified in hexadecimal notation). They can be or-ed together to exclude multiple conditions:

0x00000001Ignore time validity status of certificate.
0x00000002Ignore time validity status of CTL.
0x00000004Ignore non-nested certificate times.
0x00000010Allow unknown Certificate Authority.
0x00000020Ignore wrong certificate usage.
0x00000100Ignore unknown certificate revocation status.
0x00000200Ignore unknown CTL signer revocation status.
0x00000400Ignore unknown Certificate Authority revocation status.
0x00000800Ignore unknown Root revocation status.
0x00008000Allow test Root certificate.
0x00004000Trust test Root certificate.
0x80000000Ignore non-matching CN (certificate CN not-matching server name).

TLS12SignatureAlgorithms:   Defines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True.

This setting specifies the allowed server certificate signature algorithms when UseInternalSecurityAPI is True and SSLEnabledProtocols is set to allow TLS 1.2.

When specified the adapter will verify that the server certificate signature algorithm is among the values specified in this setting. If the server certificate signature algorithm is unsupported the adapter will fail with an error.

The format of this value is a comma separated list of hash-signature combinations. For instance:

// The "Other" could contain ALL of these lines:
UseInternalSecurityAPI=true
SSLEnabledProtocols=3072
TLS12SignatureAlgorithms=sha1-rsa,sha1-dsa,sha256-rsa,sha256-dsa
The default value for this setting is "sha1-rsa,sha1-dsa,sha224-rsa,sha224-dsa,sha256-rsa,sha256-dsa,sha384-rsa,sha384-dsa,sha512-rsa,sha512-dsa".

In order to not restrict the server's certificate signature algorithm, specify an empty string as the value for this setting, which will cause the signature_algorithms TLS 1.2 extension to not be sent.

TLS13SignatureAlgorithms:   The allowed certificate signature algorithms.

This setting holds a comma separated list of allowed signature algorithms. Possible values are:

  • "rsa_pkcs1_sha256" (default)
  • "rsa_pkcs1_sha384" (default)
  • "rsa_pkcs1_sha512" (default)
The default value is rsa_pkcs1_sha256,rsa_pkcs1_sha384,rsa_pkcs1_sha512. This setting is only applicable when SSLEnabledProtocols includes TLS 1.3.
TLSNamedGroups:   The supported (EC)DHE groups.

This setting specifies a comma separated list of (EC)DHE groups that are supported for key exchange. The values are ordered from most preferred to least preferred. The following values are supported:

  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1"
  • "ffdhe_2048" (default)
  • "ffdhe_3072" (default)
  • "ffdhe_4096"
  • "ffdhe_6144"
  • "ffdhe_8192"

The default value is ecdhe_secp256r1,ecdhe_secp384r1,ffdhe_2048,ffdhe_3072. This setting is only applicable when SSLEnabledProtocols includes TLS 1.3. Note that groups of larger size require more computational resources and will impact performance.

General Configuration Settings

AbsoluteTimeout:   Determines whether timeouts are inactivity timeouts or absolute timeouts.

If AbsoluteTimeout is set to True, any method which does not complete within Timeout seconds will be aborted. By default, AbsoluteTimeout is False, and the timeout is an inactivity timeout.

LocalHost:   The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost configuration contains the name of the local host as obtained by the Gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the adapter initiate connections (or accept in the case of server adapters) only through that interface.

If the adapter is connected, the LocalHost configuration shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

TcpNoDelay:   Whether or not to delay when sending packets.

When true, the socket will send all data that is ready to send at once. When false, the socket will send smaller buffered packets of data at small intervals. This is known as the Nagle algorithm.

By default, this config is set to false.

UseInternalSecurityAPI:   Tells the adapter whether or not to use the system security libraries or an internal implementation.

By default the adapter will use the system security libraries to perform cryptographic functions. When set to False calls to unmanaged code will be made. In certain environments this is not desirable. To use a completely managed security implementation set this setting to True. Setting this to True tells the adapter to use the internal implementation instead of using the system's security API.

Note: This setting is static. The value set is applicable to all adapters used in the application.

When this value is set the product's system DLL is no longer required as a reference, as all unmanaged code is stored in that file.

Supported Macros

The adapter also supports the following Macros. These values are not case sensitive and would be supplied to a property in the form %MacroName%.

TempThis is resolved to the full path to the system's temporary directory.
MessageIDGlobally unique identifier (GUID) of the message in BizTalk Server.
SourceFileNameThe original file name. This includes the extension and excludes the file path, for example, Sample.xml
SourceFileNameNoExtThe original file name without the extension or file path, for example, Sample
RemoteFileNameThe name of the file as it was uploaded to the remote server. This includes the extension and excludes the file path, for example, Sample.xml. Valid only for AS3, FTP, and SFTP Send Adapters.
DestinationPartyName of the destination party.
DestinationPartyQualifierQualifier of the destination party.
SourcePartyName of the source party.
SourcePartyQualifierQualifier of the source party.
DateTime:CustomFormatThis special value allows you to specify your own custom time format. For instance DateTime:yyyy would be resolved to the 4 digit year.
DateThe date format yyyy-MM-dd.
DateTimeThe date format yyyy-MM-ddThhmmss.
TimeThe date format hhmmss.
DateTime_BTS2000The date format yyyyMMddhhmmssf.
DateTime.TZThe date format yyyy-MM-ddThhmmsszzz.
Time.TZThe date format hhmmsszzz.

 
 
Copyright (c) 2021 /n software inc. - All rights reserved.
/n software Adapters for BizTalk - Version 20.0 [Build 7724]