SFTPClient Component
Properties Methods Events Configuration Settings Errors
The SFTPClient component provides client-side functionality for SFTP (Secure File Transfer Protocol).
Syntax
TsbxSFTPClient
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:
- AutoAdjustTransferBlock to false,
- PipelineLength to 1,
- UploadBlockSize to 16384,
- DownloadBlockSize to 16384.
Property List
The following is the full list of the properties of the component with short descriptions. Click on the links for further details.
AuthAttempts | Specifies the number of SSH authentication attempts. |
AutoAdjustTransferBlock | Specifies whether to adjust the send and receive buffer sizes automatically. |
Connected | Indicates if the client is connected to the SFTP server. |
ConnInfoClientKeyAlgorithm | Specifies the client's key algorithm. |
ConnInfoClientKeyBits | Specifies the length of the client's key. |
ConnInfoClientKeyFingerprint | The fingerprint (hash value) of the client's public key. |
ConnInfoCloseReason | Contains the line sent by the server just before closing the connection. |
ConnInfoCompressionAlgorithmInbound | Compression algorithm for the incoming traffic. |
ConnInfoCompressionAlgorithmOutbound | Compression algorithm for the outgoing traffic. |
ConnInfoEncryptionAlgorithmInbound | Encryption algorithm for the incoming traffic. |
ConnInfoEncryptionAlgorithmOutbound | Encryption algorithm for the outgoing traffic. |
ConnInfoInboundEncryptionKeyBits | Specifies the length of the key used to encrypt the incoming traffic. |
ConnInfoKexAlgorithm | The key exchange algorithm used during the SSH handshake. |
ConnInfoKexBits | The number of bits used by the key exchange algorithm. |
ConnInfoKexLines | The contents of the received KexInit packet. |
ConnInfoMacAlgorithmInbound | MAC algorithm used for the incoming connection. |
ConnInfoMacAlgorithmOutbound | MAC algorithm used for outbound connection. |
ConnInfoOutboundEncryptionKeyBits | Specifies the length of the key used to encrypt the outgoing traffic. |
ConnInfoPublicKeyAlgorithm | Specifies the public key algorithm which was used during the SSH handshake. |
ConnInfoServerKeyBits | Specifies the number of bits in the server's key. |
ConnInfoServerKeyFingerprint | The fingerprint (hash value) of the server's public key. |
ConnInfoServerSoftwareName | Returns the name of the SSH software running on the server side. |
ConnInfoTotalBytesReceived | Returns the total number of bytes received over this connection. |
ConnInfoTotalBytesSent | Returns the total number of bytes sent over this connection. |
ConnInfoVersion | Specifies SSH protocol version. |
CurrListEntryATime | Contains the last access time for this file, in UTC. |
CurrListEntryCTime | Contains this file's creation time, in UTC. |
CurrListEntryDirectory | Specifies whether this entry is a directory. |
CurrListEntryFileType | Specifies 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 . |
CurrListEntryGroupExecute | Controls file execution permission for the group users. |
CurrListEntryGroupRead | Controls file read permission for the group users. |
CurrListEntryGroupWrite | Controls file write permission for the group users. |
CurrListEntryHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
CurrListEntryLongName | Contains the long name of the file (human-readable, ftp-like). |
CurrListEntryMTime | Specifies the last modification time, in UTC. |
CurrListEntryName | Specifies the file name. |
CurrListEntryOtherExecute | Controls file execution permission for other users (users that are neither owners, nor belong to the same group). |
CurrListEntryOtherRead | Controls file read permission for other users (users that are neither owners, nor belong to the same group). |
CurrListEntryOtherWrite | Controls file write permission for other users (users that are neither owners, nor belong to the same group). |
CurrListEntryOwner | Specifies the owner of the file/directory. |
CurrListEntryPath | Contains the full path to the file. |
CurrListEntrySize | The size of the file in bytes. |
CurrListEntryUserExecute | Controls file execution permission for the file owner. |
CurrListEntryUserRead | Controls file read permission for the file owner. |
CurrListEntryUserWrite | Controls file write permission for the file owner. |
DownloadBlockSize | The download block size in bytes. |
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. |
ForceCompression | Enforces compression for the SSH layer. |
KeyFingerprintSHA1 | Contains the SHA-1 fingerprint (hash) of the key. |
KeyFingerprintSHA256 | Contains the SHA-256 fingerprint (hash) of the key. |
KeyHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
MaxSFTPVersion | Higher SFTP version to support. |
MinSFTPVersion | Lower SFTP version to support. |
Password | Specifies user's authentication password. |
PipelineLength | The number of parallelized transfer requests. |
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. |
ServerKeyAlgorithm | Specifies the key algorithm. |
ServerKeyBits | The number of bits in the key: the more the better, 2048 or 4096 are typical values. |
ServerKeyComment | The comment for the public key. |
ServerKeyCurve | Specifies the elliptical curve when EC cryptography is used. |
ServerKeyDSSG | The G (Generator) parameter of the DSS signature key. |
ServerKeyDSSP | The P (Prime) parameter of the DSS signature key. |
ServerKeyDSSQ | The Q (Prime Factor) parameter of the DSS signature key. |
ServerKeyDSSX | The X (Private key) parameter of the DSS signature key. |
ServerKeyDSSY | The Y (Public key) parameter of the DSS signature key. |
ServerKeyECCD | The value of the secret key (the order of the public key, D) if elliptic curve (EC) cryptography is used. |
ServerKeyECCQX | The value of the X coordinate of the public key if elliptic curve (EC) cryptography is used. |
ServerKeyECCQY | The value of the Y coordinate of the public key if elliptic curve (EC) cryptography is used. |
ServerKeyEdPrivate | The value of the private key if EdDSA (Edwards-curve Digital Signature Algorithm) algorithm is used. |
ServerKeyEdPublic | The value of the public key if EdDSA (Edwards-curve Digital Signature Algorithm) algorithm is used. |
ServerKeyFingerprintMD5 | Contains the MD5 fingerprint (hash) of the key. |
ServerKeyFingerprintSHA1 | Contains the SHA-1 fingerprint (hash) of the key. |
ServerKeyFingerprintSHA256 | Contains the SHA-256 fingerprint (hash) of the key. |
ServerKeyHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
ServerKeyIsExtractable | Whether the key is extractable (e. |
ServerKeyIsPrivate | Whether this key is a private key or not. |
ServerKeyIsPublic | Whether this key is a public key or not. |
ServerKeyKDFRounds | Returns the number of iterations of the Key Derivation Function (KDF) used to generate this key. |
ServerKeyKDFSalt | The salt value used by the Key Derivation Function (KDF) to generate this key. |
ServerKeyKeyFormat | Specifies the format in which the key is stored. |
ServerKeyKeyProtectionAlgorithm | Specifies the key protection algorithm. |
ServerKeyRSAExponent | Returns the e parameter (public exponent) of the RSA key. |
ServerKeyRSAIQMP | Returns the iqmp parameter of the RSA key. |
ServerKeyRSAModulus | Returns the m parameter (public modulus) of the RSA key. |
ServerKeyRSAP | Returns the p parameter (first factor of the common modulus n) of the RSA key. |
ServerKeyRSAPrivateExponent | Returns the d parameter (private exponent) of the RSA key. |
ServerKeyRSAQ | Returns the q parameter (second factor of the common modulus n) of the RSA key. |
ServerKeySubject | Specifies the public key owner (subject). |
SocketDNSMode | Selects the DNS resolver to use: the component'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. |
SSHSettingsAutoAdjustCiphers | Whether the SSH client should adjust its list of supported ciphers 'on-the-fly' for greater compatibility with the server it is connecting to. |
SSHSettingsBaseConfiguration | Allows to choose base configuration of SSH settings, tuned up for different purposes such as high security or higher compatibility. |
SSHSettingsCompressionAlgorithms | A list of session compression algorithms separated with commas or semicolons. |
SSHSettingsCompressionLevel | Possible values for the Compression Level range from 0 (minimum compression) to 9 (maximum compression). |
SSHSettingsDefaultWindowSize | The 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. |
SSHSettingsEncryptionAlgorithms | A list of session encryption algorithms separated with commas or semicolons. |
SSHSettingsForceCompression | Whether the SSH client should explicitly request compression. |
SSHSettingsGSSAuthTypes | A comma-separated list of authentication types. |
SSHSettingsGSSDelegateCreds | Switches credential delegation on or off. |
SSHSettingsGSSHostname | The GSS host name, in form of a FQDN (e. |
SSHSettingsGSSLib | A path to the GSS-API library (DLL or SO). |
SSHSettingsGSSMechanisms | A comma-separated list of GSS mechanisms to use. |
SSHSettingsGSSProtocols | A comma-separated list of SSPI protocols. |
SSHSettingsHandshakeTimeout | Specifies the maximal time for the SSH handshake to proceed, in seconds. |
SSHSettingsKexAlgorithms | A list of key exchange algorithms separated with commas or semicolons. |
SSHSettingsMacAlgorithms | A list of MAC (for message authentication code ) algorithms separated with commas or semicolons. |
SSHSettingsMaxSSHPacketSize | Specifies the maximum length of one SSH packet in bytes. |
SSHSettingsMinWindowSize | Specifies the minimal internal window size. |
SSHSettingsObfuscateHandshake | Enables or disables handshake obfuscation. |
SSHSettingsObfuscationPassword | Specifies the password used to encrypt the handshake when ObfuscateHandshake is set. |
SSHSettingsPublicKeyAlgorithms | A list of public key algorithms separated with commas or semicolons. |
SSHSettingsRequestPasswordChange | Whether to request a password change when connecting. |
SSHSettingsSoftwareName | The name to be used by the component to identify itself. |
SSHSettingsTrustAllKeys | Enables or disables explicit trust to all server keys. |
SSHSettingsUseAuthAgent | Enables or disables the use of external key agent, such as Putty key agent. |
SSHSettingsVersions | Specifies enabled SSH protocol versions (1 or 2). |
TrustedKeysFile | A file containing the keys of authorized servers. |
UploadBlockSize | The upload block size in bytes. |
Username | The client's username to authenticate to the server. |
UseUTF8 | Enables UTF8 for all string content. |
Version | The SFTP version negotiated. |
Method List
The following is the full list of the methods of the component with short descriptions. Click on the links for further details.
AbsolutePath | Requests the absolute path for a relative path. |
ChangeDir | Changes current working directory on the server. |
Config | Sets or retrieves a configuration setting. |
Connect | Connects to an SFTP server. |
CreateLink | Creates a symbolic or hard link to a remote file. |
DeleteDir | Removes directory from the SFTP server. |
DelFile | Deletes a file from the SFTP server. |
DeleteFiles | Deletes a group of files from the SFTP server. |
DirExists | Checks if a directory exists on the SFTP server. |
Disconnect | Disconnects from the SFTP server. |
DownloadBytes | Downloads a file from the server into an array of bytes. |
DownloadFile | Downloads a file from the SFTP server. |
DownloadFiles | Downloads multiple files from the SFTP server. |
ExecuteSSHCommand | Sends an SSH command to the server in the middle of SFTP session. |
ExtensionCmd | Sends an extension command to the server. |
FileExists | Checks whether a file exists on the server. |
GetCurrentDir | Returns the current directory on the SFTP server. |
GetFileSize | Checks the size of a remote file. |
ListDir | Lists the content of the current remote directory. |
MakeDir | Creates a new directory on the server. |
RenameFile | Renames a file. |
RequestAttributes | Requests attributes of the remote file. |
SetAttributes | Sets the attributes upon a remote file. |
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 component with short descriptions. Click on the links for further details.
AuthAttempt | Fires when an authentication attempt is performed. |
AuthFailed | Fires if an authentication attempt fails. |
AuthSucceeded | Reports a successful authentication. |
Banner | Reports the receipt of the Welcome message from the server. |
Disconnect | Reports SFTP connection closure. |
Error | Information about errors during SFTP connection. |
ExternalSign | Handles remote or external signing initiated by the SignExternal method or other source. |
FileOperation | Signifies the start of a file transfer operation. |
FileOperationResult | Signifies the completion of a file transfer operation. |
KnownKeyReceived | Signals that the server has introduced itself with a known key. |
ListEntry | Reports a directory listing entry to the application. |
Notification | This event notifies the application about an underlying control flow event. |
PasswordChangeRequest | Signals that the server requests a password change. |
PrivateKeyNeeded | Asks the application for the client's private key. |
Progress | Fires periodically during the data transfer. |
UnknownKeyReceived | Signals that the server has introduced itself with an unknown key. |
Configuration Settings
The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.
AdjustFileTimes | Whether file times should be adjusted after upload/download. |
ASCIIMode | Whether ASCII transfer mode is used. |
AvailableSpace | Returns details of server disk space availability. This protocol extension must be supported by the server for this request to work. |
CaseConversion | Whether case conversion must be applied to file names as they are downloaded. |
CaseSensitive | Specifies if file paths are case-sensitive. |
CopyMode | Defines what to do with each successfully copied file. |
DefOutboundBlockSize | The default outbound block size. |
DisablePacketFragmentation | Enables or disables SSH packet fragmentation. |
ErrorOrigin | Specifies whether the error is local or remote. |
ErrorSeverity | Specifies whether the error is fatal. |
FileHash | Returns the hash of the specified file. This protocol extension must be supported by the server for this request to work. |
HashAlgorithm | The hash algorithm to use for the protocol operations. |
HomeDir | Returns a user's home directory. This protocol extension must be supported by the server for this request to work. |
IncomingSpeedLimit | Specifies incoming speed limit. |
KeepAlivePeriod | The inactivity period after which a keep-alive signal will be sent. |
LocalCharset | Charset used on the client machine. |
LocalNewLineConvention | A character string for the end of line (EOL) indication on the local machine. |
Mode | The file open mode to use. |
NewLineConvention | A character string for the end of line (EOL) indication on the server. |
OutgoingSpeedLimit | Specifies incoming speed limit. |
PreserveExistingFileTimes | Whether original file times should be restored upon transfer. |
Recursive | Whether subdirectories should also be scanned for matching files. |
RedirectStdErr | Whether to redirect output to StdErr. |
RemoteCharset | Charset used on the server. |
SFTPBufferSize | The size of internal buffer used for data transfer. |
SFTPServerExecutableLocations | Location of the SFTP server executable. |
StatVFS | Returns VFS details. This protocol extension must be supported by the server for this request to work. |
StdErrData | The buffer for writing StdErr data. |
TempFolder | Returns the temporary directory offered by the server. This protocol extension must be supported by the server for this request to work. |
TempPath | Location where the temporary files are stored. |
TreatZeroSizeAsUndefined | Whether zero size returned by STAT should be considered as undefined. |
UseTruncateFlagOnUpload | whether to use the 'truncate' flag on file upload. |
UseUTF8OnV3 | Whether to apply UTF-8 conversion for SFTP protocol versions 3 and lower. |
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 component (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 components 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. |