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/Makefile | 3 +- lib/ssh/doc/src/configure_algos.xml | 457 ++++++++++++++++++++++++++++++++++++ lib/ssh/doc/src/ssh.xml | 80 ++++++- lib/ssh/doc/src/ssh_app.xml | 4 +- lib/ssh/doc/src/usersguide.xml | 1 + 5 files changed, 541 insertions(+), 4 deletions(-) create mode 100644 lib/ssh/doc/src/configure_algos.xml (limited to 'lib') diff --git a/lib/ssh/doc/src/Makefile b/lib/ssh/doc/src/Makefile index a759854da4..adbda5a030 100644 --- a/lib/ssh/doc/src/Makefile +++ b/lib/ssh/doc/src/Makefile @@ -53,7 +53,8 @@ XML_PART_FILES = part_notes.xml \ XML_CHAPTER_FILES = notes.xml \ introduction.xml \ ssh_protocol.xml \ - using_ssh.xml + using_ssh.xml \ + configure_algos.xml BOOK_FILES = book.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.

+
+ + + +
+ + diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index ea7e975ef5..48553bf503 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -108,6 +108,9 @@ double_algs() =

[{client2serverlist,simple_algs()},{server2client,simple_algs()}] | simple_algs()

 + + modify_algs_list() = +

list( {append,algs_list()} | {prepend,algs_list()} | {rm,algs_list()} )

 @@ -254,7 +257,8 @@

- + +

List of algorithms to use in the algorithm negotiation. The default algs_list() can be obtained from default_algorithms/0. @@ -275,6 +279,8 @@ for cipher but specifies the same algorithms for mac and compression in both directions. The kex (key exchange) is implicit but public_key is set explicitly.

+

For background and more examples see the User's Guide.

+

Changing the values can make a connection less secure. Do not change unless you know exactly what you are doing. If you do not understand the values then you @@ -282,6 +288,41 @@ + + + +

Modifies the list of algorithms to use in the algorithm negotiation. The modifications are + applied after the option preferred_algorithms is applied (if existing)

+

The possible modifications are to:

+ +

Append or prepend supported but not enabled algorithm(s) to the list of + algorithms.

If the wanted algorithms already are in the list of algorithms, they will first + be removed and then appended or prepended. +

+ +

Remove (rm) one or more algorithms from the list of algorithms.

 + +

If an unsupported algorithm is in the list, it will be silently ignored

+ +

Here is an example of this option:

+ +{modify_algorithms, + [{prepend, [{kex, ['diffie-hellman-group1-sha1']}], + {rm, [{compression, [none]}]} + ] +} + +

The example specifies that:

+ +

the old key exchange algorithm 'diffie-hellman-group1-sha1' should be + the main alternative. It will be the main alternative since it is prepened to the list

+ +

The compression algorithm none (= no compression) is removed so compression is enforced

+ + +

For background and more examples see the User's Guide.

+ +

Sets the three diffie-hellman-group-exchange parameters that guides the connected server in choosing a group. @@ -555,6 +596,8 @@ for cipher but specifies the same algorithms for mac and compression in both directions. The kex (key exchange) is implicit but public_key is set explicitly.

+

For background and more examples see the User's Guide.

+

Changing the values can make a connection less secure. Do not change unless you know exactly what you are doing. If you do not understand the values then you @@ -562,6 +605,41 @@ + + + +

Modifies the list of algorithms to use in the algorithm negotiation. The modifications are + applied after the option preferred_algorithms is applied (if existing)

+

The possible modifications are to:

+ +

Append or prepend supported but not enabled algorithm(s) to the list of + algorithms.

If the wanted algorithms already are in the list of algorithms, they will first + be removed and then appended or prepended. +

+ +

Remove (rm) one or more algorithms from the list of algorithms.

 + +

If an unsupported algorithm is in the list, it will be silently ignored

+ +

Here is an example of this option:

+ +{modify_algorithms, + [{prepend, [{kex, ['diffie-hellman-group1-sha1']}], + {rm, [{compression, [none]}]} + ] +} + +

The example specifies that:

+ +

the old key exchange algorithm 'diffie-hellman-group1-sha1' should be + the main alternative. It will be the main alternative since it is prepened to the list

+ +

The compression algorithm none (= no compression) is removed so compression is enforced

+ + +

For background and more examples see the User's Guide.

+ +

Defines the groups the server may choose among when diffie-hellman-group-exchange is negotiated. diff --git a/lib/ssh/doc/src/ssh_app.xml b/lib/ssh/doc/src/ssh_app.xml index 33ec7aaee0..1cbbdfcf38 100644 --- a/lib/ssh/doc/src/ssh_app.xml +++ b/lib/ssh/doc/src/ssh_app.xml @@ -97,7 +97,7 @@

The known_hosts file contains a list of approved servers and their public keys. Once a server is listed, it can be verified without user interaction. -

+

Authorized Keys @@ -135,7 +135,7 @@

Supported algorithms are:

- + Key exchange algorithms diff --git a/lib/ssh/doc/src/usersguide.xml b/lib/ssh/doc/src/usersguide.xml index 70051ba771..d902df6848 100644 --- a/lib/ssh/doc/src/usersguide.xml +++ b/lib/ssh/doc/src/usersguide.xml @@ -36,4 +36,5 @@ + -- cgit v1.2.3