SecureBlackbox 2020 Python Edition

Questions / Feedback?

FTPClient Class

Properties   Methods   Events   Configuration Settings   Errors  

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

Syntax

class 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 tls_settings property to adjust this setting.
  • If your server requires you to authenticate with a certificate, you can provide one via the client_chain 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 trusted_certificates and known_certificates collections.
  • FTP protocol includes its own set of settings, such as passive_mode, encrypt_data_channel, or adjust_pasv_address. These may be configured on this stage, or later into the connection.
  • In some network environments, you may also need to make adjustments to socket_settings 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 (upload_file or upload_bytes), file downloads (download_file, download_bytes), and directory operations (list_dir, make_dir).

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. on_progress event fires periodically during the transfer operation to let you know of the operation progress. on_control_send and on_control_receive report the protocol communication log. on_file_operation and on_file_operation_result report the start and completion of an individual transfer operation within a multi-file transfer call (such as upload_files).

Property List


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

adjust_pasv_addressEnables or disables automatic adjustment of passive-mode addresses.
blocked_cert_countThe number of records in the BlockedCert arrays.
blocked_cert_bytesReturns raw certificate data in DER format.
blocked_cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
client_cert_countThe number of records in the ClientCert arrays.
client_cert_bytesReturns raw certificate data in DER format.
client_cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
connectedIndicates whether the class is connected to the server.
ctl_conn_info_aead_cipherIndicates whether the encryption algorithm used is an AEAD cipher.
ctl_conn_info_chain_validation_detailsThe details of a certificate chain validation outcome.
ctl_conn_info_chain_validation_resultThe outcome of a certificate chain validation routine.
ctl_conn_info_ciphersuiteThe cipher suite employed by this connection.
ctl_conn_info_client_authenticatedSpecifies whether client authentication was performed during this connection.
ctl_conn_info_client_auth_requestedSpecifies whether client authentication was requested during this connection.
ctl_conn_info_connection_establishedIndicates whether the connection has been established fully.
ctl_conn_info_connection_idThe unique identifier assigned to this connection.
ctl_conn_info_digest_algorithmThe digest algorithm used in a TLS-enabled connection.
ctl_conn_info_encryption_algorithmThe symmetric encryption algorithm used in a TLS-enabled connection.
ctl_conn_info_exportableIndicates whether a TLS connection uses a reduced-strength exportable cipher.
ctl_conn_info_key_exchange_algorithmThe key exchange algorithm used in a TLS-enabled connection.
ctl_conn_info_key_exchange_key_bitsThe length of the key exchange key of a TLS-enabled connection.
ctl_conn_info_named_ec_curveThe elliptic curve used in this connection.
ctl_conn_info_pfs_cipherIndicates whether the chosen ciphersuite provides perfect forward secrecy (PFS).
ctl_conn_info_pre_shared_identity_hintA hint professed by the server to help the client select the PSK identity to use.
ctl_conn_info_public_key_bitsThe length of the public key.
ctl_conn_info_resumed_sessionIndicates whether a TLS-enabled connection was spawned from another TLS connection.
ctl_conn_info_secure_connectionIndicates whether TLS or SSL is enabled for this connection.
ctl_conn_info_server_authenticatedIndicates whether server authentication was performed during a TLS-enabled connection.
ctl_conn_info_signature_algorithmThe signature algorithm used in a TLS handshake.
ctl_conn_info_symmetric_block_sizeThe block size of the symmetric algorithm used.
ctl_conn_info_symmetric_key_bitsThe key length of the symmetric algorithm used.
ctl_conn_info_total_bytes_receivedThe total number of bytes received over this connection.
ctl_conn_info_total_bytes_sentThe total number of bytes sent over this connection.
ctl_conn_info_validation_logContains the server certificate's chain validation log.
ctl_conn_info_versionIndicates the version of SSL/TLS protocol negotiated during this connection.
curr_list_entry_entry_formatThe file listing format: cfefUnknown 0 cfefUnix 1 cfefWindows 2 cfefMLSD 3 .
curr_list_entry_file_dateFile last modification date.
curr_list_entry_file_typeThe type of the entry: cfetUnknown 0 cfetDirectory 1 cfetFile 2 cfetSymlink 3 cfetSpecial 4 cfetCurrentDirectory 5 cfetParentDirectory 6 .
curr_list_entry_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
curr_list_entry_nameThe file or directory name.
curr_list_entry_pathThe full path to the file or directory.
curr_list_entry_raw_dataThe unparsed entry as returned by the server.
curr_list_entry_sizeFile size in bytes.
data_conn_info_aead_cipherIndicates whether the encryption algorithm used is an AEAD cipher.
data_conn_info_chain_validation_detailsThe details of a certificate chain validation outcome.
data_conn_info_chain_validation_resultThe outcome of a certificate chain validation routine.
data_conn_info_ciphersuiteThe cipher suite employed by this connection.
data_conn_info_client_authenticatedSpecifies whether client authentication was performed during this connection.
data_conn_info_client_auth_requestedSpecifies whether client authentication was requested during this connection.
data_conn_info_connection_establishedIndicates whether the connection has been established fully.
data_conn_info_connection_idThe unique identifier assigned to this connection.
data_conn_info_digest_algorithmThe digest algorithm used in a TLS-enabled connection.
data_conn_info_encryption_algorithmThe symmetric encryption algorithm used in a TLS-enabled connection.
data_conn_info_exportableIndicates whether a TLS connection uses a reduced-strength exportable cipher.
data_conn_info_key_exchange_algorithmThe key exchange algorithm used in a TLS-enabled connection.
data_conn_info_key_exchange_key_bitsThe length of the key exchange key of a TLS-enabled connection.
data_conn_info_named_ec_curveThe elliptic curve used in this connection.
data_conn_info_pfs_cipherIndicates whether the chosen ciphersuite provides perfect forward secrecy (PFS).
data_conn_info_pre_shared_identity_hintA hint professed by the server to help the client select the PSK identity to use.
data_conn_info_public_key_bitsThe length of the public key.
data_conn_info_resumed_sessionIndicates whether a TLS-enabled connection was spawned from another TLS connection.
data_conn_info_secure_connectionIndicates whether TLS or SSL is enabled for this connection.
data_conn_info_server_authenticatedIndicates whether server authentication was performed during a TLS-enabled connection.
data_conn_info_signature_algorithmThe signature algorithm used in a TLS handshake.
data_conn_info_symmetric_block_sizeThe block size of the symmetric algorithm used.
data_conn_info_symmetric_key_bitsThe key length of the symmetric algorithm used.
data_conn_info_total_bytes_receivedThe total number of bytes received over this connection.
data_conn_info_total_bytes_sentThe total number of bytes sent over this connection.
data_conn_info_validation_logContains the server certificate's chain validation log.
data_conn_info_versionIndicates the version of SSL/TLS protocol negotiated during this connection.
encrypt_data_channelEnables or disables data channel encryption.
external_crypto_custom_paramsCustom parameters to be passed to the signing service (uninterpreted).
external_crypto_dataAdditional data to be included in the async state and mirrored back by the requestor.
external_crypto_external_hash_calculationSpecifies whether the message hash is to be calculated at the external endpoint.
external_crypto_hash_algorithmSpecifies the request's signature hash algorithm.
external_crypto_key_idThe ID of the pre-shared key used for DC request authentication.
external_crypto_key_secretThe pre-shared key used for DC request authentication.
external_crypto_methodSpecifies the asynchronous signing method.
external_crypto_modeSpecifies the external cryptography mode.
external_crypto_public_key_algorithmProvide public key algorithm here if the certificate is not available on the pre-signing stage.
known_cert_countThe number of records in the KnownCert arrays.
known_cert_bytesReturns raw certificate data in DER format.
known_cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
known_crl_countThe number of records in the KnownCRL arrays.
known_crl_bytesReturns raw CRL data in DER format.
known_crl_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
known_ocsp_countThe number of records in the KnownOCSP arrays.
known_ocsp_bytesBuffer containing raw OCSP response data.
known_ocsp_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
passive_modeEnables or disables passive transfer mode.
passwordThe connecting user's authentication password.
proxy_addressThe IP address of the proxy server.
proxy_authenticationThe authentication type used by the proxy server.
proxy_passwordThe password to authenticate to the proxy server.
proxy_portThe port on the proxy server to connect to.
proxy_proxy_typeThe type of the proxy server.
proxy_request_headersContains HTTP request headers for WebTunnel and HTTP proxy.
proxy_response_bodyContains the HTTP or HTTPS (WebTunnel) proxy response body.
proxy_response_headersContains response headers received from an HTTP or HTTPS (WebTunnel) proxy server.
proxy_use_i_pv6Specifies whether IPv6 should be used when connecting through the proxy.
proxy_use_proxyEnables or disables proxy-driven connection.
proxy_usernameSpecifies the username credential for proxy authentication.
restart_atThe offset to restart the file transfer from.
server_cert_countThe number of records in the ServerCert arrays.
server_cert_bytesReturns raw certificate data in DER format.
server_cert_ca_key_idA unique identifier (fingerprint) of the CA certificate's private key.
server_cert_fingerprintContains the fingerprint (a hash imprint) of this certificate.
server_cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
server_cert_issuerThe common name of the certificate issuer (CA), typically a company name.
server_cert_issuer_rdnA collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate issuer.
server_cert_key_algorithmSpecifies the public key algorithm of this certificate.
server_cert_key_bitsReturns the length of the public key.
server_cert_key_fingerprintReturns a fingerprint of the public key contained in the certificate.
server_cert_key_usageIndicates the purposes of the key contained in the certificate, in the form of an OR'ed flag set.
server_cert_public_key_bytesContains the certificate's public key in DER format.
server_cert_self_signedIndicates whether the certificate is self-signed (root) or signed by an external CA.
server_cert_serial_numberReturns the certificate's serial number.
server_cert_sig_algorithmIndicates the algorithm that was used by the CA to sign this certificate.
server_cert_subjectThe common name of the certificate holder, typically an individual's name, a URL, an e-mail address, or a company name.
server_cert_subject_key_idContains a unique identifier (fingerprint) of the certificate's private key.
server_cert_subject_rdnA collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate holder (subject).
server_cert_valid_fromThe time point at which the certificate becomes valid, in UTC.
server_cert_valid_toThe time point at which the certificate expires, in UTC.
socket_dns_modeSelects the DNS resolver to use: the class's (secure) built-in one, or the one provided by the system.
socket_dns_portSpecifies the port number to be used for sending queries to the DNS server.
socket_dns_query_timeoutThe timeout (in milliseconds) for each DNS query.
socket_dns_serversThe addresses of DNS servers to use for address resolution, separated by commas or semicolons.
socket_dns_total_timeoutThe timeout (in milliseconds) for the whole resolution process.
socket_incoming_speed_limitThe maximum number of bytes to read from the socket, per second.
socket_local_addressThe local network interface to bind the socket to.
socket_local_portThe local port number to bind the socket to.
socket_outgoing_speed_limitThe maximum number of bytes to write to the socket, per second.
socket_timeoutThe maximum period of waiting, in milliseconds, after which the socket operation is considered unsuccessful.
socket_use_i_pv6Enables or disables IP protocol version 6.
tls_auto_validate_certificatesSpecifies whether server-side TLS certificates should be validated automatically using internal validation rules.
tls_base_configurationSelects the base configuration for the TLS settings.
tls_ciphersuitesA list of ciphersuites separated with commas or semicolons.
tlsec_curvesDefines the elliptic curves to enable.
tls_force_resume_if_destination_changesWhether to force TLS session resumption when the destination address changes.
tls_pre_shared_identityDefines the identity used when the PSK (Pre-Shared Key) key-exchange mechanism is negotiated.
tls_pre_shared_keyContains the pre-shared for the PSK (Pre-Shared Key) key-exchange mechanism, encoded with base16.
tls_pre_shared_key_ciphersuiteDefines the ciphersuite used for PSK (Pre-Shared Key) negotiation.
tls_renegotiation_attack_prevention_modeSelects renegotiation attack prevention mechanism.
tls_revocation_checkSpecifies the kind(s) of revocation check to perform.
tlsssl_optionsVarious 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.
tlstls_modeSpecifies the TLS mode to use.
tls_use_extended_master_secretEnables Extended Master Secret Extension, as defined in RFC 7627.
tls_use_session_resumptionEnables or disables TLS session resumption capability.
tls_versionsTh SSL/TLS versions to enable by default.
transfer_typeSets the file transfer mode.
trusted_cert_countThe number of records in the TrustedCert arrays.
trusted_cert_bytesReturns raw certificate data in DER format.
trusted_cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
usernameThe 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.

