IPWorks EDI 2020 Node.js Edition

Questions / Feedback?

OFTPServer Class

Properties   Methods   Events   Configuration Settings   Errors  

The OFTPServer class implements the server side of the Odette File Transfer Protocol.

Syntax

ipworksedi.oftpserver()

Remarks

The OFTPServer component implements an OFTP server. It is a lightweight server that supports version 1.2, 1.3, 1.4, and 2.0 of OFTP.

Sending and Receiving Files

To use the class first decide if you will support TLS/SSL connections or not. If UseSSL is set to true, all clients will be expected to connect in TLS/SSL. If UseSSL is set to false (default), all clients are expected to connect in plaintext. If UseSSL is true, only clients that support Version 2.0 of the protocol can connect.

Once you have decided whether or not to support TLS/SSL, specify the port you wish the server to listen on in LocalPort. By default this value is 3305.

Next, specify values for ServerSSIDCode, ServerSFIDCode, ServerPassword.

Then set Listening to true to start listening for incoming requests.

When a client connects, you will have an opportunity to authenticate the client before continuing the connection. This is done when the AcceptConnection event fires. Within this event you can validate that the connecting client has access based on rules you determine. If you wish to reject the connection set the Accept parameter to false. Within this event you can also specify the directory to which files sent by the client to the server are saved. It is necessary to specify the directory within this event, as the client can start sending files as soon as the connection is complete. To specify the download directory set the OFTPConnectionDownloadDirectory property. For instance:

oftpserver1.SetOFTPConnectionDownloadDirectory(e->ConnectionId, "C:\\Downloads");

When the connection is complete, the client may send files. If the client does send a file the AcceptFile event will fire and you will have the opportunity to reject the file by setting the Accept parameter of the event. In addition you will have a chance to change the filename by setting the Filename parameter if desired.

After the client has sent all the files it is configured to send, it will pass control to the server. At that time the ReadyToSend event will fire, and the OFTPConnectionReadyToSend property will be set to true. After this, you can either end the session with the client by calling Logoff or send files to the client. To send files to the client simply call the SendFile method with the specified parameters.

TLS/SSL Notes

When UseSSL is set to true, the server must be configured with a TLS/SSL certificate before it is started. Set SSLCert to a valid certificate with corresponding private key before setting Listening to true. This may be a PFX file, PEM key, or a certificate in a windows certificate store. See the SSLCert property for more information.

After SSLCert is set to a valid certificate and Listening is set to true, when a client connects the SSLStatus event will fire during the TLS/SSL negotiation. This is purely informational, if there is an error the Error event will fire.

If you want to require TLS/SSL client authentication, set SSLAuthenticateClients to true before setting Listening to true. This will force clients to present a certificate during TLS/SSL negotiation to be used for authorization. In this case the SSLClientAuthentication event will fire and you must set the Accept parameter within the event to true in order to accept the client's certificate and proceed with the connection.

Example Code


MyOftpserver server;

server.SetServerSSIDCode("SERVERSSID");
server.SetServerSFIDCode("SERVERSFID");
server.SetServerPassword("SERVER");

server.SetListening(true);

...
//Within the main loop of the application call server.DoEvents() in a loop
//to process events.

//When the ReadyToSend event fires the server can then send files to the client. To do this call the SendFile method.
//Alternatively, monitor server.GetOFTPConnectionReadyToSend(<ConnectionId>) to determine when files can be sent.
class MyOFTPServer : public OFTPServer {
public:
    MyOFTPServer() {}

    virtual int FireAcceptConnection(OFTPServerAcceptConnectionEventParams* e) {
        clientConnectionId = e->ConnectionId;
        clientSSIDCode = strdup(e->ClientSSIDCode);

        this->SetOFTPConnectionDownloadDirectory(e->ConnectionId, INCOMING_DIR);

        return 0;
    }
    virtual int FireAcceptFile(OFTPServerAcceptFileEventParams* e) {
        //e->Accept = False; //To reject a file set e->Accept to false
        return 0;
    }

    virtual int FirePITrail(OFTPServerPITrailEventParams* e) {
        char logmsg[MAX_PATH];
        if (e->Direction == 0) {
            sprintf(logmsg, "CLIENT: %s : %s", e->CommandId, e->CommandDescription);
        }
        else {
            sprintf(logmsg, "SERVER: %s : %s", e->CommandId, e->CommandDescription);
        }
        printf(logmsg);
        return 0;
    }

    virtual int FireError(OFTPServerErrorEventParams* e) {
        printf("[%d] %s\n", e->ErrorCode,strdup(e->Description));
        return 0;
    }
};

Property List


