SecureBlackbox 2020 Python Edition

Questions / Feedback?

SFTPClient Class

Properties   Methods   Events   Configuration Settings   Errors  

The SFTPClient class provides client-side functionality for SFTP (Secure File Transfer Protocol).

Syntax

class secureblackbox.SFTPClient

Remarks

SFTP is a file transfer subsystem that runs on top of secure shell (SSH) connection. This means that SFTP uses the whole strength of security provided by the SSH protocol, at the same time providing strong file transfer capabilities.

Please do keep in mind that there exist two protocols that offer similar secure file transfer features. SFTP works on top of SSH and normally uses port 22. FTPS works on top of TLS (or SSL) and normally uses ports 21 and 990. The protocols are very different, so please make sure you are after the right component. This component works with SFTP. Use the FTPClient component to connect to FTPS servers.

Below are the typical steps that let you integrate SFTPClient to your project:

  • Set up your username and password. SSH uses mandatory client-side authentication, so in most cases you need to provide your username, your password, or, sometimes, your private key. Use key property to provide your key, if needed.
  • Be ready to handle server authentication, which is also mandatory in SSH. SSH operates a concept of a trusted keys file, where keys of known servers are stored. You can assign a path to your own trusted keys file to the trusted_keys_file property. When a client receives a server key, it reports it to your code via its on_known_key_received or on_unknown_key_received event, depending on whether the key was found in the trusted list. If you leave trusted_keys_file empty, SFTPClient will only be able to fire the on_unknown_key_received event, since there will be no known keys to report.
  • If needed, customize proxy parameters and ssh_settings.
  • Consider interacting more with SFTPClient by subscribing to on_auth_attempt, on_auth_failed, and on_auth_succeeded events to be notified about the client authentication progress.
  • When you are ready to connect, call connect, passing the details of the server as parameters. During the initial handshake, the following events will fire: on_unknown_key_received (or on_known_key_received), and then one or more on_auth_attempt, on_auth_failed and on_auth_succeeded.
  • Upon completion of the connect method, the component is ready for file operations. Use download_file, upload_file, list_dir, delete_file and other file transfer methods to work with the server file system.
  • When you are done with your work, call disconnect to close the connection.

Some SFTP servers, primarily older ones, may expose various transfer issues. If you come across a weird issue that you believe should not be happening (such as repeated connection closures in the middle of the transfer), please try adjusting the following properties:

These adjustments will put SFTPClient in very conservative transfer setup. While this setup may be quite sluggish with modern servers, it should make SFTPClient interoperable with most older servers.

Property List


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

