.TH SSH 7 "ssh 4.10.8" "Ericsson AB" "Erlang Application Definition"
.SH NAME
SSH \- The ssh application implements the Secure Shell (SSH) protocol and
  provides an SSH File Transfer Protocol (SFTP) client and server.
.SH DESCRIPTION
.LP
The \fIssh\fR\& application is an implementation of the SSH protocol in Erlang\&. \fIssh\fR\& offers API functions to write customized SSH clients and servers as well as making the Erlang shell available over SSH\&. An SFTP client, \fIssh_sftp\fR\&, and server, \fIssh_sftpd\fR\&, are also included\&.
.SH "DEPENDENCIES"

.LP
The \fIssh\fR\& application uses the applications public_key and crypto to handle public keys and encryption\&. Hence, these applications must be loaded for the \fIssh\fR\& application to work\&. The call ssh:start/0 will do the necessary calls to application:start/1,2 before it starts the \fIssh\fR\& itself\&.
.SH "CONFIGURATION"

.LP
The SSH application uses Configuration Parameters\&. Where to set them are described in config User\&'s Guide with SSH details in Configuration in SSH\&.
.LP
Some special configuration files from OpenSSH are also used:
.RS 2
.TP 2
*
\fIknown_hosts\fR\&
.LP
.TP 2
*
\fIauthorized_keys\fR\&
.LP
.TP 2
*
\fIauthorized_keys2\fR\&
.LP
.TP 2
*
\fIid_dsa\fR\&\fI(disabled by default)\fR\& 
.LP
.TP 2
*
\fIid_rsa\fR\&\fI(disabled by default from OTP-24)\fR\& 
.LP
.TP 2
*
\fIid_ecdsa\fR\&
.LP
.TP 2
*
\fIid_ed25519\fR\&
.LP
.TP 2
*
\fIid_ed448\fR\&
.LP
.TP 2
*
\fIssh_host_dsa_key\fR\&\fI(disabled by default)\fR\& 
.LP
.TP 2
*
\fIssh_host_rsa_key\fR\&\fI(disabled by default from OTP-24)\fR\& 
.LP
.TP 2
*
\fIssh_host_ecdsa_key\fR\&
.LP
.TP 2
*
\fIssh_host_ed25519_key\fR\&
.LP
.TP 2
*
\fIssh_host_ed448_key\fR\&
.LP
.RE

.LP
By default, \fIssh\fR\& looks for \fIid_*\fR\&, \fIknown_hosts\fR\&, and \fIauthorized_keys\fR\& in \fI~/\&.ssh\fR\&, and for the ssh_host_*_key files in \fI/etc/ssh\fR\&\&. These locations can be changed by the options \fIuser_dir\fR\& and \fIsystem_dir\fR\&\&. More about where to set them is described in Configuration in SSH\&.
.LP
Public key handling can also be customized through a callback module that implements the behaviors ssh_client_key_api and ssh_server_key_api\&.
.LP
See also the default callback module documentation in ssh_file\&.
.SH "PUBLIC KEYS"

.LP
\fIid_*\fR\& are the users private key files\&. Notice that the public key is part of the private key so the \fIssh\fR\& application does not use the \fIid_*\&.pub\fR\& files\&. These are for the user\&'s convenience when it is needed to convey the user\&'s public key\&.
.LP
See ssh_file for details\&.
.SH "KNOWN HOSTS"

.LP
The \fIknown_hosts\fR\& file contains a list of approved servers and their public keys\&. Once a server is listed, it can be verified without user interaction\&.
.LP
See ssh_file for details\&.
.SH "AUTHORIZED KEYS"

.LP
The \fIauthorized_key\fR\& 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 \fIssh\fR\& daemon\&.
.LP
See ssh_file for details\&.
.SH "HOST KEYS"