The following is the full list of the properties of the class with short descriptions. Click on the links for further 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.
ConnectionBacklogThe maximum number of pending connections maintained by the TCP/IP subsystem.
OFTPConnectionCountThe number of records in the OFTPConnection arrays.
OFTPConnectionCompressWhether or not compression is used on the outgoing or incoming file.
OFTPConnectionConnectedThis property is used to disconnect individual connections and/or show their status.
OFTPConnectionConnectionIdThis property contains an identifier generated by the class to identify each connection.
OFTPConnectionDownloadDirectoryThe directory to which files will be saved.
OFTPConnectionEncryptionAlgorithmThe encryption algorithm used when sending files to the client.
OFTPConnectionLocalAddressThis property shows the IP address of the interface through which the connection is passing.
OFTPConnectionMaxRecordSizeThis value determines the maximum length for a record in the outgoing virtual file.
OFTPConnectionReadyToSendSpecifies whether or not the server can send to the client.
OFTPConnectionRecipientCertStoreThe name of the certificate store for the recipient certificate.
OFTPConnectionRecipientCertStorePasswordIf 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.
OFTPConnectionRecipientCertStoreTypeThe type of certificate store for this certificate.
OFTPConnectionRecipientCertSubjectThe subject of the recipient certificate.
OFTPConnectionRemoteHostThis property shows the IP address of the remote host through which the connection is coming.
OFTPConnectionRemotePortThis property shows the TCP port on the remote host through which the connection is coming.
OFTPConnectionSFIDCodeThe connected client's SFID code.
OFTPConnectionSignedReceiptIndicates whether a signed receipt is requested.
OFTPConnectionSSIDCodeThe connected client's SSID code.
OFTPConnectionTimeoutA timeout for the class.
OFTPConnectionVersionThis holds the version of OFTP supported by the client.
OFTPConnectionVirtualFileDateSet this to the date/time stamp for the virtual file before sending.
OFTPConnectionVirtualFileFormatThe structure of the outgoing or incoming file.
OFTPConnectionVirtualFileSecurityLevelSpecifies security options for the outgoing or incoming file.
DefaultTimeoutAn initial timeout value to be used by incoming connections.
ListeningIf True, the class accepts incoming connections on LocalPort.
LocalHostThe name of the local host or user-assigned IP interface through which connections are initiated or accepted.
LocalPortThe TCP port in the local host where the class listens.
ServerPasswordThe server's password.
ServerSFIDCodeServer's SFID code.
ServerSSIDCodeThe server's SSID code.
SSLAuthenticateClientsIf true, the server asks the client(s) for a certificate.
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.
TrustedCertCountThe number of records in the TrustedCert arrays.
TrustedCertEncodedThe certificate (PEM/base64 encoded).
TrustedCertStoreThe name of the certificate store for the client certificate.
TrustedCertStorePasswordIf 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.
TrustedCertStoreTypeThe type of certificate store for this certificate.
TrustedCertSubjectThe subject of the certificate used for client authentication.
UseSSLUse SSL to access the RemoteHost .

Method List


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

ChangeDirectionSends a Change Direction (CD) command.
ConfigSets or retrieves a configuration setting.
DisconnectDisconnect the specified client.
DoEventsProcesses events from the internal message queue.
ExchangeCertificateExchange a certificate with the remote host.
ImportTrustedCertsImports a list of trusted CA certificates.
InterruptInterrupts a synchronous send to the remote host.
LogoffEnds a session with the connection client.
ResetResets the state of the control.
SendEndResponseSends an EERP/NERP asynchronously.
SendFileSends a file to the specified client.
ShutdownShuts down the server.

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.

AcceptConnectionFired when a client connects.
AcceptFileFired when the client sends a file.
CertificateReceivedFired when a certificate is received from the remote host.
ConnectedFired immediately after a connection completes (or fails).
ConnectionRequestFired when a request for connection comes from a remote host.
DisconnectedFired when a connection is closed.
EndResponseFired every time an end response is received from the client.
EndTransferFired when a file finishes transferring.
ErrorInformation about errors during data delivery.
PITrailFired when any protocol level communication occurs.
ReadyToSendFired when the class is ready to send data.
SSLClientAuthenticationFired when the client presents its credentials to the server.
SSLConnectionRequestFires when an SSL connection is requested.
SSLStatusShows the progress of the secure connection.
StartTransferFired when a document starts transferring.
TransferFired while a document transfers (delivers document).

Configuration Settings


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