auth_attemptsSpecifies the number of SSH authentication attempts.
auto_adjust_transfer_blockSpecifies whether to adjust the send and receive buffer sizes automatically.
connectedIndicates if the client is connected to the SFTP server.
conn_info_client_key_algorithmSpecifies the client's key algorithm.
conn_info_client_key_bitsSpecifies the length of the client's key.
conn_info_client_key_fingerprintThe fingerprint (hash value) of the client's public key.
conn_info_close_reasonContains the line sent by the server just before closing the connection.
conn_info_compression_algorithm_inboundCompression algorithm for the incoming traffic.
conn_info_compression_algorithm_outboundCompression algorithm for the outgoing traffic.
conn_info_encryption_algorithm_inboundEncryption algorithm for the incoming traffic.
conn_info_encryption_algorithm_outboundEncryption algorithm for the outgoing traffic.
conn_info_inbound_encryption_key_bitsSpecifies the length of the key used to encrypt the incoming traffic.
conn_info_kex_algorithmThe key exchange algorithm used during the SSH handshake.
conn_info_kex_bitsThe number of bits used by the key exchange algorithm.
conn_info_kex_linesThe contents of the received KexInit packet.
conn_info_mac_algorithm_inboundMAC algorithm used for the incoming connection.
conn_info_mac_algorithm_outboundMAC algorithm used for outbound connection.
conn_info_outbound_encryption_key_bitsSpecifies the length of the key used to encrypt the outgoing traffic.
conn_info_public_key_algorithmSpecifies the public key algorithm which was used during the SSH handshake.
conn_info_server_key_bitsSpecifies the number of bits in the server's key.
conn_info_server_key_fingerprintThe fingerprint (hash value) of the server's public key.
conn_info_server_software_nameReturns the name of the SSH software running on the server side.
conn_info_total_bytes_receivedReturns the total number of bytes received over this connection.
conn_info_total_bytes_sentReturns the total number of bytes sent over this connection.
conn_info_versionSpecifies SSH protocol version.
curr_list_entry_a_timeContains the last access time for this file, in UTC.
curr_list_entry_c_timeContains this file's creation time, in UTC.
curr_list_entry_directorySpecifies whether this entry is a directory.
curr_list_entry_file_typeSpecifies the type of this entry, one of the following: cftFile 0 cftDirectory 1 cftSymblink 2 cftSpecial 3 cftUnknown 4 cftSocket 5 cftCharDevice 6 cftBlockDevice 7 cftFIFO 8 .
curr_list_entry_group_executeControls file execution permission for the group users.
curr_list_entry_group_readControls file read permission for the group users.
curr_list_entry_group_writeControls file write permission for the group users.
curr_list_entry_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
curr_list_entry_long_nameContains the long name of the file (human-readable, ftp-like).
curr_list_entry_m_timeSpecifies the last modification time, in UTC.
curr_list_entry_nameSpecifies the file name.
curr_list_entry_other_executeControls file execution permission for other users (users that are neither owners, nor belong to the same group).
curr_list_entry_other_readControls file read permission for other users (users that are neither owners, nor belong to the same group).
curr_list_entry_other_writeControls file write permission for other users (users that are neither owners, nor belong to the same group).
curr_list_entry_ownerSpecifies the owner of the file/directory.
curr_list_entry_pathContains the full path to the file.
curr_list_entry_sizeThe size of the file in bytes.
curr_list_entry_user_executeControls file execution permission for the file owner.
curr_list_entry_user_readControls file read permission for the file owner.
curr_list_entry_user_writeControls file write permission for the file owner.
download_block_sizeThe download block size in bytes.
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.
force_compressionEnforces compression for the SSH layer.
key_fingerprint_sha1Contains the SHA-1 fingerprint (hash) of the key.
key_fingerprint_sha256Contains the SHA-256 fingerprint (hash) of the key.
key_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
max_sftp_versionHigher SFTP version to support.
min_sftp_versionLower SFTP version to support.
passwordSpecifies user's authentication password.
pipeline_lengthThe number of parallelized transfer requests.
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.
server_key_algorithmSpecifies the key algorithm.
server_key_bitsThe number of bits in the key: the more the better, 2048 or 4096 are typical values.
server_key_commentThe comment for the public key.
server_key_curveSpecifies the elliptical curve when EC cryptography is used.
server_key_dssgThe G (Generator) parameter of the DSS signature key.
server_key_dsspThe P (Prime) parameter of the DSS signature key.
server_key_dssqThe Q (Prime Factor) parameter of the DSS signature key.
server_key_dssxThe X (Private key) parameter of the DSS signature key.
server_key_dssyThe Y (Public key) parameter of the DSS signature key.
server_key_eccdThe value of the secret key (the order of the public key, D) if elliptic curve (EC) cryptography is used.
server_key_eccqxThe value of the X coordinate of the public key if elliptic curve (EC) cryptography is used.
server_key_eccqyThe value of the Y coordinate of the public key if elliptic curve (EC) cryptography is used.
server_key_ed_privateThe value of the private key if EdDSA (Edwards-curve Digital Signature Algorithm) algorithm is used.
server_key_ed_publicThe value of the public key if EdDSA (Edwards-curve Digital Signature Algorithm) algorithm is used.
server_key_fingerprint_md5Contains the MD5 fingerprint (hash) of the key.
server_key_fingerprint_sha1Contains the SHA-1 fingerprint (hash) of the key.
server_key_fingerprint_sha256Contains the SHA-256 fingerprint (hash) of the key.
server_key_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
server_key_is_extractableWhether the key is extractable (e.
server_key_is_privateWhether this key is a private key or not.
server_key_is_publicWhether this key is a public key or not.
server_key_kdf_roundsReturns the number of iterations of the Key Derivation Function (KDF) used to generate this key.
server_key_kdf_saltThe salt value used by the Key Derivation Function (KDF) to generate this key.
server_key_key_formatSpecifies the format in which the key is stored.
server_key_key_protection_algorithmSpecifies the key protection algorithm.
server_key_rsa_exponentReturns the e parameter (public exponent) of the RSA key.
server_key_rsaiqmpReturns the iqmp parameter of the RSA key.
server_key_rsa_modulusReturns the m parameter (public modulus) of the RSA key.
server_key_rsapReturns the p parameter (first factor of the common modulus n) of the RSA key.
server_key_rsa_private_exponentReturns the d parameter (private exponent) of the RSA key.
server_key_rsaqReturns the q parameter (second factor of the common modulus n) of the RSA key.
server_key_subjectSpecifies the public key owner (subject).
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.
ssh_settings_auto_adjust_ciphersWhether the SSH client should adjust its list of supported ciphers 'on-the-fly' for greater compatibility with the server it is connecting to.
ssh_settings_base_configurationAllows to choose base configuration of SSH settings, tuned up for different purposes such as high security or higher compatibility.
ssh_settings_compression_algorithmsA list of session compression algorithms separated with commas or semicolons.
ssh_settings_compression_levelPossible values for the Compression Level range from 0 (minimum compression) to 9 (maximum compression).
ssh_settings_default_window_sizeThe SSH window size specifies how many bytes the client can send to the server in the command channel without obtaining pre-authorization for the further send from the server.
ssh_settings_encryption_algorithmsA list of session encryption algorithms separated with commas or semicolons.
ssh_settings_force_compressionWhether the SSH client should explicitly request compression.
ssh_settings_gss_auth_typesA comma-separated list of authentication types.
ssh_settings_gss_delegate_credsSwitches credential delegation on or off.
ssh_settings_gss_hostnameThe GSS host name, in form of a FQDN (e.
ssh_settings_gss_libA path to the GSS-API library (DLL or SO).
ssh_settings_gss_mechanismsA comma-separated list of GSS mechanisms to use.
ssh_settings_gss_protocolsA comma-separated list of SSPI protocols.
ssh_settings_handshake_timeoutSpecifies the maximal time for the SSH handshake to proceed, in seconds.
ssh_settings_kex_algorithmsA list of key exchange algorithms separated with commas or semicolons.
ssh_settings_mac_algorithmsA list of MAC (for message authentication code ) algorithms separated with commas or semicolons.
ssh_settings_max_ssh_packet_sizeSpecifies the maximum length of one SSH packet in bytes.
ssh_settings_min_window_sizeSpecifies the minimal internal window size.
ssh_settings_obfuscate_handshakeEnables or disables handshake obfuscation.
ssh_settings_obfuscation_passwordSpecifies the password used to encrypt the handshake when ObfuscateHandshake is set.
ssh_settings_public_key_algorithmsA list of public key algorithms separated with commas or semicolons.
ssh_settings_request_password_changeWhether to request a password change when connecting.
ssh_settings_software_nameThe name to be used by the class to identify itself.
ssh_settings_trust_all_keysEnables or disables explicit trust to all server keys.
ssh_settings_use_auth_agentEnables or disables the use of external key agent, such as Putty key agent.
ssh_settings_versionsSpecifies enabled SSH protocol versions (1 or 2).
trusted_keys_fileA file containing the keys of authorized servers.
upload_block_sizeThe upload block size in bytes.
usernameThe client's username to authenticate to the server.
use_utf8Enables UTF8 for all string content.
versionThe SFTP version negotiated.

Method List


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

absolute_pathRequests the absolute path for a relative path.
change_dirChanges current working directory on the server.
configSets or retrieves a configuration setting.
connectConnects to an SFTP server.
create_linkCreates a symbolic or hard link to a remote file.
delete_dirRemoves directory from the SFTP server.
delete_fileDeletes a file from the SFTP server.
delete_filesDeletes a group of files from the SFTP server.
dir_existsChecks if a directory exists on the SFTP server.
disconnectDisconnects from the SFTP server.
download_bytesDownloads a file from the server into an array of bytes.
download_fileDownloads a file from the SFTP server.
download_filesDownloads multiple files from the SFTP server.
execute_ssh_commandSends an SSH command to the server in the middle of SFTP session.
extension_cmdSends an extension command to the server.
file_existsChecks whether a file exists on the server.
get_current_dirReturns the current directory on the SFTP server.
get_file_sizeChecks the size of a remote file.
list_dirLists the content of the current remote directory.
make_dirCreates a new directory on the server.
rename_fileRenames a file.
request_attributesRequests attributes of the remote file.
set_attributesSets the attributes upon a remote file.
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_auth_attemptFires when an authentication attempt is performed.
on_auth_failedFires if an authentication attempt fails.
on_auth_succeededReports a successful authentication.
on_bannerReports the receipt of the Welcome message from the server.
on_disconnectReports SFTP connection closure.
on_errorInformation about errors during SFTP connection.
on_external_signHandles remote or external signing initiated by the SignExternal method or other source.
on_file_operationSignifies the start of a file transfer operation.
on_file_operation_resultSignifies the completion of a file transfer operation.
on_known_key_receivedSignals that the server has introduced itself with a known key.
on_list_entryReports a directory listing entry to the application.
on_notificationThis event notifies the application about an underlying control flow event.
on_password_change_requestSignals that the server requests a password change.
on_private_key_neededAsks the application for the client's private key.
on_progressFires periodically during the data transfer.
on_unknown_key_receivedSignals that the server has introduced itself with an unknown key.

Configuration Settings


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

AdjustFileTimesWhether file times should be adjusted after upload/download.
ASCIIModeWhether ASCII transfer mode is used.
AvailableSpaceReturns details of server disk space availability. This protocol extension must be supported by the server for this request to work.
CaseConversionWhether case conversion must be applied to file names as they are downloaded.
CaseSensitiveSpecifies if file paths are case-sensitive.
CopyModeDefines what to do with each successfully copied file.
DefOutboundBlockSizeThe default outbound block size.
DisablePacketFragmentationEnables or disables SSH packet fragmentation.
ErrorOriginSpecifies whether the error is local or remote.
ErrorSeveritySpecifies whether the error is fatal.
FileHashReturns the hash of the specified file. This protocol extension must be supported by the server for this request to work.
HashAlgorithmThe hash algorithm to use for the protocol operations.
HomeDirReturns a user's home directory. This protocol extension must be supported by the server for this request to work.
IncomingSpeedLimitSpecifies incoming speed limit.
KeepAlivePeriodThe inactivity period after which a keep-alive signal will be sent.
LocalCharsetCharset used on the client machine.
LocalNewLineConventionA character string for the end of line (EOL) indication on the local machine.
ModeThe file open mode to use.
NewLineConventionA character string for the end of line (EOL) indication on the server.
OutgoingSpeedLimitSpecifies incoming speed limit.
PreserveExistingFileTimesWhether original file times should be restored upon transfer.
RecursiveWhether subdirectories should also be scanned for matching files.
RedirectStdErrWhether to redirect output to StdErr.
RemoteCharsetCharset used on the server.
SFTPBufferSizeThe size of internal buffer used for data transfer.
SFTPServerExecutableLocationsLocation of the SFTP server executable.
StatVFSReturns VFS details. This protocol extension must be supported by the server for this request to work.
StdErrDataThe buffer for writing StdErr data.
TempFolderReturns the temporary directory offered by the server. This protocol extension must be supported by the server for this request to work.
TempPathLocation where the temporary files are stored.
TreatZeroSizeAsUndefinedWhether zero size returned by STAT should be considered as undefined.
UseTruncateFlagOnUploadwhether to use the 'truncate' flag on file upload.
UseUTF8OnV3Whether to apply UTF-8 conversion for SFTP protocol versions 3 and lower.
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]