Skip to content

Commit 686f9a9

Browse files
u3su3s
committed
ssh: update documentation guides for OTP 29
Fix stale algorithm examples, typos, and heading structure across all 7 SSH guide files. - Re-capture all default_algorithms outputs for OTP 29 (mlkem, curve25519, ed25519, etm MACs, chacha20) - Fix 11 typos/grammar errors in configure_algos.md - Add mlkem768x25519-sha256 to ssh_app.md algorithm list - Add PQC section to hardening.md - Restructure headings in configure_algos.md, configurations.md, hardening.md, terminology.md (remove ## Introduction wrappers, eliminate #### depth) - Convert plain-text notes to admonitions in using_ssh.md - Fix "Creating a Subsystem" example (byte_size, logger, ssh_cm) - Replace tabs with spaces in code blocks - Note disabled-by-default shell/exec/SFTP in terminology.md
1 parent 1f14220 commit 686f9a9

7 files changed

Lines changed: 484 additions & 469 deletions

File tree

‎lib/ssh/doc/guides/configurations.md‎

Lines changed: 67 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -21,21 +21,19 @@ limitations under the License.
2121
-->
2222
# Configuration in SSH
2323

24-
## Introduction
25-
26-
The OTP SSH app can be configurated by a large amount of _Options_. This chapter
24+
The OTP SSH app can be configured by a large number of _Options_. This chapter
2725
will not go into details of what each of the options does. It will however
2826
describe and define different ways by which they could be entered.
2927

3028
Options for hardening are described in the [Hardening SSH](hardening.md)
3129
chapter. How the options for algorithm configuration interact are described in
3230
the [Configuring algorithms in SSH](configure_algos.md) chapter.
3331

34-
## Options configuration
32+
## Setting options
3533

36-
There are from OTP-23.0 two main ways to set an option:
34+
There are two ways to set an option:
3735

38-
- Like before, in the `Options` parameter in the Erlang code in a call to for
36+
- In the `Options` parameter in the Erlang code in a call to for
3937
example `ssh:daemon/3` or `ssh:connect/3` or any of their variants. Example:
4038

4139
```erlang
@@ -58,10 +56,10 @@ There are from OTP-23.0 two main ways to set an option:
5856
{vsn, "4.9"},
5957
{modules, [ssh,
6058
...
61-
ssh_xfer]},
59+
ssh_xfer]},
6260
{registered, []},
6361
{applications, [kernel, stdlib, crypto, public_key]},
64-
{env, [{user, "bar"]}, % <<<<<<<<<<<<<<<<<<<<<<<<<<<<<< HERE
62+
{env, [{user, "bar"}]}, % <<<<<<<<<<<<<<<<<<<<<<<<<<<<<< HERE
6563
{mod, {ssh_app, []}},
6664
...
6765
```
@@ -75,19 +73,15 @@ There are from OTP-23.0 two main ways to set an option:
7573
where `ex1.config` contains:
7674
7775
```erlang
78-
[
79-
{ssh, [{user, "foo"}]}
80-
].
76+
[{ssh, [{user, "foo"}]}].
8177
```
8278
8379
If the option is intended only for a server or for a client, it may be set in
8480
this way:
8581
8682
```erlang
87-
[
88-
{ssh, [{server_options,[{user, "foo"}]},
89-
{client_options,[{user, "bar"}]}
90-
].
83+
[{ssh, [{server_options, [{user, "foo"}]},
84+
{client_options, [{user, "bar"}]}]}].
9185
```
9286

9387
A server (daemon) will use the user name `foo`, and a client will use the name
@@ -108,10 +102,12 @@ There is an ordering, which is:
108102
If the same option is set at two different levels, the one at the highest level
109103
is used.
110104

111-
The only exception is the
112-
[modify_algorithms](`t:ssh:modify_algorithms_common_option/0`) common option.
113-
They are all applied in ascending level order on the set of algorithms. So a
114-
`modify_algorithms` on level one is applied before one of level two and so on.
105+
> #### Note {: .info }
106+
>
107+
> The only exception is the
108+
> [modify_algorithms](`t:ssh:modify_algorithms_common_option/0`) common option.
109+
> They are all applied in ascending level order on the set of algorithms. So a
110+
> `modify_algorithms` on level one is applied before one of level two and so on.
115111
116112
If there is an
117113
[preferred_algorithms](`t:ssh:preferred_algorithms_common_option/0`) option on
@@ -125,68 +121,70 @@ set without code changes, only by adding an option in a config file. This can be
125121
used to interoperate with legacy systems that still uses algorithms no longer
126122
considered secure enough to be supported by default.
127123

128-
### Algorithm configuration
124+
## Algorithm configuration
129125

130-
There is a [separate chapter](configure_algos.md#introduction) about how
126+
There is a [separate chapter](configure_algos.md) about how
131127
[preferred_algorithms](`t:ssh:preferred_algorithms_common_option/0`) and
132128
[modify_algorithms](`t:ssh:modify_algorithms_common_option/0`) co-operate. How
133129
the different configuration levels affect them, is described here in this
134130
section.
135131

136-
#### The ssh:start/0 function
132+
### Algorithms before and after ssh:start/0
137133

138134
If the application SSH is _not_ [started](`ssh:start/0`), the command
139135
`ssh:default_algorithms/0` delivers the list of default (hardcoded) algorithms
140136
with respect to the support in the current cryptolib.
141137

142138
If the application SSH _is_ [started](`ssh:start/0`), the command
143-
`ssh:default_algorithms/0` delvers the list of algorithms after application of
139+
`ssh:default_algorithms/0` delivers the list of algorithms after application of
144140
level 0 and level 1 configurations.
145141

146142
Here is an example. The config-file has the following contents:
147143

148144
```text
149145
$ cat ex2.config
150-
[
151-
{ssh, [{preferred_algorithms, [{cipher, ['aes192-ctr']},
152-
{public_key, ['ssh-rsa']},
146+
[{ssh, [{preferred_algorithms, [{cipher, ['aes192-ctr']},
147+
{public_key, ['ssh-rsa']},
153148
{kex, ['ecdh-sha2-nistp384']},
154-
{mac, ['hmac-sha1']}]}]}
155-
].
149+
{mac, ['hmac-sha1']}]}]}].
156150
```
157151

158152
Erlang is started with `ex2.config` as configuration and we check the default
159153
set of algorithms before starting ssh:
160154

161155
```text
162156
$ erl -config ex2
163-
Erlang/OTP 23 [RELEASE CANDIDATE 1] [erts-10.6.4] [source-96a0823109] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:1] [hipe]
157+
Erlang/OTP 29 [erts-15.2.4] [source] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:1] [jit:ns]
164158
165-
Eshell V10.6.4 (abort with ^G)
159+
Eshell V15.2.4 (press Ctrl+G to abort, type help(). for help)
166160
1> ssh:default_algorithms().
167-
[{kex,['ecdh-sha2-nistp384','ecdh-sha2-nistp521',
168-
'ecdh-sha2-nistp256','diffie-hellman-group-exchange-sha256',
161+
[{kex,['mlkem768x25519-sha256','curve25519-sha256',
162+
'curve25519-sha256@libssh.org','curve448-sha512',
163+
'ecdh-sha2-nistp521','ecdh-sha2-nistp384',
164+
'ecdh-sha2-nistp256',
165+
'diffie-hellman-group-exchange-sha256',
169166
'diffie-hellman-group16-sha512',
170167
'diffie-hellman-group18-sha512',
171-
'diffie-hellman-group14-sha256','curve25519-sha256',
172-
'curve25519-sha256@libssh.org','curve448-sha512',
173-
'diffie-hellman-group14-sha1',
174-
'diffie-hellman-group-exchange-sha1']},
175-
{public_key,['ecdsa-sha2-nistp384','ecdsa-sha2-nistp521',
176-
'ecdsa-sha2-nistp256','ssh-ed25519','ssh-ed448','ssh-rsa',
177-
'rsa-sha2-256','rsa-sha2-512','ssh-dss']},
178-
{cipher,[{client2server,['chacha20-poly1305@openssh.com',
179-
'aes256-gcm@openssh.com','aes256-ctr','aes192-ctr',
180-
'aes128-gcm@openssh.com','aes128-ctr','aes256-cbc',
181-
'aes192-cbc','aes128-cbc','3des-cbc']},
182-
{server2client,['chacha20-poly1305@openssh.com',
183-
'aes256-gcm@openssh.com','aes256-ctr','aes192-ctr',
184-
'aes128-gcm@openssh.com','aes128-ctr','aes256-cbc',
185-
'aes192-cbc','aes128-cbc','3des-cbc']}]},
186-
{mac,[{client2server,['hmac-sha2-256','hmac-sha2-512',
187-
'hmac-sha1']},
188-
{server2client,['hmac-sha2-256','hmac-sha2-512',
189-
'hmac-sha1']}]},
168+
'diffie-hellman-group14-sha256']},
169+
{public_key,['ssh-ed25519','ssh-ed448','ecdsa-sha2-nistp521',
170+
'ecdsa-sha2-nistp384','ecdsa-sha2-nistp256',
171+
'rsa-sha2-512','rsa-sha2-256']},
172+
{cipher,[{client2server,['aes256-gcm@openssh.com','aes256-ctr',
173+
'aes192-ctr','aes128-gcm@openssh.com',
174+
'aes128-ctr',
175+
'chacha20-poly1305@openssh.com']},
176+
{server2client,['aes256-gcm@openssh.com','aes256-ctr',
177+
'aes192-ctr','aes128-gcm@openssh.com',
178+
'aes128-ctr',
179+
'chacha20-poly1305@openssh.com']}]},
180+
{mac,[{client2server,['hmac-sha2-512-etm@openssh.com',
181+
'hmac-sha2-256-etm@openssh.com',
182+
'hmac-sha2-512','hmac-sha2-256',
183+
'hmac-sha1-etm@openssh.com','hmac-sha1']},
184+
{server2client,['hmac-sha2-512-etm@openssh.com',
185+
'hmac-sha2-256-etm@openssh.com',
186+
'hmac-sha2-512','hmac-sha2-256',
187+
'hmac-sha1-etm@openssh.com','hmac-sha1']}]},
190188
{compression,[{client2server,[none,'zlib@openssh.com']},
191189
{server2client,[none,'zlib@openssh.com']}]}]
192190
```
@@ -213,7 +211,7 @@ We see that the algorithm set is changed to the one in the `ex2.config`. Since
213211
`compression` is not specified in the file, the hard-coded default is still used
214212
for that entry.
215213

216-
#### Establishing a connection (ssh:connect et al) or starting a daemon (ssh:daemon)
214+
### Options in ssh:connect and ssh:daemon
217215

218216
Both when the client establishes a connection with ssh:connect or other
219217
functions, or a daemon is started with ssh:daemon, the option lists in the
@@ -235,17 +233,10 @@ algorithm set. We remove the only one (`'ecdh-sha2-nistp384'`) and add
235233

236234
```erlang
237235
4> {ok,C} = ssh:connect(loopback, 22,
238-
[{modify_algorithms,
239-
[{rm,
240-
[ {kex,['ecdh-sha2-nistp384']} ]
241-
},
242-
{append,
243-
[ {kex,['curve25519-sha256@libssh.org']} ]
244-
}
245-
]
246-
}
247-
]).
248-
{ok,>0.118.0>}
236+
[{modify_algorithms,
237+
[{rm, [{kex, ['ecdh-sha2-nistp384']}]},
238+
{append, [{kex, ['curve25519-sha256@libssh.org']}]}]}]).
239+
{ok,<0.118.0>}
249240
```
250241

251242
We check which algorithms are negotiated by the client and the server, and note
@@ -265,7 +256,7 @@ that the (only) `kex` algorithm `'curve25519-sha256@libssh.org'` was selected:
265256
{recv_ext_info,true}]}
266257
```
267258

268-
#### Example of modify_algorithms handling
259+
### Example: modify_algorithms across levels
269260

270261
We will now check if the
271262
[modify_algorithms](`t:ssh:modify_algorithms_common_option/0`) on a lower level
@@ -277,21 +268,18 @@ but not in the default set.
277268
The config file `ex3.config` has the contents:
278269

279270
```erlang
280-
[
281-
{ssh, [{modify_algorithms,
282-
[ {prepend, [{public_key, ['ssh-dss']}]} ]
283-
}]}
284-
].
271+
[{ssh, [{modify_algorithms,
272+
[{prepend, [{public_key, ['ssh-dss']}]}]}]}].
285273
```
286274

287275
A newly started erlang shell shows that no `'ssh-dss'` is present in the
288276
`public_key` entry:
289277

290278
```erlang
291279
1> proplists:get_value(public_key, ssh:default_algorithms()).
292-
['ecdsa-sha2-nistp384','ecdsa-sha2-nistp521',
293-
'ecdsa-sha2-nistp256','ssh-ed25519','ssh-ed448',
294-
'rsa-sha2-256','rsa-sha2-512','ssh-rsa']
280+
['ssh-ed25519','ssh-ed448','ecdsa-sha2-nistp521',
281+
'ecdsa-sha2-nistp384','ecdsa-sha2-nistp256',
282+
'rsa-sha2-512','rsa-sha2-256']
295283
2>
296284
```
297285

@@ -301,14 +289,12 @@ A call to `ssh:connect/3` removes all algorithms but one of each type:
301289
2> ssh:start().
302290
ok
303291
3> {ok,C} = ssh:connect(loopback, 22,
304-
[{preferred_algorithms,
305-
[{public_key, ['ecdsa-sha2-nistp256']},
306-
{kex, ['ecdh-sha2-nistp256']},
307-
{cipher, ['chacha20-poly1305@openssh.com']},
308-
{mac, ['hmac-sha2-256']},
309-
{compression, [none]}
310-
]}
311-
]).
292+
[{preferred_algorithms,
293+
[{public_key, ['ecdsa-sha2-nistp256']},
294+
{kex, ['ecdh-sha2-nistp256']},
295+
{cipher, ['chacha20-poly1305@openssh.com']},
296+
{mac, ['hmac-sha2-256']},
297+
{compression, [none]}]}]).
312298
{ok,<0.101.0>}
313299
4> ssh:connection_info(C,algorithms).
314300
{algorithms,[{kex,'ecdh-sha2-nistp256'},
@@ -331,6 +317,6 @@ This example showed that we could augment the set of algorithms with a
331317
config-file without the need to change the actual call.
332318

333319
For demonstration purposes we used `prepend` instead of `append`. This forces
334-
the negotiation to select `ssh-dss` since the the full list of public key
320+
the negotiation to select `ssh-dss` since the full list of public key
335321
algorithms was `['ssh-dss','ecdsa-sha2-nistp256']`. Normally it is safer to
336322
append a non-default algorithm.

0 commit comments

Comments
 (0)