AllowRetry[ConnectionId]Whether to send a retry indicator when rejecting a file.
CDAfterSendEndResponse[ConnectionId]Whether to issue a CD command after sending an asynchronous EERP.
CertificateStore[ConnectionId]The name of the certificate store.
CertificateStorePassword[ConnectionId]The certificate password.
CertificateStoreType[ConnectionId]The type of certificate store.
CertificateSubject[ConnectionId]The certificate subject.
CertificateTypeSpecifies the type of certificate being supplied.
CertificateType[ConnectionId]Specifies the type of certificate being supplied.
ConnectionType[ConnectionId]Specifies the type of connection that will be created.
CreditCount[ConnectionId]Specifies the maximum credit value.
DefaultIdleTimeoutThe default idle timeout for inactive clients.
DefaultReceiptHashAlgorithmThe receipt hash algorithm to request when sending a file.
DeleteOnErrorWhether received files are deleted when there is an error during processing.
DisconnectAfterEndSessionDetermines if the connection is closed immediately after ending the session.
ExchangeBufferSize[ConnectionId]Specifies the data exchange buffer size in bytes.
ExchangeCertStoreTypeSpecifies the store type when loading a certificate to be exchanged.
ExchangeCertSubjectThe subject of the certificate being exchanged.
FailOnUntrustedCertWhether or not to throw an exception when untrusted certificates are used.
FileDescription[ConnectionId]Additional description information sent with the file.
FileHashAlgorithm[ConnectionId]The hash algorithm to use when sending a file.
FireEndResponseOnSendDetermines if the EndResponse event is fired for outgoing EERP and NERPs.
FollowRedirectsDetermines behavior when importing trusted certificates and a HTTP redirect is returned.
FriendlyLogFormatDetermines if a more friendly format is applied to PITrail event out.
IdleTimeoutThe idle timeout for this connection.
KeepAliveThis property enables the SO_KEEPALIVE option on the incoming connections. This option prevents long connections from timing out in case of inactivity.
LingerThis property controls how a connection is closed. The default is True. In this case the connection is closed only after all the data is sent. Setting it to False forces an abrupt (hard) disconnection. Any data that was in the sending queue may be lost.
ReceivedConnectionType[ConnectionId]Returns the connection type specified by the client.
ReceivedFileDateTime[ConnectionId]The datetime of the file being received.
ReceivedFileDescription[ConnectionId]Additional description information received with the file.
ReceivedFileEncryptionAlg[ConnectionId]The encryption algorithm used for the file being received.
ReceivedFileName[ConnectionId]Returns the name of the received file.
ReceivedFileNameFormatThe name format of received files.
ReceivedFileNameFormat[ConnectionId]The name format of received files.
RecipientCertificateTypeSpecifies the type of recipient certificate being supplied.
Retry[ConnectionId]Indicates whether the recipient allows the send to be retried.
SecureAuthenticationSpecifies secure authentication requirements for connecting clients.
SendCDAfterEFPASpecifies whether a CD is always sent after receiving an EFPA.
ServerPassword[ConnectionId]Sets or gets the ServerPassword for a particular connection.
ServerSFIDCode[ConnectionId]Sets or gets the ServerSFIDCode for a particular connection.
ServerSSIDCode[ConnectionId]Sets the ServerSSIDCode for a particular connection.
TempPath[ConnectionId]The path of a directory where temporary files will be created.
TrustedCertsDataSpecifies the source to be used when importing trusted certificates.
VirtualFileDateFormatThe DateTime format of received files.
AllowedClientsA comma-separated list of host names or IP addresses that can access the class.
BindExclusivelyWhether or not the class considers a local port reserved for exclusive use.
ConnectionUIDThe unique connectionId for a connection.
DefaultConnectionTimeoutThe inactivity timeout applied to the SSL handshake.
InBufferSizeThe size in bytes of the incoming queue of the socket.
KeepAliveIntervalThe retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.
KeepAliveRetryCountThe number of keep-alive packets to be sent before the remotehost is considered disconnected.
KeepAliveTimeThe inactivity time in milliseconds before a TCP keep-alive packet is sent.
MaxConnectionsThe maximum number of connections available.
OutBufferSizeThe size in bytes of the outgoing queue of the socket.
TcpNoDelayWhether or not to delay when sending packets.
UseIOCPWhether to use the completion port I/O model.
UseIPv6Whether to use IPv6.
UseWindowsMessagesWhether to use the WSAAsyncSelect I/O model.
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.
SSLCACertFilePathsThe paths to CA certificate files on Unix/Linux.
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.
SSLNegotiatedVersionReturns 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.
BuildInfoInformation about the product's build.
CodePageThe system code page used for Unicode to Multibyte translations.
LicenseInfoInformation about the current license.
ProcessIdleEventsWhether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillisThe length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPITells the class 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 Node.js Edition - Version 20.0 [Build 8203]