Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

SSH (7erl)

Name

SSH - The ssh application implements the Secure Shell (SSH) protocol and provides an SSH File Transfer Protocol (SFTP) client and server.

Synopsis

Please see following description for synopsis

Description

Erlang Application Definition                                           SSH(7)



NAME
       SSH  -  The  ssh application implements the Secure Shell (SSH) protocol
       and
         provides an SSH File Transfer Protocol (SFTP) client and server.

DESCRIPTION
       The ssh application is an implementation of the SSH protocol in Erlang.
       ssh offers API functions to write customized SSH clients and servers as
       well as making the Erlang shell available over  SSH.  An  SFTP  client,
       ssh_sftp, and server, ssh_sftpd, are also included.

DEPENDENCIES
       The ssh application uses the applications public_key and crypto to han-
       dle public keys and  encryption.  Hence,  these  applications  must  be
       loaded  for  the  ssh application to work. The call ssh:start/0 will do
       the necessary calls to application:start/1,2 before it starts  the  ssh
       itself.

CONFIGURATION
       The  SSH  application  uses Configuration Parameters. Where to set them
       are described in config User's Guide with SSH details in  Configuration
       in SSH.

       Some special configuration files from OpenSSH are also used:

         * known_hosts

         * authorized_keys

         * authorized_keys2

         * id_dsa(supported but disabled by default)

         * id_rsa(SHA1  sign/verify are supported but disabled by default from
           OTP-24)

         * id_ecdsa

         * id_ed25519

         * id_ed448

         * ssh_host_dsa_key(supported but disabled by default)

         * ssh_host_rsa_key(SHA1 sign/verify are  supported  but  disabled  by
           default from OTP-24)

         * ssh_host_ecdsa_key

         * ssh_host_ed25519_key

         * ssh_host_ed448_key

       By  default,  ssh  looks  for id_*, known_hosts, and authorized_keys in
       ~/.ssh, and for the ssh_host_*_key files in /etc/ssh.  These  locations
       can be changed by the options user_dir and system_dir. More about where
       to set them is described in Configuration in SSH.

       Public key handling can also be customized through  a  callback  module
       that     implements     the     behaviors     ssh_client_key_api    and
       ssh_server_key_api.

       See also the default callback module documentation in ssh_file.

       Disabled public key algorithms can be enabled with the  preferred_algo-
       rithms or modify_algorithms options. See Example 9 in Configuring algo-
       rithms in SSH for a description.

PUBLIC KEYS
       id_* are the users private key files. Notice that  the  public  key  is
       part  of  the  private  key  so  the  ssh  application does not use the
       id_*.pub files. These are for the user's convenience when it is  needed
       to convey the user's public key.

       See ssh_file for details.

KNOWN HOSTS
       The known_hosts file contains a list of approved servers and their pub-
       lic keys. Once a server is listed, it  can  be  verified  without  user
       interaction.

       See ssh_file for details.

AUTHORIZED KEYS
       The  authorized_key  file  keeps  track of the user's authorized public
       keys. The most common use of this file is to let users log  in  without
       entering their password, which is supported by the Erlang ssh daemon.

       See ssh_file for details.

HOST KEYS
       RSA, DSA (if enabled), ECDSA, ED25519 and ED448 host keys are supported
       and  are  expected  to  be  found  in  files  named   ssh_host_rsa_key,
       ssh_host_dsa_key,    ssh_host_ecdsa_key,    ssh_host_ed25519_key    and
       ssh_host_ed448_key.

       See ssh_file for details.

ERROR LOGGER AND EVENT HANDLERS
       The ssh application uses the default OTP error logger to log unexpected
       errors or print information about special events.

SUPPORTED SPECIFICATIONS AND STANDARDS
       The supported SSH version is 2.0.

