AS4Client Component

Properties   Methods   Events   Config Settings   Errors  

The AS4Client component connects to a server to send or receive files.

Syntax

TibeAS4Client

Remarks

The AS4Client component may be used to send or receive files from a server. The component will connect to a server and either send files (push), or request files to download (pull).

Sending Files

SendFiles sends the files specified by EDIData to URL.

Before calling this method set AgreementRef to the agreement identifier used by both parties. Set AS4From and AS4To. Set EDIData specifies the file(s) to be sent. To encrypt the data set RecipientCerts. To sign the data set SigningCert. The SignerCert property should be set to verify the signed receipt.

When this method is called the file(s) will be sent and any returned receipts will be verified.

To indicate a synchronous receipt is expected set ReceiptReplyMode to rrmSync. The following properties are applicable when calling this method with an agreement specifying a synchronous receipt (a receipt provided in the response):

• AgreementRef
• AS4From
• AS4To
• EDIData
• URL
• RecipientCerts (required to encrypt)
• SignerCert (required to verify signed receipts)
• SigningCert (required to sign files)
• ConversationId (optional)
• EncryptionAlgorithm (optional)
• LogDirectory (optional)
• MessageId (optional)
• MessageProperties (optional)
• Profile (optional)
• ReceiptReplyMode
• Service (optional)
• ServiceType (optional)
• SignatureAlgorithm (optional)

SendFiles Example (synchronous receipt): client.Profile = As4clientProfiles.ebpfENTSOG; //Specify the agreement and party information client.AgreementRef = "http://agreements.company.com/sign_and_encrypt"; client.AS4From.Role = "Sender"; client.AS4From.Id = "org:b2b:example:company:A"; client.AS4To.Role = "Receiver"; client.AS4To.Id = "org:b2b:example:company:B"; //Configure the component to expect a synchronous receipt. client.ReceiptReplyMode = As4clientReceiptReplyModes.rrmSync; //Company A's private certificate. Used to sign the outgoing message and files. client.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "C:\\files\\CompanyA.pfx", "password", "*"); //Company B's public certificate. Used to encrypt the outgoing file. client.RecipientCerts.Add(new Certificate("C:\\files\\as4\\CompanyB.cer")); //Company B's public certificate. Used to verify the signed receipt. client.SignerCert = new Certificate("C:\\files\\as4\\CompanyB.cer"); client.URL = "http://www.company.com:9090/msh"; EBData data = new EBData(); data.EDIType = "application/edi-x12"; data.Filename = "C:\\files\\myfile.x12"; data.Name = "myfile.x12"; client.EDIData.Add(data); //Send file(s) and verify the receipt. client.SendFiles();

The component also supports asynchronous receipts. In this configuration a file is sent from the component to another party, but the receipt is not returned in the response. Instead the other party sends the receipt at a later time. The AS4Server component may be used inside a web page to receive the asynchronous receipt. After receiving the receipt either AS4Server or AS4Client may be used to verify the receipt.

Details about the original message must be stored so that the receipt can be correlated with the message and properly verified. The easiest way to do this is to set AsyncReceiptInfoDir before calling SendFiles. The component will automatically store the required information.

See the VerifyReceipt method of AS4Server for details about verifying asynchronous receipts.

To indicate an asynchronous receipt is expected set ReceiptReplyMode to rrmAsync. The following properties are applicable when calling this method with an agreement specifying a synchronous receipt (a receipt provided in the response):

• AgreementRef
• AS4From
• AS4To
• AsyncReceiptInfoDir
• EDIData
• URL
• RecipientCerts (required to encrypt)
• SignerCert (required to verify signed receipts)
• SigningCert (required to sign files)
• ConversationId (optional)
• EncryptionAlgorithm (optional)
• LogDirectory (optional)
• MessageId (optional)
• MessageProperties (optional)
• OriginalSOAPMessage (optional)
• OriginalSOAPMessageId (optional)
• Profile (optional)
• ReceiptReplyMode
• Service (optional)
• ServiceType (optional)
• SignatureAlgorithm (optional)

SendFiles Example (asynchronous receipt): client.Profile = As4clientProfiles.ebpfENTSOG; //Specify the agreement and party information client.AgreementRef = "http://agreements.company.com/sign_and_encrypt_async"; client.AS4From.Role = "Sender"; client.AS4From.Id = "org:b2b:example:company:A"; client.AS4To.Role = "Receiver"; client.AS4To.Id = "org:b2b:example:company:B"; //Configure the component to expect a synchronous receipt. client.ReceiptReplyMode = As4clientReceiptReplyModes.rrmAsync; client.AsyncReceiptInfoDir = "C:\\async_info"; //Company A's private certificate. Used to sign the outgoing message and files. client.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "C:\\files\\CompanyA.pfx", "password", "*"); //Company B's public certificate. Used to encrypt the outgoing files. client.RecipientCerts.Add(new Certificate("C:\\files\\as4\\CompanyB.cer")); //Company B's public certificate. Used to verify the signed receipt. client.SignerCert = new Certificate("C:\\files\\as4\\CompanyB.cer"); client.URL = "http://www.company.com:9090/msh"; EBData data = new EBData(); data.EDIType = "application/edi-x12"; data.Filename = "C:\\files\\myfile.x12"; data.Name = "myfile.x12"; client.EDIData.Add(data); //Send file(s). client.SendFiles();

At this point the file(s) have been sent, but a receipt has not yet been received. AS4Server can be used within a web site to listen for the receipt. //**** Inside a web site **** As4server server = new As4server; server.ReadRequest(); if (!String.IsNullOrEmpty(server.IncomingReceipt.Content)) { server.AsyncReceiptInfoDir = "C:\\async_info"; server.VerifyReceipt(); //The receipt is now verified }

Receiving Files

ReceiveFiles establishes a connection to the server specified by URL and receives files.

The MPC specifies the Message Partition Channel from which messages will be received. The server will reply with files from this channel. If IncomingDirectory is set before calling this method the files will be written to the specified folder, otherwise inspect EDIData to obtain the received file data. The following properties are applicable when calling this method:

• SigningCert (required to sign the request)
• Certificate (required for decryption)
• SignerCert (required for signature verification)
• URL
• IncomingDirectory (optional)
• LogDirectory
• MPC
• TokenUser
• TokenPassword
• TokenPasswordType

• AS4From
• AS4To
• AgreementRef
• ConversationId
• Service
• ServiceAction
• ServiceType
• MessageId
• Receipt

To bundle the receipt with a subsequent ReceiveFiles call the Receipt property must hold the receipt. If the same instance of the component is being used this is already true since Receipt is populated automatically after receiving the file. To use another instance of the component for multiple calls to ReceiveFiles be sure to save the Receipt's Content and RefToMessageId values for later use.