.LP
RSA, DSA (if enabled), ECDSA, ED25519 and ED448 host keys are supported and are expected to be found in files named \fIssh_host_rsa_key\fR\&, \fIssh_host_dsa_key\fR\&, \fIssh_host_ecdsa_key\fR\&, \fIssh_host_ed25519_key\fR\& and \fIssh_host_ed448_key\fR\&\&.
.LP
See ssh_file for details\&.
.SH "ERROR LOGGER AND EVENT HANDLERS"

.LP
The \fIssh\fR\& application uses the default OTP error logger to log unexpected errors or print information about special events\&.
.SH "SUPPORTED SPECIFICATIONS AND STANDARDS"

.LP
The supported SSH version is 2\&.0\&.
.SH "ALGORITHMS"

.LP
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 modify_algorithms in the ssh:daemon/1,2,3 and ssh:connect/3,4 functions\&.
.LP
Supported algorithms are (in the default order):
.RS 2
.TP 2
.B
Key exchange algorithms:

.RS 2
.TP 2
*
ecdh-sha2-nistp384
.LP
.TP 2
*
ecdh-sha2-nistp521
.LP
.TP 2
*
ecdh-sha2-nistp256
.LP
.TP 2
*
diffie-hellman-group-exchange-sha256
.LP
.TP 2
*
diffie-hellman-group16-sha512
.LP
.TP 2
*
diffie-hellman-group18-sha512
.LP
.TP 2
*
diffie-hellman-group14-sha256
.LP
.TP 2
*
curve25519-sha256
.LP
.TP 2
*
curve25519-sha256@libssh\&.org
.LP
.TP 2
*
curve448-sha512
.LP
.RE

.RS 2
.LP
The following unsecure \fIsha1\fR\& algorithms are now disabled by default:
.RE

.RS 2
.TP 2
*
(diffie-hellman-group14-sha1)
.LP
.TP 2
*
(diffie-hellman-group-exchange-sha1)
.LP
.TP 2
*
(diffie-hellman-group1-sha1)
.LP
.RE

.RS 2
.LP
They can be enabled with the preferred_algorithms or modify_algorithms options\&. Use for example the Option value \fI{modify_algorithms, [{append, [{kex,[\&'diffie-hellman-group1-sha1\&']}]}]}\fR\&)
.RE

.TP 2
.B
Public key algorithms:

.RS 2
.TP 2
*
ecdsa-sha2-nistp384
.LP
.TP 2
*
ecdsa-sha2-nistp521
.LP
.TP 2
*
ecdsa-sha2-nistp256
.LP
.TP 2
*
ssh-ed25519
.LP
.TP 2
*
ssh-ed448
.LP
.TP 2
*
rsa-sha2-256
.LP
.TP 2
*
rsa-sha2-512
.LP
.TP 2
*
ssh-rsa \fI(disabled by default from OTP-24)\fR\& 
.LP
.RE

.RS 2
.LP
The following unsecure \fIsha1\fR\& algorithm is now disabled by default:
.RE

.RS 2
.TP 2
*
(ssh-dss)
.LP
.RE

.RS 2
.LP
It can be enabled with the preferred_algorithms or modify_algorithms options\&. Use for example the Option value \fI{modify_algorithms, [{append, [{public_key,[\&'ssh-dss\&']}]}]}\fR\&)
.RE

.TP 2
.B
MAC algorithms:

.RS 2
.TP 2
*
hmac-sha2-256-etm@openssh\&.com
.LP
.TP 2
*
hmac-sha2-512-etm@openssh\&.com
.LP
.TP 2
*
hmac-sha1-etm@openssh\&.com
.LP
.TP 2
*
hmac-sha2-256
.LP
.TP 2
*
hmac-sha2-512
.LP
.TP 2
*
hmac-sha1
.LP
.RE

.RS 2
.LP
The following unsecure \fIsha1\fR\& algorithm is disabled by default:
.RE

.RS 2
.TP 2
*
(hmac-sha1-96)
.LP
.RE

