ssh(6) - f31

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. 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

CONFIGURATION

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
28         * known_hosts
29
30         * authorized_keys
31
32         * authorized_keys2
33
34         * id_dsa
35
36         * id_rsa
37
38         * id_ecdsa
39
40         * ssh_host_dsa_key
41
42         * ssh_host_rsa_key
43
44         * ssh_host_ecdsa_key
45
46       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
50       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
54       See also the default callback module documentation in ssh_file.
55

PUBLIC KEYS

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

KNOWN HOSTS

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

AUTHORIZED KEYS

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

HOST KEYS

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

ERROR LOGGER AND EVENT HANDLERS

78       The ssh application uses the default OTP error logger to log unexpected
79       errors or print information about special events.
80

SUPPORTED SPECIFICATIONS AND STANDARDS

82       The supported SSH version is 2.0.
83

ALGORITHMS

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
92       Supported algorithms are (in the default order):
93
94         Key exchange algorithms:
95
96
97           * ecdh-sha2-nistp384
98
99           * ecdh-sha2-nistp521
100
101           * ecdh-sha2-nistp256
102
103           * diffie-hellman-group-exchange-sha256
104
105           * diffie-hellman-group16-sha512
106
107           * diffie-hellman-group18-sha512
108
109           * diffie-hellman-group14-sha256
110
111           * curve25519-sha256
112
113           * curve25519-sha256@libssh.org
114
115           * curve448-sha512
116
117           * diffie-hellman-group14-sha1
118
119           * diffie-hellman-group-exchange-sha1
120
121           * (diffie-hellman-group1-sha1, retired: It can be enabled with  the
122             preferred_algorithms or modify_algorithms options)
123
124         Public key algorithms:
125
126
127           * ecdsa-sha2-nistp384
128
129           * ecdsa-sha2-nistp521
130
131           * ecdsa-sha2-nistp256
132
133           * ssh-ed25519
134
135           * ssh-ed448
136
137           * ssh-rsa
138
139           * rsa-sha2-256
140
141           * rsa-sha2-512
142
143           * ssh-dss
144
145         MAC algorithms:
146
147
148           * hmac-sha2-256
149
150           * hmac-sha2-512
151
152           * hmac-sha1
153
154         Encryption algorithms (ciphers):
155
156
157           * chacha20-poly1305@openssh.com
158
159           * aes256-gcm@openssh.com
160
161           * aes256-ctr
162
163           * aes192-ctr
164
165           * aes128-gcm@openssh.com
166
167           * aes128-ctr
168
169           * aes128-cbc
170
171           * 3des-cbc
172
173           * (AEAD_AES_128_GCM, not enabled per default)
174
175           * (AEAD_AES_256_GCM, not enabled per default)
176
177           See  the  text  at the description of the rfc 5647 further down for
178           more information regarding AEAD_AES_*_GCM.
179
180           Following the internet de-facto standard, the cipher and mac  algo‐
181           rithm    AEAD_AES_128_GCM    is    selected    when    the   cipher
182           aes128-gcm@openssh.com is negotiated. The cipher and mac  algorithm
183           AEAD_AES_256_GCM is selected when the cipher aes256-gcm@openssh.com
184           is negotiated.
185
186         Compression algorithms:
187
188
189           * none
190
191           * zlib@openssh.com
192
193           * zlib
194

UNICODE SUPPORT

196       Unicode filenames are supported if the emulator and the underlaying  OS
197       support  it.  See section DESCRIPTION in the file manual page in Kernel
198       for information about this subject.
199
200       The shell and the cli both support unicode.
201

RFCS

