GISBReceiver Bean
Properties Methods Events Configuration Settings Errors
The GISBReceiver component is used to process EDI messages and generate receipts.
Syntax
InEDI.Gisbreceiver
Remarks
The GISBReceiver implements server-side processing of EDI messages, as specified in versions 1.4 and 1.6 of the GISB/NAESB specification. It can be used to decrypt and verify incoming messages; in version 1.6, it may additionally be used to generate signed receipts. The bean is designed to be easily incorporated into an HTTP server, and features custom functionality for server environments such as ASP.NET.
Basic Operation
The ProcessRequest method is used to process incoming messages and generate responses. ProcessRequest will parse the form data, determine DataFrom and DataTo, and then attempt to process any signed or encrypted data using PGP.
The bean offers two methods for PGP operations. The first is an internal OpenPGP implementation that requires no additional dependencies. This is the default mode of operation. Alternatively a separate provider such as GnuPGP may be used to perform the PGP operations. PGPProviderType specifies which provider to use.
Internal Provider (Default)
When using the internal PGP provider no special steps are required. The following table defines possible values that may be passed to the SetPGPParam.
| homedir | The directory containing the public keyring, secret keyring and trust database. Please note this defaults to the application preferences directory of the user, hence if the GNUPG provider is being used from a ASP.NET application, homedir should be specified. |
| passphrase | The passphrase to access the secret keys in the secret-keyring. |
| userid | The identifier used to identify a secret key within the secret-keyring. Note: When decrypting if this value is not specified the bean will attempt to find the key within the keyring automatically based on information available in the PGP message itself. |
| recipient-userid | The identifier used to identify a public key within the public keyring. Note: When verifying a signature if this value is not specified the bean will attempt to find the key within the keyring automatically based on information available in the PGP message itself. |
| timeout | The timeout in milliseconds that the provider will wait for a response from the OpenPGP executable. The default is 5000 (5 seconds). |
| usetempfile | If set to "true" the provider will write data to be processed to a temporary file on disk. This is useful when working with large files or binary files. |
| signingalgorithm | The signing algorithm to use when SignData is True. Possible values are:
|
| encryptingalgorithm | The encrypting algorithm to use when EncryptData is True. Possible values are:
|
| compressionmethod | The compression method to use. Possible values are:
|
External Provider
The PGP operations may be performed by an external implementation such as GnuPG.
A PGP provider is a simple module that allows the bean to offload PGP operations to the PGP software of your choice. The interface is designed to be generic in its ability to include various PGP software and is limited to only the bare minimum capabilities required for a GISB message exchange. We include a PGP provider implementation for GnuPG which may be used as a reference to implement other providers.
A PGP provider is simply a class that should have the following methods. The bean uses reflection to access the methods of the provider.
public void setParam(String name, String value);
public byte[] encrypt(byte[] data);
public byte[] decrypt(byte[] data);
public byte[] sign(byte[] data);
public byte[] signAndEncrypt(byte[] data);
public boolean verifySignature(byte[] signature, byte[] signedData);
The following table defines possible values that may be passed to the SetPGPParam.
| gpg-path | The path to the OpenPGP executable for the desired implementation. |
| homedir | The directory containing the public keyring, secret keyring and trust database. Please note this defaults to the application preferences directory of the user, hence if the GNUPG provider is being used from a ASP.NET application, homedir should be specified. |
| passphrase | The passphrase to access the secret keys in the secret-keyring. |
| userid | The identifier used to identify a secret key within the secret-keyring. |
| recipient-userid | The identifier used to identify a public key within the public keyring. |
| timeout | The timeout in milliseconds that the provider will wait for a response from the OpenPGP executable. The default is 5000 (5 seconds). |
| usetempfile | If set to "true" the provider will write data to be processed to a temporary file on disk. This is useful when working with large files or binary files. |
The bean expects the encryption to return an ASCII armored output and the signing to compute a detached signature.
Note: GnuPG is the Free Software Foundation's implementation of OpenPGP. It is free software and is recommended by NAESB (in version 1.6 of the EDM specification) for use in GISB/NAESB applications.
GnuPG is not included with this package, so you should download the latest version from http://www.gnupg.org. You might use GnuPG (or other software) to import your trading partners' public keys, and to import or generate a private key for yourself. These operations are outside the scope of this software, so please see the GnuPG documentation for details.
Finally, the bean will generate a Response which you may send to the client with SendResponse.
The most important part of the Response is the RequestStatus; this property will contain either "ok" or an error message to be returned to the requesting client. By default the bean will accept any post that conforms to the standard. If you want to be more restrictive you should first invoke ParseRequest to determine the sender, check the message security used, and extract the EDI data. If there is a problem you may then set RequestStatus to an error before calling CreateResponse. Please see the RequestStatus property for a list of standard error messages.
If you use version 1.4 of the GISB/NAESB protocol, the response will be a simple HTML reply. If you use version 1.6 the sender has the option of requesting a signed receipt. In all cases the response may be created with CreateResponse and sent with SendResponse.
To create log files, set LogDirectory prior to invoking ProcessRequest. This will log all incoming and outgoing data, and will also write the received EDI files to disk.
Additional Server-Side Functionality
When used in a server environment such as ASP, ASP.NET, etc., the bean 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.
Property List
The following is the full list of the properties of the bean with short descriptions. Click on the links for further details.
| DataElements | Collection of data elements for the client's request. |
| DataFrom | The identity of the sending system. |
| DataTo | The identity of the receiving system. |
| EncryptionType | The MIME type of the encrypted data. |
| ErrorMessage | If the client sent an error notification, the error message. |
| GISBData | The EDI Payload of the message. |
| GISBVersion | The version of the GISB/NAESB protocol used. |
| LogDirectory | The path to a directory for logging. |
| LogFile | The log file written. |
| PGPProvider | The PGP provider provides an interface to the PGP cryptography software. |
| ReceiptSigningProtocol | The protocol used to sign the receipt, if any. |
| ReceiptType | The type of receipt to be returned, if any. |
| Request | The HTTP request to be processed. |
| RequestHeaders | The HTTP headers in the request. |
| RequestStatus | The status of the request. |
| Response | The response generated by the component. |
| ResponseHeaders | The response headers generated by the component. |
| ServerId | The ID of your server. |
| SignatureType | The MIME type of the signature (if any). |
| TransactionId | The transaction ID of the message. |
Method List
The following is the full list of the methods of the bean with short descriptions. Click on the links for further details.
| config | Sets or retrieves a configuration setting . |
| createResponse | Creates the response. |
| parseFormData | Processes the form data, and populates the appropriate properties. |
| parseRequest | Processes the EDI data. |
| processRequest | Processes the EDI data, and generates the receipt. |
| readRequest | Reads the AS2 request from the given HTTP servlet request. |
| reset | Resets the state of the control. |
| sendResponse | In a server environment, responds to the requesting client. |
| setPGPParam | Sets a parameter in the PGP provider. |
Event List
The following is the full list of the events fired by the bean with short descriptions. Click on the links for further details.
| Error | Information about errors during data delivery. |
| Log | Fires with log information during processing. |
Configuration Settings
The following is a list of configuration settings for the bean with short descriptions. Click on the links for further details.
| LogLevel | Specifies the level of detail that is logged. |
| RequireEncryption | Whether an error should be thrown if an unencrypted message is received. |
| RequireSignature | Whether an error should be thrown if an unsigned message is received. |
| TimeCFormat | The format of the Time-C data element. |
| TimeCQualifier | The UTC off-set of the server. |
| PGPProviderType | Which PGP implementation to use. |
| LogFilename | The base name of the log file. |
| GUIAvailable | Tells the component whether or not a message loop is available for processing events. |
| UseDaemonThreads | Whether threads created by the component are daemon threads. |
| UseInternalSecurityAPI | Tells the component whether or not to use the system security libraries or an internal implementation. |