abortAborts the previous FTP service command and any associated transfer of data.
acctSends an Account command.
append_bytesAppends a byte array to a server-side file.
append_fileUploads a file to the server.
change_dirChanges the current directory.
clear_command_channelSends CCC (Clear Command Channel) command to the server.
configSets or retrieves a configuration setting.
connectConnects to the FTP server.
delete_dirDeletes a directory on the server.
delete_fileDeletes a file on the server.
dir_existsChecks if a directory exists on the server.
disconnectDisconnects from the server.
download_bytesDownloads a file from the server into an array of bytes.
download_fileDownloads a file from the server.
download_filesDownloads multiple files from the server.
file_existsChecks if a file exists on the server.
get_current_dirReturns the server-side current directory.
get_file_sizeReturns the size of a remote file.
list_dirLists the contents of a remote directory.
make_dirCreates a new directory on the server.
noopSends a NOOP command to the server.
renameRenames a file.
send_commandSends a custom command to the server.
upload_bytesUploads a byte array to the server.
upload_fileUploads a file to the server.
upload_filesUploads 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.

on_certificate_validateFires when the server's TLS certificate has to be validated.
on_control_receiveFires when data is received via the control channel.
on_control_sendFires when data is about to be set via the control channel.
on_errorInformation about errors during data delivery.
on_external_signHandles remote or external signing initiated by the SignExternal method or other source.
on_file_operationMarks the start of a file transfer.
on_file_operation_resultReports the result of a file transfer operation.
on_list_entryReports a single entry from the requested directory listing.
on_notificationThis event notifies the application about an underlying control flow event.
on_progressReports the data transfer progress.
on_text_data_lineReports 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.

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 class (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 classes 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 Python Edition - Version 20.0 [Build 8154]