IPWorks EDI 2020 Delphi Edition

Questions / Feedback?

AS2Receiver Component

Properties   Methods   Events   Configuration Settings   Errors  

The AS2Receiver component is used to process EDI messages and generate receipts.

Syntax

TibeAS2Receiver

Remarks

The AS2Receiver implements server-side processing of EDI messages, as specified in [AS2] and RFC 3335. It can be used to decrypt and verify incoming messages and to generate receipts including Message Disposition Notifications (MDNs). The component is designed to be easily incorporated into an HTTP server, and features custom functionality for server environments such as ASP.NET.

BASIC OPERATION

When an AS2 request comes in, you should first invoke ReadRequest. This will populate AS2From and AS2To, and based on this information, you may then set the appropriate certificates. You may specify your certificate with the Certificate property, and your trading partner's (signing) certificate with the SignerCert property.

Then, invoke ProcessRequest to process the request and generate the MDN receipt as specified in [AS2] and RFC 3335. If the request was processed successfully, EDIData will contain the transmitted EDI data. If a problem occurred, EDIData will not be populated and an exception will be thrown. In either case MDNReceipt will contain the RFC-compliant receipt, which should be returned to the client.

The MDNReceipt may be returned by invoking SendResponse. The receipt will be returned either synchronously in the HTTP reply, or asynchronously over a separate HTTP, HTTPS, or SMTP connection, as requested by the client.

To create log files, set LogDirectory prior to invoking ProcessRequest. This will log all incoming and outgoing data.

The following example illustrates how to use the component from an ASP.NET page. Note that in Java it will be necessary to provide an HTTPServletRequest as an argument to ReadRequest before processing the request.

EXAMPLE

AS2Receiver1.ReadRequest();
// At this point, you should check the values of AS2From and AS2To.
AS2Receiver1.Certificate = new Certificate(CertStoreTypes.cstPFXFile, "c:\\my_server_directory\\my_pfx_file.pfx", "my password", "CN=Me");
AS2Receiver1.SignerCert = new Certificate("c:\\my_server_directory\\my_partner_cer_file.cer");
AS2Receiver1.LogDirectory = "c:\\my_server_directory\\my_log_directory";
AS2Receiver1.ProcessRequest();
AS2Receiver1.SendResponse();
Additional functionality allows the user to examine details of the client's request, to permit certain types of errors, or to customize the outgoing MDN.

ADVANCED FUNCTIONALITY

Advanced functionality is provided to allow the user to break down the AS2 process, and to allow finer control over the operation of the server. Where ProcessRequest automates the entire process, additional methods are also provided to handle each step separately.

Parsing Incoming Data

To process an EDI message, invoke ReadRequest to process the headers from the server, or alternatively, manually set Request to the contents of the HTTP request. It may contain both headers and body, or the headers may be specified separately in RequestHeaders. This will provide more information about the client's request, without attempting to read the underlying EDI data.

After invoking ReadRequest, the AS2From, AS2To, and MessageId properties will contain the appropriate values. MDNTo will contain a nonempty string if an MDN is requested; RequestedSignatureProtocol, RequestedMICAlgorithms, and ReceiptDeliveryOption provide more information about the client's request. Finally, RequestHeaders contains the complete list of HTTP/AS2 headers.

Next, invoke ParseRequest. The certificate used to decrypt and sign should be specified with the Certificate property, and your partner's signing certificate should be specified with SignerCert. This will process the headers, decompress and/or decrypt the message (if applicable), and verify the signature (if present). EncryptionType, SignatureType, and CompressionFormat describe whether and how the data was encrypted, signed, and compressed, respectively.

ParseRequest will populate EDIType and Data.

Error Handling

If any errors occur an exception will be thrown and EDIData will not be populated. Information about the exception will be provided through the exception's error code and message and also through ScanResult. An MDN receipt reporting the error may still be generated; it is recommended that server software trap the error and invoke CreateMDNReceipt to report the error to the client.

