SFTPClient Component
Properties Methods Events Configuration Settings Errors
The SFTPClient component provides client-side functionality for SFTP (Secure File Transfer Protocol).
Syntax
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 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. |
ConnectionInfo | Contains the secure connection info. |
CurrentListEntry | Contains the current entry returned by ListDir . |
DownloadBlockSize | The download block size in bytes. |
ExternalCrypto | Provides access to external signing and DC parameters. |
ForceCompression | Enforces compression for the SSH layer. |
Key | Contains the client's SSH key. |
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. |
Proxy | The proxy server settings. |
ServerKey | Returns the server's public key. |
SocketSettings | Manages network connection settings. |
SSHSettings | The SSH connection settings. |
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. |
DeleteFile | 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. |
DownloadStream | Downloads a file 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. |
UploadStream | Uploads a file 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. |