ReceiveFiles Example: client.Profile = As4clientProfiles.ebpfENTSOG; //Company A's private certificate. Used for signing the request. client.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "C:\\files\\as4\\CompanyA.pfx", "password", "*"); //Company A's private certificate. Used for decrypting the file. client.Certificate = new Certificate(CertStoreTypes.cstPFXFile, "C:\\files\\as4\\CompanyA.pfx", "password", "*"); //Company B's public certificate. Used for signature verification. client.SignerCert = new Certificate("C:\\files\\as4\\CompanyB.cer"); client.URL = "http://www.company.com:9090/msh"; //Message Channel id client.MPC = "mpc_a"; client.IncomingDirectory = "C:\\incoming_dir"; client.ReceiveFiles(); //Inspect client.AgreementRef and other properties for information about the received files Console.WriteLine(client.AgreementRef); Console.WriteLine(client.AS4From.Id); Console.WriteLine(client.AS4To.Id); Console.WriteLine(client.ConversationId); //Save the receipt for later use string receiptContent = client.Receipt.Content; string receiptRefId = client.Receipt.RefToMessageId;

At this stage the receipt data is saved. Later when making another call to ReceiveFiles and populate the Receipt property with this receipt data. When ReceiveFiles is called again, the receipt for the previous message will be included with the request. client.Receipt = new EBReceipt(receiptRefId, receiptContent); client.ReceiveFiles(); //This will now include the bundled receipt

Sending Asynchronous Receipts

SendReceipt sends an asynchronous receipt to the URL.

This method is typically used in conjunction with AS4Server to send an asynchronous receipt after receiving a message. The receipt will be created at the time of the incoming request, then saved for later use. When the receipt is to be sent populate Receipt and call this method.

//Send an asynchronous receipt client.URL = ""http://www.company.com:9090/msh""; client.Receipt = new EBReceipt(server.Receipt.RefToMessageId, server.Receipt.Content); client.ReceiptReplyMode = As4clientReceiptReplyModes.rrmAsync; client.SendReceipt();

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

AgreementRef Property (AS4Client Component)

The agreement reference.

Syntax

property AgreementRef: String read get_AgreementRef write set_AgreementRef;

Default Value

''

Remarks

This property holds a value identifying the agreement between the two parties. The agreement is made outside the scope of the request and response and governs details about the interaction including reply mode, signing and encryption options, etc.

The value of this property should be set to a mutually agreed upon identifier. Both parties will use this value know what the expected requirements are for a particular request or response.

The format of this value is typically a URI, such as "http://mycompany.com/agreement_01" but can be any unique string that both parties are configured to accept. Another common format is the concatenation of the AS4From and AS4To values.

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:CollaborationInfo/eb:AgreementRef"

AS4From Property (AS4Client Component)

Defines information about the originating party.

Syntax

property AS4From: TibeEBPartyInfo read get_AS4From write set_AS4From;

Remarks

This property defines information about the party that originates the message.

AS4To Property (AS4Client Component)

Defines information about the responding party.

Syntax

property AS4To: TibeEBPartyInfo read get_AS4To write set_AS4To;

Remarks

This property defines information about the party that receives the message.

AsyncReceiptInfoDir Property (AS4Client Component)

A directory to hold information used for asynchronous receipt verification.

Syntax

property AsyncReceiptInfoDir: String read get_AsyncReceiptInfoDir write set_AsyncReceiptInfoDir;

Default Value

''

Remarks

This setting specifies a directory which holds information about the original message that was sent.

When sending files and requesting asynchronous receipts set this directory to a location where data can be stored. When the receipt is later received this property should be set so original message information can be read in order to verify the receipt.

As an alternative the original message information may be manually stored by saving the values of OriginalSOAPMessage and OriginalSOAPMessageId after sending a file. In this case OriginalSOAPMessage and OriginalSOAPMessageId should be populated before verifying the receipt.

See the VerifyReceipt method of AS4Server for more details about verifying asynchronous receipts.

Certificate Property (AS4Client Component)

The certificate with private key used for decryption.

Syntax

property Certificate: TibeCertificate read get_Certificate write set_Certificate;

Remarks

This property specifies a certificate with private key. It is used to decrypt received files.

CompressionFormat Property (AS4Client Component)

The compression format (if any) to use.

Syntax

property CompressionFormat: TibeTAS4CompressionFormats read get_CompressionFormat write set_CompressionFormat;

TibeTAS4CompressionFormats = (
  ebcfNone,
  ebcfGZIP
);

Default Value

ebcfNone

Remarks

This setting specifies the compression format to be applied to the parts specified by EDIData. When Profile is set to Standard the default value is 0 (ebcfNone). When Profile is set to ENTSOG or eDelivery the default value is 1 (ebcfGZIP).

Possible values are:

• 0 (ebcfNone - default for Standard)
• 1 (ebcfGZIP - default for ENTSOG and eDelivery)

Note: When Profile is set to Standard the first EDIData part will be included in the SOAP body if the EDIType is "text/xml" or "application/xml". In that case since the data is included in the SOAP body it will not be compressed. When Profile is set to ENTSOG all EDIData parts are compressed.

ConversationId Property (AS4Client Component)

The Conversation Id of the message.

Syntax

property ConversationId: String read get_ConversationId write set_ConversationId;

Default Value

''

Remarks

This property specifies an Id that may be used to identify a set of related messages. This is required and if a value is not specified one will automatically be created.

Note: When Profile is set to ebpfENTSOG this value will always be empty.

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:CollaborationInfo/eb:ConversationId"

Cookies Property (AS4Client Component)

A collection of cookies.

Syntax

property Cookies: TibeHTTPCookieList read get_Cookies write set_Cookies;

Remarks

This property contains a collection of cookies. To add cookies to outgoing HTTP requests, add cookies (of type HTTPCookie) to this collection.

To see cookies that are set by the server, use the SetCookie event, which displays the cookies and their properties as set by the server. Those cookies also are added to Cookies.

MaxHTTPCookies can be used to control the maximum number of cookies saved.

This property is not available at design time.

EDIData Property (AS4Client Component)

The EDI data.

Syntax

property EData: TibeEBDataList read get_EDIData write set_EDIData;

Remarks

This property defines the EDI data to be sent. This may include multiple files.

This property is not available at design time.

EncryptionAlgorithm Property (AS4Client Component)

The algorithm used to encrypt the EDI data.

Syntax

property EncryptionAlgorithm: String read get_EncryptionAlgorithm write set_EncryptionAlgorithm;

Default Value

'AES128GCM'

Remarks

If RecipientCerts contains a valid certificate, the data will be encrypted using this certificate and the algorithm specified in EncryptionAlgorithm. If EncryptionAlgorithm is set to the empty string, the data will not be encrypted.

The component supports "3DES", or industry-standard 168-bit Triple-DES encryption.

The component supports "AES" encryption with a default keysize of 128 bits. You may also set "AESCBC192" or "AESCBC256" for 192- and 256-bit keysizes.

Possible values are:

• 3DES
• DES
• AESCBC128
• AESCBC192
• AESCBC256
• AES128GCM (default)
• AES192GCM
• AES256GCM

Errors Property (AS4Client Component)

A collection of errors.

Syntax

property Errors: TibeEBErrorList read get_Errors write set_Errors;

Remarks

This property is populated with error information. There may be one or more errors.

