ssh(6) - f29

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

PUBLIC KEYS

55       id_dsa,  id_rsa  and  id_ecdsa  are the users private key files. Notice
56       that the public key is part of the private key so the  ssh  application
57       does not use the id_<*>.pub files. These are for the user's convenience
58       when it is needed to convey the user's public key.
59

KNOWN HOSTS

61       The known_hosts file contains a list of approved servers and their pub‐
62       lic  keys.  Once  a  server  is listed, it can be verified without user
63       interaction.
64

AUTHORIZED KEYS

66       The authorized_key file keeps track of  the  user's  authorized  public
67       keys.  The  most common use of this file is to let users log in without
68       entering their password, which is supported by the Erlang ssh daemon.
69

HOST KEYS

71       RSA, DSA and ECDSA host keys are supported and are expected to be found
72       in     files     named     ssh_host_rsa_key,    ssh_host_dsa_key    and
73       ssh_host_ecdsa_key.
74

ERROR LOGGER AND EVENT HANDLERS

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

SUPPORTED SPECIFICATIONS AND STANDARDS

80       The supported SSH version is 2.0.
81

ALGORITHMS

83       The actual set of algorithms may vary depending on which OpenSSL crypto
84       library that is installed on the machine. For the list on a  particular
85       installation,  use  the  command ssh:default_algorithms/0. The user may
86       override the default algorithm configuration both on  the  server  side
87       and  the  client  side.  See  the  option  preferred_algorithms  in the
88       ssh:daemon/1,2,3 and ssh:connect/3,4 functions.
89
90       Supported algorithms are:
91
92         Key exchange algorithms:
93
94
95           * ecdh-sha2-nistp256
96
97           * ecdh-sha2-nistp384
98
99           * ecdh-sha2-nistp521
100
101           * diffie-hellman-group-exchange-sha1
102
103           * diffie-hellman-group-exchange-sha256
104
105           * diffie-hellman-group14-sha1
106
107           * diffie-hellman-group14-sha256
108
109           * diffie-hellman-group16-sha512
110
111           * diffie-hellman-group18-sha512
112
113           * (diffie-hellman-group1-sha1, retired: can  be  enabled  with  the
114             preferred_algorithms option)
115
116         Public key algorithms:
117
118
119           * ecdsa-sha2-nistp256
120
121           * ecdsa-sha2-nistp384
122
123           * ecdsa-sha2-nistp521
124
125           * ssh-rsa
126
127           * ssh-dss
128
129           * rsa-sha2-256
130
131           * rsa-sha2-512
132
133         MAC algorithms:
134
135
136           * hmac-sha2-256
137
138           * hmac-sha2-512
139
140           * hmac-sha1
141
142         Encryption algorithms (ciphers):
143
144
145           * aes128-gcm@openssh.com
146
147           * aes256-gcm@openssh.com
148
149           * aes128-ctr
150
151           * aes192-ctr
152
153           * aes256-ctr
154
155           * aes128-cbc
156
157           * 3des-cbc
158
159           * (AEAD_AES_128_GCM, not enabled per default)
160
161           * (AEAD_AES_256_GCM, not enabled per default)
162
163           See  the  text  at the description of the rfc 5647 further down for
164           more information regarding AEAD_AES_*_GCM.
165
166           Following the internet de-facto standard, the cipher and mac  algo‐
167           rithm    AEAD_AES_128_GCM    is    selected    when    the   cipher
168           aes128-gcm@openssh.com is negotiated. The cipher and mac  algorithm
169           AEAD_AES_256_GCM is selected when the cipher aes256-gcm@openssh.com
170           is negotiated.
171
172         Compression algorithms:
173
174
175           * none
176
177           * zlib@openssh.com
178
179           * zlib
180

UNICODE SUPPORT

182       Unicode filenames are supported if the emulator and the underlaying  OS
183       support  it.  See section DESCRIPTION in the file manual page in Kernel
184       for information about this subject.
185
186       The shell and the cli both support unicode.
187

RFCS

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