4 Configuration in SSH
4.1 Introduction
The OTP SSH app can be configurated by a large amount of Options. This chapter will not go into details of what each of the options does. It will however describe and define different ways by which they could be entered.
4.2 Options configuration
The most familiar way is probably by writting options in a call to for example ssh:daemon/3 or ssh:connect/3 or any of their variants
There are from OPT-23.0 three main ways to set an option:
- In the Options parameter in the Erlang code
by writting options in a call to for example
ssh:daemon/3 or
ssh:connect/3 or
any of their variants. Example:
ssh:connect(22, [{user,"foo"}]) - On the erl command line. Example:
erl -ssh user \"foo\"
- In a .config file. Example:
where ex1.config contains:
erl -config ex1
[ {ssh, [{user, "foo"}]} ].If the option is intended only for a server or for a client, it may be set in this way:
[ {ssh, [{server_options,[{user, "foo"}]}, {client_options,[{user, "bar"}]} ].A server (daemon) will use the user name foo, and a client will use the name bar.
4.3 Precedens
So if an option is set in more than one way, what happens?
There is an ordering, which is:
- Level 0: Hard-coded default value
- Level 1: Separate env-options
- Level 2: Env-options in server_options or client_options
- Level 3: Option in argument list to a function
If the same option is set at two different levels, the one at the highest level is used.
The only exception is the modify_algorithms common option. They are all applied in ascending levle order on the set of algorithms. So a modify_algorithms on level zero is applied before one of level one and so on.
If there is an preferred_algorithms option on some level the whole set is replaced by that in that option and all modify_algorithms are applied in level ordering. The reason for this, is to enable the user to add an algorithm that has been removed from the default set without code changes, only by adding an option in a config file. Such happens when algorithms are no longer considered safe and removed from the SSH default set.
Algorithm configuration
There is a separate chapter about how preferred_algorithms and modify_algorithms co-operate. How the different configuration levels affect them, is described here in this section.
The ssh:start/0 function
If the application SSH is not started, the command ssh:default_algorithms/0 delivers the list of default (hardcoded) algorithms with respect to the support in the current cryptolib.
If the application SSH is started, the command ssh:default_algorithms/0 delvers the list of algorithms after application of level 0 and level 1 configurations.
Here is an example. The config-file has the following contents:
$ cat ex2.config
[
{ssh, [{preferred_algorithms, [{cipher, ['aes192-ctr']},
{public_key, ['ssh-rsa']},
{kex, ['ecdh-sha2-nistp384']},
{mac, ['hmac-sha1']}]}]}
].Erlang is started with ex2.config as configuration and we check the default set of algorithms before starting ssh:
$ erl -config ex2
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]
Eshell V10.6.4 (abort with ^G)
1> ssh:default_algorithms().
[{kex,['ecdh-sha2-nistp384','ecdh-sha2-nistp521',
'ecdh-sha2-nistp256','diffie-hellman-group-exchange-sha256',
'diffie-hellman-group16-sha512',
'diffie-hellman-group18-sha512',
'diffie-hellman-group14-sha256','curve25519-sha256',
'curve25519-sha256@libssh.org','curve448-sha512',
'diffie-hellman-group14-sha1',
'diffie-hellman-group-exchange-sha1']},
{public_key,['ecdsa-sha2-nistp384','ecdsa-sha2-nistp521',
'ecdsa-sha2-nistp256','ssh-ed25519','ssh-ed448','ssh-rsa',
'rsa-sha2-256','rsa-sha2-512','ssh-dss']},
{cipher,[{client2server,['chacha20-poly1305@openssh.com',
'aes256-gcm@openssh.com','aes256-ctr','aes192-ctr',
'aes128-gcm@openssh.com','aes128-ctr','aes256-cbc',
'aes192-cbc','aes128-cbc','3des-cbc']},
{server2client,['chacha20-poly1305@openssh.com',
'aes256-gcm@openssh.com','aes256-ctr','aes192-ctr',
'aes128-gcm@openssh.com','aes128-ctr','aes256-cbc',
'aes192-cbc','aes128-cbc','3des-cbc']}]},
{mac,[{client2server,['hmac-sha2-256','hmac-sha2-512',
'hmac-sha1']},
{server2client,['hmac-sha2-256','hmac-sha2-512',
'hmac-sha1']}]},
{compression,[{client2server,[none,'zlib@openssh.com',zlib]},
{server2client,[none,'zlib@openssh.com',zlib]}]}]Note that the algorithms in the file ex2.config is not yet applied. They will be when we start ssh:
2> ssh:start().
ok
3> ssh:default_algorithms().
[{kex,['ecdh-sha2-nistp384']},
{public_key,['ssh-rsa']},
{cipher,[{client2server,['aes192-ctr']},
{server2client,['aes192-ctr']}]},
{mac,[{client2server,['hmac-sha1']},
{server2client,['hmac-sha1']}]},
{compression,[{client2server,[none,'zlib@openssh.com',zlib]},
{server2client,[none,'zlib@openssh.com',zlib]}]}]
4> We see that the algorithm set is changed to the one in the ex2.config. Since compression is not specified in the file, the hard-coded default is still used for that entry.
Establishing a connection (ssh:connect et al) or starting a daemon (ssh:daemon)
Both when the client establish a connection with ssh:connect or other functions, or a daemon is started with ssh:daemon, the option lists in the function calls are also used.
If a client is started (ssh:connect et al), the environment variable client_options is used. Similarly for a daemon the server_options variable is handled.
If any preferred_algorithms is present, the one with the highest level is used, that is, the Option list parameter has the highest priority. Then the modify_algorithms on all levels in order starting with level 0 are applied.
We continue the example above by connecting to a server and modifying the kex algorithm set. We remove the only one ('ecdh-sha2-nistp384') and add 'curve25519-sha256@libssh.org' by appending it to the now empty list:
4> {ok,C} = ssh:connect(loopback, 22,
[{modify_algorithms,
[{rm,
[ {kex,['ecdh-sha2-nistp384']} ]
},
{append,
[ {kex,['curve25519-sha256@libssh.org']} ]
}
]
}
]).
{ok,>0.118.0>}We check which algoritms are negotiated by the client and the server, and note that the (only) kex algorithm 'curve25519-sha256@libssh.org' was selected:
5> ssh:connection_info(C, algorithms).
{algorithms,[{kex,'curve25519-sha256@libssh.org'},
{hkey,'ssh-rsa'},
{send_mac,'hmac-sha1'},
{recv_mac,'hmac-sha1'},
{encrypt,'aes192-ctr'},
{decrypt,'aes192-ctr'},
{compress,none},
{decompress,none},
{send_ext_info,false},
{recv_ext_info,true}]}Example of modify_algorithms handling
We will no check if the modify_algorithms on a lower level is applied to a preferred_algorithms on a higher level. We will do that by enabling the ssh-dss algorithm that is supported, but not in the default set.
The config file ex3.config has the contents:
[
{ssh, [{modify_algorithms,
[ {prepend, [{public_key, ['ssh-dss']}]} ]
}]}
].A newly started erlang shell shows that no 'ssh-dss' is present in the public_key entry:
1> proplists:get_value(public_key, ssh:default_algorithms()). ['ecdsa-sha2-nistp384','ecdsa-sha2-nistp521', 'ecdsa-sha2-nistp256','ssh-ed25519','ssh-ed448', 'rsa-sha2-256','rsa-sha2-512','ssh-rsa'] 2>
A call to ssh:connect/3 removes all algorithms but one of each type:
2> ssh:start().
ok
3> {ok,C} = ssh:connect(loopback, 22,
[{preferred_algorithms,
[{public_key, ['ecdsa-sha2-nistp256']},
{kex, ['ecdh-sha2-nistp256']},
{cipher, ['chacha20-poly1305@openssh.com']},
{mac, ['hmac-sha2-256']},
{compression, [none]}
]}
]).
{ok,<0.101.0>}
4> ssh:connection_info(C,algorithms).
{algorithms,[{kex,'ecdh-sha2-nistp256'},
{hkey,'ssh-dss'},
{send_mac,'chacha20-poly1305@openssh.com'},
{recv_mac,'chacha20-poly1305@openssh.com'},
{encrypt,'chacha20-poly1305@openssh.com'},
{decrypt,'chacha20-poly1305@openssh.com'},
{compress,none},
{decompress,none},
{send_ext_info,false},
{recv_ext_info,true}]}
5>But 'ssh-dss' is selected although the call inserted only 'ecdsa-sha2-nistp256' as acceptable.
This example showed that we could augment the set of algorithms with a config-file without the need to change the actual call.
For demonstration purposes we used prepend instead of append. This forces the negotiation to select ssh-dss since the the full list of public key algorithms was ['ssh-dss','ecdsa-sha2-nistp256']. Normally it is safer to append a non-default algorithm.