1SSH(7) Erlang Application Definition SSH(7)
2
3
4
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. The call ssh:start/0 will do
20 the necessary calls to application:start/1,2 before it starts the ssh
21 itself.
22
24 The SSH application uses Configuration Parameters. Where to set them
25 are described in config User's Guide with SSH details in Configuration
26 in SSH.
27
28 Some special configuration files from OpenSSH are also used:
29
30 * known_hosts
31
32 * authorized_keys
33
34 * authorized_keys2
35
36 * id_dsa(supported but disabled by default)
37
38 * id_rsa(SHA1 sign/verify are supported but disabled by default from
39 OTP-24)
40
41 * id_ecdsa
42
43 * id_ed25519
44
45 * id_ed448
46
47 * ssh_host_dsa_key(supported but disabled by default)
48
49 * ssh_host_rsa_key(SHA1 sign/verify are supported but disabled by de‐
50 fault from OTP-24)
51
52 * ssh_host_ecdsa_key
53
54 * ssh_host_ed25519_key
55
56 * ssh_host_ed448_key
57
58 By default, ssh looks for id_*, known_hosts, and authorized_keys in
59 ~/.ssh, and for the ssh_host_*_key files in /etc/ssh. These locations
60 can be changed by the options user_dir and system_dir. More about where
61 to set them is described in Configuration in SSH.
62
63 Public key handling can also be customized through a callback module
64 that implements the behaviors ssh_client_key_api and
65 ssh_server_key_api.
66
67 See also the default callback module documentation in ssh_file.
68
69 Disabled public key algorithms can be enabled with the preferred_algo‐
70 rithms or modify_algorithms options. See Example 9 in Configuring algo‐
71 rithms in SSH for a description.
72
74 id_* are the users private key files. Notice that the public key is
75 part of the private key so the ssh application does not use the
76 id_*.pub files. These are for the user's convenience when it is needed
77 to convey the user's public key.
78
79 See ssh_file for details.
80
82 The known_hosts file contains a list of approved servers and their pub‐
83 lic keys. Once a server is listed, it can be verified without user in‐
84 teraction.
85
86 See ssh_file for details.
87
89 The authorized_key file keeps track of the user's authorized public
90 keys. The most common use of this file is to let users log in without
91 entering their password, which is supported by the Erlang ssh daemon.
92
93 See ssh_file for details.
94
96 RSA, DSA (if enabled), ECDSA, ED25519 and ED448 host keys are supported
97 and are expected to be found in files named ssh_host_rsa_key,
98 ssh_host_dsa_key, ssh_host_ecdsa_key, ssh_host_ed25519_key and
99 ssh_host_ed448_key.
100
101 See ssh_file for details.
102
104 The ssh application uses the default OTP error logger to log unexpected
105 errors or print information about special events.
106
108 The supported SSH version is 2.0.
109
111 The actual set of algorithms may vary depending on which OpenSSL crypto
112 library that is installed on the machine. For the list on a particular
113 installation, use the command ssh:default_algorithms/0. The user may
114 override the default algorithm configuration both on the server side
115 and the client side. See the options preferred_algorithms and mod‐
116 ify_algorithms in the ssh:daemon/1,2,3 and ssh:connect/3,4 functions.
117
118 Supported algorithms are (in the default order):
119
120 Key exchange algorithms:
121
122
123 * ecdh-sha2-nistp384
124
125 * ecdh-sha2-nistp521
126
127 * ecdh-sha2-nistp256
128
129 * diffie-hellman-group-exchange-sha256
130
131 * diffie-hellman-group16-sha512
132
133 * diffie-hellman-group18-sha512
134
135 * diffie-hellman-group14-sha256
136
137 * curve25519-sha256
138
139 * curve25519-sha256@libssh.org
140
141 * curve448-sha512
142
143 The following unsecure SHA1 algorithms are now disabled by default:
144
145 * (diffie-hellman-group14-sha1)
146
147 * (diffie-hellman-group-exchange-sha1)
148
149 * (diffie-hellman-group1-sha1)
150
151 They can be enabled with the preferred_algorithms or modify_algo‐
152 rithms options. Use for example the Option value {modify_algo‐
153 rithms, [{append, [{kex,['diffie-hellman-group1-sha1']}]}]})
154
155 Public key algorithms:
156
157
158 * ecdsa-sha2-nistp384
159
160 * ecdsa-sha2-nistp521
161
162 * ecdsa-sha2-nistp256
163
164 * ssh-ed25519
165
166 * ssh-ed448
167
168 * rsa-sha2-256
169
170 * rsa-sha2-512
171
172 The following unsecure SHA1 algorithms are supported but disabled
173 by default:
174
175 * (ssh-dss)
176
177 * (ssh-rsa)
178
179 See Disabled public key algorithms can be enabled with the pre‐
180 ferred_algorithms or modify_algorithms options. See Example 9 in
181 Configuring algorithms in SSH for a description.
182
183 MAC algorithms:
184
185
186 * hmac-sha2-256-etm@openssh.com
187
188 * hmac-sha2-512-etm@openssh.com
189
190 * hmac-sha1-etm@openssh.com
191
192 * hmac-sha2-256
193
194 * hmac-sha2-512
195
196 * hmac-sha1
197
198 The following unsecure SHA1 algorithm is disabled by default:
199
200 * (hmac-sha1-96)
201
202 It can be enabled with the preferred_algorithms or modify_algo‐
203 rithms options. Use for example the Option value {modify_algo‐
204 rithms, [{append, [{mac,['hmac-sha1-96']}]}]})
205
206 Encryption algorithms (ciphers):
207
208
209 * chacha20-poly1305@openssh.com
210
211 * aes256-gcm@openssh.com
212
213 * aes256-ctr
214
215 * aes192-ctr
216
217 * aes128-gcm@openssh.com
218
219 * aes128-ctr
220
221 * aes256-cbc
222
223 * aes192-cbc
224
225 * aes128-cbc
226
227 * 3des-cbc
228
229 * (AEAD_AES_128_GCM, not enabled per default)
230
231 * (AEAD_AES_256_GCM, not enabled per default)
232
233 See the text at the description of the rfc 5647 further down for
234 more information regarding AEAD_AES_*_GCM.
235
236 Following the internet de-facto standard, the cipher and mac algo‐
237 rithm AEAD_AES_128_GCM is selected when the cipher
238 aes128-gcm@openssh.com is negotiated. The cipher and mac algorithm
239 AEAD_AES_256_GCM is selected when the cipher aes256-gcm@openssh.com
240 is negotiated.
241
242 Compression algorithms:
243
244
245 * none
246
247 * zlib@openssh.com
248
249 * zlib
250
252 Unicode filenames are supported if the emulator and the underlaying OS
253 support it. See section DESCRIPTION in the file manual page in Kernel
254 for information about this subject.
255
256 The shell and the cli both support unicode.
257
259 The following rfc:s are supported:
260
261 * RFC 4251, The Secure Shell (SSH) Protocol Architecture.
262
263 Except
264
265 * 9.4.6 Host-Based Authentication
266
267 * 9.5.2 Proxy Forwarding
268
269 * 9.5.3 X11 Forwarding
270
271 * RFC 4252, The Secure Shell (SSH) Authentication Protocol.
272
273 Except
274
275 * 9. Host-Based Authentication: "hostbased"
276
277 * RFC 4253, The Secure Shell (SSH) Transport Layer Protocol.
278
279 Except
280
281 * 8.1. diffie-hellman-group1-sha1
282
283 * 6.6. Public Key Algorithms
284
285 * ssh-dss
286
287 * ssh-rsa
288
289 They are disabled by default as they now are regarded insecure, but
290 they can be enabled with the preferred_algorithms or modify_algo‐
291 rithms options. See Example 8 (diffie-hellman-group1-sha1) and Ex‐
292 ample 9 (ssh-dss) in Configuring algorithms in SSH for descrip‐
293 tions.
294
295 * RFC 4254, The Secure Shell (SSH) Connection Protocol.
296
297 Except
298
299 * 6.3. X11 Forwarding
300
301 * 7. TCP/IP Port Forwarding
302
303 * RFC 4256, Generic Message Exchange Authentication for the Secure
304 Shell Protocol (SSH).
305
306 Except
307
308 * num-prompts > 1
309
310 * password changing
311
312 * other identification methods than userid-password
313
314 * RFC 4419, Diffie-Hellman Group Exchange for the Secure Shell (SSH)
315 Transport Layer Protocol.
316
317 Except
318
319 * 4.1. diffie-hellman-group-exchange-sha1
320
321 It is disabled by defaultas as it now is regarded insecure, but it
322 can be enabled with the preferred_algorithms or modify_algorithms
323 options.
324
325 * RFC 4716, The Secure Shell (SSH) Public Key File Format.
326
327 * RFC 5647, AES Galois Counter Mode for the Secure Shell Transport
328 Layer Protocol.
329
330 There is an ambiguity in the synchronized selection of cipher and
331 mac algorithm. This is resolved by OpenSSH in the ciphers
332 aes128-gcm@openssh.com and aes256-gcm@openssh.com which are imple‐
333 mented. If the explicit ciphers and macs AEAD_AES_128_GCM or
334 AEAD_AES_256_GCM are needed, they could be enabled with the options
335 preferred_algorithms or modify_algorithms.
336
337 Warning:
338 If the client or the server is not Erlang/OTP, it is the users re‐
339 sponsibility to check that other implementation has the same inter‐
340 pretation of AEAD_AES_*_GCM as the Erlang/OTP SSH before enabling
341 them. The aes*-gcm@openssh.com variants are always safe to use since
342 they lack the ambiguity.
343
344
345 The second paragraph in section 5.1 is resolved as:
346
347 * If the negotiated cipher is AEAD_AES_128_GCM, the mac algorithm
348 is set to AEAD_AES_128_GCM.
349
350 * If the negotiated cipher is AEAD_AES_256_GCM, the mac algorithm
351 is set to AEAD_AES_256_GCM.
352
353 * If the mac algorithm is AEAD_AES_128_GCM, the cipher is set to
354 AEAD_AES_128_GCM.
355
356 * If the mac algorithm is AEAD_AES_256_GCM, the cipher is set to
357 AEAD_AES_256_GCM.
358
359 The first rule that matches when read in order from the top is ap‐
360 plied
361
362 * RFC 5656, Elliptic Curve Algorithm Integration in the Secure Shell
363 Transport Layer.
364
365 Except
366
367 * 5. ECMQV Key Exchange
368
369 * 6.4. ECMQV Key Exchange and Verification Method Name
370
371 * 7.2. ECMQV Message Numbers
372
373 * 10.2. Recommended Curves
374
375 * RFC 6668, SHA-2 Data Integrity Verification for the Secure Shell
376 (SSH) Transport Layer Protocol
377
378 Comment: Defines hmac-sha2-256 and hmac-sha2-512
379
380 * Draft-ietf-curdle-ssh-kex-sha2 (work in progress), Key Exchange
381 (KEX) Method Updates and Recommendations for Secure Shell (SSH).
382
383 Deviations:
384
385 * diffie-hellman-group1-sha1
386
387 * diffie-hellman-group-exchange-sha1
388
389 * diffie-hellman-group14-sha1
390
391 are not enabled by default as they now are regarded insecure, but
392 are still supported and can be enabled with the options pre‐
393 ferred_algorithms or modify_algorithms.
394
395 * RFC 8332, Use of RSA Keys with SHA-256 and SHA-512 in the Secure
396 Shell (SSH) Protocol.
397
398 * RFC 8308, Extension Negotiation in the Secure Shell (SSH) Protocol.
399
400 Implemented are:
401
402 * The Extension Negotiation Mechanism
403
404 * The extension server-sig-algs
405
406 * Secure Shell (SSH) Key Exchange Method Using Curve25519 and
407 Curve448
408
409 * RFC 8709 Ed25519 and Ed448 public key algorithms for the Secure
410 Shell (SSH) protocol
411
413 application(3)
414
415
416
417Ericsson AB ssh 4.13.2.1 SSH(7)