Common errors defined in the ebMS specifications are listed below for reference.

Firewall Property (AS4Client Component)

A set of properties related to firewall access.

Syntax

property Firewall: TibeFirewall read get_Firewall write set_Firewall;

Remarks

This is a Firewall-type property, which contains fields describing the firewall through which the component will attempt to connect.

IncomingDirectory Property (AS4Client Component)

The directory to which incoming files are saved.

Syntax

property IncomingDirectory: String read get_IncomingDirectory write set_IncomingDirectory;

Default Value

''

Remarks

If IncomingDirectory is set, the received files will be stored in the specified directory. If a filename is specified in the EDI message, the component will write to the specified filename, otherwise, a filename will be automatically generated based on a timestamp of the incoming transmission. In either case, if the filename exists on disk, the data will be written to the same name with a "-duplicate?" appended to the filename, where "?" is the number of duplicates.

This property is optional, if not set file data will be stored in EDIData.

LocalHost Property (AS4Client Component)

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

Syntax

property LocalHost: String read get_LocalHost write set_LocalHost;

Default Value

''

Remarks

This property 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 IP address of an interface will make the component initiate connections (or accept in the case of server components) only through that interface. It is recommended to provide an IP address rather than a hostname when setting this property to ensure the desired interface is used.

If the component is connected, the LocalHost property 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).

Note: LocalHost is not persistent. You must always set it in code, and never in the property window.

LogDirectory Property (AS4Client Component)

The path to a directory for logging.

Syntax

property LogDirectory: String read get_LogDirectory write set_LogDirectory;

Default Value

''

Remarks

Setting LogDirectory will instruct the component to log the details of each transmission to unique files in the specified directory. For each request processed, the component will log the complete text of the outgoing request and the incoming response.

The component will write multiple log files for each transmission, with separate extensions for each type of data:

One or more of these log files may be disabled by setting the LogOptions configuration setting. LogDirectory supports several macros that can be used to specify a unique directory path. If the path specified does not already exist, the component will attempt to create the directory. The following macros are supported:

The filenames will be chosen automatically by the component. Each filename will be the system time, in the format YYYY-MM-DD-HH-MM-SS-MMMM, with extensions "-2", "-3", used in case files of those names already exist. After each transaction is processed LogFile will contain the name of the files just written, minus the extension.

If logs cannot be written an exception will be thrown.

LogFile Property (AS4Client Component)

The log file written.

Syntax

property LogFile: String read get_LogFile;

Default Value

''

Remarks

If LogDirectory is specified a log file will be written in the specified directory and LogFile will contain the full path and name of the files written, minus the extension.

The component will write multiple log files for each transmission, with separate extensions for each type of data:

One or more of these log files may be disabled by setting the LogOptions configuration setting. LogDirectory supports several macros that can be used to specify a unique directory path. If the path specified does not already exist, the component will attempt to create the directory. The following macros are supported:

The filenames will be chosen automatically by the component. Each filename will be the system time, in the format YYYY-MM-DD-HH-MM-SS-MMMM, with extensions "-2", "-3", used in case files of those names already exist. After each transaction is processed LogFile will contain the name of the files just written, minus the extension.

If logs cannot be written an exception will be thrown.

This property is read-only.

MessageId Property (AS4Client Component)

The unique Id of the message.

Syntax

property MessageId: String read get_MessageId write set_MessageId;

Default Value

''

Remarks

This property defines the unique Id of the message. When sending files the component will automatically generate a value in the format "GUID@nsoftware". When receiving files the Id will be populated with the value read from the message.

In most cases there is no need to set this value, however if a file needs to be retransmitted using the same message Id for reliability this may be set. In AS4Client this may be set before calling SendFiles. In AS4Server this may be set after calling ReadRequest and before calling SendResponse.

This property is not available at design time.

MessageProperties Property (AS4Client Component)

A collection of message properties.

Syntax

property MessageProperties: TibeEBPropertyList read get_MessageProperties write set_MessageProperties;

Remarks

This collection specifies the message level properties that are sent with the message. This may be used to add additional values. The semantics of the values are beyond the scope of AS4, but this may be used for values that assist with processing, or other user-defined use cases.

These properties may be populated before sending a message, and are populated after parsing an incoming message.

Sending

When sending a message any number of properties may be added. The PropertyType property is optional. For instance: //using fields client.MessageProperties.Add(new EBProperty()); client.MessageProperties[0].Name = "name1"; client.MessageProperties[0].Value = "value1"; client.MessageProperties[0].PropertyType = "string"; //optional //using constructor client.MessageProperties.Add(new EBProperty("name2", "value2"));

Receiving

When receiving a message the properties may be read from this collection. For instance: for (int i = 0; i < server.MessageProperties.Count; i++) { Console.WriteLine(server.MessageProperties[i].Name + ": " + server.MessageProperties[i].Value); }

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:MessageProperties""

MPC Property (AS4Client Component)

The MPC (Message Partition Channel) from which to receive files.

Syntax

property MPC: String read get_MPC write set_MPC;

Default Value

''

Remarks

This property specifies the MPC (Message Partition Channel) from which to receive files. This must be set before calling ReceiveFiles. The value specified here must be known to the other party.

When left unspecified this indicates the default MPC.

This value corresponds to the ebMS element "eb:Messaging/eb:SignalMessage/eb:PullRequest/@mpc"

OriginalSOAPMessage Property (AS4Client Component)

The original SOAP message used to verify the receipt.

Syntax

property OriginalSOAPMessage: String read get_OriginalSOAPMessage write set_OriginalSOAPMessage;

Default Value

''

Remarks

OriginalSOAPMessage and OriginalSOAPMessageId may be used as an alternative to AsyncReceiptInfoDir when verifying receipts.

If AsyncReceiptInfoDir is not set when the original message is sent, these values will be populated after the send and the values should be saved.

Before verifying the receipt set these properties to their original values.

This property is not available at design time.

OriginalSOAPMessageId Property (AS4Client Component)

The original SOAP message Id used to verify the receipt.

Syntax

property OriginalSOAPMessageId: String read get_OriginalSOAPMessageId write set_OriginalSOAPMessageId;

Default Value

''

Remarks

OriginalSOAPMessage and OriginalSOAPMessageId may be used as an alternative to AsyncReceiptInfoDir when verifying receipts.

If AsyncReceiptInfoDir is not set when the original message is sent, these values will be populated after the send and the values should be saved.

Before verifying the receipt set these properties to their original values.

This property is not available at design time.

Profile Property (AS4Client Component)

The AS4 profile.

Syntax

property Profile: TibeTProfiles read get_Profile write set_Profile;

TibeTProfiles = (
  ebpfStandard,
  ebpfENTSOG,
  ebpfEDelivery,
  ebpfBDEW,
  ebpfENTSOG_V4,
  ebpfEDelivery_V2
);

Default Value

ebpfStandard

Remarks

This property specifies the AS4 profile to use. Different profiles may have different requirements and default options. Setting this property to the correct value ensures that the right options are selected in order to conform to the profile. Possible values are:

