GISBSender Component
Properties Methods Events Configuration Settings Errors
The GISBSender component implements an GISB / EDM client.
Syntax
nsoftware.InEDI.Gisbsender
Remarks
The GISBSender component is used to send EDI or other documents using the GISB (Gas Industry Standards Board) / NAESB (North American Energy Standards Board) EDM (Electronic Delivery Mechanism) protocol.
When sending an EDI message, the client should specify, at a minimum, DataFrom, DataTo, URL, Data, and EDIType. The Post method should then be invoked.
Basic Features: GISB Versions 1.4 and above
Security is provided via the use of PGP. If you want to sign and/or encrypt your message set the SignData and EncryptData properties to true. The component does not itself implement PGP, instead it uses a
The component 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 component 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 component 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 component 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 called "IPWorksGISBPGPProvider" that should have the following methods. The component 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 bool 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 component 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. to allow you to process the PGP data with a library of your choice.
TLS/SSL will also be used if the scheme in URL is "https". In case your trading partner is using a self-signed certificate you may set SSLAcceptServerCert or trap the SSLServerAuthentication event to accept the certificate.
After you Post the server will issue a brief reply. If the server indicates some sort of an error an exception will be thrown. However, the absence of an error message does not necessarily mean that the server was able to read the EDI data. The server may attempt to process the data after closing the connection; if it finds an error it might send a separate error notification which may be processed by the GISBReceiver component.
Extended Security Options: NAESB Version 1.6
Version 1.6 of the NAESB/GISB protocol includes extensions to allow additional security. Like the AS2 protocol, version 1.6 allows for the use of receipts.
To request a receipt, set the ReceiptTo property. The ReceiptType and ReceiptSecurity properties may be used to customize the receipt request; by default, the component will request a GISB-Acknowledgement-Receipt signed over an SHA-1 hash. The receipt will be returned in the HTTP reply, and will automatically be verified by the component.
Property List
The following is the full list of the properties of the component with short descriptions. Click on the links for further details.
Cookies | Collection of cookies. |
DataElements | Collection of extra data elements for the outgoing request. |
DataFrom | The identity of the sending system. |
DataTo | The identity of the receiving system. |
EncryptData | Whether or not to encrypt the data. |
Firewall | A set of properties related to firewall access. |
GISBData | The EDI Payload of the message. |
GISBVersion | The version of GISB/NAESB being used. |
LocalHost | The name of the local host or user-assigned IP interface through which connections are initiated or accepted. |
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. |
Proxy | A set of properties related to proxy access. |
ReceiptSecurity | [1.6] Used to indicate the security options requested for the receipt. |
ReceiptSigningProtocol | [1.6] Indicates the protocol used to sign the receipt. |
ReceiptTo | [1.6] Used to request a receipt. |
ReceiptType | [1.6] The type of receipt requested. |
ReplyHeaders | The HTTP headers provided for the Response . |
RequestStatus | The status of the request. |
ResponseContent | The response returned from the server. |
SignData | Whether or not to sign the data. |
SSLAcceptServerCert | Instructs the component to unconditionally accept the server certificate that matches the supplied certificate. |
SSLCert | The certificate to be used during SSL negotiation. |
SSLServerCert | The server certificate for the last established connection. |
Subject | The subject of the message. |
Timeout | A timeout for the component. |
TransactionId | The transaction ID of the message. |
URL | The URL to post to. |
UserAgent | Information about the user agent. |
Method List
The following is the full list of the methods of the component with short descriptions. Click on the links for further details.
Config | Sets or retrieves a configuration setting . |
DoEvents | Processes events from the internal message queue. |
Post | Post data to the server, and check the receipt. |
Reset | Resets the state of the control. |
SetPGPParam | Sets a parameter in the PGP provider. |
SetUploadStream | Sets the stream to be uploaded to the server. |
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.
Connected | Fired immediately after a connection completes (or fails). |
Disconnected | Fired when a connection is closed. |
EndTransfer | Fired when a document finishes transferring. |
Error | Information about errors during data delivery. |
Header | Fired every time a header line comes in. |
Log | Fires with log information during processing. |
SetCookie | Fired for every cookie set by the server. |
SSLServerAuthentication | Fired after the server presents its certificate to the client. |
SSLStatus | Shows the progress of the secure connection. |
StartTransfer | Fired when a document starts transferring (after the headers). |
Transfer | Fired while a document transfers (delivers document). |
Configuration Settings
The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.
AllowOldPacketType | Whether to allow the older encrypted packet type. |
LogLevel | Specifies the level of detail that is logged. |
PGPCombineSignAndEncrypt | Whether to sign and encrypt in a single step or not. |
PGPProviderType | Which PGP implementation to use. |
AuthScheme | The authorization scheme to be used when server authorization is to be performed. |
Authorization | The Authorization string to be sent to the server. |
User | A user name if authentication is to be used. |
Password | A password if authentication is to be used. |
LogFilename | The base name of the log file. |
GUIAvailable | Tells the component whether or not a message loop is available for processing events. |
UseBackgroundThread | Whether threads created by the component are background threads. |
UseInternalSecurityAPI | Tells the component whether or not to use the system security libraries or an internal implementation. |