From c657c2133913412f02442b2366c5580d0bc4beef Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Mon, 28 Aug 2017 15:32:08 +0200 Subject: ssh: Document the option modify_algorithms and a User's Guide chapter --- lib/ssh/doc/src/configure_algos.xml | 457 ++++++++++++++++++++++++++++++++++++ 1 file changed, 457 insertions(+) create mode 100644 lib/ssh/doc/src/configure_algos.xml (limited to 'lib/ssh/doc/src/configure_algos.xml') diff --git a/lib/ssh/doc/src/configure_algos.xml b/lib/ssh/doc/src/configure_algos.xml new file mode 100644 index 0000000000..ebd128c097 --- /dev/null +++ b/lib/ssh/doc/src/configure_algos.xml @@ -0,0 +1,457 @@ + + + + +
+ + 2017 + 2017 + Ericsson AB. All Rights Reserved. + + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + + + Configuring algorithms in SSH + + + + + + configure_algos.xml +
+ +
+ + Introduction +

To fully understand how to configure the algorithms, we must understand partly both how the ssh protocol + works and how the OTP SSH app handles the corresponding items

+ +

The first subsection will give a short background about the ssh protocol while later sections describes + the implementation and provides many examples

+ +
+ Basics of the ssh protocol's algorithms handling + +

SSH uses different sets of algorithms in different phases of a session. Which + algorithms to use is negotiated by the client and the server at the beginning of a session. + See RFC 4253, + "The Secure Shell (SSH) Transport Layer Protocol" for details. +

+ +

The negotiation is simple: both peers sends their list of supported alghorithms to the other part. + The first algorithm on the client's list that also in on the server's list is selected. So it is the + client's orderering of the list that gives the priority for the algorithms.

+ +

There are five lists exchanged in the connection setup. Three of them are also divided in two + directions, to and from the server.

+ +

The lists are (named as in the SSH application's options):

+ + kex + +

Key exchange.

+

An algorithm is selected for computing a secret encryption key. Among examples are: + the old nowadays week 'diffie-hellman-group-exchange-sha1' and the very strong and modern + 'ecdh-sha2-nistp512'.

+ + + public_key + +

Server host key

+

The asymetric encryption algorithm used in the server's private-public host key pair. + Examples include the well-known RSA 'ssh-rsa' and elliptic curve 'ecdsa-sha2-nistp521'. +

+ + + cipher + +

Symetric cipher algorithm used for the message encryption. This algorithm will use the key calculated + in the kex phase (together with other info) to genereate the actual key used. Examples are + tripple-DES '3des-cbc' and one of many AES variants 'aes192-ctr'. +

+

This list is actually two - one for each direction server-to-client and client-to-server. Therefore it + is possible but rare to have different algorithms in the two directions in one connection.

+ + + mac + +

Message authentication code

+

"Check sum" of each message sent between the peers. Examples are SHA 'hmac-sha1' and + SHA2 'hmac-sha2-512'.

+

This list is also divided into two for the both directions

+ + + compression + +

If and how to compress the message. Examples are none, that is, no compression and + zlib.

+

This list is also divided into two for the both directions

+ + + +
+ +
+ The SSH app's mechanism +

The set of algorithms that the SSH app uses by default depends on the algoritms supported by the:

+ +

crypto app,

+ +

The cryptolib OTP is linked with, usally the one the OS uses, probably OpenSSL,

+ +

and finaly what the SSH app implements

+ + +

Due to this, it impossible to list in documentation what algorithms that are available in a certain installation.

+

There is an important commands to list the actual algorithms and their ordering: + ssh:default_algorithms/0.

+ +0> 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', + 'diffie-hellman-group14-sha1', + 'diffie-hellman-group-exchange-sha1']}, + {public_key,['ecdsa-sha2-nistp384','ecdsa-sha2-nistp521', + 'ecdsa-sha2-nistp256','ssh-rsa','rsa-sha2-256', + 'rsa-sha2-512','ssh-dss']}, + {cipher,[{client2server,['aes256-gcm@openssh.com', + 'aes256-ctr','aes192-ctr','aes128-gcm@openssh.com', + 'aes128-ctr','aes128-cbc','3des-cbc']}, + {server2client,['aes256-gcm@openssh.com','aes256-ctr', + 'aes192-ctr','aes128-gcm@openssh.com','aes128-ctr', + '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]}]}] + + +

To change this listing, there are two options which can be used in + ssh:default_algorithms/2,3,4 + and + ssh:daemon/2,3. The options could of course + be used in all other functions that initiates connections.

+ +

The options are preferred_algorithms and modify_algorithms. The first one + replaces the default set, while the latter modifies the default set.