When Profile is set to ebpfENTSOG the following settings are automatically applied:

When Profile is set to ebpfENTSOG_V4, version 4 of the ENTSOG profile is used and the following settings are automatically applied:

When Profile is set to ebpfEDelivery the following settings are automatically applied:

When Profile is set to ebpfEDelivery_V2, version 2 of the eDelivery profile is used and the following settings are automatically applied:

When Profile is set to ebpfBDEW the following settings are automatically applied:

Proxy Property (AS4Client Component)

A set of properties related to proxy access.

Syntax

property Proxy: TibeProxy read get_Proxy write set_Proxy;

Remarks

This property contains fields describing the proxy through which the component will attempt to connect.

Receipt Property (AS4Client Component)

The receipt of a message.

Syntax

property Receipt: TibeEBReceipt read get_Receipt write set_Receipt;

Remarks

This property holds the receipt of a message.

Sending

When sending files if a synchronous receipt is returned in the response it is verified and this property is populated.

Receiving

When receiving files this property is populated with the receipt to send after a file is received. If this property is populated the receipt will be sent in the next request made by calling ReceiveFiles.

If the receipt is not to be bundled with a subsequent call to ReceiveFiles the SendReceipt method may be used to directly send a receipt to the other party.

ReceiptReplyMode Property (AS4Client Component)

The expected receipt reply mode.

Syntax

property ReceiptReplyMode: TibeTReceiptReplyModes read get_ReceiptReplyMode write set_ReceiptReplyMode;

TibeTReceiptReplyModes = (
  rrmSync,
  rrmAsync,
  rrmNone
);

Default Value

rrmSync

Remarks

This setting tells the component how to expect or deliver a receipt. Possible values are:

It is important to always set this property to the correct value in both AS4Client and AS4Server, whether sending or receiving, so the component can build a valid message. This should be set to the previously agreed upon value between the parties in the agreement identified by AgreementRef

RecipientCerts Property (AS4Client Component)

The public certificate used to encrypt files when sending.

Syntax

property RecipientCerts: TibeCertificateList read get_RecipientCerts write set_RecipientCerts;

Remarks

The encryption certificates of the recipients. If this property is specified, the files being sent will be encrypted using the algorithm given by EncryptionAlgorithm.

This property is not available at design time.

RefToMessageId Property (AS4Client Component)

Specifies the RefToMessageId in the message.

Syntax

property RefToMessageId: String read get_RefToMessageId write set_RefToMessageId;

Default Value

''

Remarks

This property specifies the RefToMessageId value in the message being sent.

This property is only applicable when Profile is set to ebpfEDelivery. The eDelivery profile supports the Two-Way/Push-and-Push MEP (Message Exchange Pattern), where sending a file can be in reference to a previously received file. In this case RefToMessageId specifies the Id of the previously received message to which this send is in reference.

When sending with AS4Client this should only be set when using the eDelivery profile and need to explicitly specify the RefToMessageId value as per the Two-Way/Push-And-Push MEP.

When receiving with AS4Server this may be read after receiving a message.

RolloverCertificate Property (AS4Client Component)

The rollover decryption certificate.

Syntax

property RolloverCertificate: TibeCertificate read get_RolloverCertificate write set_RolloverCertificate;

Remarks

The rollover digital certificate that the component will use to decrypt incoming transmissions. This may be used to specify an additional decryption certificate during a period of transition between private certificates in the application.

When specified the component will be able to decrypt messages that were encrypted with the corresponding public certificate of either Certificate or RolloverCertificate.

RolloverCertificate must be set to a private key certificate.

RolloverSigningCert Property (AS4Client Component)

Contains the certificate to use when signing messages.

Syntax

property RolloverSigningCert: TibeCertificate read get_RolloverSigningCert write set_RolloverSigningCert;

Remarks

This is your rollover signing certificate. This may be used to specify an additional signing certificate during a period of transition between private certificates in the application.

If this property is specified, the message content will be signed using both SigningCert and RolloverSigningCert. The recipient will be able to verify the signature with either corresponding public certificate.

If set, this property should be a private key instance of Certificate.

Service Property (AS4Client Component)

The service which acts on the message.

Syntax

property Service: String read get_Service write set_Service;

Default Value

'http://docs.oasis-open.org/ebxml-msg/as4/200902/service'

Remarks

This property specifies the service which acts on the message. This should only be changed from the default value if there is a specific reason to do so.

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:CollaborationInfo/eb:Service"

ServiceAction Property (AS4Client Component)

The action within a service that acts on the message.

Syntax

property ServiceAction: String read get_ServiceAction write set_ServiceAction;

Default Value

'http://docs.oasis-open.org/ebxml-msg/as4/200902/action'

Remarks

This property defines the action within a service that acts upon a message. This should only be changed from the default value if there is a specific reason to do so.

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:CollaborationInfo/eb:Action".

ServiceType Property (AS4Client Component)

The type of service.

Syntax

property ServiceType: String read get_ServiceType write set_ServiceType;

Default Value

''

Remarks

This optionally specifies the type of the service. The semantics of this value should be agreed upon by both parties ahead of time. It may be used to tell the other party how to interpret the Service value.

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:CollaborationInfo/eb:Service@type"

SignatureAlgorithm Property (AS4Client Component)

Signature algorithm to be used in the message.

Syntax

property SignatureAlgorithm: String read get_SignatureAlgorithm write set_SignatureAlgorithm;

Default Value

'sha-256'

Remarks

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

• SHA1
• MD5
• SHA-256 (or SHA256) (default)
• SHA-384 (or SHA384)
• SHA-512 (or SHA512)
• SHA-224 (or SHA224)
• ECDSA-SHA1
• ECDSA-SHA224
• ECDSA-SHA256
• ECDSA-SHA384
• ECDSA-SHA512
• EDDSA-ED25519
• EDDSA-ED448

The default value is "SHA-256".

SignerCert Property (AS4Client Component)

The public certificate used to verify signatures.

Syntax

property SignerCert: TibeCertificate read get_SignerCert write set_SignerCert;

Remarks

This property specifies a public certificate used to verify signatures on received messages, receipts, and files. If the content is signed by the other party, it is verified using this certificate.

SigningCert Property (AS4Client Component)

The certificate with private key used to sign messages and files.

Syntax

property SigningCert: TibeCertificate read get_SigningCert write set_SigningCert;

Remarks

This property specifies a certificate with private key used to sign outgoing messages and files. If this property is specified, the message content will be signed using the algorithm given by SignatureAlgorithm.

Used to sign any outgoing message. This applies to requests made when calling SendFiles and ReceiveFiles.

SSLAcceptServerCert Property (AS4Client Component)

Instructs the component to unconditionally accept the server certificate that matches the supplied certificate.

Syntax

property SSLAcceptServerCert: TibeCertificate read get_SSLAcceptServerCert write set_SSLAcceptServerCert;

Remarks

If it finds any issues with the certificate presented by the server, the component will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Note: This functionality is provided only for cases in which you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

SSLCert Property (AS4Client Component)

The certificate to be used during Secure Sockets Layer (SSL) negotiation.

