SSH(6) - f34

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           * ssh-rsa (SHA1 sign/verify are supported but disabled  by  default
173             from OTP-24)
174
175           The  following unsecure SHA1 algorithm is supported but disabled by
176           default:
177
178           * (ssh-dss)
179
180           See Disabled public key algorithms can be  enabled  with  the  pre‐
181           ferred_algorithms  or  modify_algorithms  options. See Example 9 in
182           Configuring algorithms in SSH for a description.
183
184         MAC algorithms:
185
186
187           * hmac-sha2-256-etm@openssh.com
188
189           * hmac-sha2-512-etm@openssh.com
190
191           * hmac-sha1-etm@openssh.com
192
193           * hmac-sha2-256
194
195           * hmac-sha2-512
196
197           * hmac-sha1
198
199           The following unsecure SHA1 algorithm is disabled by default:
200
201           * (hmac-sha1-96)
202
203           It can be enabled with  the  preferred_algorithms  or  modify_algo‐
204           rithms  options.  Use  for  example  the Option value {modify_algo‐
205           rithms, [{append, [{mac,['hmac-sha1-96']}]}]})
206
207         Encryption algorithms (ciphers):
208
209
210           * chacha20-poly1305@openssh.com
211
212           * aes256-gcm@openssh.com
213
214           * aes256-ctr
215
216           * aes192-ctr
217
218           * aes128-gcm@openssh.com
219
220           * aes128-ctr
221
222           * aes256-cbc
223
224           * aes192-cbc
225
226           * aes128-cbc
227
228           * 3des-cbc
229
230           * (AEAD_AES_128_GCM, not enabled per default)
231
232           * (AEAD_AES_256_GCM, not enabled per default)
233
234           See the text at the description of the rfc 5647  further  down  for
235           more information regarding AEAD_AES_*_GCM.
236
237           Following  the internet de-facto standard, the cipher and mac algo‐
238           rithm   AEAD_AES_128_GCM    is    selected    when    the    cipher
239           aes128-gcm@openssh.com  is negotiated. The cipher and mac algorithm
240           AEAD_AES_256_GCM is selected when the cipher aes256-gcm@openssh.com
241           is negotiated.
242
243         Compression algorithms:
244
245
246           * none
247
248           * zlib@openssh.com
249
250           * zlib
251

UNICODE SUPPORT

253       Unicode  filenames are supported if the emulator and the underlaying OS
254       support it. See section DESCRIPTION in the file manual page  in  Kernel
255       for information about this subject.
256
257       The shell and the cli both support unicode.
258

RFCS