.RS 2
.LP
It can be enabled with the preferred_algorithms or modify_algorithms options\&. Use for example the Option value \fI{modify_algorithms, [{append, [{mac,[\&'hmac-sha1-96\&']}]}]}\fR\&)
.RE

.TP 2
.B
Encryption algorithms (ciphers):

.RS 2
.TP 2
*
chacha20-poly1305@openssh\&.com
.LP
.TP 2
*
aes256-gcm@openssh\&.com
.LP
.TP 2
*
aes256-ctr
.LP
.TP 2
*
aes192-ctr
.LP
.TP 2
*
aes128-gcm@openssh\&.com
.LP
.TP 2
*
aes128-ctr
.LP
.TP 2
*
aes256-cbc
.LP
.TP 2
*
aes192-cbc
.LP
.TP 2
*
aes128-cbc
.LP
.TP 2
*
3des-cbc
.LP
.TP 2
*
(AEAD_AES_128_GCM, not enabled per default)
.LP
.TP 2
*
(AEAD_AES_256_GCM, not enabled per default)
.LP
.RE

.RS 2
.LP
See the text at the description of the rfc 5647 further down for more information regarding AEAD_AES_*_GCM\&.
.RE

.RS 2
.LP
Following the internet de-facto standard, the cipher and mac algorithm 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\&.
.RE

.TP 2
.B
Compression algorithms:

.RS 2
.TP 2
*
none
.LP
.TP 2
*
zlib@openssh\&.com
.LP
.TP 2
*
zlib
.LP
.RE

.RE
.SH "UNICODE SUPPORT"

.LP
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\&.
.LP
The shell and the cli both support unicode\&.
.SH "RFCS"

.LP
The following rfc:s are supported:
.RS 2
.TP 2
*
RFC 4251, The Secure Shell (SSH) Protocol Architecture\&. 
.RS 2
.LP
Except
.RE

.RS 2
.TP 2
*
9\&.4\&.6 Host-Based Authentication
.LP
.TP 2
*
9\&.5\&.2 Proxy Forwarding
.LP
.TP 2
*
9\&.5\&.3 X11 Forwarding
.LP
.RE

.RS 2
.LP

.RE

.LP
.TP 2
*
RFC 4252, The Secure Shell (SSH) Authentication Protocol\&. 
.RS 2
.LP
Except
.RE

.RS 2
.TP 2
*
9\&. Host-Based Authentication: "hostbased"
.LP
.RE

.RS 2
.LP

.RE

.LP
.TP 2
*
RFC 4253, The Secure Shell (SSH) Transport Layer Protocol\&. 
.RS 2
.LP
Except
.RE

.RS 2
.TP 2
*
8\&.1\&. diffie-hellman-group1-sha1
.LP
.TP 2
*
6\&.6\&. Public Key Algorithms 
.RS 2
.TP 2
*
ssh-dss
.LP
.RE

.LP
.RE

.RS 2
.LP
They are disabled by default, but can be enabled with the preferred_algorithms or modify_algorithms options\&.
.RE

.LP
.TP 2
*
RFC 4254, The Secure Shell (SSH) Connection Protocol\&. 
.RS 2
.LP
Except
.RE

.RS 2
.TP 2
*
6\&.3\&. X11 Forwarding
.LP
.TP 2
*
7\&. TCP/IP Port Forwarding
.LP
.RE

.RS 2
.LP

.RE

.LP
.TP 2
*
RFC 4256, Generic Message Exchange Authentication for the Secure Shell Protocol (SSH)\&. 
.RS 2
.LP
Except
.RE

.RS 2
.TP 2
*
\fInum-prompts > 1\fR\&
.LP
.TP 2
*
password changing
.LP
.TP 2
*
other identification methods than userid-password
.LP
.RE

.RS 2
.LP

.RE

.LP
.TP 2
*
RFC 4419, Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol\&. 
.RS 2
.LP
Except
.RE

.RS 2
.TP 2
*
4\&.1\&. diffie-hellman-group-exchange-sha1
.LP
.RE

