FTPClient Class
Properties Methods Events Configuration Settings Errors
The FTPClient class provides client-side functionality for FTP and FTPS protocols.
Syntax
secureblackbox.ftpclient()
Remarks
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 class with short descriptions. Click on the links for further details.
AdjustPasvAddress | Enables or disables automatic adjustment of passive-mode addresses. |
BlockedCertCount | The number of records in the BlockedCert arrays. |
BlockedCertBytes | Returns raw certificate data in DER format. |
BlockedCertHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
ClientCertCount | The number of records in the ClientCert arrays. |
ClientCertBytes | Returns raw certificate data in DER format. |
ClientCertHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
Connected | Indicates whether the class is connected to the server. |
CtlConnInfoAEADCipher | Indicates whether the encryption algorithm used is an AEAD cipher. |
CtlConnInfoChainValidationDetails | The details of a certificate chain validation outcome. |
CtlConnInfoChainValidationResult | The outcome of a certificate chain validation routine. |
CtlConnInfoCiphersuite | The cipher suite employed by this connection. |
CtlConnInfoClientAuthenticated | Specifies whether client authentication was performed during this connection. |
CtlConnInfoClientAuthRequested | Specifies whether client authentication was requested during this connection. |
CtlConnInfoConnectionEstablished | Indicates whether the connection has been established fully. |
CtlConnInfoConnectionID | The unique identifier assigned to this connection. |
CtlConnInfoDigestAlgorithm | The digest algorithm used in a TLS-enabled connection. |
CtlConnInfoEncryptionAlgorithm | The symmetric encryption algorithm used in a TLS-enabled connection. |
CtlConnInfoExportable | Indicates whether a TLS connection uses a reduced-strength exportable cipher. |
CtlConnInfoKeyExchangeAlgorithm | The key exchange algorithm used in a TLS-enabled connection. |
CtlConnInfoKeyExchangeKeyBits | The length of the key exchange key of a TLS-enabled connection. |
CtlConnInfoNamedECCurve | The elliptic curve used in this connection. |
CtlConnInfoPFSCipher | Indicates whether the chosen ciphersuite provides perfect forward secrecy (PFS). |
CtlConnInfoPreSharedIdentityHint | A hint professed by the server to help the client select the PSK identity to use. |
CtlConnInfoPublicKeyBits | The length of the public key. |
CtlConnInfoResumedSession | Indicates whether a TLS-enabled connection was spawned from another TLS connection. |
CtlConnInfoSecureConnection | Indicates whether TLS or SSL is enabled for this connection. |
CtlConnInfoServerAuthenticated | Indicates whether server authentication was performed during a TLS-enabled connection. |
CtlConnInfoSignatureAlgorithm | The signature algorithm used in a TLS handshake. |
CtlConnInfoSymmetricBlockSize | The block size of the symmetric algorithm used. |
CtlConnInfoSymmetricKeyBits | The key length of the symmetric algorithm used. |
CtlConnInfoTotalBytesReceived | The total number of bytes received over this connection. |
CtlConnInfoTotalBytesSent | The total number of bytes sent over this connection. |
CtlConnInfoValidationLog | Contains the server certificate's chain validation log. |
CtlConnInfoVersion | Indicates the version of SSL/TLS protocol negotiated during this connection. |
CurrListEntryEntryFormat | The file listing format: cfefUnknown 0 cfefUnix 1 cfefWindows 2 cfefMLSD 3 . |
CurrListEntryFileDate | File last modification date. |
CurrListEntryFileType | The type of the entry: cfetUnknown 0 cfetDirectory 1 cfetFile 2 cfetSymlink 3 cfetSpecial 4 cfetCurrentDirectory 5 cfetParentDirectory 6 . |
CurrListEntryHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
CurrListEntryName | The file or directory name. |
CurrListEntryPath | The full path to the file or directory. |
CurrListEntryRawData | The unparsed entry as returned by the server. |
CurrListEntrySize | File size in bytes. |
DataConnInfoAEADCipher | Indicates whether the encryption algorithm used is an AEAD cipher. |
DataConnInfoChainValidationDetails | The details of a certificate chain validation outcome. |
DataConnInfoChainValidationResult | The outcome of a certificate chain validation routine. |
DataConnInfoCiphersuite | The cipher suite employed by this connection. |
DataConnInfoClientAuthenticated | Specifies whether client authentication was performed during this connection. |
DataConnInfoClientAuthRequested | Specifies whether client authentication was requested during this connection. |
DataConnInfoConnectionEstablished | Indicates whether the connection has been established fully. |
DataConnInfoConnectionID | The unique identifier assigned to this connection. |
DataConnInfoDigestAlgorithm | The digest algorithm used in a TLS-enabled connection. |
DataConnInfoEncryptionAlgorithm | The symmetric encryption algorithm used in a TLS-enabled connection. |
DataConnInfoExportable | Indicates whether a TLS connection uses a reduced-strength exportable cipher. |
DataConnInfoKeyExchangeAlgorithm | The key exchange algorithm used in a TLS-enabled connection. |
DataConnInfoKeyExchangeKeyBits | The length of the key exchange key of a TLS-enabled connection. |
DataConnInfoNamedECCurve | The elliptic curve used in this connection. |
DataConnInfoPFSCipher | Indicates whether the chosen ciphersuite provides perfect forward secrecy (PFS). |
DataConnInfoPreSharedIdentityHint | A hint professed by the server to help the client select the PSK identity to use. |
DataConnInfoPublicKeyBits | The length of the public key. |
DataConnInfoResumedSession | Indicates whether a TLS-enabled connection was spawned from another TLS connection. |
DataConnInfoSecureConnection | Indicates whether TLS or SSL is enabled for this connection. |
DataConnInfoServerAuthenticated | Indicates whether server authentication was performed during a TLS-enabled connection. |
DataConnInfoSignatureAlgorithm | The signature algorithm used in a TLS handshake. |
DataConnInfoSymmetricBlockSize | The block size of the symmetric algorithm used. |
DataConnInfoSymmetricKeyBits | The key length of the symmetric algorithm used. |
DataConnInfoTotalBytesReceived | The total number of bytes received over this connection. |
DataConnInfoTotalBytesSent | The total number of bytes sent over this connection. |
DataConnInfoValidationLog | Contains the server certificate's chain validation log. |
DataConnInfoVersion | Indicates the version of SSL/TLS protocol negotiated during this connection. |
EncryptDataChannel | Enables or disables data channel encryption. |
ExternalCryptoCustomParams | Custom parameters to be passed to the signing service (uninterpreted). |
ExternalCryptoData | Additional data to be included in the async state and mirrored back by the requestor. |
ExternalCryptoExternalHashCalculation | Specifies whether the message hash is to be calculated at the external endpoint. |
ExternalCryptoHashAlgorithm | Specifies the request's signature hash algorithm. |
ExternalCryptoKeyID | The ID of the pre-shared key used for DC request authentication. |
ExternalCryptoKeySecret | The pre-shared key used for DC request authentication. |
ExternalCryptoMethod | Specifies the asynchronous signing method. |
ExternalCryptoMode | Specifies the external cryptography mode. |
ExternalCryptoPublicKeyAlgorithm | Provide public key algorithm here if the certificate is not available on the pre-signing stage. |
KnownCertCount | The number of records in the KnownCert arrays. |
KnownCertBytes | Returns raw certificate data in DER format. |
KnownCertHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
KnownCRLCount | The number of records in the KnownCRL arrays. |
KnownCRLBytes | Returns raw CRL data in DER format. |
KnownCRLHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
KnownOCSPCount | The number of records in the KnownOCSP arrays. |
KnownOCSPBytes | Buffer containing raw OCSP response data. |
KnownOCSPHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
PassiveMode | Enables or disables passive transfer mode. |
Password | The connecting user's authentication password. |
ProxyAddress | The IP address of the proxy server. |
ProxyAuthentication | The authentication type used by the proxy server. |
ProxyPassword | The password to authenticate to the proxy server. |
ProxyPort | The port on the proxy server to connect to. |
ProxyProxyType | The type of the proxy server. |
ProxyRequestHeaders | Contains HTTP request headers for WebTunnel and HTTP proxy. |
ProxyResponseBody | Contains the HTTP or HTTPS (WebTunnel) proxy response body. |
ProxyResponseHeaders | Contains response headers received from an HTTP or HTTPS (WebTunnel) proxy server. |
ProxyUseIPv6 | Specifies whether IPv6 should be used when connecting through the proxy. |
ProxyUseProxy | Enables or disables proxy-driven connection. |
ProxyUsername | Specifies the username credential for proxy authentication. |
RestartAt | The offset to restart the file transfer from. |
ServerCertCount | The number of records in the ServerCert arrays. |
ServerCertBytes | Returns raw certificate data in DER format. |
ServerCertCAKeyID | A unique identifier (fingerprint) of the CA certificate's private key. |
ServerCertFingerprint | Contains the fingerprint (a hash imprint) of this certificate. |
ServerCertHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
ServerCertIssuer | The common name of the certificate issuer (CA), typically a company name. |
ServerCertIssuerRDN | A collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate issuer. |
ServerCertKeyAlgorithm | Specifies the public key algorithm of this certificate. |
ServerCertKeyBits | Returns the length of the public key. |
ServerCertKeyFingerprint | Returns a fingerprint of the public key contained in the certificate. |
ServerCertKeyUsage | Indicates the purposes of the key contained in the certificate, in the form of an OR'ed flag set. |
ServerCertPublicKeyBytes | Contains the certificate's public key in DER format. |
ServerCertSelfSigned | Indicates whether the certificate is self-signed (root) or signed by an external CA. |
ServerCertSerialNumber | Returns the certificate's serial number. |
ServerCertSigAlgorithm | Indicates the algorithm that was used by the CA to sign this certificate. |
ServerCertSubject | The common name of the certificate holder, typically an individual's name, a URL, an e-mail address, or a company name. |
ServerCertSubjectKeyID | Contains a unique identifier (fingerprint) of the certificate's private key. |
ServerCertSubjectRDN | A collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate holder (subject). |
ServerCertValidFrom | The time point at which the certificate becomes valid, in UTC. |
ServerCertValidTo | The time point at which the certificate expires, in UTC. |
SocketDNSMode | Selects the DNS resolver to use: the class's (secure) built-in one, or the one provided by the system. |
SocketDNSPort | Specifies the port number to be used for sending queries to the DNS server. |
SocketDNSQueryTimeout | The timeout (in milliseconds) for each DNS query. |
SocketDNSServers | The addresses of DNS servers to use for address resolution, separated by commas or semicolons. |
SocketDNSTotalTimeout | The timeout (in milliseconds) for the whole resolution process. |
SocketIncomingSpeedLimit | The maximum number of bytes to read from the socket, per second. |
SocketLocalAddress | The local network interface to bind the socket to. |
SocketLocalPort | The local port number to bind the socket to. |
SocketOutgoingSpeedLimit | The maximum number of bytes to write to the socket, per second. |
SocketTimeout | The maximum period of waiting, in milliseconds, after which the socket operation is considered unsuccessful. |
SocketUseIPv6 | Enables or disables IP protocol version 6. |
TLSAutoValidateCertificates | Specifies whether server-side TLS certificates should be validated automatically using internal validation rules. |
TLSBaseConfiguration | Selects the base configuration for the TLS settings. |
TLSCiphersuites | A list of ciphersuites separated with commas or semicolons. |
TLSECCurves | Defines the elliptic curves to enable. |
TLSForceResumeIfDestinationChanges | Whether to force TLS session resumption when the destination address changes. |
TLSPreSharedIdentity | Defines the identity used when the PSK (Pre-Shared Key) key-exchange mechanism is negotiated. |
TLSPreSharedKey | Contains the pre-shared for the PSK (Pre-Shared Key) key-exchange mechanism, encoded with base16. |
TLSPreSharedKeyCiphersuite | Defines the ciphersuite used for PSK (Pre-Shared Key) negotiation. |
TLSRenegotiationAttackPreventionMode | Selects renegotiation attack prevention mechanism. |
TLSRevocationCheck | Specifies the kind(s) of revocation check to perform. |
TLSSSLOptions | Various SSL (TLS) protocol options, set of cssloExpectShutdownMessage 0x001 Wait for the close-notify message when shutting down the connection cssloOpenSSLDTLSWorkaround 0x002 (DEPRECATED) Use a DTLS version workaround when talking to very old OpenSSL versions cssloDisableKexLengthAlignment 0x004 Do not align the client-side PMS by the RSA modulus size. |
TLSTLSMode | Specifies the TLS mode to use. |
TLSUseExtendedMasterSecret | Enables Extended Master Secret Extension, as defined in RFC 7627. |
TLSUseSessionResumption | Enables or disables TLS session resumption capability. |
TLSVersions | Th SSL/TLS versions to enable by default. |
TransferType | Sets the file transfer mode. |
TrustedCertCount | The number of records in the TrustedCert arrays. |
TrustedCertBytes | Returns raw certificate data in DER format. |
TrustedCertHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
Username | The connecting user's username (login name). |
Method List
The following is the full list of the methods of the class with short descriptions. Click on the links for further details.
Abort | Aborts the previous FTP service command and any associated transfer of data. |
Acct | Sends an Account command. |
AppendBytes | Appends a byte array to a server-side file. |
AppendFile | Uploads a file to the server. |
ChangeDir | Changes the current directory. |
ClearCommandChannel | Sends CCC (Clear Command Channel) command to the server. |
Config | Sets or retrieves a configuration setting. |
Connect | Connects to the FTP server. |
DeleteDir | Deletes a directory on the server. |
DeleteFile | Deletes a file on the server. |
DirExists | Checks if a directory exists on the server. |
Disconnect | Disconnects from the server. |
DownloadBytes | Downloads a file from the server into an array of bytes. |
DownloadFile | Downloads a file from the server. |
DownloadFiles | Downloads multiple files from the server. |
FileExists | Checks if a file exists on the server. |
GetCurrentDir | Returns the server-side current directory. |
GetFileSize | Returns the size of a remote file. |
ListDir | Lists the contents of a remote directory. |
MakeDir | Creates a new directory on the server. |
Noop | Sends a NOOP command to the server. |
Rename | Renames a file. |
SendCommand | Sends a custom command to the server. |
UploadBytes | Uploads a byte array to the server. |
UploadFile | Uploads a file to the server. |
UploadFiles | Uploads multiple files to 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.
CertificateValidate | Fires when the server's TLS certificate has to be validated. |
ControlReceive | Fires when data is received via the control channel. |
ControlSend | Fires when data is about to be set via the control channel. |
Error | Information about errors during data delivery. |
ExternalSign | Handles remote or external signing initiated by the SignExternal method or other source. |
FileOperation | Marks the start of a file transfer. |
FileOperationResult | Reports the result of a file transfer operation. |
ListEntry | Reports a single entry from the requested directory listing. |
Notification | This event notifies the application about an underlying control flow event. |
Progress | Reports the data transfer progress. |
TextDataLine | Reports next transferred data line. |
Configuration Settings
The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.
AccountInfo | Parameters for the ACCT command. |
AuthCmd | Authorization command to be used to request an explicit SSL session. |
CaseConversion | Whether file names and paths should be case-converted. |
CaseSensitive | Case-sensitivity of file names and paths. |
CloseQuietly | Set this to true to avoid sending QUIT command on session closure. |
ConcurrentConnections | Number of simultaneous connections for download. |
CopyMode | What to do with the originals of the copied files. |
ErrorOrigin | Specifies where the error has been originated. |
ErrorSeverity | Error severity. |
EventOrigin | Indicates the channel that has fired the event. |
ExtHOSTSupported | Whether HOST extension is supported. |
ExtMDTMSupported | Whether MDTM extension is supported. |
ExtMFMTSupported | Whether MFMT extension is supported. |
ExtMLSTSupported | Whether MLST extension is supported. |
ExtOPTSUTF8Supported | Whether OPTS UTF8 extension is supported. |
ExtRESTSupported | Whether REST extension is supported. |
ExtSIZESupported | Whether SIZE extension is supported. |
ExtXCRCSupported | Whether XCRC extension is supported. |
ExtXMD5Supported | Whether XMD5 extension is supported. |
FTPBufferSize | Buffer size in binary mode. |
FTPTextBufferSize | Buffer size in text mode. |
IgnoreSystemTrust | Whether trusted Windows Certificate Stores should be treated as trusted. |
ListenTimeout | Listening socket timeout. |
LocalNewLineConvention | Defines the local newline convention. |
MinSizeForConcurrentDownload | Files bigger than this size will be downloaded concurrently. |
Mode | What to do if the destination file already exists. |
ModeZ | Switches on data compression. |
Options | Various FTP options. |
Recursive | Whether to scan subdirectories. |
TempPath | Path for storing temporary files. |
TolerateMinorChainIssues | Whether to tolerate minor chain issues. |
TransferKeepAliveInterval | Keep-alive interval for the data channel transfers. |
TransferTimeout | Timeout for data transfer in active mode. |
UseMicrosoftCTL | Enables or disables automatic use of Microsoft online certificate trust list. |
UseProxySettingsForDataChannel | Whether the proxy settings should be applied to data channel. |
UseSystemCertificates | Enables or disables the use of the system certificates. |
CheckKeyIntegrityBeforeUse | Enables or disable private key integrity check before use. |
CookieCaching | Specifies whether a cookie cache should be used for HTTP(S) transports. |
Cookies | Gets or sets local cookies for the class (supported for HTTPClient, RESTClient and SOAPClient only). |
DefDeriveKeyIterations | Specifies the default key derivation algorithm iteration count. |
EnableClientSideSSLFFDHE | Enables or disables finite field DHE key exchange support in TLS clients. |
GlobalCookies | Gets or sets global cookies for all the HTTP transports. |
HttpUserAgent | Specifies the user agent name to be used by all HTTP clients. |
LogDestination | Specifies the debug log destination. |
LogDetails | Specifies the debug log details to dump. |
LogFile | Specifies the debug log filename. |
LogFilters | Specifies the debug log filters. |
LogFlushMode | Specifies the log flush mode. |
LogLevel | Specifies the debug log level. |
LogMaxEventCount | Specifies the maximum number of events to cache before further action is taken. |
LogRotationMode | Specifies the log rotation mode. |
MaxASN1BufferLength | Specifies the maximal allowed length for ASN.1 primitive tag data. |
MaxASN1TreeDepth | Specifies the maximal depth for processed ASN.1 trees. |
OCSPHashAlgorithm | Specifies the hash algorithm to be used to identify certificates in OCSP requests. |
UseOwnDNSResolver | Specifies whether the client classes should use own DNS resolver. |
UseSharedSystemStorages | Specifies whether the validation engine should use a global per-process copy of the system certificate stores. |
UseSystemOAEPAndPSS | Enforces or disables the use of system-driven RSA OAEP and PSS computations. |
UseSystemRandom | Enables or disables the use of the OS PRNG. |