cfftp: Opening and closing secure FTP server connections

Description

To establish a connection with a secure FTP server, use the open action with a connection attribute, specify that secure = "yes", and specify the key, passphrase, and fingerprint as appropriate.

<cfftp  
    action = "open|close" 
    connection = "name" 
    fingerprint = "ssh-dss.ssh-rsa" 
    key = "private key" 
    passive = "yes|no"> 
    passphrase = "passphrase" 
    password = "password" 
    port = "port" 
    proxyServer = "proxy server" 
    retryCount = "number" 
    secure = "yes|no" 
    server = "server" 
    stopOnError = "yes|no" 
    timeout = "time-out in seconds" 
    username = "name">
Note: You can specify this tag’s attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag’s attribute names as structure keys.

See also

cfhttp, cfldap, cfmail, cfpop

Attributes

Attribute

Req/Opt

Default

Description

action

Required

FTP operation to perform.

  • open: creates an FTP connection.

  • close: terminates an FTP connection.

connection

Optional, but always used with open or close

Name of the FTP connection. If you specify the username, password, and server attributes, and if no connection exists for them, ColdFusion creates one. Calls to cfftp with the same connection name reuse the connection.

fingerprint

Optional. Used only when server, username, and password are supplied

Fingerprint of the host key in the form ssh-dss.ssh-rsa, which is a 16-byte unique identifier for the server attribute that you specify, The fingerprint consists of eight pairs of hexadecimal values in the form hh:hh:hh:hh::hh:hh:hh:hh. ColdFusion checks the fingerprint of the remote server only if the fingerprint value is specified.

key

Required if action="open" (When secure="yes", either password or key is required.)

Public-key–based authentication. Refers to the absolute path to the private key of the user. Possession of a private key provides authentication by sending a signature created with a private key. The server must ensure that the key is a valid authentication for the user and that the signature is valid. Both must be valid to accept the authentication.

passive

Optional

no

Valid only if secure="no".

  • yes: enables passive mode.

  • no

passphrase

Optional. Used when key is specified

Because private keys are stored in an encrypted form on the client host, the user must supply a passphrase to enable generating the signature.

password

Required if action="open" (When secure="yes", either password or key is required.)

Password to log in the user.

port

Optional

21

Remote port to which to connect.

proxyServer

Optional

String. Name of proxy server (or servers) to use, if proxy access is specified.

retryCount

Optional

1

Number of retries until failure is reported.

secure

Optional

no

  • yes: enables secure FTP

  • no

server

Required if

action="open"

FTP server to which to connect; for example, ftp.myserver.com.

stopOnError

Optional

no

  • yes: halts processing, displays an appropriate error.

  • no: if secure="yes", populates the following variables:

  • If ColdFusion fails to connect to the secure FTP server, it halts processing and displays the appropriate error message

  • cfftp.succeeded: yes or no

  • cfftp.errorCode: error number

  • cfftp.errorText: message text

  • For all file operations, returns the following error codes:

SSH-CONNECT 25

SSH_MSG_USERAUTH_FAILURE 51

SSH_MSG_USERAUTH_SUCCESS 52

SSH_MSG_REQUEST_SUCCESS 81

SSH_MSG_REQUEST_FAILURE 82

For conditional operations, use cfftp.errorCode. Do not use cfftp.errorText for this purpose.

timeout

Optional

30

Value in seconds for the time-out of all operations, including individual data request operations.

username

Required if action="open"

User name to pass in the FTP operation.

Usage

The cfftp tag lets you open a connection to a Secure Shell (SSH) server by using either symmetric or asymmetric encryption. To use symmetric encryption, you specify secure="yes", the user name, password, connection, and fingerprint. To use asymmetric encryption, first generate private-public key pairs for each user authorized to have access to the server. Each authorized user’s public key is stored on the server; each user’s private key is encrypted and stored on that user’s computer. To open a connection to the SSH server, you specify secure="yes", the user name, the password, or the private key and the passphrase that the server uses to decrypt the private key, connection, and fingerprint. After you open the connection to the SSH server, you can use that connection for any action supported by the cfftp tag.

To keep a connection open throughout a session or longer, put the connection name in the Session or Application scope; for example, specify connection="Session.FTPConnection". However, if you do this, specify the full variable name in all FTP operations, and use the close action when you are finished. Keeping a connection open prevents others from using the FTP server; so close a connection as soon as possible. If you do not assign the connection name to Session or Application variable, the connection remains open for the current page only, and you do not have to close it manually.

Changes to a cached connection, such as changing retryCount or timeout values, might require reestablishing the connection.

Example

<!--- This example uses symmetric encryption. ---> 
 
<!--- Open the secure connection. ---> 
<cfftp action = "open" 
    username = "myusername" 
    connection = "My_query" 
    password = "mypassword" 
    fingerprint = "12:34:56:78:AB:CD:EF:FE:DC:BA:87:65:43:21" 
    server = "ftp.tucows.com" 
    secure = "yes"> 
<p>Did it succeed? <cfoutput>#cfftp.succeeded#</cfoutput> 
<cfdump var ="#My_query# label="connection"> 
 
<!--- Transfer files to the remote server. ---> 
<cfset absolutePathToLocalFile="C:\one\two\myfile.htm"> 
    <cfif FileExists(absolutePathToLocalFile)> 
        <cfftp action = "putFile" 
            connection="My_query" 
            localFile="#variables.absolutePathToLocalFile#" 
            remoteFile="/home/myname/sftptest/myfile.htm"> 
    <cfelse> 
        <!--- Put error handling code here. ---> 
    </cfif> 
<p>Did it succeed? <cfoutput>#cfftp.succeeded#</cfoutput> 
 
<!--- Close the connection. ---> 
<cfftp action="close" connection="My_query">

Example

<!--- This example uses asymmetric encryption. ---> 
 
<!--- Open the secure connection. ---> 
<cfftp action = "open" 
    username = "myusername" 
    connection = "My_query" 
    key="C:\mykeys\myprivatekey" 
    passphrase = "zHx628Fg" 
    fingerprint = "12:34:56:78:AB:CD:EF:FE:DC:BA:87:65:43:21" 
    server = "ftp.tucows.com" 
    secure = "yes"> 
<p>Did it succeed? <cfoutput>#cfftp.succeeded#</cfoutput> 
<cfdump var ="#My_query# label="connection"> 
 
<!--- List files on the remote server. ---> 
<cftry> 
    <!--- List the files in a directory. ---> 
        <cfftp action = "listDir" 
            connection="My_query" 
            stopOnError="yes" 
            name="ListFiles" 
            directory="/"> 
    <cfcatch> 
        <!--- Close the connection. ---> 
        <cfftp action="close" connection="My_query" stopOnError="no"> 
    </cfcatch> 
</cftry>