AS4Server Class

Properties   Methods   Events   Config Settings   Errors  

The AS4Server class implements an AS4 / ebHandler.

Syntax

class ipworksedi.AS4Server

Remarks

The AS4Server class implements server-side processing of AS4 messages. It may be used to receive files form a client (push), respond to a client's request for files (pull), and also handles generating and verifying receipts.

The class is designed to be easily integrated into a HTTP server, such as ASP.NET, but may also be used outside of a web server. The examples below assume the class is used within an environment where there is an HTTP context.

To begin, when a request is received first call read_request. This reads the AS4 request from the content of the request (and optionally the request_headers_string) property. Alternatively the request data may be passed directly to the class by specifying calling set_request_stream. After calling read_request the following properties may be checked:

• agreement_ref
• as4_from
• as4_to
• conversation_id
• edi_data
• errors
• incoming_receipt
• message_id
• message_properties
• mpc
• service
• service_action
• service_type

The first step after calling read_request is to determine if the client is sending files (push) or requesting files (pull). To determine this check the value of agreement_ref and mpc. For instance: if (server.AgreementRef == "" && server.MPC != "") { //The client is requesting files from the specified MPC //No other relevant properties are populated } else //AgreementRef is not empty, and MPC is empty { //The client is sending files. AgreementRef is populated with the agreement reference. //AS4From, AS4To, ConversationId, etc are populated }

Determining if the request contains an asynchronous receipt from a previous transmission may also be done at this time by checking the incoming_receipt property's incoming_receipt_content property. If it is populated a receipt is present. To verify the receipt set async_receipt_info_dir to the directory where information about the message was originally stored and call verify_receipt. If the receipt is signed signer_cert must also be set. See the section below and also send_files for more details.

Once information about the request is determined the class may then be configured to respond appropriately depending on the operation.

Receiving Files and Sending a Receipt

When receiving files first check the agreement_ref, as4_from, and as4_to properties to determine who is sending the files and with what previously agreed upon configuration. Once this is known, if the request is signed and encrypted set certificate to the decryption certificate and signer_cert to the public certificate used for signature verification. incoming_directory may optionally be set to automatically store the incoming files. //Process incoming files and send a signed receipt server.ReadRequest(); //Inspect values from the request in order to load appropriate certificates etc. //Console.WriteLine(server.AgreementRef); //Console.WriteLine(server.AS4From.Id); //Console.WriteLine(server.AS4To.Id);) server.IncomingDirectory = "..\\MyFiles"; //Our private certificate. Used to decrypt the incoming file server.Certificate = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); //Partner's public certificate. Used to verify the signature on the incoming message and files. server.SignerCert = new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer")); server.ParseRequest(); server.ReceiptReplyMode = As4serverReceiptReplyModes.rrmSync; //Our private certificate. Used to sign the receipt. server.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); server.SendResponse(); //Sends the receipt Receiving Files and Sending an Asynchronous Receipt

Receipts may be sent in the response (synchronous) or at a later time (asynchronous). If the agreement specifies that the receipt be sent asynchronously the following steps may be taken to send the receipt.

After calling read_request the receipt_reply_mode may be set to indicate the receipt will be returned asynchronously. After calling parse_request call send_ack_response to send back a HTTP 200 OK to the client. The receipt may then be returned later.

To send an asynchronous receipt AS4Client may be used. This can be sent to the partner's web site, or bundled with a later response (depending on the agreement made between the parties). In the example below AS4Client is used to send the receipt to the other party's web site.

//Process incoming files and send an asynchronous receipt server.ReadRequest(); //Inspect values from the request in order to load appropriate certificates etc. //Console.WriteLine(server.AgreementRef); //Console.WriteLine(server.AS4From.Id); //Console.WriteLine(server.AS4To.Id);) server.IncomingDirectory = "..\\MyFiles"; //Our private certificate. Used to decrypt the incoming file server.Certificate = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); //Partner's public certificate. Used to verify the signature on the incoming message and files. server.SignerCert = new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer")); server.ParseRequest(); server.ReceiptReplyMode = As4serverReceiptReplyModes.rrmAsync; //Our private certificate. Used to sign the receipt. server.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); server.SendAckResponse(); //Sends an ack, but not the receipt At this point receipt is populated with the receipt to be sent. Store the Receipt's receipt_content and receipt_ref_to_message_id values for use when sending the receipt later. Sending a receipt can be done with AS4Client.

//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();

Sending Files

To process a request to send files first check the mpc property. This holds the Message Partition Channel (MPC) from which the client would like to receive files. Next, set agreement_ref, as4_from, as4_to. Check incoming_receipt to determine if the request has a bundled receipt. If it does verify_receipt can be called to verify the receipt.

Note: If the client requests files from the default MPC then mpc may be empty. See MessageType for details.

If the client makes use of UsernameToken authentication the on_token_authentication event will fire when processing the request.

To send files back to the client simply set edi_data to the files you wish to send. When send_response is called the files will be sent back to the client.

//Process a request to send files (pull) //Holds information from the original send so that receipts can be verified later server.AsyncReceiptInfoDir = Path.Combine(Request.PhysicalApplicationPath, "..\\temp\\ReceiptInfoDir") server.Profile = As4serverProfiles.ebpfENTSOG; server.ReadRequest(); //The receipt may be signed depending upon the AgreementRef server.SignerCert = new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer")); //If the request has a bundled receipt verify it first if (!string.IsNullOrEmpty(server.IncomingReceipt.Content)) { server.VerifyReceipt(); } //If the request is a pull request (MPC is set) if (server.AgreementRef == "" && server.MPC != "") { server.AgreementRef = "http://agreements.company.com/pull_files"; server.AS4From.Id = "org:holodeckb2b:example:company:B"; server.AS4From.Role = "Sender"; server.AS4To.Id = "org:holodeckb2b:example:company:A"; server.AS4To.Role = "Receiver"; server.ReceiptReplyMode = As4serverReceiptReplyModes.rrmAsync; //Our private certificate. Used to sign the message and files. server.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); //Partner's public certificate. Used to encrypt files. server.RecipientCerts.Add(new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer"))); EBData data = new EBData(); data.EDIType = "text/xml"; data.Data = "<test>Hello AS4 World!</test>"; server.EDIData.Add(data); server.SendResponse(); }

Processing Receipts

Any incoming request may potentially include a receipt. The request may be a receipt by itself, or it may be bundled with another type of request (send/receive). When initially sending files async_receipt_info_dir may be set to store data about the original message on disk for use when verifying the receipt. If this is not desired manually store the original_soap_message and original_soap_message_id instead.

To detect if an incoming request contains a receipt simply check the incoming_receipt property's receipt_content property. If it is populated the request includes a receipt. Set async_receipt_info_dir to the same location as when the file was originally sent. Or alternatively set original_soap_message and original_soap_message_id properties to the original values.

If the receipt is signed set signer_cert to the public certificate which will be used to verify the signature. Lastly call verify_receipt. This will perform any signature verification and verify the receipt content as well, matching it to the original message values.

server.ReadRequest(); //The receipt may be signed depending upon the AgreementRef server.SignerCert = new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer")); //If the request contains a receipt verify it if (!string.IsNullOrEmpty(server.IncomingReceipt.Content)) { server.VerifyReceipt(); }

Property List

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

Method List

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

Event List

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

Config Settings

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

agreement_ref Property

The agreement reference.

Syntax

def get_agreement_ref() -> str: ...
def set_agreement_ref(value: str) -> None: ...

agreement_ref = property(get_agreement_ref, set_agreement_ref)

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 as4_from and as4_to values.

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

as4_from_id Property

The Id of the party.

Syntax

def get_as4_from_id() -> str: ...
def set_as4_from_id(value: str) -> None: ...

as4_from_id = property(get_as4_from_id, set_as4_from_id)

Default Value

""

Remarks

The Id of the party. This value is required.

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From/eb:PartyId"

as4_from_id_type Property

The optional type of the Id.

Syntax

def get_as4_from_id_type() -> str: ...
def set_as4_from_id_type(value: str) -> None: ...

as4_from_id_type = property(get_as4_from_id_type, set_as4_from_id_type)

Default Value

""

Remarks

The optional type of the Id. If specified this value should be the domain to which the Id belongs.

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From/eb:PartyId@type"

as4_from_role Property

This property specifies the role of the party.

Syntax

def get_as4_from_role() -> str: ...
def set_as4_from_role(value: str) -> None: ...

as4_from_role = property(get_as4_from_role, set_as4_from_role)

Default Value

""

Remarks

This property specifies the role of the party. This may be any value agreed upon by the trading partners.

In as4_from this specified the role of the party sending the document. The default value is "http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/initiator".

In as4_to this specifies the role of the party receiving the document. The default value is "http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/responder".

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From/eb:Role"

as4_to_id Property

The Id of the party.

Syntax

def get_as4_to_id() -> str: ...
def set_as4_to_id(value: str) -> None: ...

as4_to_id = property(get_as4_to_id, set_as4_to_id)

Default Value

""

Remarks

The Id of the party. This value is required.

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From/eb:PartyId"

as4_to_id_type Property

The optional type of the Id.

Syntax

def get_as4_to_id_type() -> str: ...
def set_as4_to_id_type(value: str) -> None: ...

as4_to_id_type = property(get_as4_to_id_type, set_as4_to_id_type)

Default Value

""

Remarks

The optional type of the Id. If specified this value should be the domain to which the Id belongs.

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From/eb:PartyId@type"

as4_to_role Property

This property specifies the role of the party.

Syntax

def get_as4_to_role() -> str: ...
def set_as4_to_role(value: str) -> None: ...

as4_to_role = property(get_as4_to_role, set_as4_to_role)

Default Value

""

Remarks

This property specifies the role of the party. This may be any value agreed upon by the trading partners.

In as4_from this specified the role of the party sending the document. The default value is "http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/initiator".

In as4_to this specifies the role of the party receiving the document. The default value is "http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/responder".

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From/eb:Role"

async_receipt_info_dir Property

A directory to hold information used for asynchronous receipt verification.

Syntax

def get_async_receipt_info_dir() -> str: ...
def set_async_receipt_info_dir(value: str) -> None: ...

async_receipt_info_dir = property(get_async_receipt_info_dir, set_async_receipt_info_dir)

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 original_soap_message and original_soap_message_id after sending a file. In this case original_soap_message and original_soap_message_id should be populated before verifying the receipt.

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

cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_cert_store() -> bytes: ...
def set_cert_store(value: bytes) -> None: ...

cert_store = property(get_cert_store, set_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The cert_store_type property denotes the type of the certificate store specified by cert_store. If the store is password-protected, specify the password in cert_store_password.

cert_store is used in conjunction with the cert_subject property to specify client certificates. If cert_store has a value, and cert_subject or cert_encoded is set, a search for a certificate is initiated. Please see the cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_cert_store_password() -> str: ...
def set_cert_store_password(value: str) -> None: ...

cert_store_password = property(get_cert_store_password, set_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_cert_store_type() -> int: ...
def set_cert_store_type(value: int) -> None: ...

cert_store_type = property(get_cert_store_type, set_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_cert_subject() -> str: ...
def set_cert_subject(value: str) -> None: ...

cert_subject = property(get_cert_subject, set_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_cert_encoded() -> bytes: ...
def set_cert_encoded(value: bytes) -> None: ...

cert_encoded = property(get_cert_encoded, set_cert_encoded)

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The cert_store and cert_subject properties also may be used to specify a certificate.

When cert_encoded is set, a search is initiated in the current cert_store for the private key of the certificate. If the key is found, cert_subject is updated to reflect the full subject of the selected certificate; otherwise, cert_subject is set to an empty string.

conversation_id Property

The Conversation Id of the message.

Syntax

def get_conversation_id() -> str: ...
def set_conversation_id(value: str) -> None: ...

conversation_id = property(get_conversation_id, set_conversation_id)

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"

edi_data_count Property

The number of records in the EDI arrays.

Syntax

def get_edi_data_count() -> int: ...
def set_edi_data_count(value: int) -> None: ...

edi_data_count = property(get_edi_data_count, set_edi_data_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• edi_data
• ediedi_type
• edi_file_name
• edi_name
• edi_property_count
• edi_property_index
• edi_property_name
• edi_property_value
• edi_schema_location
• edi_schema_namespace
• edi_schema_version

The array indices start at 0 and end at edi_data_count - 1.

edi_data Property

This property contains the EDI payload of the transmission.

Syntax

def get_edi_data(edi_data_index: int) -> bytes: ...
def set_edi_data(edi_data_index: int, value: bytes) -> None: ...

Default Value

""

Remarks

This property contains the EDI payload of the transmission.

When sending files this may be specified to the data to be sent. This can be used as an alternative to setting edi_file_name.

When receiving files this will only be populated if incoming_directory and edi_output_stream have not been specified and parse_request finishes without an error. If so, Data will contain the full decrypted text of the EDI message.

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

The edi_data_index parameter specifies the index of the item in the array. The size of the array is controlled by the edi_data_count property.

ediedi_type Property

The Content-Type of the EDI message.

Syntax

def get_ediedi_type(edi_data_index: int) -> str: ...
def set_ediedi_type(edi_data_index: int, value: str) -> None: ...

Default Value

""

Remarks

The Content-Type of the EDI message. Sample values are "application/edi-x12", "application/edifact" or "application/xml".

The edi_data_index parameter specifies the index of the item in the array. The size of the array is controlled by the edi_data_count property.

edi_file_name Property

When sending, if FileName is specified, the file specified will be used for the EDI payload of the transmission.

Syntax

def get_edi_file_name(edi_data_index: int) -> str: ...
def set_edi_file_name(edi_data_index: int, value: str) -> None: ...

Default Value

""

Remarks

When sending, if edi_file_name is specified, the file specified will be used for the EDI payload of the transmission. edi_name will be populated with the name of the file.

When receiving, if incoming_directory is set, this will be populated with the name of the file which contains the processed message contents.

Note: When edi_output_stream is set, the data will be written to the stream and this property will not be populated.

The edi_data_index parameter specifies the index of the item in the array. The size of the array is controlled by the edi_data_count property.

edi_name Property

Name is the final name to be associated with the contents of either the Data or FileName properties.

Syntax

def get_edi_name(edi_data_index: int) -> str: ...
def set_edi_name(edi_data_index: int, value: str) -> None: ...

Default Value

"rfc1767.edi"

Remarks

edi_name is the final name to be associated with the contents of either the edi_data or edi_file_name properties. This corresponds to the filename attribute of the Content-Disposition header for the EDI payload.

When constructing EDI data to be sent, edi_name will be set to the same value as edi_file_name, but can be overridden after setting edi_file_name to indicate that another name should be used in the outbound request's Content-Disposition MIME header.

When receiving EDI data, edi_name will be read out of the "filename" attribute of the inbound request's Content-Disposition MIME header.

The edi_data_index parameter specifies the index of the item in the array. The size of the array is controlled by the edi_data_count property.

edi_property_count Property

The number of properties for this file.

Syntax

def get_edi_property_count(edi_data_index: int) -> int: ...
def set_edi_property_count(edi_data_index: int, value: int) -> None: ...

Default Value

0

Remarks

The number of properties for this file.

Each file may contain zero or more properties associated with it. This property, in conjunction with edi_property_index, edi_property_name, and edi_property_value can be used to specify properties when sending and read properties when receiving.

Sending

When sending files to add properties set edi_property_count to specify the number of properties. Then set edi_property_index to select the property. Set edi_property_name and edi_property_value to define the values for the property at edi_property_index. For instance: data = new EBData(); data.EDIType = "image/jpeg"; data.FileName = "..\\1.jpg"; data.Name = "1.jpg"; data.PropertyCount = 2; //Define two properties data.PropertyIndex = 0; //Select the first property data.PropertyName = "name1"; data.PropertyValue = "value1"; data.PropertyIndex = 1; //Select the second property data.PropertyName = "name2"; data.PropertyValue = "value2";

Receiving

When receiving files these properties may be queried to retrieve the values set by the sender. Inspect edi_property_count to obtain the number of properties. Next set edi_property_index to select a property and query edi_property_name and edi_property_value. For instance:

for (int i = 0; i < server.EDIData[0].PropertyCount;i++) { server.EDIData[0].PropertyIndex = i; Console.WriteLine(server.EDIData[0].PropertyName + ": " + server.EDIData[0].PropertyValue); }

The edi_data_index parameter specifies the index of the item in the array. The size of the array is controlled by the edi_data_count property.

edi_property_index Property

Selects a property at the specified index.

Syntax

def get_edi_property_index(edi_data_index: int) -> int: ...
def set_edi_property_index(edi_data_index: int, value: int) -> None: ...

Default Value

0

Remarks

Selects a property at the specified index.

The edi_data_index parameter specifies the index of the item in the array. The size of the array is controlled by the edi_data_count property.

edi_property_name Property

The name of the property.

Syntax

def get_edi_property_name(edi_data_index: int) -> str: ...
def set_edi_property_name(edi_data_index: int, value: str) -> None: ...

Default Value

""

Remarks

The name of the property.

The edi_data_index parameter specifies the index of the item in the array. The size of the array is controlled by the edi_data_count property.

edi_property_value Property

The value of the property.

Syntax

def get_edi_property_value(edi_data_index: int) -> str: ...
def set_edi_property_value(edi_data_index: int, value: str) -> None: ...

Default Value

""

Remarks

The value of the property.

The edi_data_index parameter specifies the index of the item in the array. The size of the array is controlled by the edi_data_count property.

edi_schema_location Property

The SchemaLocation , SchemaNamespace , and SchemaVersion optionally define the schema that applies to this particular file.

Syntax

def get_edi_schema_location(edi_data_index: int) -> str: ...
def set_edi_schema_location(edi_data_index: int, value: str) -> None: ...

Default Value

""

Remarks

The edi_schema_location, edi_schema_namespace, and edi_schema_version optionally define the schema that applies to this particular file. This may be used by the receiving party to properly interpret the file data.

Schema information is not required, but if schema information is included edi_schema_location is required and must be set to the URI of the schema.

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:PayloadInfo/eb:PartInfo/eb:Schema@location"

The edi_data_index parameter specifies the index of the item in the array. The size of the array is controlled by the edi_data_count property.

edi_schema_namespace Property

The namespace of the schema.

Syntax

def get_edi_schema_namespace(edi_data_index: int) -> str: ...
def set_edi_schema_namespace(edi_data_index: int, value: str) -> None: ...

Default Value

""

Remarks

The namespace of the schema. This property is optional. Refer to edi_schema_location for details.

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:PayloadInfo/eb:PartInfo/eb:Schema@namespace"

The edi_data_index parameter specifies the index of the item in the array. The size of the array is controlled by the edi_data_count property.

edi_schema_version Property

The version of the schema.

Syntax

def get_edi_schema_version(edi_data_index: int) -> str: ...
def set_edi_schema_version(edi_data_index: int, value: str) -> None: ...

Default Value

""

Remarks

The version of the schema. This property is optional. Refer to edi_schema_location for details.

This value corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:PayloadInfo/eb:PartInfo/eb:Schema@namespace"

The edi_data_index parameter specifies the index of the item in the array. The size of the array is controlled by the edi_data_count property.

encryption_algorithm Property

The algorithm used to encrypt the EDI data.

Syntax

def get_encryption_algorithm() -> str: ...
def set_encryption_algorithm(value: str) -> None: ...

encryption_algorithm = property(get_encryption_algorithm, set_encryption_algorithm)

Default Value

"AES128GCM"

Remarks

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

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

The class 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

error_count Property

The number of records in the Error arrays.

Syntax

def get_error_count() -> int: ...
def set_error_count(value: int) -> None: ...

error_count = property(get_error_count, set_error_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• error_category
• error_code
• error_description
• error_detail
• error_origin
• error_ref_message_id
• error_severity
• error_short_description

The array indices start at 0 and end at error_count - 1.

error_category Property

The category of error.

Syntax

def get_error_category(error_index: int) -> str: ...
def set_error_category(error_index: int, value: str) -> None: ...

Default Value

""

Remarks

The category of error. Typical values include "Content", "Packaging", "UnPackaging", "Communication", and "InternalProcess". This value is optional.

The error_index parameter specifies the index of the item in the array. The size of the array is controlled by the error_count property.

error_code Property

The error code.

Syntax

def get_error_code(error_index: int) -> str: ...
def set_error_code(error_index: int, value: str) -> None: ...

Default Value

""

Remarks

The error code. This value is required. The standard format is "EBMS:0001", where "0001" is the numeric code portion.

The error_index parameter specifies the index of the item in the array. The size of the array is controlled by the error_count property.

error_description Property

The description of the error.

Syntax

def get_error_description(error_index: int) -> str: ...
def set_error_description(error_index: int, value: str) -> None: ...

Default Value

""

Remarks

The description of the error. This value is optional.

The error_index parameter specifies the index of the item in the array. The size of the array is controlled by the error_count property.

error_detail Property

Additional details about the error.

Syntax

def get_error_detail(error_index: int) -> str: ...
def set_error_detail(error_index: int, value: str) -> None: ...

Default Value

""

Remarks

Additional details about the error. This may include other helpful information such as a stack trace. This value is optional.

The error_index parameter specifies the index of the item in the array. The size of the array is controlled by the error_count property.

error_origin Property

The module within which the error occurred.

Syntax

def get_error_origin(error_index: int) -> str: ...
def set_error_origin(error_index: int, value: str) -> None: ...

Default Value

""

Remarks

The module within which the error occurred. Typical values include "ebMS", "reliability", and "security". This value is optional.

The error_index parameter specifies the index of the item in the array. The size of the array is controlled by the error_count property.

error_ref_message_id Property

The MessageId to which the error applies.

Syntax

def get_error_ref_message_id(error_index: int) -> str: ...
def set_error_ref_message_id(error_index: int, value: str) -> None: ...

Default Value

""

Remarks

The MessageId to which the error applies. This is optional but should be supplied if possible.

The error_index parameter specifies the index of the item in the array. The size of the array is controlled by the error_count property.

error_severity Property

The severity of the error.

Syntax

def get_error_severity(error_index: int) -> int: ...
def set_error_severity(error_index: int, value: int) -> None: ...

Default Value

0

Remarks

The severity of the error. Possible values are:

• 0 (ebstWarning - default)
• 1 (ebstFailure)

The error_index parameter specifies the index of the item in the array. The size of the array is controlled by the error_count property.

error_short_description Property

A short description of the error.

Syntax

def get_error_short_description(error_index: int) -> str: ...
def set_error_short_description(error_index: int, value: str) -> None: ...

Default Value

""

Remarks

A short description of the error. This may be helpful for logging or readability. This value is optional.

The error_index parameter specifies the index of the item in the array. The size of the array is controlled by the error_count property.

incoming_directory Property

The directory to which incoming files are saved.

Syntax

def get_incoming_directory() -> str: ...
def set_incoming_directory(value: str) -> None: ...

incoming_directory = property(get_incoming_directory, set_incoming_directory)

Default Value

""

Remarks

If incoming_directory 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 edi_data.

incoming_receipt_content Property

The content of the receipt.

Syntax

def get_incoming_receipt_content() -> str: ...

incoming_receipt_content = property(get_incoming_receipt_content, None)

Default Value

""

Remarks

The content of the receipt. This is the raw XML of the receipt.

The class will automatically create the receipt, and verify the receipt, depending on the method called. In most cases this is simply informational and may be stored for logging purposes if desired.

This property is read-only.

incoming_receipt_ref_to_message_id Property

The Message Id to which this receipt applies.

Syntax

def get_incoming_receipt_ref_to_message_id() -> str: ...

incoming_receipt_ref_to_message_id = property(get_incoming_receipt_ref_to_message_id, None)

Default Value

""

Remarks

The Message Id to which this receipt applies. This is the original Message Id from the initial transmission of the file. This allows the receipt to be correlated with the original transmission.

The class will automatically create the receipt, and verify the receipt, depending on the method called. In most cases this is simply informational and may be stored for logging purposes if desired.

This property is read-only.

log_directory Property

The path to a directory for logging.

Syntax

def get_log_directory() -> str: ...
def set_log_directory(value: str) -> None: ...

log_directory = property(get_log_directory, set_log_directory)

Default Value

""

Remarks

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

The class 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. log_directory supports several macros that can be used to specify a unique directory path. If the path specified does not already exist, the class will attempt to create the directory. The following macros are supported:

The filenames will be chosen automatically by the class. 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 log_file will contain the name of the files just written, minus the extension.

If logs cannot be written an exception will be thrown.

log_file Property

The log file written.

Syntax

def get_log_file() -> str: ...

log_file = property(get_log_file, None)

Default Value

""

Remarks

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

The class 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. log_directory supports several macros that can be used to specify a unique directory path. If the path specified does not already exist, the class will attempt to create the directory. The following macros are supported:

The filenames will be chosen automatically by the class. 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 log_file 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.

message_id Property

The unique Id of the message.

Syntax

def get_message_id() -> str: ...
def set_message_id(value: str) -> None: ...

message_id = property(get_message_id, set_message_id)

Default Value

""

Remarks

This property defines the unique Id of the message. When sending files the class 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 send_files. In AS4Server this may be set after calling read_request and before calling send_response.

message_property_count Property

The number of records in the MessageProperty arrays.

Syntax

def get_message_property_count() -> int: ...
def set_message_property_count(value: int) -> None: ...

message_property_count = property(get_message_property_count, set_message_property_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• message_property_name
• message_property_property_type
• message_property_value

The array indices start at 0 and end at message_property_count - 1.

message_property_name Property

This property defines the name of the message property.

Syntax

def get_message_property_name(message_property_index: int) -> str: ...
def set_message_property_name(message_property_index: int, value: str) -> None: ...

Default Value

""

Remarks

This property defines the name of the message property. This is required.

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

The message_property_index parameter specifies the index of the item in the array. The size of the array is controlled by the message_property_count property.

message_property_property_type Property

The optional type of the message property.

Syntax

def get_message_property_property_type(message_property_index: int) -> str: ...
def set_message_property_property_type(message_property_index: int, value: str) -> None: ...

Default Value

""

Remarks

The optional type of the message property.

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

The message_property_index parameter specifies the index of the item in the array. The size of the array is controlled by the message_property_count property.

message_property_value Property

The value of the message property.

Syntax

def get_message_property_value(message_property_index: int) -> str: ...
def set_message_property_value(message_property_index: int, value: str) -> None: ...

Default Value

""

Remarks

The value of the message property.

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

The message_property_index parameter specifies the index of the item in the array. The size of the array is controlled by the message_property_count property.

mpc Property

The MPC (Message Partition Channel) from which files are requested.

Syntax

def get_mpc() -> str: ...
def set_mpc(value: str) -> None: ...

mpc = property(get_mpc, set_mpc)

Default Value

""

Remarks

This property specifies the MPC (Message Partition Channel) from which to receive files. This must be set before calling receive_files. 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"

This property defines the MPC (Message Partition Channel) from which the client requests files. This is populated after calling read_request and is used to determine from which channel to provide files to the client.

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

original_soap_message Property

The original SOAP message used to verify the receipt.

Syntax

def get_original_soap_message() -> str: ...
def set_original_soap_message(value: str) -> None: ...

original_soap_message = property(get_original_soap_message, set_original_soap_message)

Default Value

""

Remarks

original_soap_message and original_soap_message_id may be used as an alternative to async_receipt_info_dir when verifying receipts.

If async_receipt_info_dir 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.

original_soap_message_id Property

The original SOAP message Id used to verify the receipt.

Syntax

def get_original_soap_message_id() -> str: ...
def set_original_soap_message_id(value: str) -> None: ...

original_soap_message_id = property(get_original_soap_message_id, set_original_soap_message_id)

Default Value

""

Remarks

original_soap_message and original_soap_message_id may be used as an alternative to async_receipt_info_dir when verifying receipts.

If async_receipt_info_dir 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.

profile Property

The AS4 profile.

Syntax

def get_profile() -> int: ...
def set_profile(value: int) -> None: ...

profile = property(get_profile, set_profile)

Default Value

0

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:

receipt_content Property

The content of the receipt.

Syntax

def get_receipt_content() -> str: ...
def set_receipt_content(value: str) -> None: ...

receipt_content = property(get_receipt_content, set_receipt_content)

Default Value

""

Remarks

The content of the receipt. This is the raw XML of the receipt.

The class will automatically create the receipt, and verify the receipt, depending on the method called. In most cases this is simply informational and may be stored for logging purposes if desired.

receipt_ref_to_message_id Property

The Message Id to which this receipt applies.

Syntax

def get_receipt_ref_to_message_id() -> str: ...
def set_receipt_ref_to_message_id(value: str) -> None: ...

receipt_ref_to_message_id = property(get_receipt_ref_to_message_id, set_receipt_ref_to_message_id)

Default Value

""

Remarks

The Message Id to which this receipt applies. This is the original Message Id from the initial transmission of the file. This allows the receipt to be correlated with the original transmission.

The class will automatically create the receipt, and verify the receipt, depending on the method called. In most cases this is simply informational and may be stored for logging purposes if desired.

receipt_reply_mode Property

The expected receipt reply mode.

Syntax

def get_receipt_reply_mode() -> int: ...
def set_receipt_reply_mode(value: int) -> None: ...

receipt_reply_mode = property(get_receipt_reply_mode, set_receipt_reply_mode)

Default Value

0

Remarks

This setting tells the class 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 class can build a valid message. This should be set to the previously agreed upon value between the parties in the agreement identified by agreement_ref

recipient_cert_count Property

The number of records in the RecipientCert arrays.

Syntax

def get_recipient_cert_count() -> int: ...
def set_recipient_cert_count(value: int) -> None: ...

recipient_cert_count = property(get_recipient_cert_count, set_recipient_cert_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• recipient_cert_encoded

The array indices start at 0 and end at recipient_cert_count - 1.

recipient_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_recipient_cert_encoded(recipient_cert_index: int) -> bytes: ...
def set_recipient_cert_encoded(recipient_cert_index: int, value: bytes) -> None: ...

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The recipient_cert_store and recipient_cert_subject properties also may be used to specify a certificate.

When recipient_cert_encoded is set, a search is initiated in the current recipient_cert_store for the private key of the certificate. If the key is found, recipient_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, recipient_cert_subject is set to an empty string.

The recipient_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the recipient_cert_count property.

ref_to_message_id Property

Specifies the RefToMessageId in the message.

Syntax

def get_ref_to_message_id() -> str: ...
def set_ref_to_message_id(value: str) -> None: ...

ref_to_message_id = property(get_ref_to_message_id, set_ref_to_message_id)

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 ref_to_message_id 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.

request Property

The HTTP request to be processed.

Syntax

def get_request() -> bytes: ...
def set_request(value: bytes) -> None: ...

request = property(get_request, set_request)

Default Value

""

Remarks

The body of the request to be processed. The HTTP headers may be set separately in request_headers_string. If they are included, a double CRLF pair should be used to separate the headers from the body.

request_header_count Property

The number of records in the RequestHeader arrays.

Syntax

def get_request_header_count() -> int: ...
def set_request_header_count(value: int) -> None: ...

request_header_count = property(get_request_header_count, set_request_header_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• request_header_field
• request_header_value

The array indices start at 0 and end at request_header_count - 1.

request_header_field Property

This property contains the name of the HTTP header (this is the same case as it is delivered).

Syntax

def get_request_header_field(request_header_index: int) -> str: ...
def set_request_header_field(request_header_index: int, value: str) -> None: ...

Default Value

""

Remarks

This property contains the name of the HTTP Header (this is the same case as it is delivered).

The request_header_index parameter specifies the index of the item in the array. The size of the array is controlled by the request_header_count property.

request_header_value Property

This property contains the header contents.

Syntax

def get_request_header_value(request_header_index: int) -> str: ...
def set_request_header_value(request_header_index: int, value: str) -> None: ...

Default Value

""

Remarks

This property contains the Header contents.

The request_header_index parameter specifies the index of the item in the array. The size of the array is controlled by the request_header_count property.

request_headers_string Property

The HTTP headers in the AS4 request.

Syntax

def get_request_headers_string() -> str: ...
def set_request_headers_string(value: str) -> None: ...

request_headers_string = property(get_request_headers_string, set_request_headers_string)

Default Value

""

Remarks

The entire list of headers, concatenated into a single string. These will include all HTTP headers. Specific headers may be accessed through request_headers.

rollover_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_rollover_cert_store() -> bytes: ...
def set_rollover_cert_store(value: bytes) -> None: ...

rollover_cert_store = property(get_rollover_cert_store, set_rollover_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The rollover_cert_store_type property denotes the type of the certificate store specified by rollover_cert_store. If the store is password-protected, specify the password in rollover_cert_store_password.

rollover_cert_store is used in conjunction with the rollover_cert_subject property to specify client certificates. If rollover_cert_store has a value, and rollover_cert_subject or rollover_cert_encoded is set, a search for a certificate is initiated. Please see the rollover_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

rollover_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_rollover_cert_store_password() -> str: ...
def set_rollover_cert_store_password(value: str) -> None: ...

rollover_cert_store_password = property(get_rollover_cert_store_password, set_rollover_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

rollover_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_rollover_cert_store_type() -> int: ...
def set_rollover_cert_store_type(value: int) -> None: ...

rollover_cert_store_type = property(get_rollover_cert_store_type, set_rollover_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

rollover_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_rollover_cert_subject() -> str: ...
def set_rollover_cert_subject(value: str) -> None: ...

rollover_cert_subject = property(get_rollover_cert_subject, set_rollover_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

rollover_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_rollover_cert_encoded() -> bytes: ...
def set_rollover_cert_encoded(value: bytes) -> None: ...

rollover_cert_encoded = property(get_rollover_cert_encoded, set_rollover_cert_encoded)

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The rollover_cert_store and rollover_cert_subject properties also may be used to specify a certificate.

When rollover_cert_encoded is set, a search is initiated in the current rollover_cert_store for the private key of the certificate. If the key is found, rollover_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, rollover_cert_subject is set to an empty string.

rollover_signing_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_rollover_signing_cert_store() -> bytes: ...
def set_rollover_signing_cert_store(value: bytes) -> None: ...

rollover_signing_cert_store = property(get_rollover_signing_cert_store, set_rollover_signing_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The rollover_signing_cert_store_type property denotes the type of the certificate store specified by rollover_signing_cert_store. If the store is password-protected, specify the password in rollover_signing_cert_store_password.

rollover_signing_cert_store is used in conjunction with the rollover_signing_cert_subject property to specify client certificates. If rollover_signing_cert_store has a value, and rollover_signing_cert_subject or rollover_signing_cert_encoded is set, a search for a certificate is initiated. Please see the rollover_signing_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

rollover_signing_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_rollover_signing_cert_store_password() -> str: ...
def set_rollover_signing_cert_store_password(value: str) -> None: ...

rollover_signing_cert_store_password = property(get_rollover_signing_cert_store_password, set_rollover_signing_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

rollover_signing_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_rollover_signing_cert_store_type() -> int: ...
def set_rollover_signing_cert_store_type(value: int) -> None: ...

rollover_signing_cert_store_type = property(get_rollover_signing_cert_store_type, set_rollover_signing_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

rollover_signing_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_rollover_signing_cert_subject() -> str: ...
def set_rollover_signing_cert_subject(value: str) -> None: ...

rollover_signing_cert_subject = property(get_rollover_signing_cert_subject, set_rollover_signing_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

rollover_signing_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_rollover_signing_cert_encoded() -> bytes: ...
def set_rollover_signing_cert_encoded(value: bytes) -> None: ...

rollover_signing_cert_encoded = property(get_rollover_signing_cert_encoded, set_rollover_signing_cert_encoded)

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The rollover_signing_cert_store and rollover_signing_cert_subject properties also may be used to specify a certificate.

When rollover_signing_cert_encoded is set, a search is initiated in the current rollover_signing_cert_store for the private key of the certificate. If the key is found, rollover_signing_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, rollover_signing_cert_subject is set to an empty string.

service Property

The service which acts on the message.

Syntax

def get_service() -> str: ...
def set_service(value: str) -> None: ...

service = property(get_service, 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"

service_action Property

The action within a service that acts on the message.

Syntax

def get_service_action() -> str: ...
def set_service_action(value: str) -> None: ...

service_action = property(get_service_action, set_service_action)

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".

service_type Property

The type of service.

Syntax

def get_service_type() -> str: ...
def set_service_type(value: str) -> None: ...

service_type = property(get_service_type, set_service_type)

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"

signature_algorithm Property

Signature algorithm to be used in the message.

Syntax

def get_signature_algorithm() -> str: ...
def set_signature_algorithm(value: str) -> None: ...

signature_algorithm = property(get_signature_algorithm, set_signature_algorithm)

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".

signer_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_signer_cert_store() -> bytes: ...
def set_signer_cert_store(value: bytes) -> None: ...

signer_cert_store = property(get_signer_cert_store, set_signer_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The signer_cert_store_type property denotes the type of the certificate store specified by signer_cert_store. If the store is password-protected, specify the password in signer_cert_store_password.

signer_cert_store is used in conjunction with the signer_cert_subject property to specify client certificates. If signer_cert_store has a value, and signer_cert_subject or signer_cert_encoded is set, a search for a certificate is initiated. Please see the signer_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

signer_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_signer_cert_store_password() -> str: ...
def set_signer_cert_store_password(value: str) -> None: ...

signer_cert_store_password = property(get_signer_cert_store_password, set_signer_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

signer_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_signer_cert_store_type() -> int: ...
def set_signer_cert_store_type(value: int) -> None: ...

signer_cert_store_type = property(get_signer_cert_store_type, set_signer_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

signer_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_signer_cert_subject() -> str: ...
def set_signer_cert_subject(value: str) -> None: ...

signer_cert_subject = property(get_signer_cert_subject, set_signer_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

signer_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_signer_cert_encoded() -> bytes: ...
def set_signer_cert_encoded(value: bytes) -> None: ...

signer_cert_encoded = property(get_signer_cert_encoded, set_signer_cert_encoded)

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The signer_cert_store and signer_cert_subject properties also may be used to specify a certificate.

When signer_cert_encoded is set, a search is initiated in the current signer_cert_store for the private key of the certificate. If the key is found, signer_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, signer_cert_subject is set to an empty string.

signing_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_signing_cert_store() -> bytes: ...
def set_signing_cert_store(value: bytes) -> None: ...

signing_cert_store = property(get_signing_cert_store, set_signing_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The signing_cert_store_type property denotes the type of the certificate store specified by signing_cert_store. If the store is password-protected, specify the password in signing_cert_store_password.

signing_cert_store is used in conjunction with the signing_cert_subject property to specify client certificates. If signing_cert_store has a value, and signing_cert_subject or signing_cert_encoded is set, a search for a certificate is initiated. Please see the signing_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

signing_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_signing_cert_store_password() -> str: ...
def set_signing_cert_store_password(value: str) -> None: ...

signing_cert_store_password = property(get_signing_cert_store_password, set_signing_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

signing_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_signing_cert_store_type() -> int: ...
def set_signing_cert_store_type(value: int) -> None: ...

signing_cert_store_type = property(get_signing_cert_store_type, set_signing_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

signing_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_signing_cert_subject() -> str: ...
def set_signing_cert_subject(value: str) -> None: ...

signing_cert_subject = property(get_signing_cert_subject, set_signing_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

signing_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_signing_cert_encoded() -> bytes: ...
def set_signing_cert_encoded(value: bytes) -> None: ...

signing_cert_encoded = property(get_signing_cert_encoded, set_signing_cert_encoded)

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The signing_cert_store and signing_cert_subject properties also may be used to specify a certificate.

When signing_cert_encoded is set, a search is initiated in the current signing_cert_store for the private key of the certificate. If the key is found, signing_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, signing_cert_subject is set to an empty string.

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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.

do_events Method

This method processes events from the internal message queue.

Syntax

def do_events() -> None: ...

Remarks

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

interrupt Method

This method interrupts the current method.

Syntax

def interrupt() -> None: ...

Remarks

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

parse_request Method

Parses and processes the message.

Syntax

def parse_request() -> None: ...

Remarks

This method processes the message in the request. If the message is encrypted, it will be decrypted. If the message is signed, the signature will be verified. This method should be called after calling read_request and specifying any necessary certificates for the operation to complete successfully.

Receiving Files and Sending a Receipt

When receiving files first check the agreement_ref, as4_from, and as4_to properties to determine who is sending the files and with what previously agreed upon configuration. Once this is known, if the request is signed and encrypted set certificate to the decryption certificate and signer_cert to the public certificate used for signature verification. incoming_directory may optionally be set to automatically store the incoming files. //Process incoming files and send a signed receipt server.ReadRequest(); //Inspect values from the request in order to load appropriate certificates etc. //Console.WriteLine(server.AgreementRef); //Console.WriteLine(server.AS4From.Id); //Console.WriteLine(server.AS4To.Id);) server.IncomingDirectory = "..\\MyFiles"; //Our private certificate. Used to decrypt the incoming file server.Certificate = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); //Partner's public certificate. Used to verify the signature on the incoming message and files. server.SignerCert = new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer")); server.ParseRequest(); server.ReceiptReplyMode = As4serverReceiptReplyModes.rrmSync; //Our private certificate. Used to sign the receipt. server.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); server.SendResponse(); //Sends the receipt Receiving Files and Sending an Asynchronous Receipt

Receipts may be sent in the response (synchronous) or at a later time (asynchronous). If the agreement specifies that the receipt be sent asynchronously the following steps may be taken to send the receipt.

After calling read_request the receipt_reply_mode may be set to indicate the receipt will be returned asynchronously. After calling parse_request call send_ack_response to send back a HTTP 200 OK to the client. The receipt may then be returned later.

To send an asynchronous receipt AS4Client may be used. This can be sent to the partner's web site, or bundled with a later response (depending on the agreement made between the parties). In the example below AS4Client is used to send the receipt to the other party's web site.

//Process incoming files and send an asynchronous receipt server.ReadRequest(); //Inspect values from the request in order to load appropriate certificates etc. //Console.WriteLine(server.AgreementRef); //Console.WriteLine(server.AS4From.Id); //Console.WriteLine(server.AS4To.Id);) server.IncomingDirectory = "..\\MyFiles"; //Our private certificate. Used to decrypt the incoming file server.Certificate = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); //Partner's public certificate. Used to verify the signature on the incoming message and files. server.SignerCert = new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer")); server.ParseRequest(); server.ReceiptReplyMode = As4serverReceiptReplyModes.rrmAsync; //Our private certificate. Used to sign the receipt. server.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); server.SendAckResponse(); //Sends an ack, but not the receipt At this point receipt is populated with the receipt to be sent. Store the Receipt's receipt_content and receipt_ref_to_message_id values for use when sending the receipt later. Sending a receipt can be done with AS4Client.

//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();

Sending Files

To process a request to send files first check the mpc property. This holds the Message Partition Channel (MPC) from which the client would like to receive files. Next, set agreement_ref, as4_from, as4_to. Check incoming_receipt to determine if the request has a bundled receipt. If it does verify_receipt can be called to verify the receipt.

Note: If the client requests files from the default MPC then mpc may be empty. See MessageType for details.

If the client makes use of UsernameToken authentication the on_token_authentication event will fire when processing the request.

To send files back to the client simply set edi_data to the files you wish to send. When send_response is called the files will be sent back to the client.

//Process a request to send files (pull) //Holds information from the original send so that receipts can be verified later server.AsyncReceiptInfoDir = Path.Combine(Request.PhysicalApplicationPath, "..\\temp\\ReceiptInfoDir") server.Profile = As4serverProfiles.ebpfENTSOG; server.ReadRequest(); //The receipt may be signed depending upon the AgreementRef server.SignerCert = new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer")); //If the request has a bundled receipt verify it first if (!string.IsNullOrEmpty(server.IncomingReceipt.Content)) { server.VerifyReceipt(); } //If the request is a pull request (MPC is set) if (server.AgreementRef == "" && server.MPC != "") { server.AgreementRef = "http://agreements.company.com/pull_files"; server.AS4From.Id = "org:holodeckb2b:example:company:B"; server.AS4From.Role = "Sender"; server.AS4To.Id = "org:holodeckb2b:example:company:A"; server.AS4To.Role = "Receiver"; server.ReceiptReplyMode = As4serverReceiptReplyModes.rrmAsync; //Our private certificate. Used to sign the message and files. server.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); //Partner's public certificate. Used to encrypt files. server.RecipientCerts.Add(new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer"))); EBData data = new EBData(); data.EDIType = "text/xml"; data.Data = "<test>Hello AS4 World!</test>"; server.EDIData.Add(data); server.SendResponse(); }

read_request Method

Reads the AS4 request.

Syntax

def read_request() -> None: ...

Remarks

To begin, when a request is received first call read_request. This reads the AS4 request from the content of the request (and optionally the request_headers_string) property. Alternatively the request data may be passed directly to the class by specifying calling set_request_stream. After calling read_request the following properties may be checked:

• agreement_ref
• as4_from
• as4_to
• conversation_id
• edi_data
• errors
• incoming_receipt
• message_id
• message_properties
• mpc
• service
• service_action
• service_type

The first step after calling read_request is to determine if the client is sending files (push) or requesting files (pull). To determine this check the value of agreement_ref and mpc. For instance: if (server.AgreementRef == "" && server.MPC != "") { //The client is requesting files from the specified MPC //No other relevant properties are populated } else //AgreementRef is not empty, and MPC is empty { //The client is sending files. AgreementRef is populated with the agreement reference. //AS4From, AS4To, ConversationId, etc are populated }

Determining if the request contains an asynchronous receipt from a previous transmission may also be done at this time by checking the incoming_receipt property's incoming_receipt_content property. If it is populated a receipt is present. To verify the receipt set async_receipt_info_dir to the directory where information about the message was originally stored and call verify_receipt. If the receipt is signed signer_cert must also be set. See the section below and also send_files for more details.

Once information about the request is determined the class may then be configured to respond appropriately depending on the operation.

reset Method

Resets the state of the control.

Syntax

def reset() -> None: ...

Remarks

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

send_ack_response Method

Sends an acknowledgement of the request only.

Syntax

def send_ack_response() -> None: ...

Remarks

This method is used to respond to a client who sends a file and the agreement dictates that the receipt be returned asynchronously. In this case no receipt should be returned to the client. This method will send an acknowledgment only (no receipt) to the client to indicate that the request was received and processed.

This method is only applicable when receipt_reply_mode is set to rrmAsync.

send_response Method

This method sends the response over the current HTTP context.

Syntax

def send_response() -> None: ...

Remarks

This method sends the response. This should be called after parse_request to deliver the response to the client.

Receiving Files and Sending a Receipt

When receiving files first check the agreement_ref, as4_from, and as4_to properties to determine who is sending the files and with what previously agreed upon configuration. Once this is known, if the request is signed and encrypted set certificate to the decryption certificate and signer_cert to the public certificate used for signature verification. incoming_directory may optionally be set to automatically store the incoming files. //Process incoming files and send a signed receipt server.ReadRequest(); //Inspect values from the request in order to load appropriate certificates etc. //Console.WriteLine(server.AgreementRef); //Console.WriteLine(server.AS4From.Id); //Console.WriteLine(server.AS4To.Id);) server.IncomingDirectory = "..\\MyFiles"; //Our private certificate. Used to decrypt the incoming file server.Certificate = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); //Partner's public certificate. Used to verify the signature on the incoming message and files. server.SignerCert = new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer")); server.ParseRequest(); server.ReceiptReplyMode = As4serverReceiptReplyModes.rrmSync; //Our private certificate. Used to sign the receipt. server.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); server.SendResponse(); //Sends the receipt Receiving Files and Sending an Asynchronous Receipt

Receipts may be sent in the response (synchronous) or at a later time (asynchronous). If the agreement specifies that the receipt be sent asynchronously the following steps may be taken to send the receipt.

After calling read_request the receipt_reply_mode may be set to indicate the receipt will be returned asynchronously. After calling parse_request call send_ack_response to send back a HTTP 200 OK to the client. The receipt may then be returned later.

To send an asynchronous receipt AS4Client may be used. This can be sent to the partner's web site, or bundled with a later response (depending on the agreement made between the parties). In the example below AS4Client is used to send the receipt to the other party's web site.

//Process incoming files and send an asynchronous receipt server.ReadRequest(); //Inspect values from the request in order to load appropriate certificates etc. //Console.WriteLine(server.AgreementRef); //Console.WriteLine(server.AS4From.Id); //Console.WriteLine(server.AS4To.Id);) server.IncomingDirectory = "..\\MyFiles"; //Our private certificate. Used to decrypt the incoming file server.Certificate = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); //Partner's public certificate. Used to verify the signature on the incoming message and files. server.SignerCert = new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer")); server.ParseRequest(); server.ReceiptReplyMode = As4serverReceiptReplyModes.rrmAsync; //Our private certificate. Used to sign the receipt. server.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); server.SendAckResponse(); //Sends an ack, but not the receipt At this point receipt is populated with the receipt to be sent. Store the Receipt's receipt_content and receipt_ref_to_message_id values for use when sending the receipt later. Sending a receipt can be done with AS4Client.

//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();

Sending Files

To process a request to send files first check the mpc property. This holds the Message Partition Channel (MPC) from which the client would like to receive files. Next, set agreement_ref, as4_from, as4_to. Check incoming_receipt to determine if the request has a bundled receipt. If it does verify_receipt can be called to verify the receipt.

Note: If the client requests files from the default MPC then mpc may be empty. See MessageType for details.

If the client makes use of UsernameToken authentication the on_token_authentication event will fire when processing the request.

To send files back to the client simply set edi_data to the files you wish to send. When send_response is called the files will be sent back to the client.

//Process a request to send files (pull) //Holds information from the original send so that receipts can be verified later server.AsyncReceiptInfoDir = Path.Combine(Request.PhysicalApplicationPath, "..\\temp\\ReceiptInfoDir") server.Profile = As4serverProfiles.ebpfENTSOG; server.ReadRequest(); //The receipt may be signed depending upon the AgreementRef server.SignerCert = new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer")); //If the request has a bundled receipt verify it first if (!string.IsNullOrEmpty(server.IncomingReceipt.Content)) { server.VerifyReceipt(); } //If the request is a pull request (MPC is set) if (server.AgreementRef == "" && server.MPC != "") { server.AgreementRef = "http://agreements.company.com/pull_files"; server.AS4From.Id = "org:holodeckb2b:example:company:B"; server.AS4From.Role = "Sender"; server.AS4To.Id = "org:holodeckb2b:example:company:A"; server.AS4To.Role = "Receiver"; server.ReceiptReplyMode = As4serverReceiptReplyModes.rrmAsync; //Our private certificate. Used to sign the message and files. server.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyB.pfx"), "password", "*"); //Partner's public certificate. Used to encrypt files. server.RecipientCerts.Add(new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer"))); EBData data = new EBData(); data.EDIType = "text/xml"; data.Data = "<test>Hello AS4 World!</test>"; server.EDIData.Add(data); server.SendResponse(); }

verify_receipt Method

Verifies a received receipt.

Syntax

def verify_receipt() -> None: ...

Remarks

This method is used to verify asynchronous receipts held in incoming_receipt.

Processing Receipts

Any incoming request may potentially include a receipt. The request may be a receipt by itself, or it may be bundled with another type of request (send/receive). When initially sending files async_receipt_info_dir may be set to store data about the original message on disk for use when verifying the receipt. If this is not desired manually store the original_soap_message and original_soap_message_id instead.

To detect if an incoming request contains a receipt simply check the incoming_receipt property's receipt_content property. If it is populated the request includes a receipt. Set async_receipt_info_dir to the same location as when the file was originally sent. Or alternatively set original_soap_message and original_soap_message_id properties to the original values.

If the receipt is signed set signer_cert to the public certificate which will be used to verify the signature. Lastly call verify_receipt. This will perform any signature verification and verify the receipt content as well, matching it to the original message values.

server.ReadRequest(); //The receipt may be signed depending upon the AgreementRef server.SignerCert = new Certificate(Path.Combine(Request.PhysicalApplicationPath, "..\\files\\CompanyA.cer")); //If the request contains a receipt verify it if (!string.IsNullOrEmpty(server.IncomingReceipt.Content)) { server.VerifyReceipt(); }

on_error Event

Fired when information is available about errors during data delivery.

Syntax

class AS4ServerErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class AS4Server:
@property
def on_error() -> Callable[[AS4ServerErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[AS4ServerErrorEventParams], None]) -> None: ...

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

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.

on_log Event

Fired with log information while processing a message.

Syntax

class AS4ServerLogEventParams(object):
  @property
  def log_type() -> str: ...

  @property
  def log_message() -> str: ...

# In class AS4Server:
@property
def on_log() -> Callable[[AS4ServerLogEventParams], None]: ...
@on_log.setter
def on_log(event_hook: Callable[[AS4ServerLogEventParams], None]) -> None: ...

Remarks

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

Log messages available through this event correspond to log files written to log_directory. This event provides a way to obtain log messages without relying on files on disk. This event fires regardless of the value of log_directory (i.e. when log_directory 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:

on_recipient_info Event

Fired for each recipient certificate of the encrypted message.

Syntax

class AS4ServerRecipientInfoEventParams(object):
  @property
  def issuer() -> str: ...

  @property
  def serial_number() -> str: ...

  @property
  def subject_key_identifier() -> str: ...

  @property
  def encryption_algorithm() -> str: ...

# In class AS4Server:
@property
def on_recipient_info() -> Callable[[AS4ServerRecipientInfoEventParams], None]: ...
@on_recipient_info.setter
def on_recipient_info(event_hook: Callable[[AS4ServerRecipientInfoEventParams], None]) -> None: ...

Remarks

When parse_request 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"

on_signer_cert_info Event

This event is fired during verification of the signed message.

Syntax

class AS4ServerSignerCertInfoEventParams(object):
  @property
  def issuer() -> str: ...

  @property
  def serial_number() -> str: ...

  @property
  def subject_key_identifier() -> str: ...

  @property
  def cert_encoded() -> bytes: ...

# In class AS4Server:
@property
def on_signer_cert_info() -> Callable[[AS4ServerSignerCertInfoEventParams], None]: ...
@on_signer_cert_info.setter
def on_signer_cert_info(event_hook: Callable[[AS4ServerSignerCertInfoEventParams], None]) -> None: ...

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 signer_cert 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 class will automatically use this value to perform signature verification.

The signer_cert 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.

on_token_authentication Event

Fired when the client makes use of UsernameToken authentication.

Syntax

class AS4ServerTokenAuthenticationEventParams(object):
  @property
  def user() -> str: ...

  @property
  def password() -> str: ...
  @password.setter
  def password(value) -> None: ...

  @property
  def password_type() -> str: ...

  @property
  def accept() -> bool: ...
  @accept.setter
  def accept(value) -> None: ...

# In class AS4Server:
@property
def on_token_authentication() -> Callable[[AS4ServerTokenAuthenticationEventParams], None]: ...
@on_token_authentication.setter
def on_token_authentication(event_hook: Callable[[AS4ServerTokenAuthenticationEventParams], None]) -> None: ...

Remarks

This event fires when a client sends a request that includes UsernameToken authentication. This is typically only used by clients initiating a pull request.

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 class will hash the provided password value and compare it to the value in the request. If it matched the class will accept the request. If it does not match the class 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 client by calling send_response.

AS4Server Config Settings

AS4Server 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

AS4Server Errors

AS4Server Errors

HTTP Errors

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

TCPClient Errors

TCP/IP Errors