SecureBlackbox 2020 Java Edition

Questions / Feedback?

SFTPClient Class

Properties   Methods   Events   Configuration Settings   Errors  

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




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 TrustedKeysFile property. When a client receives a server key, it reports it to your code via its KnownKeyReceived or UnknownKeyReceived event, depending on whether the key was found in the trusted list. If you leave TrustedKeysFile empty, SFTPClient will only be able to fire the UnknownKeyReceived event, since there will be no known keys to report.
  • If needed, customize Proxy parameters and SSHSettings.
  • Consider interacting more with SFTPClient by subscribing to AuthAttempt, AuthFailed, and AuthSucceeded 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: UnknownKeyReceived (or KnownKeyReceived), and then one or more AuthAttempt, AuthFailed and AuthSucceeded.
  • Upon completion of the Connect method, the component is ready for file operations. Use DownloadFile, UploadFile, ListDir, DeleteFile 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.

AuthAttemptsSpecifies the number of SSH authentication attempts.
AutoAdjustTransferBlockSpecifies whether to adjust the send and receive buffer sizes automatically.
ConnectedIndicates if the client is connected to the SFTP server.
ConnectionInfoContains the secure connection info.
CurrentListEntryContains the current entry returned by ListDir .
DownloadBlockSizeThe download block size in bytes.
ExternalCryptoProvides access to external signing and DC parameters.
ForceCompressionEnforces compression for the SSH layer.
KeyContains the client's SSH key.
MaxSFTPVersionHigher SFTP version to support.
MinSFTPVersionLower SFTP version to support.
PasswordSpecifies user's authentication password.
PipelineLengthThe number of parallelized transfer requests.
ProxyThe proxy server settings.
ServerKeyReturns the server's public key.
SocketSettingsManages network connection settings.
SSHSettingsThe SSH connection settings.
TrustedKeysFileA file containing the keys of authorized servers.
UploadBlockSizeThe upload block size in bytes.
UsernameThe client's username to authenticate to the server.
UseUTF8Enables 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.

AbsolutePathRequests the absolute path for a relative path.
ChangeDirChanges current working directory on the server.
ConfigSets or retrieves a configuration setting.
ConnectConnects to an SFTP server.
CreateLinkCreates a symbolic or hard link to a remote file.
DeleteDirRemoves directory from the SFTP server.
DeleteFileDeletes a file from the SFTP server.
DeleteFilesDeletes a group of files from the SFTP server.
DirExistsChecks if a directory exists on the SFTP server.
DisconnectDisconnects from the SFTP server.
DownloadBytesDownloads a file from the server into an array of bytes.
DownloadFileDownloads a file from the SFTP server.
DownloadFilesDownloads multiple files from the SFTP server.
DownloadStreamDownloads a file from the SFTP server.
ExecuteSSHCommandSends an SSH command to the server in the middle of SFTP session.
ExtensionCmdSends an extension command to the server.
FileExistsChecks whether a file exists on the server.
GetCurrentDirReturns the current directory on the SFTP server.
GetFileSizeChecks the size of a remote file.
ListDirLists the content of the current remote directory.
MakeDirCreates a new directory on the server.
RenameFileRenames a file.
RequestAttributesRequests attributes of the remote file.
SetAttributesSets the attributes upon a remote file.
UploadBytesUploads a byte array to the server.
UploadFileUploads a file to the server.
UploadFilesUploads multiple files to the server.
UploadStreamUploads a file 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.

AuthAttemptFires when an authentication attempt is performed.
AuthFailedFires if an authentication attempt fails.
AuthSucceededReports a successful authentication.
BannerReports the receipt of the Welcome message from the server.
DisconnectReports SFTP connection closure.
ErrorInformation about errors during SFTP connection.
ExternalSignHandles remote or external signing initiated by the SignExternal method or other source.
FileOperationSignifies the start of a file transfer operation.
FileOperationResultSignifies the completion of a file transfer operation.
KnownKeyReceivedSignals that the server has introduced itself with a known key.
ListEntryReports a directory listing entry to the application.
NotificationThis event notifies the application about an underlying control flow event.
PasswordChangeRequestSignals that the server requests a password change.
PrivateKeyNeededAsks the application for the client's private key.
ProgressFires periodically during the data transfer.
UnknownKeyReceivedSignals 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 Java Edition - Version 20.0 [Build 8165]