The ErrorProcessingFlags property may be configured to allow predetermined types of errors. If ErrorProcessingFlags is set when ParseRequest (or ProcessRequest) is invoked, the errors specified will be allowed, an exception will not be thrown, and EDIData will still be determined. However, ScanResult will still report the error, as will the receipt generated by CreateMDNReceipt. To avoid reporting the errors in the receipt, set the ErrorReportingFlags property.

Creating an MDN-based Receipt

An MDN-based receipt may be created by invoking CreateMDNReceipt. Regardless of the success or failure of ProcessRequest, the receipt may be created as specified in RFCs 3335 and 2298. If no errors occurred when ProcessRequest was invoked, the receipt will report success and will be suitable for non-repudiation of receipt (NRR) if signed. If errors occurred, the MDN will report that an error occurred and that the EDI data was not processed. It is strongly recommended that server software trap any errors thrown by ProcessRequest and return the receipt in this case as well.

The MDNReceipt will consist of the MDN itself, a human-readable message, MIME headers and footers, and a signature if applicable. The receipt may be generated by invoking CreateMDNReceipt and customized further by setting the parameters to CreateMDNReceipt.

The Message parameter to CreateMDNReceipt may be used to customize the human-readable message in the receipt. If it is set to an empty string, an appropriate message will automatically be written whenever MDNReceipt is regenerated.

The receipt will be signed using the protocol specified by ReceiptSigningProtocol, if any. The certificate used to sign the receipt is specified by Certificate. By default the receipt will be signed if explicitly requested by the client, and unsigned otherwise.

Error reporting may be controlled by configuring ErrorReportingFlags. By default, any errors will cause MDNReceipt to report a failure to process the message (either "failed/Failure" or "processed/Error" will be reported, according to the specification and the type of error). Setting ErrorReportingFlags will cause the MDNReceipt to overlook the chosen types of errors. If all errors are overlooked, the MDNReceipt will report success and calculate a MIC on the original message as usual. A warning may be reported by setting the MDNWarning configuration setting.

Additional Server-Side Functionality

When used in a server environment such as ASP.NET, the component may be used to interface directly with the underlying HTTP context. If Request is not set by the user, ParseRequest and ProcessRequest will first get the request from the underlying HTTP environment, if possible. SendResponse will send the reply in this environment if able; otherwise the reply will be directed to standard out.

ASP.NET Core Notes

The component may be used within any .NET Standard compatible platform, including .NET Core and ASP.NET Core. When using AS2Receiver within an ASP.NET Core MVC application the component can be configured to automatically read from the request context, and send using the response context. To do so pass the HttpContext to the constructor of the AS2Receiver class. For instance:


//Inside HomeController.cs
As2receiver as2 = new As2receiver(HttpContext);

Property List


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

AS2FromThe AS2 Identifier of the sending system.
AS2ToThe AS2 Identifier of the receiving system.
AttachmentsCollection of files attached to the current message.
CEMDetailsA collection of Certificate Exchange Messaging (CEM) details.
CertEncodedThe certificate (PEM/base64 encoded).
CertStoreThe name of the certificate store for the client certificate.
CertStorePasswordIf the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
CertStoreTypeThe type of certificate store for this certificate.
CertSubjectThe subject of the certificate used for client authentication.
CompressionFormatThe compression format used on the incoming message.
EDIDataThe EDI data sent in Request .
FirewallA set of properties related to firewall access.
IncomingDirectoryThe directory to be used to store incoming messages.
LocalHostThe name of the local host or user-assigned IP interface through which connections are initiated or accepted.
LogDirectoryThe path to a directory for logging.
LogFileThe log file written.
MDNReceiptThe MDN-based receipt generated by the component.
MDNToThe recipient for the Message Disposition Notification (MDN).
MessageIdThe message ID of the incoming message.
ReceiptDeliveryOptionA URL indicating how the receipt is to be delivered.
RequestThe HTTP request to be processed.
RequestHeadersThe HTTP headers in the AS2 request.
RequestHeadersStringThe HTTP headers in the AS2 request.
RestartDirectoryThe directory to log cached files when using AS2 restart functionality.
RolloverCertEncodedThe certificate (PEM/base64 encoded).
RolloverCertStoreThe name of the certificate store for the client certificate.
RolloverCertStorePasswordIf the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
RolloverCertStoreTypeThe type of certificate store for this certificate.
RolloverCertSubjectThe subject of the certificate used for client authentication.
ScanResultThe result of invoking ParseRequest .
SignerCertEncodedThe certificate (PEM/base64 encoded).
SignerCertStoreThe name of the certificate store for the client certificate.
SignerCertStorePasswordIf the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
SignerCertStoreTypeThe type of certificate store for this certificate.
SignerCertSubjectThe subject of the certificate used for client authentication.
SSLAcceptServerCertEncodedThe certificate (PEM/base64 encoded).
SSLAcceptServerCertStoreThe name of the certificate store for the client certificate.
SSLAcceptServerCertStorePasswordIf the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
SSLAcceptServerCertStoreTypeThe type of certificate store for this certificate.
SSLAcceptServerCertSubjectThe subject of the certificate used for client authentication.
SSLCertEncodedThe certificate (PEM/base64 encoded).
SSLCertStoreThe name of the certificate store for the client certificate.
SSLCertStorePasswordIf the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
SSLCertStoreTypeThe type of certificate store for this certificate.
SSLCertSubjectThe subject of the certificate used for client authentication.
UsePSSWhether to use RSA-PSS during signing and verification.