203       The following rfc:s are supported:
204
205         * RFC 4251, The Secure Shell (SSH) Protocol Architecture.
206
207           Except
208
209           * 9.4.6 Host-Based Authentication
210
211           * 9.5.2 Proxy Forwarding
212
213           * 9.5.3 X11 Forwarding
214
215         * RFC 4252, The Secure Shell (SSH) Authentication Protocol.
216
217           Except
218
219           * 9. Host-Based Authentication: "hostbased"
220
221         * RFC 4253, The Secure Shell (SSH) Transport Layer Protocol.
222
223           Except
224
225           * 8.1. diffie-hellman-group1-sha1.  Disabled  by  default,  can  be
226             enabled   with   the  preferred_algorithms  or  modify_algorithms
227             options.
228
229         * RFC 4254, The Secure Shell (SSH) Connection Protocol.
230
231           Except
232
233           * 6.3. X11 Forwarding
234
235           * 7. TCP/IP Port Forwarding
236
237         * RFC 4256, Generic Message Exchange Authentication  for  the  Secure
238           Shell Protocol (SSH).
239
240           Except
241
242           * num-prompts > 1
243
244           * password changing
245
246           * other identification methods than userid-password
247
248         * RFC  4419, Diffie-Hellman Group Exchange for the Secure Shell (SSH)
249           Transport Layer Protocol.
250
251         * RFC 4716, The Secure Shell (SSH) Public Key File Format.
252
253         * RFC 5647, AES Galois Counter Mode for the  Secure  Shell  Transport
254           Layer Protocol.
255
256           There  is  an ambiguity in the synchronized selection of cipher and
257           mac  algorithm.  This  is  resolved  by  OpenSSH  in  the   ciphers
258           aes128-gcm@openssh.com  and aes256-gcm@openssh.com which are imple‐
259           mented. If  the  explicit  ciphers  and  macs  AEAD_AES_128_GCM  or
260           AEAD_AES_256_GCM are needed, they could be enabled with the options
261           preferred_algorithms or modify_algorithms.
262
263     Warning:
264         If the client or the server  is  not  Erlang/OTP,  it  is  the  users
265         responsibility to check that other implementation has the same inter‐
266         pretation of AEAD_AES_*_GCM as the  Erlang/OTP  SSH  before  enabling
267         them.  The aes*-gcm@openssh.com variants are always safe to use since
268         they lack the ambiguity.
269
270
271           The second paragraph in section 5.1 is resolved as:
272
273           * If the negotiated cipher is AEAD_AES_128_GCM, the  mac  algorithm
274             is set to AEAD_AES_128_GCM.
275
276           * If  the  negotiated cipher is AEAD_AES_256_GCM, the mac algorithm
277             is set to AEAD_AES_256_GCM.
278
279           * If the mac algorithm is AEAD_AES_128_GCM, the cipher  is  set  to
280             AEAD_AES_128_GCM.
281
282           * If  the  mac  algorithm is AEAD_AES_256_GCM, the cipher is set to
283             AEAD_AES_256_GCM.
284
285           The first rule that matches when read in  order  from  the  top  is
286           applied
287
288         * RFC  5656, Elliptic Curve Algorithm Integration in the Secure Shell
289           Transport Layer.
290
291           Except
292
293           * 5. ECMQV Key Exchange
294
295           * 6.4. ECMQV Key Exchange and Verification Method Name
296
297           * 7.2. ECMQV Message Numbers
298
299           * 10.2. Recommended Curves
300
301         * RFC 6668, SHA-2 Data Integrity Verification for  the  Secure  Shell
302           (SSH) Transport Layer Protocol
303
304           Comment: Defines hmac-sha2-256 and hmac-sha2-512
305
306         * Draft-ietf-curdle-ssh-kex-sha2  (work  in  progress),  Key Exchange
307           (KEX) Method Updates and Recommendations for Secure Shell (SSH).
308
309           Deviations:
310
311           * The diffie-hellman-group1-sha1 is not enabled by default, but  is
312             still  supported  and  can  be  enabled  with  the  options  pre‐
313             ferred_algorithms or modify_algorithms.
314
315           * The  questionable  sha1-based  algorithms   diffie-hellman-group-
316             exchange-sha1  and  diffie-hellman-group14-sha1 are still enabled
317             by default for compatibility with ancient  clients  and  servers.
318             They  can  be  disabled  with the options preferred_algorithms or
319             modify_algorithms. They will be  disabled  by  default  when  the
320             draft is turned into an RFC.
321
322         * RFC  8332,  Use  of RSA Keys with SHA-256 and SHA-512 in the Secure
323           Shell (SSH) Protocol.
324
325         * RFC 8308, Extension Negotiation in the Secure Shell (SSH) Protocol.
326
327           Implemented are:
328
329           * The Extension Negotiation Mechanism
330
331           * The extension server-sig-algs
332
333         * Secure  Shell  (SSH)  Key  Exchange  Method  using  Curve25519  and
334           Curve448 (work in progress)
335
336         * Ed25519  and Ed448 public key algorithms for the Secure Shell (SSH)
337           protocol (work in progress)
338