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/ssh/doc/src') 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 From 10dd3321f37175b0adb4c8a31371419d45bf94d0 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Fri, 8 Sep 2017 18:16:24 +0200 Subject: ssh: Doc modified after comments --- lib/ssh/doc/src/configure_algos.xml | 73 +++++++++++-------------------------- lib/ssh/doc/src/ssh.xml | 39 +++++++++++++++----- 2 files changed, 52 insertions(+), 60 deletions(-) (limited to 'lib/ssh/doc/src') diff --git a/lib/ssh/doc/src/configure_algos.xml b/lib/ssh/doc/src/configure_algos.xml index ebd128c097..dd60324851 100644 --- a/lib/ssh/doc/src/configure_algos.xml +++ b/lib/ssh/doc/src/configure_algos.xml @@ -35,11 +35,11 @@
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

+

To fully understand how to configure the algorithms, it is essential to have a basic understanding of the SSH protocol + and how 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

+

The first subsection will give a short background of the SSH protocol while later sections describes + the implementation and provides some examples

Basics of the ssh protocol's algorithms handling @@ -77,7 +77,7 @@ cipher -

Symetric cipher algorithm used for the message encryption. This algorithm will use the key calculated +

Symetric cipher algorithm used for the payload 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'.

@@ -115,7 +115,7 @@

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: +

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

0> ssh:default_algorithms(). @@ -143,8 +143,8 @@ {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 +

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

@@ -160,8 +160,9 @@

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.

+

To forsee the effect of an option there is an experimental function ssh:chk_algos_opts(Opts). + It mangles the options preferred_algorithms + and modify_algorithms in the same way as ssh:dameon, ssh:connect and their friends does.

Example 1 @@ -292,11 +293,12 @@
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 +

A situation where it might be useful to add an algorithm is when one need to use a supported but disabled one. + An example is the 'diffie-hellman-group1-sha1' which nowadays is very unsecure and therefore disabled. It is however still supported and might be used.

+ +

The option preferred_algorithms may be complicated to use for adding or removing single algorithms. + First one has to list them with ssh:default_algorithms() and then do changes in the lists.

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

@@ -352,8 +354,8 @@
Example 6 -

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

+

In this example, we in put the 'diffie-hellman-group1-sha1' first and also move the + 'ecdh-sha2-nistp521' to the end in the kex list, that is, append it.

6> ssh:chk_algos_opts( [{modify_algorithms, @@ -377,46 +379,15 @@ ..... ] -

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

+

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

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( +7> ssh:chk_algos_opts( [{preferred_algorithms, [{cipher,['aes128-ctr']}, {mac,['hmac-sha2-256']}, @@ -446,8 +417,8 @@ {server2client,[none]}]}] -

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

+

It is of course questionable why anyone would like to use the both these options together, + but it is possible if an unforeseen need should arise.

diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index 48553bf503..d9516fff12 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -292,18 +292,39 @@

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:

+ applied after the option preferred_algorithms (if existing) is applied.

+

The algoritm for modifications works like this:

-

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

+ +

Input is the modify_algs_list() and a set of algorithms A + obtained from the preferred_algorithms option if existing, or else from the + ssh:default_algorithms/0. +

+ + +

The head of the modify_algs_list() modifies A giving the result A'.

+

The possible modifications are:

+ + +

Append or prepend supported but not enabled algorithm(s) to the list of + algorithms. If the wanted algorithms already are in A they will first + be removed and then appended or prepended, +

+ + +

Remove (rm) one or more algorithms from A. +

+ + + + +

Repeat the modification step with the tail of modify_algs_list() and the resulting + A'. +

-

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

 -

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

- +

If an unsupported algorithm is in the modify_algs_list(), it will be silently ignored

+

If there are more than one modify_algorithms options, the result is undefined.

Here is an example of this option:

{modify_algorithms, -- cgit v1.2.3