SFTP (SSH) Keys

SFTP supports authentication using cryptographic keys, as opposed to a username and password. SFTP keys, when added in Files.com, provide access via SFTP only, and do not confer any access via APIs, SDKs, or the web.

The use of an SSH Key to authenticate is not mandatory. SSH Keys can either be used as an optional alternative to a password, as an additional factor for authentication, or as a mandatory replacement for a password, depending on how the system is configured.

SSH Keys will never grant access to a shell or system prompt at Files.com and are only for SFTP protocol usage.

Explanation of Public/Private Key Cryptography

An SSH Key is really a matched pair: a public key and a corresponding private key.

When generating an SSH key, the two halves (public and private) will always be created.

The private key must never be shared, and should remain under the control of the user, script, or system that will be using SFTP to connect to an SFTP account. The private key is the equivalent of your password and should be protected similarly.

The public key can be shared with any system that needs to provide secure access to the user, script, or system that owns the corresponding private key. The public key does not need to be kept secret and can be distributed freely. The public key has no power, authorization, or authority without the corresponding private key.

Never share a private key. Whenever exchanging SSH keys for use with SFTP or SSH access, only send or share the public key portion.

Adding SFTP Keys in Files.com

SSH Keys can be imported into Files.com and used to authenticate users.

Users can add their own SSH public keys to their account profile.

Site Administrators can add an SSH key to any Files.com user account. Workspace Administrators can add SSH keys for their Workspace users. Partner Admins can manage SSH keys for their Partner's users.

Only key types supported by your site can be added or imported.

Once imported, the user account can use their SSH private key to authenticate and gain access to Files.com using the SFTP protocol.

Public keys are not viewable once saved, but can be identified by their unique key fingerprint. If you need to verify that you have the correct key, you can view the public key's fingerprint. If you believe that the key pair has been compromised or is no longer in use, delete the key.

Supported Key Types

We support the ED25519 (including ED25519-sk), ECDSA (including ECDSA-sk), RSA, and DSA encryption types for keys.

We recommend using ED25519 keys because they are the most secure. RSA and DSA keys are considered less secure and slower than ED25519.

If using an RSA key, we recommend using a key length of at least 2048 bits.

The supported key types depend on your SFTP Ciphers setting. By default, insecure key types, such as DSA, are blocked when you try to add them. To allow these less secure keys, enable the Require the most secure, modern ciphers for FTP, but allow SFTP connections to use insecure ciphers option in your site's Ciphers settings.

Supported Public Key Formats

Public keys may be provided in standard OpenSSH format, RFC-4716 format, or in PPK (PuTTY Private Key) format. OpenSSH format is the default format produced by modern OpenSSH tools such as ssh-keygen, and is most commonly used on Linux and macOS systems. RFC 4716 is the IETF standard SSH public key file format, sometimes referred to as the "SSH2 public key" format, and is commonly exported by tools like PuTTYgen. PPK is a proprietary format used by PuTTY and WinSCP, and can contain any of the supported key types listed above. Files.com accepts public keys in any of these formats.

You can tell if your key is in a standard format by opening the file in a text editor and reading the first line.

OpenSSH Public Keys

Public keys in OpenSSH format contain only one line of text. The text starts with the key type followed by a long block of text and an optional comment. For an RSA key, this would look something like the following.

ssh-rsa AAABIYe....1v9cGwe696GTAGBxx+y1qbYj+j6UdU54sQiHLsuQ= user@computer

Private keys in OpenSSH format include multiple lines and start with a header line reading:

-----BEGIN OPENSSH PRIVATE KEY-----

If your key file says -----BEGIN OPENSSH PRIVATE KEY-----, you are not looking at the public key file.

RFC 4716 / SSH2 Public Keys

SSH2-compatible public keys use RFC 4716 format. The first line will start with this text:

---- BEGIN SSH2 PUBLIC KEY ----

PPK Key Files

PPK files contain both the private and public keys in the same file, usually ending in the extension .ppk. The first few lines of a PPK file indicate what format is expected and whether the keys included are encrypted.

PuTTY-User-Key-File-(VERSION): (ALGORITHM_NAME)
Encryption: (ENCRYPTION_TYPE)
Comment: (KEY_COMMENT_STRING)

VERSION is a decimal number giving the version number of the file format itself. The current file format version is 3.

ALGORITHM_NAME is the SSH protocol identifier for the public key algorithm that this key is used for. Examples include ssh-rsa, ssh-dss , ecdsa-sha2-nistp384 , among others.

ENCRYPTION_TYPE indicates whether this key is encrypted in the file, and if so, by what method. Currently the only supported encryption types are aes256-cbc and none.

KEY_COMMENT_STRING is a free text field giving the comment. This text must be a single line with no line breaks.

SFTP Keys and Authentication Methods

The way an SSH Key interacts with authentication depends on how the user account is configured.

SFTP Keys for User Accounts with Passwords

When a user account is configured with a password, the SSH Key will act as an additional method of authentication. This means that either the SSH Key or the password can be used to authenticate an SFTP connection by that user account. A user account is considered to have a password when the Authentication Method for that account was configured to use any of the following options:

• Password
• Imported hash
• Password and SFTP/SSH Key
• Email sign-up
• Any of the available Single-Sign-On (SSO) methods

SFTP Keys for User Accounts without Passwords

A user account is considered to have no password when the Authentication Method for that account is set to None. When a user account is configured with no password, only an SSH Key or an API key can be used by the user to authenticate an SFTP connection.

SFTP Keys and Two-Factor Authentication (2FA)

When a user account is configured to Require Two-factor authentication then SSH Keys cannot be used to authenticate.

SSH Keys can only be used with user accounts that have no 2FA requirement.

Enable 2FA for SSH Keys by using key types of ecdsa-sk or ed25519-sk. This implements a 2FA method that is managed by the SSH Key itself.