ssh(7)



SSH(7)                   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(disabled by default)

         * id_rsa(disabled by default from OTP-24)

         * id_ecdsa

         * id_ed25519

         * id_ed448

         * ssh_host_dsa_key(disabled by default)

         * ssh_host_rsa_key(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.

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  in-
       teraction.

       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

           * ssh-rsa (disabled by default from OTP-24)

           The following unsecure sha1 algorithm is now disabled by default:

           * (ssh-dss)

           It can be enabled with  the  preferred_algorithms  or  modify_algo-
           rithms  options.  Use  for  example  the Option value {modify_algo-
           rithms, [{append, [{public_key,['ssh-dss']}]}]})

         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

           They  are  disabled  by  default,  but can be enabled with the pre-
           ferred_algorithms or modify_algorithms options.

         * 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  default,  but  can  be  enabled  with  the  pre-
           ferred_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 re-
         sponsibility 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 ap-
           plied

         * 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, but are still supported and can be en-
           abled with the options preferred_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 (work in progress)

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

SEE ALSO
       application(3erl)

Ericsson AB                        ssh 4.10                             SSH(7)

Man(1) output converted with man2html
list of all man pages