ALGORITHMS
       The actual set of algorithms may vary depending on which OpenSSL crypto
       library that is installed on the machine. For the list on a  particular
       installation,  use  the  command ssh:default_algorithms/0. The user may
       override the default algorithm configuration both on  the  server  side
       and  the  client  side.  See  the options preferred_algorithms and mod-
       ify_algorithms in the ssh:daemon/1,2,3 and ssh:connect/3,4 functions.

       Supported algorithms are (in the default order):

         Key exchange algorithms:


           * ecdh-sha2-nistp384

           * ecdh-sha2-nistp521

           * ecdh-sha2-nistp256

           * diffie-hellman-group-exchange-sha256

           * diffie-hellman-group16-sha512

           * diffie-hellman-group18-sha512

           * diffie-hellman-group14-sha256

           * curve25519-sha256

           * curve25519-sha256@libssh.org

           * curve448-sha512

           The following unsecure SHA1 algorithms are now disabled by default:

           * (diffie-hellman-group14-sha1)

           * (diffie-hellman-group-exchange-sha1)

           * (diffie-hellman-group1-sha1)

           They can be enabled with the preferred_algorithms  or  modify_algo-
           rithms  options.  Use  for  example  the Option value {modify_algo-
           rithms, [{append, [{kex,['diffie-hellman-group1-sha1']}]}]})

         Public key algorithms:


           * ecdsa-sha2-nistp384

           * ecdsa-sha2-nistp521

           * ecdsa-sha2-nistp256

           * ssh-ed25519

           * ssh-ed448

           * rsa-sha2-256

           * rsa-sha2-512

           The following unsecure SHA1 algorithms are supported  but  disabled
           by default:

           * (ssh-dss)

           * (ssh-rsa)

           See  Disabled  public  key  algorithms can be enabled with the pre-
           ferred_algorithms or modify_algorithms options. See  Example  9  in
           Configuring algorithms in SSH for a description.

         MAC algorithms:


           * hmac-sha2-256-etm@openssh.com

           * hmac-sha2-512-etm@openssh.com

           * hmac-sha1-etm@openssh.com

           * hmac-sha2-256

           * hmac-sha2-512

           * hmac-sha1

           The following unsecure SHA1 algorithm is disabled by default:

           * (hmac-sha1-96)

           It  can  be  enabled  with the preferred_algorithms or modify_algo-
           rithms options. Use for  example  the  Option  value  {modify_algo-
           rithms, [{append, [{mac,['hmac-sha1-96']}]}]})

         Encryption algorithms (ciphers):


           * chacha20-poly1305@openssh.com

           * aes256-gcm@openssh.com

           * aes256-ctr

           * aes192-ctr

           * aes128-gcm@openssh.com

           * aes128-ctr

           * aes256-cbc

           * aes192-cbc

           * aes128-cbc

           * 3des-cbc

           * (AEAD_AES_128_GCM, not enabled per default)

           * (AEAD_AES_256_GCM, not enabled per default)

           See  the  text  at the description of the rfc 5647 further down for
           more information regarding AEAD_AES_*_GCM.

           Following the internet de-facto standard, the cipher and mac  algo-
           rithm    AEAD_AES_128_GCM    is    selected    when    the   cipher
           aes128-gcm@openssh.com is negotiated. The cipher and mac  algorithm
           AEAD_AES_256_GCM is selected when the cipher aes256-gcm@openssh.com
           is negotiated.

         Compression algorithms:


           * none

           * zlib@openssh.com

           * zlib

UNICODE SUPPORT
       Unicode filenames are supported if the emulator and the underlaying  OS
       support  it.  See section DESCRIPTION in the file manual page in Kernel
       for information about this subject.

       The shell and the cli both support unicode.