Method List


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

AckRequestOptional. Acknowledges the incoming request.
ConfigSets or retrieves a configuration setting.
CreateMDNReceiptCreates MDNReceipt .
ParseRequestParses the EDI message and determines the EDIData .
ProcessRequestProcesses the EDI data, and generates the receipt.
ProcessRestartRequestProcesses the AS2 restart request, and sends a response to the client.
ReadRequestReads the AS2 request from the HTTP session.
ResetResets the state of the control.
SendAsyncMDNSends the MDNReceipt to the RemoteURL specified.
SendResponseIn a server environment, responds to the requesting client with MDNReceipt .
SetTPInfoA convenient way to set AS2 communication parameters using XML strings.

Event List


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

CEMRequestFired when a Certificate Exchange Messaging (CEM) request is received.
CEMResponseFired when a Certificate Exchange Messaging (CEM) response is received.
EDIDataInfoFired when processing an incoming message.
ErrorInformation about errors during data delivery.
LogFired with log information while processing a message.
RecipientInfoFired for each recipient certificate of the encrypted message.
SignerCertInfoFired during verification of the signed message.
SSLServerAuthenticationFor asynchronous HTTPS MDNs, fired after the server presents its certificate.
SSLStatusShows the progress of the secure connection.

Configuration Settings


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

