SecureBlackbox 2020 C++ 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

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 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.
ConnInfoClientKeyAlgorithmSpecifies the client's key algorithm.
ConnInfoClientKeyBitsSpecifies the length of the client's key.
ConnInfoClientKeyFingerprintThe fingerprint (hash value) of the client's public key.
ConnInfoCloseReasonContains the line sent by the server just before closing the connection.
ConnInfoCompressionAlgorithmInboundCompression algorithm for the incoming traffic.
ConnInfoCompressionAlgorithmOutboundCompression algorithm for the outgoing traffic.
ConnInfoEncryptionAlgorithmInboundEncryption algorithm for the incoming traffic.
ConnInfoEncryptionAlgorithmOutboundEncryption algorithm for the outgoing traffic.
ConnInfoInboundEncryptionKeyBitsSpecifies the length of the key used to encrypt the incoming traffic.
ConnInfoKexAlgorithmThe key exchange algorithm used during the SSH handshake.
ConnInfoKexBitsThe number of bits used by the key exchange algorithm.
ConnInfoKexLinesThe contents of the received KexInit packet.
ConnInfoMacAlgorithmInboundMAC algorithm used for the incoming connection.
ConnInfoMacAlgorithmOutboundMAC algorithm used for outbound connection.
ConnInfoOutboundEncryptionKeyBitsSpecifies the length of the key used to encrypt the outgoing traffic.
ConnInfoPublicKeyAlgorithmSpecifies the public key algorithm which was used during the SSH handshake.
ConnInfoServerKeyBitsSpecifies the number of bits in the server's key.
ConnInfoServerKeyFingerprintThe fingerprint (hash value) of the server's public key.
ConnInfoServerSoftwareNameReturns the name of the SSH software running on the server side.
ConnInfoTotalBytesReceivedReturns the total number of bytes received over this connection.
ConnInfoTotalBytesSentReturns the total number of bytes sent over this connection.
ConnInfoVersionSpecifies SSH protocol version.
CurrListEntryATimeContains the last access time for this file, in UTC.
CurrListEntryCTimeContains this file's creation time, in UTC.
CurrListEntryDirectorySpecifies whether this entry is a directory.
CurrListEntryFileTypeSpecifies 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 .
CurrListEntryGroupExecuteControls file execution permission for the group users.
CurrListEntryGroupReadControls file read permission for the group users.
CurrListEntryGroupWriteControls file write permission for the group users.
CurrListEntryHandleAllows to get or set a 'handle', a unique identifier of the underlying property object.
CurrListEntryLongNameContains the long name of the file (human-readable, ftp-like).
CurrListEntryMTimeSpecifies the last modification time, in UTC.
CurrListEntryNameSpecifies the file name.
CurrListEntryOtherExecuteControls file execution permission for other users (users that are neither owners, nor belong to the same group).
CurrListEntryOtherReadControls file read permission for other users (users that are neither owners, nor belong to the same group).
CurrListEntryOtherWriteControls file write permission for other users (users that are neither owners, nor belong to the same group).
CurrListEntryOwnerSpecifies the owner of the file/directory.
CurrListEntryPathContains the full path to the file.
CurrListEntrySizeThe size of the file in bytes.
CurrListEntryUserExecuteControls file execution permission for the file owner.
CurrListEntryUserReadControls file read permission for the file owner.
CurrListEntryUserWriteControls file write permission for the file owner.
DownloadBlockSizeThe download block size in bytes.
ExternalCryptoCustomParamsCustom parameters to be passed to the signing service (uninterpreted).
ExternalCryptoDataAdditional data to be included in the async state and mirrored back by the requestor.
ExternalCryptoExternalHashCalculationSpecifies whether the message hash is to be calculated at the external endpoint.
ExternalCryptoHashAlgorithmSpecifies the request's signature hash algorithm.
ExternalCryptoKeyIDThe ID of the pre-shared key used for DC request authentication.
ExternalCryptoKeySecretThe pre-shared key used for DC request authentication.
ExternalCryptoMethodSpecifies the asynchronous signing method.
ExternalCryptoModeSpecifies the external cryptography mode.
ExternalCryptoPublicKeyAlgorithmProvide public key algorithm here if the certificate is not available on the pre-signing stage.
ForceCompressionEnforces compression for the SSH layer.
KeyFingerprintSHA1Contains the SHA-1 fingerprint (hash) of the key.
KeyFingerprintSHA256Contains the SHA-256 fingerprint (hash) of the key.
KeyHandleAllows to get or set a 'handle', a unique identifier of the underlying property object.
MaxSFTPVersionHigher SFTP version to support.
MinSFTPVersionLower SFTP version to support.
PasswordSpecifies user's authentication password.
PipelineLengthThe number of parallelized transfer requests.
ProxyAddressThe IP address of the proxy server.
ProxyAuthenticationThe authentication type used by the proxy server.
ProxyPasswordThe password to authenticate to the proxy server.
ProxyPortThe port on the proxy server to connect to.
ProxyProxyTypeThe type of the proxy server.
ProxyRequestHeadersContains HTTP request headers for WebTunnel and HTTP proxy.
ProxyResponseBodyContains the HTTP or HTTPS (WebTunnel) proxy response body.
ProxyResponseHeadersContains response headers received from an HTTP or HTTPS (WebTunnel) proxy server.
ProxyUseIPv6Specifies whether IPv6 should be used when connecting through the proxy.
ProxyUseProxyEnables or disables proxy-driven connection.
ProxyUsernameSpecifies the username credential for proxy authentication.
ServerKeyAlgorithmSpecifies the key algorithm.
ServerKeyBitsThe number of bits in the key: the more the better, 2048 or 4096 are typical values.
ServerKeyCommentThe comment for the public key.
ServerKeyCurveSpecifies the elliptical curve when EC cryptography is used.
ServerKeyDSSGThe G (Generator) parameter of the DSS signature key.
ServerKeyDSSPThe P (Prime) parameter of the DSS signature key.
ServerKeyDSSQThe Q (Prime Factor) parameter of the DSS signature key.
ServerKeyDSSXThe X (Private key) parameter of the DSS signature key.
ServerKeyDSSYThe Y (Public key) parameter of the DSS signature key.
ServerKeyECCDThe value of the secret key (the order of the public key, D) if elliptic curve (EC) cryptography is used.
ServerKeyECCQXThe value of the X coordinate of the public key if elliptic curve (EC) cryptography is used.
ServerKeyECCQYThe value of the Y coordinate of the public key if elliptic curve (EC) cryptography is used.
ServerKeyEdPrivateThe value of the private key if EdDSA (Edwards-curve Digital Signature Algorithm) algorithm is used.
ServerKeyEdPublicThe value of the public key if EdDSA (Edwards-curve Digital Signature Algorithm) algorithm is used.
ServerKeyFingerprintMD5Contains the MD5 fingerprint (hash) of the key.
ServerKeyFingerprintSHA1Contains the SHA-1 fingerprint (hash) of the key.
ServerKeyFingerprintSHA256Contains the SHA-256 fingerprint (hash) of the key.
ServerKeyHandleAllows to get or set a 'handle', a unique identifier of the underlying property object.
ServerKeyIsExtractableWhether the key is extractable (e.
ServerKeyIsPrivateWhether this key is a private key or not.
ServerKeyIsPublicWhether this key is a public key or not.
ServerKeyKDFRoundsReturns the number of iterations of the Key Derivation Function (KDF) used to generate this key.
ServerKeyKDFSaltThe salt value used by the Key Derivation Function (KDF) to generate this key.
ServerKeyKeyFormatSpecifies the format in which the key is stored.
ServerKeyKeyProtectionAlgorithmSpecifies the key protection algorithm.
ServerKeyRSAExponentReturns the e parameter (public exponent) of the RSA key.
ServerKeyRSAIQMPReturns the iqmp parameter of the RSA key.
ServerKeyRSAModulusReturns the m parameter (public modulus) of the RSA key.
ServerKeyRSAPReturns the p parameter (first factor of the common modulus n) of the RSA key.
ServerKeyRSAPrivateExponentReturns the d parameter (private exponent) of the RSA key.
ServerKeyRSAQReturns the q parameter (second factor of the common modulus n) of the RSA key.
ServerKeySubjectSpecifies the public key owner (subject).
SocketDNSModeSelects the DNS resolver to use: the class's (secure) built-in one, or the one provided by the system.
SocketDNSPortSpecifies the port number to be used for sending queries to the DNS server.
SocketDNSQueryTimeoutThe timeout (in milliseconds) for each DNS query.
SocketDNSServersThe addresses of DNS servers to use for address resolution, separated by commas or semicolons.
SocketDNSTotalTimeoutThe timeout (in milliseconds) for the whole resolution process.
SocketIncomingSpeedLimitThe maximum number of bytes to read from the socket, per second.
SocketLocalAddressThe local network interface to bind the socket to.
SocketLocalPortThe local port number to bind the socket to.
SocketOutgoingSpeedLimitThe maximum number of bytes to write to the socket, per second.
SocketTimeoutThe maximum period of waiting, in milliseconds, after which the socket operation is considered unsuccessful.
SocketUseIPv6Enables or disables IP protocol version 6.
SSHSettingsAutoAdjustCiphersWhether the SSH client should adjust its list of supported ciphers 'on-the-fly' for greater compatibility with the server it is connecting to.
SSHSettingsBaseConfigurationAllows to choose base configuration of SSH settings, tuned up for different purposes such as high security or higher compatibility.
SSHSettingsCompressionAlgorithmsA list of session compression algorithms separated with commas or semicolons.
SSHSettingsCompressionLevelPossible values for the Compression Level range from 0 (minimum compression) to 9 (maximum compression).
SSHSettingsDefaultWindowSizeThe 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.
SSHSettingsEncryptionAlgorithmsA list of session encryption algorithms separated with commas or semicolons.
SSHSettingsForceCompressionWhether the SSH client should explicitly request compression.
SSHSettingsGSSAuthTypesA comma-separated list of authentication types.
SSHSettingsGSSDelegateCredsSwitches credential delegation on or off.
SSHSettingsGSSHostnameThe GSS host name, in form of a FQDN (e.
SSHSettingsGSSLibA path to the GSS-API library (DLL or SO).
SSHSettingsGSSMechanismsA comma-separated list of GSS mechanisms to use.
SSHSettingsGSSProtocolsA comma-separated list of SSPI protocols.
SSHSettingsHandshakeTimeoutSpecifies the maximal time for the SSH handshake to proceed, in seconds.
SSHSettingsKexAlgorithmsA list of key exchange algorithms separated with commas or semicolons.
SSHSettingsMacAlgorithmsA list of MAC (for message authentication code ) algorithms separated with commas or semicolons.
SSHSettingsMaxSSHPacketSizeSpecifies the maximum length of one SSH packet in bytes.
SSHSettingsMinWindowSizeSpecifies the minimal internal window size.
SSHSettingsObfuscateHandshakeEnables or disables handshake obfuscation.
SSHSettingsObfuscationPasswordSpecifies the password used to encrypt the handshake when ObfuscateHandshake is set.
SSHSettingsPublicKeyAlgorithmsA list of public key algorithms separated with commas or semicolons.
SSHSettingsRequestPasswordChangeWhether to request a password change when connecting.
SSHSettingsSoftwareNameThe name to be used by the class to identify itself.
SSHSettingsTrustAllKeysEnables or disables explicit trust to all server keys.
SSHSettingsUseAuthAgentEnables or disables the use of external key agent, such as Putty key agent.
SSHSettingsVersionsSpecifies enabled SSH protocol versions (1 or 2).
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 C++ Edition - Version 20.0 [Build 8165]