Syntax

property SSLCert: TibeCertificate read get_SSLCert write set_SSLCert;

Remarks

This property includes the digital certificate that the component will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

SSLProvider Property (AS4Client Component)

The Secure Sockets Layer/Transport Layer Security (SSL/TLS) implementation to use.

Syntax

property SSLProvider: TibeTSSLProviders read get_SSLProvider write set_SSLProvider;

TibeTSSLProviders = (
  sslpAutomatic,
  sslpPlatform,
  sslpInternal
);

Default Value

sslpAutomatic

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic), the component will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are as follows:

In most cases using the default value (Automatic) is recommended. The component will select a provider depending on the current platform.

When Automatic is selected, on Windows, the component will use the platform implementation. On Linux/macOS, the component will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols, the internal implementation is used on all platforms.

SSLServerCert Property (AS4Client Component)

The server certificate for the last established connection.

Syntax

property SSLServerCert: TibeCertificate read get_SSLServerCert;

Remarks

This property contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

Timeout Property (AS4Client Component)

The timeout for the component.

Syntax

property Timeout: Integer read get_Timeout write set_Timeout;

Default Value

60

Remarks

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If Timeout is set to a positive value, the component will wait for the operation to complete before returning control.

The component will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not freeze and remains responsive.

If Timeout expires, and the operation is not yet complete, the component raises an exception.

Note: By default, all timeouts are inactivity timeouts, that is, the timeout period is extended by Timeout seconds when any amount of data is successfully sent or received.

The default value for the Timeout property is 60 seconds.

TokenPassword Property (AS4Client Component)

The password used in UsernameToken authentication.

Syntax

property TokenPassword: String read get_TokenPassword write set_TokenPassword;

Default Value

''

Remarks

This property specifies the password used in UsernameToken authentication.

UsernameToken Authentication Notes

If TokenUser and TokenPassword are specified the component will include UsernameToken authentication when ReceiveFiles is called. This functionality is only applicable when calling ReceiveFiles.

TokenPassword should normally be set to the plaintext password that both the client and server know. The component will automatically use SHA-1 to create a hash of the password when TokenPasswordType is set to tptDigest (default). The hashed password is sent in the request, along with a creation date and nonce. The server will validate these values when receiving the request.

client.TokenUser = "User"; client.TokenPassword = "MyPassword"; client.TokenPasswordType = As4clientTokenPasswordTypes.tptDigest; client.ReceiveFiles();

A creation date element is always sent in the request. A nonce is sent by default but can be disabled by setting UseNonce to False.

If TokenPasswordType is set to tptText the component will transmit value provided in TokenPassword exactly as it is provided. The value will not be hashed. This may be useful in cases where an alternative credential mechanism is used between the client and server.

TokenPasswordType Property (AS4Client Component)

The password type used in UsernameToken authentication.

Syntax

property TokenPasswordType: TibeTTokenPasswordTypes read get_TokenPasswordType write set_TokenPasswordType;

TibeTTokenPasswordTypes = (
  tptDigest,
  tptText
);

Default Value

tptDigest

Remarks

The type of password to send in the request. Possible values are:

UsernameToken Authentication Notes

If TokenUser and TokenPassword are specified the component will include UsernameToken authentication when ReceiveFiles is called. This functionality is only applicable when calling ReceiveFiles.

TokenPassword should normally be set to the plaintext password that both the client and server know. The component will automatically use SHA-1 to create a hash of the password when TokenPasswordType is set to tptDigest (default). The hashed password is sent in the request, along with a creation date and nonce. The server will validate these values when receiving the request.

client.TokenUser = "User"; client.TokenPassword = "MyPassword"; client.TokenPasswordType = As4clientTokenPasswordTypes.tptDigest; client.ReceiveFiles();

A creation date element is always sent in the request. A nonce is sent by default but can be disabled by setting UseNonce to False.

If TokenPasswordType is set to tptText the component will transmit value provided in TokenPassword exactly as it is provided. The value will not be hashed. This may be useful in cases where an alternative credential mechanism is used between the client and server.

TokenUser Property (AS4Client Component)

The username used in UsernameToken authentication.

Syntax

property TokenUser: String read get_TokenUser write set_TokenUser;

Default Value

''

Remarks

This property specifies the username to be sent for UsernameToken authentication.

UsernameToken Authentication Notes

If TokenUser and TokenPassword are specified the component will include UsernameToken authentication when ReceiveFiles is called. This functionality is only applicable when calling ReceiveFiles.

TokenPassword should normally be set to the plaintext password that both the client and server know. The component will automatically use SHA-1 to create a hash of the password when TokenPasswordType is set to tptDigest (default). The hashed password is sent in the request, along with a creation date and nonce. The server will validate these values when receiving the request.

client.TokenUser = "User"; client.TokenPassword = "MyPassword"; client.TokenPasswordType = As4clientTokenPasswordTypes.tptDigest; client.ReceiveFiles();

A creation date element is always sent in the request. A nonce is sent by default but can be disabled by setting UseNonce to False.

If TokenPasswordType is set to tptText the component will transmit value provided in TokenPassword exactly as it is provided. The value will not be hashed. This may be useful in cases where an alternative credential mechanism is used between the client and server.

URL Property (AS4Client Component)

The URL to which the request is made.

Syntax

property URL: String read get_URL write set_URL;

Default Value

''

Remarks

This property specifies the URL to which the request is made. SSL will be used if and only if the URL scheme is "https".

