SSH(6) - f39

1SSH(7)                   Erlang Application Definition                  SSH(7)
2
3
4

NAME

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

DESCRIPTION

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

DEPENDENCIES

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

CONFIGURATION

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

PUBLIC KEYS

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

KNOWN HOSTS

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

AUTHORIZED KEYS

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

HOST KEYS

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

ERROR LOGGER AND EVENT HANDLERS

104       The ssh application uses the default OTP error logger to log unexpected
105       errors or print information about special events.
106

SUPPORTED SPECIFICATIONS AND STANDARDS

108       The supported SSH version is 2.0.
109

ALGORITHMS

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

UNICODE SUPPORT

252       Unicode filenames are supported if the emulator and the  underlying  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

RFCS

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