SecureBlackbox 2020 macOS Edition

Questions / Feedback?

FTPClient Module

Properties   Methods   Events   Configuration Settings   Errors  

The FTPClient component provides client-side functionality for FTP and FTPS protocols.




FTPClient provides client-side support for the FTP (File Transfer Protocol) and FTPS (FTP-over-SSL) protocols. The FTPS protocol allows you to securely perform file transfer operations with a remote server over Transport Layer Security (TLS).

Note: TLS is a successor to the now deprecated SSL protocol, although the latter abbreviation is still widely used.

FTPClient is typically used in the following scenario:

  • Setting up the connection parameters
  • Connecting to the server and signing in
  • Performing file transfer operations
  • Closing the connection

Setting up the parameters

When working with FTP or FTP-over-TLS service you will often need to tune up several classes of settings:
  • Login credentials: these can be tuned up via the Username and Password properties.
  • TLS settings: these includes the TLS mode: explicit, implicit, or no TLS. You must get this setting right; otherwise you may not be able to connect. Use TLSSettings property to adjust this setting.
  • If your server requires you to authenticate with a certificate, you can provide one via the ClientChain property.
  • FTPClient validates the server certificate against the local security settings. If your server uses a custom or non-public PKI, you may need to provide the required trust anchors and CA certificates via the TrustedCertificates and KnownCertificates collections.
  • FTP protocol includes its own set of settings, such as PassiveMode, EncryptDataChannel, or AdjustPasvAddress. These may be configured on this stage, or later into the connection.
  • In some network environments, you may also need to make adjustments to SocketSettings and Proxy.

Connecting to the server and signing in

Call Connect to open the connection to the server. The component will use the provided credentials to sign you in automatically.

Performing file transfer operations

FTPClient offers the full set of FTP operations. These include file uploads (UploadFile or UploadBytes), file downloads (DownloadFile, DownloadBytes), and directory operations (ListDir, MakeDir).

Note that unlike SFTP, FTP only supports one transfer operation at a time. An ongoing operation should be completed or aborted before a new one can be started.

Closing the connection

Use Disconnect to close the FTP connection.

Useful info

During its work FTPClient communicates back via events. Progress event fires periodically during the transfer operation to let you know of the operation progress. ControlSend and ControlReceive report the protocol communication log. FileOperation and FileOperationResult report the start and completion of an individual transfer operation within a multi-file transfer call (such as UploadFiles).

Property List

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

AdjustPasvAddressEnables or disables automatic adjustment of passive-mode addresses.
BlockedCertificatesThe certificates that must be rejected as trust anchors.
ClientChainThe TLS client certificate chain.
ConnectedIndicates whether the component is connected to the server.
ControlConnectionInfoReturns the details of the control connection setup.
CurrentListEntryContains the details of the file entry reported by ListEntry .
DataConnectionInfoReturns the details of the data connection setup.
EncryptDataChannelEnables or disables data channel encryption.
ExternalCryptoProvides access to external signing and DC parameters.
KnownCertificatesAdditional certificates for chain validation.
KnownCRLsAdditional CRLs for chain validation.
KnownOCSPsAdditional OCSP responses for chain validation.
PassiveModeEnables or disables passive transfer mode.
PasswordThe connecting user's authentication password.
ProxyThe proxy server settings.
RestartAtThe offset to restart the file transfer from.
ServerChainThe TLS server's certificate chain.
SocketSettingsManages network connection settings.
TLSSettingsManages TLS layer settings.
TransferTypeSets the file transfer mode.
TrustedCertificatesA list of trusted certificates for chain validation.
UsernameThe connecting user's username (login name).

Method List

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

AbortAborts the previous FTP service command and any associated transfer of data.
AcctSends an Account command.
AppendBytesAppends a byte array to a server-side file.
AppendFileUploads a file to the server.
ChangeDirChanges the current directory.
ClearCommandChannelSends CCC (Clear Command Channel) command to the server.
ConfigSets or retrieves a configuration setting.
ConnectConnects to the FTP server.
DeleteDirDeletes a directory on the server.
DeleteFileDeletes a file on the server.
DirExistsChecks if a directory exists on the server.
DisconnectDisconnects from the server.
DownloadBytesDownloads a file from the server into an array of bytes.
DownloadFileDownloads a file from the server.
DownloadFilesDownloads multiple files from the server.
FileExistsChecks if a file exists on the server.
GetCurrentDirReturns the server-side current directory.
GetFileSizeReturns the size of a remote file.
ListDirLists the contents of a remote directory.
MakeDirCreates a new directory on the server.
NoopSends a NOOP command to the server.
RenameRenames a file.
SendCommandSends a custom command to the server.
UploadBytesUploads a byte array to the server.
UploadFileUploads a file to the server.
UploadFilesUploads multiple files to the server.

