1SSH(7) Erlang Application Definition SSH(7)
2
6 SSH - The ssh application implements the Secure Shell (SSH) protocol
7 and
8 provides an SSH File Transfer Protocol (SFTP) client and server.
9
11 The ssh application is an implementation of the SSH protocol in Erlang.
12 ssh offers API functions to write customized SSH clients and servers as
13 well as making the Erlang shell available over SSH. An SFTP client,
14 ssh_sftp, and server, ssh_sftpd, are also included.
15
17 The ssh application uses the applications public_key and crypto to han‐
18 dle public keys and encryption. Hence, these applications must be
19 loaded for the ssh application to work. In an embedded environment this
20 means that they must be started with application:start/1,2 before the
21 ssh application is started.
22
24 The ssh application does not have an application- specific configura‐
25 tion file, as described in application(3). However, by default it use
26 the following configuration files from OpenSSH:
27 * known_hosts
29 * authorized_keys
31 * authorized_keys2
33 * id_dsa
35 * id_rsa
37 * id_ecdsa
39 * ssh_host_dsa_key
41 * ssh_host_rsa_key
43 * ssh_host_ecdsa_key
45 By default, ssh looks for id_dsa, id_rsa, id_ecdsa_key, known_hosts,
47 and authorized_keys in ~/.ssh, and for the host key files in /etc/ssh.
48 These locations can be changed by the options user_dir and system_dir.
49 Public key handling can also be customized through a callback module
51 that implements the behaviors ssh_client_key_api and
52 ssh_server_key_api.
53 See also the default callback module documentation in ssh_file.
55
57 id_dsa, id_rsa and id_ecdsa are the users private key files. Notice
58 that the public key is part of the private key so the ssh application
59 does not use the id_<*>.pub files. These are for the user's convenience
60 when it is needed to convey the user's public key.
61
63 The known_hosts file contains a list of approved servers and their pub‐
64 lic keys. Once a server is listed, it can be verified without user
65 interaction.
66
68 The authorized_key file keeps track of the user's authorized public
69 keys. The most common use of this file is to let users log in without
70 entering their password, which is supported by the Erlang ssh daemon.
71
73 RSA, DSA and ECDSA host keys are supported and are expected to be found
74 in files named ssh_host_rsa_key, ssh_host_dsa_key and
75 ssh_host_ecdsa_key.
76
78 The ssh application uses the default OTP error logger to log unexpected
79 errors or print information about special events.
80
82 The supported SSH version is 2.0.
83
85 The actual set of algorithms may vary depending on which OpenSSL crypto
86 library that is installed on the machine. For the list on a particular
87 installation, use the command ssh:default_algorithms/0. The user may
88 override the default algorithm configuration both on the server side
89 and the client side. See the options preferred_algorithms and mod‐
90 ify_algorithms in the ssh:daemon/1,2,3 and ssh:connect/3,4 functions.
91 Supported algorithms are (in the default order):
93 Key exchange algorithms:
95 * ecdh-sha2-nistp384
98 * ecdh-sha2-nistp521
100 * ecdh-sha2-nistp256
102 * diffie-hellman-group-exchange-sha256
104 * diffie-hellman-group16-sha512
106 * diffie-hellman-group18-sha512
108 * diffie-hellman-group14-sha256
110 * curve25519-sha256
112 * curve25519-sha256@libssh.org
114 * curve448-sha512
116 * diffie-hellman-group14-sha1
118 * diffie-hellman-group-exchange-sha1
120 * (diffie-hellman-group1-sha1, retired: It can be enabled with the
122 preferred_algorithms or modify_algorithms options. Use for exam‐
123 ple the Option value {modify_algorithms, [{append,
124 [{kex,['diffie-hellman-group1-sha1']}]}]})
125 Public key algorithms:
127 * ecdsa-sha2-nistp384
130 * ecdsa-sha2-nistp521
132 * ecdsa-sha2-nistp256
134 * ssh-ed25519
136 * ssh-ed448
138 * ssh-rsa
140 * rsa-sha2-256
142 * rsa-sha2-512
144 * ssh-dss
146 MAC algorithms:
148 * hmac-sha2-256
151 * hmac-sha2-512
153 * hmac-sha1
155 * (hmac-sha1-96 It can be enabled with the preferred_algorithms or
157 modify_algorithms options. Use for example the Option value {mod‐
158 ify_algorithms, [{append, [{mac,['hmac-sha1-96']}]}]})
159 Encryption algorithms (ciphers):
161 * chacha20-poly1305@openssh.com
164 * aes256-gcm@openssh.com
166 * aes256-ctr
168 * aes192-ctr
170 * aes128-gcm@openssh.com
172 * aes128-ctr
174 * aes256-cbc
176 * aes192-cbc
178 * aes128-cbc
180 * 3des-cbc
182 * (AEAD_AES_128_GCM, not enabled per default)
184 * (AEAD_AES_256_GCM, not enabled per default)
186 See the text at the description of the rfc 5647 further down for
188 more information regarding AEAD_AES_*_GCM.
189 Following the internet de-facto standard, the cipher and mac algo‐
191 rithm AEAD_AES_128_GCM is selected when the cipher
192 aes128-gcm@openssh.com is negotiated. The cipher and mac algorithm
193 AEAD_AES_256_GCM is selected when the cipher aes256-gcm@openssh.com
194 is negotiated.
195 Compression algorithms:
197 * none
200 * zlib@openssh.com
202 * zlib
204
206 Unicode filenames are supported if the emulator and the underlaying OS
207 support it. See section DESCRIPTION in the file manual page in Kernel
208 for information about this subject.
209 The shell and the cli both support unicode.
211
213 The following rfc:s are supported:
214 * RFC 4251, The Secure Shell (SSH) Protocol Architecture.
216 Except
218 * 9.4.6 Host-Based Authentication
220 * 9.5.2 Proxy Forwarding
222 * 9.5.3 X11 Forwarding
224 * RFC 4252, The Secure Shell (SSH) Authentication Protocol.
226 Except
228 * 9. Host-Based Authentication: "hostbased"
230 * RFC 4253, The Secure Shell (SSH) Transport Layer Protocol.
232 Except
234 * 8.1. diffie-hellman-group1-sha1. Disabled by default, can be
236 enabled with the preferred_algorithms or modify_algorithms
237 options.
238 * RFC 4254, The Secure Shell (SSH) Connection Protocol.
240 Except
242 * 6.3. X11 Forwarding
244 * 7. TCP/IP Port Forwarding
246 * RFC 4256, Generic Message Exchange Authentication for the Secure
248 Shell Protocol (SSH).
249 Except
251 * num-prompts > 1
253 * password changing
255 * other identification methods than userid-password
257 * RFC 4419, Diffie-Hellman Group Exchange for the Secure Shell (SSH)
259 Transport Layer Protocol.
260 * RFC 4716, The Secure Shell (SSH) Public Key File Format.
262 * RFC 5647, AES Galois Counter Mode for the Secure Shell Transport
264 Layer Protocol.
265 There is an ambiguity in the synchronized selection of cipher and
267 mac algorithm. This is resolved by OpenSSH in the ciphers
268 aes128-gcm@openssh.com and aes256-gcm@openssh.com which are imple‐
269 mented. If the explicit ciphers and macs AEAD_AES_128_GCM or
270 AEAD_AES_256_GCM are needed, they could be enabled with the options
271 preferred_algorithms or modify_algorithms.
272 Warning:
274 If the client or the server is not Erlang/OTP, it is the users
275 responsibility to check that other implementation has the same inter‐
276 pretation of AEAD_AES_*_GCM as the Erlang/OTP SSH before enabling
277 them. The aes*-gcm@openssh.com variants are always safe to use since
278 they lack the ambiguity.
279 The second paragraph in section 5.1 is resolved as:
282 * If the negotiated cipher is AEAD_AES_128_GCM, the mac algorithm
284 is set to AEAD_AES_128_GCM.
285 * If the negotiated cipher is AEAD_AES_256_GCM, the mac algorithm
287 is set to AEAD_AES_256_GCM.
288 * If the mac algorithm is AEAD_AES_128_GCM, the cipher is set to
290 AEAD_AES_128_GCM.
291 * If the mac algorithm is AEAD_AES_256_GCM, the cipher is set to
293 AEAD_AES_256_GCM.
294 The first rule that matches when read in order from the top is
296 applied
297 * RFC 5656, Elliptic Curve Algorithm Integration in the Secure Shell
299 Transport Layer.
300 Except
302 * 5. ECMQV Key Exchange
304 * 6.4. ECMQV Key Exchange and Verification Method Name
306 * 7.2. ECMQV Message Numbers
308 * 10.2. Recommended Curves
310 * RFC 6668, SHA-2 Data Integrity Verification for the Secure Shell
312 (SSH) Transport Layer Protocol
313 Comment: Defines hmac-sha2-256 and hmac-sha2-512
315 * Draft-ietf-curdle-ssh-kex-sha2 (work in progress), Key Exchange
317 (KEX) Method Updates and Recommendations for Secure Shell (SSH).
318 Deviations:
320 * The diffie-hellman-group1-sha1 is not enabled by default, but is
322 still supported and can be enabled with the options pre‐
323 ferred_algorithms or modify_algorithms.
324 * The questionable sha1-based algorithms diffie-hellman-group-
326 exchange-sha1 and diffie-hellman-group14-sha1 are still enabled
327 by default for compatibility with ancient clients and servers.
328 They can be disabled with the options preferred_algorithms or
329 modify_algorithms. They will be disabled by default when the
330 draft is turned into an RFC.
331 * RFC 8332, Use of RSA Keys with SHA-256 and SHA-512 in the Secure
333 Shell (SSH) Protocol.
334 * RFC 8308, Extension Negotiation in the Secure Shell (SSH) Protocol.
336 Implemented are:
338 * The Extension Negotiation Mechanism
340 * The extension server-sig-algs
342 * Secure Shell (SSH) Key Exchange Method using Curve25519 and
344 Curve448 (work in progress)
345 * Ed25519 and Ed448 public key algorithms for the Secure Shell (SSH)
347 protocol (work in progress)
348
350 application(3)
351Ericsson AB ssh 4.9 SSH(7)