260       The following rfc:s are supported:
261
262         * RFC 4251, The Secure Shell (SSH) Protocol Architecture.
263
264           Except
265
266           * 9.4.6 Host-Based Authentication
267
268           * 9.5.2 Proxy Forwarding
269
270           * 9.5.3 X11 Forwarding
271
272         * RFC 4252, The Secure Shell (SSH) Authentication Protocol.
273
274           Except
275
276           * 9. Host-Based Authentication: "hostbased"
277
278         * RFC 4253, The Secure Shell (SSH) Transport Layer Protocol.
279
280           Except
281
282           * 8.1. diffie-hellman-group1-sha1
283
284           * 6.6. Public Key Algorithms
285
286             * ssh-dss
287
288           They are disabled by default as they now are regarded insecure, but
289           they can be enabled with the preferred_algorithms  or  modify_algo‐
290           rithms  options. See Example 8 (diffie-hellman-group1-sha1) and Ex‐
291           ample 9 (ssh-dss) in Configuring algorithms  in  SSH  for  descrip‐
292           tions.
293
294         * RFC 4254, The Secure Shell (SSH) Connection Protocol.
295
296           Except
297
298           * 6.3. X11 Forwarding
299
300           * 7. TCP/IP Port Forwarding
301
302         * RFC  4256,  Generic  Message Exchange Authentication for the Secure
303           Shell Protocol (SSH).
304
305           Except
306
307           * num-prompts > 1
308
309           * password changing
310
311           * other identification methods than userid-password
312
313         * RFC 4419, Diffie-Hellman Group Exchange for the Secure Shell  (SSH)
314           Transport Layer Protocol.
315
316           Except
317
318           * 4.1. diffie-hellman-group-exchange-sha1
319
320           It  is disabled by defaultas as it now is regarded insecure, but it
321           can be enabled with the preferred_algorithms  or  modify_algorithms
322           options.
323
324         * RFC 4716, The Secure Shell (SSH) Public Key File Format.
325
326         * RFC  5647,  AES  Galois Counter Mode for the Secure Shell Transport
327           Layer Protocol.
328
329           There is an ambiguity in the synchronized selection of  cipher  and
330           mac   algorithm.  This  is  resolved  by  OpenSSH  in  the  ciphers
331           aes128-gcm@openssh.com and aes256-gcm@openssh.com which are  imple‐
332           mented.  If  the  explicit  ciphers  and  macs  AEAD_AES_128_GCM or
333           AEAD_AES_256_GCM are needed, they could be enabled with the options
334           preferred_algorithms or modify_algorithms.
335
336     Warning:
337         If  the  client  or the server is not Erlang/OTP, it is the users re‐
338         sponsibility to check that other implementation has the  same  inter‐
339         pretation  of  AEAD_AES_*_GCM  as  the Erlang/OTP SSH before enabling
340         them. The aes*-gcm@openssh.com variants are always safe to use  since
341         they lack the ambiguity.
342
343
344           The second paragraph in section 5.1 is resolved as:
345
346           * If  the  negotiated cipher is AEAD_AES_128_GCM, the mac algorithm
347             is set to AEAD_AES_128_GCM.
348
349           * If the negotiated cipher is AEAD_AES_256_GCM, the  mac  algorithm
350             is set to AEAD_AES_256_GCM.
351
352           * If  the  mac  algorithm is AEAD_AES_128_GCM, the cipher is set to
353             AEAD_AES_128_GCM.
354
355           * If the mac algorithm is AEAD_AES_256_GCM, the cipher  is  set  to
356             AEAD_AES_256_GCM.
357
358           The  first rule that matches when read in order from the top is ap‐
359           plied
360
361         * RFC 5656, Elliptic Curve Algorithm Integration in the Secure  Shell
362           Transport Layer.
363
364           Except
365
366           * 5. ECMQV Key Exchange
367
368           * 6.4. ECMQV Key Exchange and Verification Method Name
369
370           * 7.2. ECMQV Message Numbers
371
372           * 10.2. Recommended Curves
373
374         * RFC  6668,  SHA-2  Data Integrity Verification for the Secure Shell
375           (SSH) Transport Layer Protocol
376
377           Comment: Defines hmac-sha2-256 and hmac-sha2-512
378
379         * Draft-ietf-curdle-ssh-kex-sha2 (work  in  progress),  Key  Exchange
380           (KEX) Method Updates and Recommendations for Secure Shell (SSH).
381
382           Deviations:
383
384           * diffie-hellman-group1-sha1
385
386           * diffie-hellman-group-exchange-sha1
387
388           * diffie-hellman-group14-sha1
389
390           are  not  enabled by default as they now are regarded insecure, but
391           are still supported and  can  be  enabled  with  the  options  pre‐
392           ferred_algorithms or modify_algorithms.
393
394         * RFC  8332,  Use  of RSA Keys with SHA-256 and SHA-512 in the Secure
395           Shell (SSH) Protocol.
396
397         * RFC 8308, Extension Negotiation in the Secure Shell (SSH) Protocol.
398
399           Implemented are:
400
401           * The Extension Negotiation Mechanism
402
403           * The extension server-sig-algs
404
405         * Secure  Shell  (SSH)  Key  Exchange  Method  using  Curve25519  and
406           Curve448 (work in progress)
407
408         * RFC  8709  Ed25519  and  Ed448 public key algorithms for the Secure
409           Shell (SSH) protocol
410