Config Method (AS4Client Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

DoEvents Method (AS4Client Component)

This method processes events from the internal message queue.

Syntax

procedure DoEvents();

Remarks

When DoEvents is called, the component processes any available events. If no events are available, it waits for a preset period of time, and then returns.

Interrupt Method (AS4Client Component)

This method interrupts the current method.

Syntax

procedure Interrupt();

Remarks

If there is no method in progress, Interrupt simply returns, doing nothing.

ReceiveFiles Method (AS4Client Component)

Connects to a server to receive files.

Syntax

procedure ReceiveFiles();

Remarks

ReceiveFiles establishes a connection to the server specified by URL and receives files.

The MPC specifies the Message Partition Channel from which messages will be received. The server will reply with files from this channel. If IncomingDirectory is set before calling this method the files will be written to the specified folder, otherwise inspect EDIData to obtain the received file data. The following properties are applicable when calling this method:

• SigningCert (required to sign the request)
• Certificate (required for decryption)
• SignerCert (required for signature verification)
• URL
• IncomingDirectory (optional)
• LogDirectory
• MPC
• TokenUser
• TokenPassword
• TokenPasswordType

• AS4From
• AS4To
• AgreementRef
• ConversationId
• Service
• ServiceAction
• ServiceType
• MessageId
• Receipt

To bundle the receipt with a subsequent ReceiveFiles call the Receipt property must hold the receipt. If the same instance of the component is being used this is already true since Receipt is populated automatically after receiving the file. To use another instance of the component for multiple calls to ReceiveFiles be sure to save the Receipt's Content and RefToMessageId values for later use.

ReceiveFiles Example: client.Profile = As4clientProfiles.ebpfENTSOG; //Company A's private certificate. Used for signing the request. client.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "C:\\files\\as4\\CompanyA.pfx", "password", "*"); //Company A's private certificate. Used for decrypting the file. client.Certificate = new Certificate(CertStoreTypes.cstPFXFile, "C:\\files\\as4\\CompanyA.pfx", "password", "*"); //Company B's public certificate. Used for signature verification. client.SignerCert = new Certificate("C:\\files\\as4\\CompanyB.cer"); client.URL = "http://www.company.com:9090/msh"; //Message Channel id client.MPC = "mpc_a"; client.IncomingDirectory = "C:\\incoming_dir"; client.ReceiveFiles(); //Inspect client.AgreementRef and other properties for information about the received files Console.WriteLine(client.AgreementRef); Console.WriteLine(client.AS4From.Id); Console.WriteLine(client.AS4To.Id); Console.WriteLine(client.ConversationId); //Save the receipt for later use string receiptContent = client.Receipt.Content; string receiptRefId = client.Receipt.RefToMessageId;

At this stage the receipt data is saved. Later when making another call to ReceiveFiles and populate the Receipt property with this receipt data. When ReceiveFiles is called again, the receipt for the previous message will be included with the request. client.Receipt = new EBReceipt(receiptRefId, receiptContent); client.ReceiveFiles(); //This will now include the bundled receipt

Reset Method (AS4Client Component)

Resets the state of the control.

Syntax

procedure Reset();

Remarks

Reset resets the state of the component. All properties will be set to their default values.

SendFiles Method (AS4Client Component)

Sends file(s) to the specified server and verify the receipt (if present).

Syntax

procedure SendFiles();

Remarks

SendFiles sends the files specified by EDIData to URL.

Before calling this method set AgreementRef to the agreement identifier used by both parties. Set AS4From and AS4To. Set EDIData specifies the file(s) to be sent. To encrypt the data set RecipientCerts. To sign the data set SigningCert. The SignerCert property should be set to verify the signed receipt.

When this method is called the file(s) will be sent and any returned receipts will be verified.

To indicate a synchronous receipt is expected set ReceiptReplyMode to rrmSync. The following properties are applicable when calling this method with an agreement specifying a synchronous receipt (a receipt provided in the response):

• AgreementRef
• AS4From
• AS4To
• EDIData
• URL
• RecipientCerts (required to encrypt)
• SignerCert (required to verify signed receipts)
• SigningCert (required to sign files)
• ConversationId (optional)
• EncryptionAlgorithm (optional)
• LogDirectory (optional)
• MessageId (optional)
• MessageProperties (optional)
• Profile (optional)
• ReceiptReplyMode
• Service (optional)
• ServiceType (optional)
• SignatureAlgorithm (optional)

SendFiles Example (synchronous receipt): client.Profile = As4clientProfiles.ebpfENTSOG; //Specify the agreement and party information client.AgreementRef = "http://agreements.company.com/sign_and_encrypt"; client.AS4From.Role = "Sender"; client.AS4From.Id = "org:b2b:example:company:A"; client.AS4To.Role = "Receiver"; client.AS4To.Id = "org:b2b:example:company:B"; //Configure the component to expect a synchronous receipt. client.ReceiptReplyMode = As4clientReceiptReplyModes.rrmSync; //Company A's private certificate. Used to sign the outgoing message and files. client.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "C:\\files\\CompanyA.pfx", "password", "*"); //Company B's public certificate. Used to encrypt the outgoing file. client.RecipientCerts.Add(new Certificate("C:\\files\\as4\\CompanyB.cer")); //Company B's public certificate. Used to verify the signed receipt. client.SignerCert = new Certificate("C:\\files\\as4\\CompanyB.cer"); client.URL = "http://www.company.com:9090/msh"; EBData data = new EBData(); data.EDIType = "application/edi-x12"; data.Filename = "C:\\files\\myfile.x12"; data.Name = "myfile.x12"; client.EDIData.Add(data); //Send file(s) and verify the receipt. client.SendFiles();

The component also supports asynchronous receipts. In this configuration a file is sent from the component to another party, but the receipt is not returned in the response. Instead the other party sends the receipt at a later time. The AS4Server component may be used inside a web page to receive the asynchronous receipt. After receiving the receipt either AS4Server or AS4Client may be used to verify the receipt.

Details about the original message must be stored so that the receipt can be correlated with the message and properly verified. The easiest way to do this is to set AsyncReceiptInfoDir before calling SendFiles. The component will automatically store the required information.

See the VerifyReceipt method of AS4Server for details about verifying asynchronous receipts.

To indicate an asynchronous receipt is expected set ReceiptReplyMode to rrmAsync. The following properties are applicable when calling this method with an agreement specifying a synchronous receipt (a receipt provided in the response):

• AgreementRef
• AS4From
• AS4To
• AsyncReceiptInfoDir
• EDIData
• URL
• RecipientCerts (required to encrypt)
• SignerCert (required to verify signed receipts)
• SigningCert (required to sign files)
• ConversationId (optional)
• EncryptionAlgorithm (optional)
• LogDirectory (optional)
• MessageId (optional)
• MessageProperties (optional)
• OriginalSOAPMessage (optional)
• OriginalSOAPMessageId (optional)
• Profile (optional)
• ReceiptReplyMode
• Service (optional)
• ServiceType (optional)
• SignatureAlgorithm (optional)

SendFiles Example (asynchronous receipt): client.Profile = As4clientProfiles.ebpfENTSOG; //Specify the agreement and party information client.AgreementRef = "http://agreements.company.com/sign_and_encrypt_async"; client.AS4From.Role = "Sender"; client.AS4From.Id = "org:b2b:example:company:A"; client.AS4To.Role = "Receiver"; client.AS4To.Id = "org:b2b:example:company:B"; //Configure the component to expect a synchronous receipt. client.ReceiptReplyMode = As4clientReceiptReplyModes.rrmAsync; client.AsyncReceiptInfoDir = "C:\\async_info"; //Company A's private certificate. Used to sign the outgoing message and files. client.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "C:\\files\\CompanyA.pfx", "password", "*"); //Company B's public certificate. Used to encrypt the outgoing files. client.RecipientCerts.Add(new Certificate("C:\\files\\as4\\CompanyB.cer")); //Company B's public certificate. Used to verify the signed receipt. client.SignerCert = new Certificate("C:\\files\\as4\\CompanyB.cer"); client.URL = "http://www.company.com:9090/msh"; EBData data = new EBData(); data.EDIType = "application/edi-x12"; data.Filename = "C:\\files\\myfile.x12"; data.Name = "myfile.x12"; client.EDIData.Add(data); //Send file(s). client.SendFiles();

At this point the file(s) have been sent, but a receipt has not yet been received. AS4Server can be used within a web site to listen for the receipt. //**** Inside a web site **** As4server server = new As4server; server.ReadRequest(); if (!String.IsNullOrEmpty(server.IncomingReceipt.Content)) { server.AsyncReceiptInfoDir = "C:\\async_info"; server.VerifyReceipt(); //The receipt is now verified }

SendReceipt Method (AS4Client Component)

Sends an asynchronous receipt.

Syntax

procedure SendReceipt();

Remarks

SendReceipt sends an asynchronous receipt to the URL.

This method is typically used in conjunction with AS4Server to send an asynchronous receipt after receiving a message. The receipt will be created at the time of the incoming request, then saved for later use. When the receipt is to be sent populate Receipt and call this method.

//Send an asynchronous receipt client.URL = ""http://www.company.com:9090/msh""; client.Receipt = new EBReceipt(server.Receipt.RefToMessageId, server.Receipt.Content); client.ReceiptReplyMode = As4clientReceiptReplyModes.rrmAsync; client.SendReceipt();

Connected Event (AS4Client Component)

Fired immediately after a connection completes (or fails).

Syntax

type TConnectedEvent = procedure (
  Sender: TObject;
  StatusCode: Integer;
  const Description: String
) of Object;

property OnConnected: TConnectedEvent read FOnConnected write FOnConnected;

Remarks

If the connection is made normally, StatusCode is 0 and Description is 'OK'.

If the connection fails, StatusCode has the error code returned by the Transmission Control Protocol (TCP)/IP stack. Description contains a description of this code. The value of StatusCode is equal to the value of the error.

Please refer to the Error Codes section for more information.

Disconnected Event (AS4Client Component)

Fired when a connection is closed.

Syntax

type TDisconnectedEvent = procedure (
  Sender: TObject;
  StatusCode: Integer;
  const Description: String
) of Object;

property OnDisconnected: TDisconnectedEvent read FOnDisconnected write FOnDisconnected;

Remarks

If the connection is broken normally, StatusCode is 0 and Description is 'OK'.

If the connection is broken for any other reason, StatusCode has the error code returned by the Transmission Control Protocol (TCP/IP) subsystem. Description contains a description of this code. The value of StatusCode is equal to the value of the TCP/IP error.

Please refer to the Error Codes section for more information.

EndTransfer Event (AS4Client Component)

Fired when a document finishes transferring.

Syntax

type TEndTransferEvent = procedure (
  Sender: TObject;
  Direction: Integer
) of Object;

property OnEndTransfer: TEndTransferEvent read FOnEndTransfer write FOnEndTransfer;

Remarks

This event is fired first when the client finishes sending data to the server (in a POST or PUT request) and then when the document text finishes transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

Error Event (AS4Client Component)

Fired when information is available about errors during data delivery.

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component raises an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

The Error event is fired in case of exceptional conditions during message processing. Normally the component raises an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Header Event (AS4Client Component)

Fired every time a header line comes in.

Syntax

type THeaderEvent = procedure (
  Sender: TObject;
  const Field: String;
  const Value: String
) of Object;

property OnHeader: THeaderEvent read FOnHeader write FOnHeader;

Remarks

The Field parameter contains the name of the HTTP header (which is the same as it is delivered). The Value parameter contains the header contents.

If the header line being retrieved is a continuation header line, then the Field parameter contains '' (empty string).

Log Event (AS4Client Component)

Fired with log information while processing a message.

Syntax

type TLogEvent = procedure (
  Sender: TObject;
  const LogType: String;
  const LogMessage: String
) of Object;

property OnLog: TLogEvent read FOnLog write FOnLog;

Remarks

This event fires once for each log message generated by the component. The verbosity is controlled by the LogLevel setting.

Log messages available through this event correspond to log files written to LogDirectory. This event provides a way to obtain log messages without relying on files on disk. This event fires regardless of the value of LogDirectory (i.e. when LogDirectory is empty the event will still fire).

The LogMessage event parameter holds the raw log data.

The LogType event parameter indicates the type of log. Possible values are:

RecipientInfo Event (AS4Client Component)

Fired for each recipient certificate of the encrypted message.

Syntax

type TRecipientInfoEvent = procedure (
  Sender: TObject;
  const Issuer: String;
  const SerialNumber: String;
  const SubjectKeyIdentifier: String;
  const EncryptionAlgorithm: String
) of Object;

property OnRecipientInfo: TRecipientInfoEvent read FOnRecipientInfo write FOnRecipientInfo;

Remarks

When ParseRequest is called and the file is encrypted, this event will fire for each recipient certificate for which the file was encrypted.

Issuer is the subject of the issuer certificate.

SerialNumber is the serial number of the encryption certificate.

SubjectKeyIdentifier is the X.509 subjectKeyIdentifier extension value of the certificate used to sign the message encoded as a hex string.

EncryptionAlgorithm is the encryption algorithm used to encrypt the message. Possible values are as follows:

• "3DES"
• "DES"
• "RC2CBC40"
• "RC2CBC64"
• "RC2CBC128" or "RC2"
• "AESCBC128" or "AES"
• "AESCBC192"
• "AESCBC256"
• "AESGCM128" or "AESGCM"
• "AESGCM192"
• "AESGCM256"

SetCookie Event (AS4Client Component)

Fired for every cookie set by the server.

Syntax

type TSetCookieEvent = procedure (
  Sender: TObject;
  const Name: String;
  const Value: String;
  const Expires: String;
  const Domain: String;
  const Path: String;
  Secure: Boolean
) of Object;

property OnSetCookie: TSetCookieEvent read FOnSetCookie write FOnSetCookie;

Remarks

This event is fired for every Set-Cookie: header received from the HTTP server.

The Name parameter contains the name of the cookie, with the corresponding value supplied in the Value parameter.

The Expires parameter contains an expiration time for the cookie (if provided by the server). The time format used is "Weekday, DD-Mon-YY HH:MM:SS GMT". If the server does not provide an expiration time, the Expires parameter will be an empty string. In this case, the convention is to drop the cookie at the end of the session.

The Domain parameter contains a domain name to limit the cookie to (if provided by the server). If the server does not provide a domain name, the Domain parameter will be an empty string. The convention in this case is to use the server specified in the URL (URLServer) as the cookie domain.

The Path parameter contains a path name to limit the cookie to (if provided by the server). If the server does not provide a cookie path, the Path parameter will be an empty string. The convention in this case is to use the path specified in the URL (URLPath) as the cookie path.

The Secure parameter specifies whether the cookie is secure. If the value of this parameter is True, the cookie value must be submitted only through a secure (HTTPS) connection.

SignerCertInfo Event (AS4Client Component)

This event is fired during verification of the signed message.

Syntax

type TSignerCertInfoEvent = procedure (
  Sender: TObject;
  const Issuer: String;
  const SerialNumber: String;
  const SubjectKeyIdentifier: String;
  const CertEncoded: String;
  const CertEncodedB: TBytes
) of Object;

property OnSignerCertInfo: TSignerCertInfoEvent read FOnSignerCertInfo write FOnSignerCertInfo;

Remarks

During verification, this event will be raised while parsing the signer's certificate information. The parameters that are populated depend on the options used when the message was originally signed. This information may be used to select the correct certificate for SignerCert to verify the signature. The following parameters may be populated:

Issuer specifies the subject of the issuer of the certificate used to sign the message.

SerialNumber is the serial number of the certificate used to sign the message.

SubjectKeyIdentifier is the X.509 subjectKeyIdentifier extension value of the certificate used to sign the message encoded as a hex string.

CertEncoded is the PEM (Base64 encoded) public certificate needed to verify the signature.

Note: When this value is present, the component will automatically use this value to perform signature verification.

The SignerCert property may be set from within this event. In this manner, the decision of which signer certificate to load may be delayed until the parameters of this event are inspected and the correct certificate can be located and loaded.

SSLServerAuthentication Event (AS4Client Component)

Fired after the server presents its certificate to the client.

Syntax

type TSSLServerAuthenticationEvent = procedure (
  Sender: TObject;
  const CertEncoded: String;
  const CertEncodedB: TBytes;
  const CertSubject: String;
  const CertIssuer: String;
  const Status: String;
  var Accept: Boolean
) of Object;

property OnSSLServerAuthentication: TSSLServerAuthenticationEvent read FOnSSLServerAuthentication write FOnSSLServerAuthentication;

Remarks

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

SSLStatus Event (AS4Client Component)

Fired when secure connection progress messages are available.

Syntax

type TSSLStatusEvent = procedure (
  Sender: TObject;
  const Message: String
) of Object;

property OnSSLStatus: TSSLStatusEvent read FOnSSLStatus write FOnSSLStatus;

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

StartTransfer Event (AS4Client Component)

Fired when a document starts transferring (after the headers).

Syntax

type TStartTransferEvent = procedure (
  Sender: TObject;
  Direction: Integer
) of Object;

property OnStartTransfer: TStartTransferEvent read FOnStartTransfer write FOnStartTransfer;

Remarks

This event is fired first when the client starts sending data to the server (in a POST or PUT request) and then when the document text starts transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

TokenAuthentication Event (AS4Client Component)

Fired when the server makes use of UsernameToken authentication.

Syntax

type TTokenAuthenticationEvent = procedure (
  Sender: TObject;
  const User: String;
  var Password: String;
  const PasswordType: String;
  var Accept: Boolean
) of Object;

property OnTokenAuthentication: TTokenAuthenticationEvent read FOnTokenAuthentication write FOnTokenAuthentication;

Remarks

This event fires when a server sends a response that includes UsernameToken authentication. This is typically only used by servers when sending a pull response.

User identifies the user.

Password should be set from within the event if PasswordType is 0 (digest). This parameter can be read when PasswordType is 1 (text).

PasswordType specifies the type of password. Possible values are:

• 0 (Digest)
• 1 (Text)

Accept may be set to manually accept the request.

When PasswordType is 0 (Digest) set the Password parameter to the plaintext password. Do not set Accept The component will hash the provided password value and compare it to the value in the request. If it matched the component will accept the request. If it does not match the component will populate Errors with an error indicating authentication has failed.

When PasswordType is 1 (Text) the Password parameter will hold the exact value received in the request. Inspect Password and determine whether to accept the request. To accept the request set Accept to True.

After this event fires if authentication failed Errors will contain an appropriate error. Send the errors back to the server by calling SendResponse.

Transfer Event (AS4Client Component)

Fired while a document transfers (delivers document).

Syntax

type TTransferEvent = procedure (
  Sender: TObject;
  Direction: Integer;
  BytesTransferred: Int64;
  PercentDone: Integer;
  const Text: String;
  const TextB: TBytes
) of Object;

property OnTransfer: TTransferEvent read FOnTransfer write FOnTransfer;

Remarks

The Text parameter contains the portion of the document text being received. It is empty if data are being posted to the server.

The BytesTransferred parameter contains the number of bytes transferred in this Direction since the beginning of the document text (excluding HTTP response headers).

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

The PercentDone parameter shows the progress of the transfer in the corresponding direction. If PercentDone can not be calculated the value will be -1.

Note: Events are not re-entrant. Performing time-consuming operations within this event will prevent it from firing again in a timely manner and may affect overall performance.

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

Constructors

>

constructor Create();

constructor Create(valEncoded: TBytes);

constructor Create(valStoreType: TibeCertStoreTypes; valStore: String; valStorePassword: String; valSubject: String);

constructor Create(valStoreType: TibeCertStoreTypes; valStore: TBytes; valStorePassword: String; valSubject: String);

EBData Type

The EDI payload of the AS4 message.

Remarks

The EDI payload of the AS4 message.

Fields

Constructors

constructor Create();

constructor Create(valData: TBytes; valEDIType: String);

constructor Create(valFileName: String; valEDIType: String);

EBError Type

This type defines details of the error.

Remarks

The properties below provide various information about the error.

Fields

Constructors

constructor Create();

EBPartyInfo Type

This type defines information about the party.

Remarks

The properties define information about the respective party. This is used to define both sending and receiving party information.

Fields

Constructors

constructor Create();

constructor Create(valId: String; valRole: String);

constructor Create(valId: String; valRole: String; valIdType: String);

EBProperty Type

A property of the message.

Remarks

This type holds details about the property of the message.

Fields

Constructors

constructor Create();

constructor Create(valName: String; valValue: String);

constructor Create(valName: String; valValue: String; valPropertyType: String);

EBReceipt Type

The receipt.

Remarks

This type contains properties that comprise the receipt.

Fields

Constructors

constructor Create();

constructor Create(valRefToMessageId: String; valContent: String);

Firewall Type

The firewall the component will connect through.

Remarks

When connecting through a firewall, this type is used to specify different properties of the firewall, such as the firewall Host and the FirewallType.

Fields

Constructors

constructor Create();

HTTPCookie Type

An HTTP cookie can be either sent to or received from the server.

Remarks

An HTTP cookie can store the cookies that are to be sent to the server. It also may store the cookies sent by the server.

Cookies that are to be sent to the server must have the Name and Value fields supplied before submitting the URL. When the SetCookie event is fired, however, all of the fields of an HTTPCookie are filled out accordingly.

Fields

Constructors

constructor Create();

constructor Create(valName: String; valValue: String);

Proxy Type

The proxy the component will connect to.

Remarks

When connecting through a proxy, this type is used to specify different properties of the proxy, such as the Server and the AuthScheme.

Fields

Constructors

constructor Create();

constructor Create(valServer: String; valPort: Integer);

constructor Create(valServer: String; valPort: Integer; valUser: String; valPassword: String);

Config Settings (AS4Client Component)

AS4Client Config Settings

<eb3:PartInfo href="cid:_de48eece-d1d8-4823-8a63-d3a8d14dc1a8@nsoftware">

<eb3:PartInfo href="cid:mypart@myhost">

AS4Component.Config("EDIDataPartId[0]=mypart@myhost");

HTTP Config Settings

TCPClient Config Settings

SSL Config Settings

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

Socket Config Settings

Base Config Settings

Trappable Errors (AS4Client Component)

AS4Client Errors

HTTP Errors

The component may also return one of the following error codes, which are inherited from other components.

TCPClient Errors

TCP/IP Errors