Search documentation of ssh

# Configuration in SSH

Copy Markdown View Source

The OTP SSH application can be configured by a large number 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.

Options for hardening are described in the Hardening SSH chapter. How the options for algorithm configuration interact are described in the Configuring algorithms in SSH chapter.

## Setting Options

There are two ways to set an option:

- In the `Options` parameter in the Erlang code in a call to for example `ssh:daemon/3` or `ssh:connect/3` or any of their variants. Example:

      ssh:connect(22, [{user,"foo"}])

- In OTP Configuration Parameters:

  - In the erl command line:

        erl -ssh user \"foo\"

  - In the `ssh.app` file, in the `env` part

        {application, ssh,
         [{description, "SSH-2 for Erlang/OTP"},
          {vsn, "4.9"},
          {modules, [ssh,
                ...
                ssh_xfer]},
          {registered, []},
          {applications, [kernel, stdlib, crypto, public_key]},
          {env, [{user, "bar"}]}, % <<<<<<<<<<<<<<<<<<<<<<<<<<<<<< HERE
          {mod, {ssh_app, []}},
               ...

  - In a .config file:

        erl -config ex1

    where `ex1.config` contains:

        [{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`.

## Precedence

If an option is set in more than one way, what happens?

There is an ordering, which is:

- Level 0: Hard-coded default values in the OTP SSH source code
- Level 1: OTP Configuration Parameters
- Level 2: Options in the OTP Configuration Parameters `server_options` or `client_options`
- Level 3: Options in argument list to a function

If the same option is set at two different levels, the one at the highest level is used.

#### Note

The only exception is the modify_algorithms common option. They are all applied in ascending level order on the set of algorithms. So a `modify_algorithms` on level one is applied before one of level two 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 applying all modify_algorithms in level order, 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. This can be used to interoperate with legacy systems that still uses algorithms no longer considered secure enough to be supported by default.

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

### Algorithms Before and After ssh:start/0

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` delivers 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 29 [erts-16.3.1] [source] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:1] [jit:ns]

    Eshell V16.3.1 (press Ctrl+G to abort, type help(). for help)
    1> ssh:default_algorithms().
    [{kex,['mlkem768x25519-sha256','curve25519-sha256',
           'curve25519-sha256@libssh.org','curve448-sha512',
           'ecdh-sha2-nistp521','ecdh-sha2-nistp384',
           'ecdh-sha2-nistp256',
           'diffie-hellman-group-exchange-sha256',
           'diffie-hellman-group16-sha512',
           'diffie-hellman-group18-sha512',
           'diffie-hellman-group14-sha256']},
     {public_key,['ssh-ed25519','ssh-ed448','ecdsa-sha2-nistp521',
                  'ecdsa-sha2-nistp384','ecdsa-sha2-nistp256',
                  'rsa-sha2-512','rsa-sha2-256']},
     {cipher,[{client2server,['aes256-gcm@openssh.com','aes256-ctr',
                              'aes192-ctr','aes128-gcm@openssh.com',
                              'aes128-ctr',
                              'chacha20-poly1305@openssh.com']},
              {server2client,['aes256-gcm@openssh.com','aes256-ctr',
                              'aes192-ctr','aes128-gcm@openssh.com',
                              'aes128-ctr',
                              'chacha20-poly1305@openssh.com']}]},
     {mac,[{client2server,['hmac-sha2-512-etm@openssh.com',
                           'hmac-sha2-256-etm@openssh.com',
                           'hmac-sha2-512','hmac-sha2-256',
                           'hmac-sha1-etm@openssh.com','hmac-sha1']},
           {server2client,['hmac-sha2-512-etm@openssh.com',
                           'hmac-sha2-256-etm@openssh.com',
                           'hmac-sha2-512','hmac-sha2-256',
                           'hmac-sha1-etm@openssh.com','hmac-sha1']}]},
     {compression,[{client2server,[none,'zlib@openssh.com']},
                   {server2client,[none,'zlib@openssh.com']}]}]

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']},
                   {server2client,[none,'zlib@openssh.com']}]}]
    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.

### Options in ssh:connect and ssh:daemon

Both when the client establishes 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 algorithms 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: modify_algorithms Across Levels

We will now 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()).
    ['ssh-ed25519','ssh-ed448','ecdsa-sha2-nistp521',
     'ecdsa-sha2-nistp384','ecdsa-sha2-nistp256',
     'rsa-sha2-512','rsa-sha2-256']
    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 full list of public key algorithms was `['ssh-dss','ecdsa-sha2-nistp256']`. Normally it is safer to append a non-default algorithm.

← Previous Page Terminology
Next Page → Configuring algorithms in SSH