AcceptAnySignerCertUsed to accept trust any signing certificate unconditionally.
AS2VersionIncomingThe version of AS2 that was used in the incoming message.
AS2VersionOutgoingThe version of AS2 to be used in the outgoing message.
AuthorizationThe Authorization string to be sent to the server.
AuthSchemeThe authorization scheme to be used when server authorization is to be performed.
CEMCertDirSpecifies the directory where certificates are saved when receiving a CEM request.
CloseStreamAfterProcessingSpecifies whether or not the OutputStream should be closed after processing.
DecodeTempDirectoryThe temp directory the component will use to decode messages.
DetectDuplicatesWhether to detect duplicate messages.
EncryptionAlgorithmThe encryption algorithm used to encrypt the incoming data.
EncryptionPaddingSchemeThe encryption padding scheme used when encrypting the incoming data.
EncryptionTypeThe MIME type of the encrypted data.
ErrorProcessingFlagsFlags controlling how errors affect ProcessRequest.
ErrorReportingFlagsFlags controlling how errors affect the MDNReceipt.
FilenameSourceThe location from which to read the filename.
InvalidFilenameMDNActionInstructs MDN disposition on invalid and duplicate filenames.
LogDebugWhether to log debug data.
LogFilenameThe base name of the log file.
LogOptionsThe information to be written to log files.
MaxPartsThe maximum number of MIME parts to process.
MDNDispositionOverrides the automatically calculated MDN disposition.
MDNMICAlgorithmThe algorithm used to sign the outgoing MDN.
MDNReportingUAThe name of the user agent performing the disposition.
MDNSendingModeThe level of end user interaction involved in sending the MDN.
MDNWarningA warning to appear in the MDN.
NormalizeMICWhether to normalize line endings before calculating the MIC.
OverwriteCEMCertsWhether existing CEM certificates are overwritten when a duplicate is received.
PasswordA password if authentication is to be used.
ProcessingErrorA processing error occurred in the received EDI message.
ProxyAuthorizationThe authorization string to be sent to the proxy server.
ProxyPasswordA password if Basic authentication is to be used for the proxy.
ProxyPortPort for the proxy server (default 80).
ProxyServerName or IP address of a proxy server (optional).
ProxyUserA user name if Basic authentication is to be used for the proxy.
ReceiptSigningProtocolThe protocol used to sign the outgoing MDN receipt.
RequestedMICAlgorithmsThe Message Integrity Check algorithm(s) requested by the client, if any.
RequestedSignatureProtocolThe signing protocol requested by the client, if any.
RequestFileReads the AS2 message from disk.
RequireAS2ToEnsure that the received message is intended for the given AS2 identifier.
RequiredSignatureAlgorithmsSpecifies a list of acceptable signature algorithms.
RequireEncryptEnsure that the received message is encrypted.
RequireOAEPEnsure that the encryption padding mode is RSAES-OAEP.
RequirePSSEnsure that the signature scheme in the received message is RSASSA-PSS.
RequireSignEnsure that the received message is signed.
ResponseSubjectThe subject to be used for the MDN response.
SenderSignatureAlgorithmThe algorithm used by the sender to sign the message.
SenderSignatureSchemeThe signature scheme used by the sender to sign the message.
SignatureTypeThe MIME type of the signature (if any).
SignerCACertCA certificate used to verify signed messages.
SMTPFromThe email address of the sender of the message.
SMTPServerThe SMTP server to be used.
UserA user name if authentication is to be used.
WarnOnMDNFailureWhether to log a .wrn file instead of a .err file when MDN delivery fails.
AcceptEncodingUsed to tell the server which types of content encodings the client supports.
AllowHTTPCompressionThis property enables HTTP compression for receiving data.
AllowHTTPFallbackWhether HTTP/2 connections are permitted to fallback to HTTP/1.1.
AppendWhether to append data to LocalFile.
AuthorizationThe Authorization string to be sent to the server.
BytesTransferredContains the number of bytes transferred in the response data.
ChunkSizeSpecifies the chunk size in bytes when using chunked encoding.
CompressHTTPRequestSet to true to compress the body of a PUT or POST request.
EncodeURLIf set to true the URL will be encoded by the component.
FollowRedirectsDetermines what happens when the server issues a redirect.
GetOn302RedirectIf set to true the component will perform a GET on the new location.
HTTP2HeadersWithoutIndexingHTTP2 headers that should not update the dynamic header table with incremental indexing.
HTTPVersionThe version of HTTP used by the component.
IfModifiedSinceA date determining the maximum age of the desired document.
KeepAliveDetermines whether the HTTP connection is closed after completion of the request.
KerberosSPNThe Service Principal Name for the Kerberos Domain Controller.
LogLevelThe level of detail that is logged.
MaxRedirectAttemptsLimits the number of redirects that are followed in a request.
NegotiatedHTTPVersionThe negotiated HTTP version.
OtherHeadersOther headers as determined by the user (optional).
ProxyAuthorizationThe authorization string to be sent to the proxy server.
ProxyAuthSchemeThe authorization scheme to be used for the proxy.
ProxyPasswordA password if authentication is to be used for the proxy.
ProxyPortPort for the proxy server (default 80).
ProxyServerName or IP address of a proxy server (optional).
ProxyUserA user name if authentication is to be used for the proxy.
SentHeadersThe full set of headers as sent by the client.
StatusLineThe first line of the last response from the server.
TransferredDataThe contents of the last response from the server.
TransferredDataLimitThe maximum number of incoming bytes to be stored by the component.
TransferredHeadersThe full set of headers as received from the server.
TransferredRequestThe full request as sent by the client.
UseChunkedEncodingEnables or Disables HTTP chunked encoding for transfers.
UseIDNsWhether to encode hostnames to internationalized domain names.
UserAgentInformation about the user agent (browser).
CloseStreamAfterTransferIf true, the component will close the upload or download stream after the transfer.
ConnectionTimeoutSets a separate timeout value for establishing a connection.
FirewallAutoDetectTells the component whether or not to automatically detect and use firewall system settings, if available.
FirewallHostName or IP address of firewall (optional).
FirewallPasswordPassword to be used if authentication is to be used when connecting through the firewall.
FirewallPortThe TCP port for the FirewallHost;.
FirewallTypeDetermines the type of firewall to connect through.
FirewallUserA user name if authentication is to be used connecting through a firewall.
KeepAliveIntervalThe retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.
KeepAliveTimeThe inactivity time in milliseconds before a TCP keep-alive packet is sent.
LingerWhen set to True, connections are terminated gracefully.
LingerTimeTime in seconds to have the connection linger.
LocalHostThe name of the local host through which connections are initiated or accepted.
LocalPortThe port in the local host where the component binds.
MaxLineLengthThe maximum amount of data to accumulate when no EOL is found.
MaxTransferRateThe transfer rate limit in bytes per second.
ProxyExceptionsListA semicolon separated list of hosts and IPs to bypass when using a proxy.
TCPKeepAliveDetermines whether or not the keep alive socket option is enabled.
TcpNoDelayWhether or not to delay when sending packets.
UseIPv6Whether to use IPv6.
LogSSLPacketsControls whether SSL packets are logged when using the internal security API.
OpenSSLCADirThe path to a directory containing CA certificates.
OpenSSLCAFileName of the file containing the list of CA's trusted by your application.
OpenSSLCipherListA string that controls the ciphers to be used by SSL.
OpenSSLPrngSeedDataThe data to seed the pseudo random number generator (PRNG).
ReuseSSLSessionDetermines if the SSL session is reused.
SSLCACertsA newline separated list of CA certificate to use during SSL client authentication.
SSLCheckCRLWhether to check the Certificate Revocation List for the server certificate.
SSLCipherStrengthThe minimum cipher strength used for bulk encryption.
SSLEnabledCipherSuitesThe cipher suite to be used in an SSL negotiation.
SSLEnabledProtocolsUsed to enable/disable the supported security protocols.
SSLEnableRenegotiationWhether the renegotiation_info SSL extension is supported.
SSLIncludeCertChainWhether the entire certificate chain is included in the SSLServerAuthentication event.
SSLNegotiatedCipherReturns the negotiated ciphersuite.
SSLNegotiatedCipherStrengthReturns the negotiated ciphersuite strength.
SSLNegotiatedCipherSuiteReturns the negotiated ciphersuite.
SSLNegotiatedKeyExchangeReturns the negotiated key exchange algorithm.
SSLNegotiatedKeyExchangeStrengthReturns the negotiated key exchange algorithm strength.
SSLNegotiatedProtocolReturns the negotiated protocol version.
SSLProviderThe name of the security provider to use.
SSLSecurityFlagsFlags that control certificate verification.
SSLServerCACertsA newline separated list of CA certificate to use during SSL server certificate validation.
TLS12SignatureAlgorithmsDefines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True.
TLS12SupportedGroupsThe supported groups for ECC.
TLS13KeyShareGroupsThe groups for which to pregenerate key shares.
TLS13SignatureAlgorithmsThe allowed certificate signature algorithms.
TLS13SupportedGroupsThe supported groups for (EC)DHE key exchange.
AbsoluteTimeoutDetermines whether timeouts are inactivity timeouts or absolute timeouts.
FirewallDataUsed to send extra data to the firewall.
InBufferSizeThe size in bytes of the incoming queue of the socket.
OutBufferSizeThe size in bytes of the outgoing queue of the socket.
BuildInfoInformation about the product's build.
CodePageThe system code page used for Unicode to Multibyte translations.
LicenseInfoInformation about the current license.
UseInternalSecurityAPITells the component whether or not to use the system security libraries or an internal implementation.

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks EDI 2020 Delphi Edition - Version 20.0 [Build 8162]