.RS 2
.LP
It is disabled by default, but can be enabled with the preferred_algorithms or modify_algorithms options\&.
.RE

.LP
.TP 2
*
RFC 4716, The Secure Shell (SSH) Public Key File Format\&. 
.RS 2
.LP

.RE

.LP
.TP 2
*
RFC 5647, AES Galois Counter Mode for the Secure Shell Transport Layer Protocol\&. 
.RS 2
.LP
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 implemented\&. 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\&.
.RE

.LP

.RS -4
.B
Warning:
.RE
If the client or the server is not Erlang/OTP, it is the users responsibility to check that other implementation has the same interpretation 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\&.

.RS 2
.LP
The second paragraph in section 5\&.1 is resolved as:
.RE

.RS 2
.TP 2
*
If the negotiated cipher is AEAD_AES_128_GCM, the mac algorithm is set to AEAD_AES_128_GCM\&.
.LP
.TP 2
*
If the negotiated cipher is AEAD_AES_256_GCM, the mac algorithm is set to AEAD_AES_256_GCM\&.
.LP
.TP 2
*
If the mac algorithm is AEAD_AES_128_GCM, the cipher is set to AEAD_AES_128_GCM\&.
.LP
.TP 2
*
If the mac algorithm is AEAD_AES_256_GCM, the cipher is set to AEAD_AES_256_GCM\&.
.LP
.RE

.RS 2
.LP
The first rule that matches when read in order from the top is applied
.RE

.LP
.TP 2
*
RFC 5656, Elliptic Curve Algorithm Integration in the Secure Shell Transport Layer\&. 
.RS 2
.LP
Except
.RE

.RS 2
.TP 2
*
5\&. ECMQV Key Exchange
.LP
.TP 2
*
6\&.4\&. ECMQV Key Exchange and Verification Method Name
.LP
.TP 2
*
7\&.2\&. ECMQV Message Numbers
.LP
.TP 2
*
10\&.2\&. Recommended Curves
.LP
.RE

.RS 2
.LP

.RE

.LP
.TP 2
*
RFC 6668, SHA-2 Data Integrity Verification for the Secure Shell (SSH) Transport Layer Protocol 
.RS 2
.LP
Comment: Defines hmac-sha2-256 and hmac-sha2-512
.RE

.LP
.TP 2
*
Draft-ietf-curdle-ssh-kex-sha2 (work in progress), Key Exchange (KEX) Method Updates and Recommendations for Secure Shell (SSH)\&. 
.RS 2
.LP
Deviations:
.RE

.RS 2
.TP 2
*
\fIdiffie-hellman-group1-sha1\fR\&
.LP
.TP 2
*
\fIdiffie-hellman-group-exchange-sha1\fR\&
.LP
.TP 2
*
\fIdiffie-hellman-group14-sha1\fR\&
.LP
.RE

.RS 2
.LP
are not enabled by default, but are still supported and can be enabled with the options preferred_algorithms or modify_algorithms\&.
.RE

.LP
.TP 2
*
RFC 8332, Use of RSA Keys with SHA-256 and SHA-512 in the Secure Shell (SSH) Protocol\&. 
.RS 2
.LP

.RE

.LP
.TP 2
*
RFC 8308, Extension Negotiation in the Secure Shell (SSH) Protocol\&. 
.RS 2
.LP
Implemented are:
.RE

.RS 2
.TP 2
*
The Extension Negotiation Mechanism
.LP
.TP 2
*
The extension \fIserver-sig-algs\fR\&
.LP
.RE

.RS 2
.LP

.RE

.LP
.TP 2
*
Secure Shell (SSH) Key Exchange Method using Curve25519 and Curve448 (work in progress)
.RS 2
.LP

.RE

.LP
.TP 2
*
RFC 8709 Ed25519 and Ed448 public key algorithms for the Secure Shell (SSH) protocol 
.LP
.RE

.SH "SEE ALSO"

.LP
application(3erl)