RFCS
       The following rfc:s are supported:

         * RFC 4251, The Secure Shell (SSH) Protocol Architecture.

           Except

           * 9.4.6 Host-Based Authentication

           * 9.5.2 Proxy Forwarding

           * 9.5.3 X11 Forwarding

         * RFC 4252, The Secure Shell (SSH) Authentication Protocol.

           Except

           * 9. Host-Based Authentication: "hostbased"

         * RFC 4253, The Secure Shell (SSH) Transport Layer Protocol.

           Except

           * 8.1. diffie-hellman-group1-sha1

           * 6.6. Public Key Algorithms

             * ssh-dss

             * ssh-rsa

           They are disabled by default as they now are regarded insecure, but
           they  can  be enabled with the preferred_algorithms or modify_algo-
           rithms options.  See  Example  8  (diffie-hellman-group1-sha1)  and
           Example  9  (ssh-dss) in Configuring algorithms in SSH for descrip-
           tions.

         * RFC 4254, The Secure Shell (SSH) Connection Protocol.

           Except

           * 6.3. X11 Forwarding

           * 7. TCP/IP Port Forwarding

         * RFC 4256, Generic Message Exchange Authentication  for  the  Secure
           Shell Protocol (SSH).

           Except

           * num-prompts > 1

           * password changing

           * other identification methods than userid-password

         * RFC  4419, Diffie-Hellman Group Exchange for the Secure Shell (SSH)
           Transport Layer Protocol.

           Except

           * 4.1. diffie-hellman-group-exchange-sha1

           It is disabled by defaultas as it now is regarded insecure, but  it
           can  be  enabled with the preferred_algorithms or modify_algorithms
           options.

         * RFC 4716, The Secure Shell (SSH) Public Key File Format.

         * RFC 5647, AES Galois Counter Mode for the  Secure  Shell  Transport
           Layer Protocol.

           There  is  an ambiguity in the synchronized selection of cipher and
           mac  algorithm.  This  is  resolved  by  OpenSSH  in  the   ciphers
           aes128-gcm@openssh.com  and aes256-gcm@openssh.com which are imple-
           mented. If  the  explicit  ciphers  and  macs  AEAD_AES_128_GCM  or
           AEAD_AES_256_GCM are needed, they could be enabled with the options
           preferred_algorithms or modify_algorithms.

     Warning:
         If the client or the server  is  not  Erlang/OTP,  it  is  the  users
         responsibility to check that other implementation has the same inter-
         pretation of AEAD_AES_*_GCM as the  Erlang/OTP  SSH  before  enabling
         them.  The aes*-gcm@openssh.com variants are always safe to use since
         they lack the ambiguity.


           The second paragraph in section 5.1 is resolved as:

           * If the negotiated cipher is AEAD_AES_128_GCM, the  mac  algorithm
             is set to AEAD_AES_128_GCM.

           * If  the  negotiated cipher is AEAD_AES_256_GCM, the mac algorithm
             is set to AEAD_AES_256_GCM.

           * If the mac algorithm is AEAD_AES_128_GCM, the cipher  is  set  to
             AEAD_AES_128_GCM.

           * If  the  mac  algorithm is AEAD_AES_256_GCM, the cipher is set to
             AEAD_AES_256_GCM.

           The first rule that matches when read in  order  from  the  top  is
           applied

         * RFC  5656, Elliptic Curve Algorithm Integration in the Secure Shell
           Transport Layer.

           Except

           * 5. ECMQV Key Exchange

           * 6.4. ECMQV Key Exchange and Verification Method Name

           * 7.2. ECMQV Message Numbers

           * 10.2. Recommended Curves

         * RFC 6668, SHA-2 Data Integrity Verification for  the  Secure  Shell
           (SSH) Transport Layer Protocol

           Comment: Defines hmac-sha2-256 and hmac-sha2-512

         * Draft-ietf-curdle-ssh-kex-sha2  (work  in  progress),  Key Exchange
           (KEX) Method Updates and Recommendations for Secure Shell (SSH).

           Deviations:

           * diffie-hellman-group1-sha1

           * diffie-hellman-group-exchange-sha1

           * diffie-hellman-group14-sha1

           are not enabled by default as they now are regarded  insecure,  but
           are  still  supported  and  can  be  enabled  with the options pre-
           ferred_algorithms or modify_algorithms.

         * RFC 8332, Use of RSA Keys with SHA-256 and SHA-512  in  the  Secure
           Shell (SSH) Protocol.

         * RFC 8308, Extension Negotiation in the Secure Shell (SSH) Protocol.

           Implemented are:

           * The Extension Negotiation Mechanism

           * The extension server-sig-algs

         * Secure  Shell  (SSH)  Key  Exchange  Method  Using  Curve25519  and
           Curve448

         * RFC 8709 Ed25519 and Ed448 public key  algorithms  for  the  Secure
           Shell (SSH) protocol

SEE ALSO
       application(3)



Ericsson AB                        ssh 4.12                             SSH(7)