Event List

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

CertificateValidateFires when the server's TLS certificate has to be validated.
ControlReceiveFires when data is received via the control channel.
ControlSendFires when data is about to be set via the control channel.
ErrorInformation about errors during data delivery.
ExternalSignHandles remote or external signing initiated by the SignExternal method or other source.
FileOperationMarks the start of a file transfer.
FileOperationResultReports the result of a file transfer operation.
ListEntryReports a single entry from the requested directory listing.
NotificationThis event notifies the application about an underlying control flow event.
ProgressReports the data transfer progress.
TextDataLineReports next transferred data line.

Configuration Settings

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

AccountInfoParameters for the ACCT command.
AuthCmdAuthorization command to be used to request an explicit SSL session.
CaseConversionWhether file names and paths should be case-converted.
CaseSensitiveCase-sensitivity of file names and paths.
CloseQuietlySet this to true to avoid sending QUIT command on session closure.
ConcurrentConnectionsNumber of simultaneous connections for download.
CopyModeWhat to do with the originals of the copied files.
ErrorOriginSpecifies where the error has been originated.
ErrorSeverityError severity.
EventOriginIndicates the channel that has fired the event.
ExtHOSTSupportedWhether HOST extension is supported.
ExtMDTMSupportedWhether MDTM extension is supported.
ExtMFMTSupportedWhether MFMT extension is supported.
ExtMLSTSupportedWhether MLST extension is supported.
ExtOPTSUTF8SupportedWhether OPTS UTF8 extension is supported.
ExtRESTSupportedWhether REST extension is supported.
ExtSIZESupportedWhether SIZE extension is supported.
ExtXCRCSupportedWhether XCRC extension is supported.
ExtXMD5SupportedWhether XMD5 extension is supported.
FTPBufferSizeBuffer size in binary mode.
FTPTextBufferSizeBuffer size in text mode.
IgnoreSystemTrustWhether trusted Windows Certificate Stores should be treated as trusted.
ListenTimeoutListening socket timeout.
LocalNewLineConventionDefines the local newline convention.
MinSizeForConcurrentDownloadFiles bigger than this size will be downloaded concurrently.
ModeWhat to do if the destination file already exists.
ModeZSwitches on data compression.
OptionsVarious FTP options.
RecursiveWhether to scan subdirectories.
TempPathPath for storing temporary files.
TolerateMinorChainIssuesWhether to tolerate minor chain issues.
TransferKeepAliveIntervalKeep-alive interval for the data channel transfers.
TransferTimeoutTimeout for data transfer in active mode.
UseMicrosoftCTLEnables or disables automatic use of Microsoft online certificate trust list.
UseProxySettingsForDataChannelWhether the proxy settings should be applied to data channel.
UseSystemCertificatesEnables or disables the use of the system certificates.
CheckKeyIntegrityBeforeUseEnables or disable private key integrity check before use.
CookieCachingSpecifies whether a cookie cache should be used for HTTP(S) transports.
CookiesGets or sets local cookies for the component (supported for HTTPClient, RESTClient and SOAPClient only).
DefDeriveKeyIterationsSpecifies the default key derivation algorithm iteration count.
EnableClientSideSSLFFDHEEnables or disables finite field DHE key exchange support in TLS clients.
GlobalCookiesGets or sets global cookies for all the HTTP transports.
HttpUserAgentSpecifies the user agent name to be used by all HTTP clients.
LogDestinationSpecifies the debug log destination.
LogDetailsSpecifies the debug log details to dump.
LogFileSpecifies the debug log filename.
LogFiltersSpecifies the debug log filters.
LogFlushModeSpecifies the log flush mode.
LogLevelSpecifies the debug log level.
LogMaxEventCountSpecifies the maximum number of events to cache before further action is taken.
LogRotationModeSpecifies the log rotation mode.
MaxASN1BufferLengthSpecifies the maximal allowed length for ASN.1 primitive tag data.
MaxASN1TreeDepthSpecifies the maximal depth for processed ASN.1 trees.
OCSPHashAlgorithmSpecifies the hash algorithm to be used to identify certificates in OCSP requests.
UseOwnDNSResolverSpecifies whether the client components should use own DNS resolver.
UseSharedSystemStoragesSpecifies whether the validation engine should use a global per-process copy of the system certificate stores.
UseSystemOAEPAndPSSEnforces or disables the use of system-driven RSA OAEP and PSS computations.
UseSystemRandomEnables or disables the use of the OS PRNG.

Copyright (c) 2022 /n software inc. - All rights reserved.
SecureBlackbox 2020 macOS Edition - Version 20.0 [Build 8165]