FileTransfer transfers files to and from a remote server. Plain FTP, FTP over TLS (FTPS, see setSecure), and SFTP -- file transfer carried over SSH -- are all supported; the protocol is chosen by the url scheme (|ftp://|, |ftps://|, |sftp://|).
SFTP identifies the server by its SSH host key rather than by a certificate chain, so there is no system trust store to fall back on. An |sftp://| transfer therefore requires the expected host key to be supplied first, with either setHostKeySha256 or setKnownHosts; without one of them the transfer fails immediately rather than connecting to an unverified server.
// a small wrapper around FileTransfer that fills in the sftp url, the
// credentials and the directories, so a caller only has to name the file
// it wants moved. The server is Wing FTP Server's public demo, which
// serves files out of /download and accepts uploads into /upload.
class BasicSftpRequest {
server = "demo.wftpserver.com:2222";
username = "demo";
password = "demo";
download_dir = "/download/";
upload_dir = "/upload/";
local_dir = ""; // set in the constructor
file = ""; // file to download/upload; set later
transfer = null;
// SFTP runs over SSH, so the server is verified by host key rather than
// by a certificate. This is the base64 SHA-256 fingerprint OpenSSH
// prints after "SHA256:"; reread it with "ssh-keygen -lf" if it changes.
host_key = "8fo3mJ9x2Cn+jXjcceuFDDcZXiS4LymvfnFrnDHw7fk";
constructor() {
this.local_dir = `${Environment.getTempPath()}/`;
this.transfer = new FileTransfer();
this.transfer.setAsync(true);
this.transfer.finished.connect(this, this.onFinished);
// without this -- or setKnownHosts() -- an sftp:// transfer is
// refused before it connects
this.transfer.setHostKeySha256(this.host_key);
}
// e.g. "sftp://demo:demo@demo.wftpserver.com:2222/download/version.txt"
remotePath(server_dir) {
const credentials = `${this.username}:${this.password}`;
return `sftp://${credentials}@${this.server}${server_dir}${this.file}`;
}
localPath() {
return `${this.local_dir}${this.file}`;
}
onFinished() {
alert(`Finished transferring ${this.file} to ${this.localPath()}`);
Application.exit();
}
download(file) {
this.file = file;
return this.transfer.download(this.remotePath(this.download_dir),
this.localPath());
}
upload(file) {
this.file = file;
return this.transfer.upload(this.localPath(),
this.remotePath(this.upload_dir));
}
}
// the class has to be declared before it is used
const sftp = new BasicSftpRequest();
sftp.download("version.txt");
// run the app -- necessary for processing events
Application.run();Calling this method causes an asynchronous transfer to abort.
Returns true upon successful completion, otherwise false if an error occurred.
Calling this method downloads a file from an FTP or an SFTP server onto the local computer. The url specified in the url parameter takes the following format: sftp://username:password@servername.domain.com/path/to/filename.ext -- If you wish to use the ftp protocol, change the protocol identifier before the first colon in the url string.
An |sftp://| url requires the server's host key to have been supplied first, with setHostKeySha256 or setKnownHosts; with neither, this method fails without connecting.
Total number of transferred bytes
A call to this method returns the total number of bytes received or sent. This function may also be called during asynchronous transfers.
A description of the last failure, or an empty string
Calling this method returns a short description of why the most recently completed transfer or rename failed, for example "SSL connect error" or "Access denied to remote resource". If the last operation succeeded, or no operation has run yet, an empty string is returned. In asynchronous mode the result is meaningful once isDone() returns true; a natural place to call it is a finished event handler that found isSuccess() false.
True if the file transfer is finished, false if it is still running
Returns a boolean value indicating whether the most recent file transfer operation is finished.
True if the last completed transfer succeeded, false otherwise
Returns true if the most recently completed transfer succeeded, false otherwise. In asynchronous mode download() and upload() return as soon as the request is started, so their return value only reports that; call this from the finished event handler (or after isDone() turns true) to find out whether the transfer actually worked.
Returns true upon successful completion, otherwise false if an error occurred.
Calling this method renames a file on a remote FTP or SFTP server The source url specified in source_url parameter takes the following format: sftp://username:password@servername.domain.com/path/to/filename.ext -- If you wish to use the ftp protocol, change the protocol identifier before the first colon in the url string. The filename specified in the new_name parameter indicates the new name that the file will take. It should be specified as a simple filename, without a qualifying path name.
The server is the one from the most recent download or upload on this object, and for |sftp://| it is verified the same way -- with the host key supplied through setHostKeySha256 or setKnownHosts.
Turns asynchronous mode on or off. If asynchronous mode is on, requests will return immediately and the processing will be done in the background. Upon completion of the request, the finished event is fired.
Points the TLS layer at a PEM file holding the certificate authority (or self-signed server certificate) that the server's certificate should be verified against, for servers whose certificate is not issued by an authority in the system trust store. Passing an empty string restores the default, which is the system store.
This ADDS a trust anchor; it does not turn verification off. A server presenting a certificate that does not chain to the supplied bundle is still rejected.
Pins the SSH host key for |sftp://| transfers. The fingerprint is the base64-encoded SHA-256 digest of the server's public host key -- the same string OpenSSH prints after the |SHA256:| prefix, and the one an administrator can read off the server with |ssh-keygen -lf| on its public host key file. Supply it with or without that prefix. A server presenting any other key is rejected and the transfer fails.
This is the simplest way to verify an SFTP server: it is one string, it needs no file on disk, and it can be read off the server once and stored with the script. setKnownHosts is the alternative for callers who already keep an OpenSSH known_hosts file. Passing an empty string clears the pin.
SFTP transfers require one of the two: with neither set, download, upload and rename fail without connecting, rather than trusting whatever key the server offers. The single exception is |setVerifyServer(false)|, which waives the requirement and makes this setting a no-op.
Points the SSH layer at an OpenSSH-format known_hosts file holding the public host keys of the servers this object is allowed to talk to, for |sftp://| transfers. Only an exact match is accepted: a server whose key is absent from the file, or present under a different value, is rejected and the transfer fails.
Use this when the caller already maintains a known_hosts file; setHostKeySha256 pins a single server without one. Passing an empty string clears the setting.
SFTP transfers require one of the two: with neither set, download, upload and rename fail without connecting, rather than trusting whatever key the server offers. The single exception is |setVerifyServer(false)|, which waives the requirement and makes this setting a no-op.
Turns FTPS on or off. When on, the connection is upgraded to TLS with the AUTH command before any credentials are sent, and both the control and data channels are encrypted; the transfer fails rather than continuing in the clear if the server does not support TLS. This is "explicit" FTPS and uses ordinary ftp:// urls on the usual port. For "implicit" FTPS, use an ftps:// url instead, which does not require this setting.
Note that FTPS is not SFTP: SFTP is a different protocol, carried over SSH. This setting has no effect on |sftp://| urls, which are encrypted by SSH itself -- see setHostKeySha256 and setKnownHosts for how an SFTP server is verified.
Verification is ON by default and should stay on. Turning it off disables EVERY check that the server is who it claims to be: for |ftps://| and FTPS the TLS certificate chain and host name are no longer checked, and for |sftp://| the SSH host key is accepted whatever it is, so setHostKeySha256 and setKnownHosts stop having any effect. The connection is still encrypted, but an attacker who can redirect it can present their own certificate or host key, read everything sent -- including the password -- and pass the traffic through unchanged.
This exists for talking to a server whose credentials cannot be verified at all, typically a test box with a self-signed certificate or a freshly imaged host. Prefer setCaInfo for a private certificate authority and setHostKeySha256 for an SSH host key: both let a specific server be trusted while everything else is still rejected. Turn this off only for a host you would be willing to hand the password to over an unauthenticated link.
Returns true upon successful completion, otherwise false if an error occurred.
Calling this method uploads a file from the local computer to an FTP or an SFTP server. The destination url specified in the destination_url parameter takes the following format: sftp://username:password@servername.domain.com/path/to/filename.ext -- If you wish to use the ftp protocol, change the protocol identifier before the first colon in the url string.
An |sftp://| url requires the server's host key to have been supplied first, with setHostKeySha256 or setKnownHosts; with neither, this method fails without connecting.