+
+
+ +
+ Replacing the default set: preferred_algorithms +

See the Reference Manual for details

+ +

Here follows a series of examples ranging from simple to more complex.

+ +

The experimental function ssh:chk_algos_opts(Opts) mangles the options preferred_algorithms + and modify_algorithms as ssh:dameon, ssh:connect and others does.

+ +
+ Example 1 +

Replace the kex algorithms list with the single algorithm 'diffie-hellman-group14-sha256':

+ +1> ssh:chk_algos_opts( + [{preferred_algorithms, + [{kex, ['diffie-hellman-group14-sha256']} + ] + } + ]). +[{kex,['diffie-hellman-group14-sha256']}, + {public_key,['ecdsa-sha2-nistp384','ecdsa-sha2-nistp521', + 'ecdsa-sha2-nistp256','ssh-rsa','rsa-sha2-256', + 'rsa-sha2-512','ssh-dss']}, + {cipher,[{client2server,['aes256-gcm@openssh.com', + 'aes256-ctr','aes192-ctr','aes128-gcm@openssh.com', + 'aes128-ctr','aes128-cbc','3des-cbc']}, + {server2client,['aes256-gcm@openssh.com','aes256-ctr', + 'aes192-ctr','aes128-gcm@openssh.com','aes128-ctr', + '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 unmentioned lists (public_key, cipher, mac and compression) + are un-changed.

+
+ +
+ Example 2 +

In the lists that are divided in two for the two directions (c.f cipher) it is possible + to change both directions at once:

+ +2> ssh:chk_algos_opts( + [{preferred_algorithms, + [{cipher,['aes128-ctr']} + ] + } + ]). +[{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', + 'diffie-hellman-group14-sha1', + 'diffie-hellman-group-exchange-sha1']}, + {public_key,['ecdsa-sha2-nistp384','ecdsa-sha2-nistp521', + 'ecdsa-sha2-nistp256','ssh-rsa','rsa-sha2-256', + 'rsa-sha2-512','ssh-dss']}, + {cipher,[{client2server,['aes128-ctr']}, + {server2client,['aes128-ctr']}]}, + {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 both lists in cipher has been changed to the provided value ('aes128-ctr').

+
+ +
+ Example 3 +

In the lists that are divided in two for the two directions (c.f cipher) it is possible + to change only one of the directions:

+ +3> ssh:chk_algos_opts( + [{preferred_algorithms, + [{cipher,[{client2server,['aes128-ctr']}]} + ] + } + ]). +[{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', + 'diffie-hellman-group14-sha1', + 'diffie-hellman-group-exchange-sha1']}, + {public_key,['ecdsa-sha2-nistp384','ecdsa-sha2-nistp521', + 'ecdsa-sha2-nistp256','ssh-rsa','rsa-sha2-256', + 'rsa-sha2-512','ssh-dss']}, + {cipher,[{client2server,['aes128-ctr']}, + {server2client,['aes256-gcm@openssh.com','aes256-ctr', + 'aes192-ctr','aes128-gcm@openssh.com','aes128-ctr', + '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]}]}] + +
+ +
+ Example 4 +

It is of course possible to change more than one list:

+ +4> ssh:chk_algos_opts( + [{preferred_algorithms, + [{cipher,['aes128-ctr']}, + {mac,['hmac-sha2-256']}, + {kex,['ecdh-sha2-nistp384']}, + {public_key,['ssh-rsa']}, + {compression,[{server2client,[none]}, + {client2server,[zlib]}]} + ] + } + ]). +[{kex,['ecdh-sha2-nistp384']}, + {public_key,['ssh-rsa']}, + {cipher,[{client2server,['aes128-ctr']}, + {server2client,['aes128-ctr']}]}, + {mac,[{client2server,['hmac-sha2-256']}, + {server2client,['hmac-sha2-256']}]}, + {compression,[{client2server,[zlib]}, + {server2client,[none]}]}] + + +

Note that the ordering of the tuples in the lists didn't matter.

+
+
+ +
+ Modifying the default set: modify_algorithms +

The option preferred_algorithms is complicated to use for adding or removing single algorithms. One has + to first list them with ssh:default_algorithms() and then do substitutions in the lists. A situation + when it might be useful to add an algorithm is when one need to use a supported but disabled one. An example + is the kex 'diffie-hellman-group1-sha1' which nowadays is very unsecure and therefore disabled. It is + however still supported and might be used.

+ +

To facilitate addition or removal of algorithms the option modify_algorithms is available. + See the Reference Manual for details.

+ +

The option takes a list with instructions to append, prepend or remove algorithms:

+ +{modify_algorithms, [{append, ...}, + {prepend, ...}, + {rm, ...} + ]} + +

Each of the ... can be a algs_list() as the argument to the preferred_algorithms option.

+
+ Example 5 +

As an example let's add the Diffie-Hellman Group1 first in the kex list. It is supported according to + Supported algoritms.

+ +5> ssh:chk_algos_opts( + [{modify_algorithms, + [{prepend, + [{kex,['diffie-hellman-group1-sha1']}] + } + ] + } + ]). +[{kex,['diffie-hellman-group1-sha1','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', + 'diffie-hellman-group14-sha1', + 'diffie-hellman-group-exchange-sha1']}, + {public_key,['ecdsa-sha2-nistp384','ecdsa-sha2-nistp521', + 'ecdsa-sha2-nistp256','ssh-rsa','rsa-sha2-256', + 'rsa-sha2-512','ssh-dss']}, + {cipher,[{client2server,['aes256-gcm@openssh.com', + 'aes256-ctr','aes192-ctr','aes128-gcm@openssh.com', + 'aes128-ctr','aes128-cbc','3des-cbc']}, + {server2client,['aes256-gcm@openssh.com','aes256-ctr', + 'aes192-ctr','aes128-gcm@openssh.com','aes128-ctr', + '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]}]}] + + +

And the result shows that the Diffie-Hellman Group1 is added at the head of the kex list

+
+ +
+ Example 6 +

In next example, we also move the 'ecdh-sha2-nistp521' to the end in the kex + list, that is, append.

+ +6> ssh:chk_algos_opts( + [{modify_algorithms, + [{prepend, + [{kex, ['diffie-hellman-group1-sha1']} + ]}, + {append, + [{kex, ['ecdh-sha2-nistp521']} + ]} + ] + } + ]). +[{kex,['diffie-hellman-group1-sha1','ecdh-sha2-nistp384', + 'ecdh-sha2-nistp256','diffie-hellman-group-exchange-sha256', + 'diffie-hellman-group16-sha512', + 'diffie-hellman-group18-sha512', + 'diffie-hellman-group14-sha256', + 'diffie-hellman-group14-sha1', + 'diffie-hellman-group-exchange-sha1','ecdh-sha2-nistp521']}, + {public_key,['ecdsa-sha2-nistp384','ecdsa-sha2-nistp521', + ..... +] + +

Note that the appended algorithm is removed from its original place and then appended.

+
+ +
+ Example 7 +

In next example, we also move the 'ecdh-sha2-nistp521' to the end in the kex + list, that is, append.

+ +7> ssh:chk_algos_opts( + [{modify_algorithms, + [{prepend, + [{kex, ['diffie-hellman-group1-sha1']} + ]}, + {append, + [{kex, ['ecdh-sha2-nistp521']} + ]} + ] + } + ]). +[{kex,['diffie-hellman-group1-sha1','ecdh-sha2-nistp384', + 'ecdh-sha2-nistp256','diffie-hellman-group-exchange-sha256', + 'diffie-hellman-group16-sha512', + 'diffie-hellman-group18-sha512', + 'diffie-hellman-group14-sha256', + 'diffie-hellman-group14-sha1', + 'diffie-hellman-group-exchange-sha1','ecdh-sha2-nistp521']}, + {public_key,['ecdsa-sha2-nistp384','ecdsa-sha2-nistp521', + ..... +] + +

Note that the appended algorithm first is removed from its original place and then appended.

+
+ + +
+ Example 8 +

In this example, we use both options (preferred_algorithms and modify_algorithms) and + also try to prepend an unsupported algorithm. Any unsupported algorithm is quietly removed.

+ +8> ssh:chk_algos_opts( + [{preferred_algorithms, + [{cipher,['aes128-ctr']}, + {mac,['hmac-sha2-256']}, + {kex,['ecdh-sha2-nistp384']}, + {public_key,['ssh-rsa']}, + {compression,[{server2client,[none]}, + {client2server,[zlib]}]} + ] + }, + {modify_algorithms, + [{prepend, + [{kex, ['some unsupported algorithm']} + ]}, + {append, + [{kex, ['diffie-hellman-group1-sha1']} + ]} + ] + } + ]). +[{kex,['ecdh-sha2-nistp384','diffie-hellman-group1-sha1']}, + {public_key,['ssh-rsa']}, + {cipher,[{client2server,['aes128-ctr']}, + {server2client,['aes128-ctr']}]}, + {mac,[{client2server,['hmac-sha2-256']}, + {server2client,['hmac-sha2-256']}]}, + {compression,[{client2server,[zlib]}, + {server2client,[none]}]}] + + +

It is of course questionable why anyone would like to use the both options together, but it is possible + if the needed.

+
+ + + +
+ + -- cgit v1.2.3