From ac4107ceea994f028ae67b43dbe6676b9ccf2b3b Mon Sep 17 00:00:00 2001 From: tmanevik Date: Thu, 19 Mar 2015 14:00:43 +0100 Subject: Editorial updates SSH application --- lib/ssh/doc/src/ssh.xml | 319 +++++++++++++++++++++++++++--------------------- 1 file changed, 181 insertions(+), 138 deletions(-) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index 0e7e3848ad..bb41a317e5 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -22,54 +22,71 @@ ssh + + 2007-10-06 + ssh - Main API of the SSH application + Main API of the ssh application -

Interface module for the SSH application.

+

Interface module for the ssh application.
SSH - SSH requires the crypto and public_key applications. - Supported SSH version is 2.0 - Supported MAC algorithms: hmac-sha2-256 and hmac-sha1 - Supported encryption algorithms: aes128-ctr, aes128-cb and 3des-cbc - Supports unicode filenames if the emulator and the underlaying OS supports it. See the DESCRIPTION section in file for information about this subject - Supports unicode in shell and cli + SSH requires the crypto and public_key applications. + Supported SSH version is 2.0. + Supported MAC algorithms: hmac-sha2-256 and hmac-sha1. + Supported encryption algorithms: aes128-ctr, aes128-cb and 3des-cbc. + Supports unicode filenames if the emulator and the underlaying OS support it. + See section DESCRIPTION in the + file manual page in kernel + for information about this subject. + Supports unicode in shell and CLI.
- DATA TYPES + DATA TYPES

Type definitions that are used more than once in - this module and/or abstractions to indicate the intended use of the data - type:

-

boolean() = true | false

-

string() = [byte()]

-

ssh_daemon_ref() - opaque to the user - returned by ssh:daemon/[1,2,3]

-

ssh_connection_ref() - opaque to the user - returned by ssh:connect/3

-

ip_address() - inet::ip_address()

-

subsystem_spec() = {subsystem_name(), - {channel_callback(), channel_init_args()}}

-

subsystem_name() = string()

-

channel_callback() = atom() - Name of the erlang module - implementing the subsystem using the ssh_channel behavior see - ssh_channel(3)

-

channel_init_args() = list()

-
+ this module, or abstractions to indicate the intended use of the data + type, or both:

+ + boolean() +

= true | false

 + string() +

= [byte()]

 + ssh_daemon_ref() +

Opaque to the user, + returned by ssh:daemon/[1,2,3]

 + ssh_connection_ref() +

Opaque to the user, + returned by ssh:connect/3

 + ip_address() +

inet::ip_address

 + subsystem_spec() +

= {subsystem_name(), + {channel_callback(), channel_init_args()}}

 + subsystem_name() +

= string()

 + channel_callback() +

= atom() - Name of the Erlang module + implementing the subsystem using the ssh_channel behavior, see + ssh_channel(3)

 + channel_init_args() +

= list()

 + + close(ConnectionRef) -> ok - Closes an SSH connection + Closes an SSH connection. ConnectionRef = ssh_connection_ref() @@ -81,135 +98,141 @@ connect(Host, Port, Options) -> connect(Host, Port, Options, Timeout) -> {ok, ssh_connection_ref()} | {error, Reason} - Connect to an ssh server. + Connects to an SSH server. Host = string() Port = integer() - The default is , the assigned well known port + is default, the assigned well-known port number for SSH. Options = [{Option, Value}] Timeout = infinity | integer(milliseconds) - Negotiation timeout, for connection timeout use the option {connect_timeout, timeout()}. + Negotiation time-out. For connection time-out, use option + {connect_timeout, timeout()}.

Connects to an SSH server. No channel is started. This is done by calling - ssh_connection:session_channel/[2, 4].

-

Options are:

+ + ssh_connection:session_channel/[2, 4].

+

Options:

- IP version to use. + +

IP version to use.

+ -

Sets the user directory i.e. the directory containing - ssh configuration files for the user such as +

Sets the user directory, that is, the directory containing + ssh configuration files for the user, such as , and + id_dsa]]>, and . Defaults to the directory normally referred to as -

+ .

 -

If the user dsa key is protected by a passphrase it can be +

If the user DSA key is protected by a passphrase, it can be supplied with this option.

-

If the user rsa key is protected by a passphrase it can be +

If the user RSA key is protected by a passphrase, it can be supplied with this option.

-

When true hosts are added to the +

When true, hosts are added to the file without asking the user. - Defaults to false. + Defaults to false.

-

If false disables the client to connect to the server - if any user interaction is needed such as accepting that - the server will be added to the known_hosts file or - supplying a password. Defaults to true. +

If false, disables the client to connect to the server + if any user interaction is needed, such as accepting + the server to be added to the known_hosts file, or + supplying a password. Defaults to true. Even if user interaction is allowed it can be - suppressed by other options such as silently_accept_hosts and - password. Do note that it may not always be desirable to use - those options from a security point of view.

+ suppressed by other options, such as silently_accept_hosts + and password. However, those optins are not always desirable + to use from a security point of view.

Sets the preferred public key algorithm to use for user - authentication. If the the preferred algorithm fails for - some reason, the other algorithm is tried. The default is + authentication. If the preferred algorithm fails, + the other algorithm is tried. The default is to try first.

 -

List of public key algorithms to try to use, 'ssh-rsa' and 'ssh-dss' available. - Will override

+

List of public key algorithms to try to use. + 'ssh-rsa' and 'ssh-dss' are available. + Overrides

-

Sets a timeout on the transport layer +

Sets a time-out on the transport layer connection. Defaults to infinity.

 -

Provides a user name. If this option is not given, ssh +

Provides a username. If this option is not given, ssh reads from the environment ( or - on unix, + on UNIX, on Windows).

 -

Provide a password for password authentication. If - this option is not given, the user will be asked for a - password if the password authentication method is +

Provides a password for password authentication. + If this option is not given, the user is asked for a + password, if the password authentication method is attempted.

 -

Module implementing the behaviour ssh_client_key_api. +

Module implementing the behaviour + ssh_client_key_api. Can be used to customize the handling of public keys.

-

If true, the client will not print out anything on authorization.

+

If true, the client does not print anything on authorization.

 -

Allow an existing file descriptor to be used - (simply passed on to the transport protocol).

 +

Allows an existing file descriptor to be used + (by passing it on to the transport protocol).

-

Provide, in bytes, when rekeying should be initiated, - defaults to one time each GB and one time per hour.

+

Provides, in bytes, when rekeying is to be initiated. + Defaults to once per each GB and once per hour.

 -

Sets a timeout on connection when no channels are active, default is infinity

 +

Sets a time-out on a connection when no channels are active. + Defaults to infinity.

 connection_info(ConnectionRef, [Option]) ->[{Option, - Value}] - Retrieves information about a connection. + Value}] + Retrieves information about a connection. Option = client_version | server_version | user | peer | sockname Value = [option_value()] - option_value() = {{Major::integer(), Minor::integer()}, VersionString::string()} | User::string() | - Peer::{inet:hostname(), {inet::ip_adress(), inet::port_number()}} | + option_value() = {{Major::integer(), Minor::integer()}, VersionString::string()} | + User::string() | Peer::{inet:hostname(), {inet::ip_adress(), inet::port_number()}} | Sockname::{inet::ip_adress(), inet::port_number()} () -

Retrieves information about a connection. -

+

Retrieves information about a connection.

 @@ -230,111 +253,127 @@

Starts a server listening for SSH connections on the given port.

-

Options are:

+

Options:

- IP version to use when the host address is specified as any. +

IP version to use when the host address is specified as any.

 - Provides specifications for handling of subsystems. The - "sftp" subsystem spec can be retrieved by calling - ssh_sftpd:subsystem_spec/1. If the subsystems option is - not present the value of - [ssh_sftpd:subsystem_spec([])] will be used. It is - of course possible to set the option to the empty list if - you do not want the daemon to run any subsystems at all. +

Provides specifications for handling of subsystems. The + "sftp" subsystem specification is retrieved by calling + ssh_sftpd:subsystem_spec/1. If the subsystems option is + not present, the value of + [ssh_sftpd:subsystem_spec([])] is used. + The option can be set to the empty list if + you do not want the daemon to run any subsystems.

 pid() | fun(string() = User, ip_address() = PeerAddr) -> pid()}]]> - Defines the read-eval-print loop used when a shell is - requested by the client. Default is to use the erlang shell: - +

Defines the read-eval-print loop used when a shell is + requested by the client. The default is to use the Erlang shell: +

- Provides your own CLI implementation, i.e. a channel callback - module that implements a shell and command execution. Note - that you may customize the shell read-eval-print loop using the - option shell which is much less work than implementing - your own CLI channel. If set to no_cli you will disable - CLI channels and only subsystem channels will be allowed. +

Provides your own CLI implementation, that is, a channel callback + module that implements a shell and command execution. The shell + read-eval-print loop can be customized, using the + option shell. This means less work than implementing + an own CLI channel. If set to no_cli, the CLI channels + are disabled and only subsystem channels are allowed.

 -

Sets the user directory i.e. the directory containing - ssh configuration files for the user such as +

Sets the user directory. That is, the directory containing + ssh configuration files for the user, such as , and + id_dsa]]>, and . Defaults to the directory normally referred to as -

+ .

Sets the system directory, containing the host key files - that identifies the host keys for ssh. The default is - , note that for security reasons - this directory is normally only accessible by the root user.

+ that identify the host keys for ssh. Defaults to + . For security reasons, + this directory is normally accessible only to the root user.

 -

Comma separated string that determines which - authentication methodes that the server should support and - in what order they will be tried. Defaults to +

Comma-separated string that determines which + authentication methods that the server is to support and + in what order they are tried. Defaults to

-

Provide passwords for password authentication.They will - be used when someone tries to connect to the server and - public key user authentication fails. The option provides - a list of valid user names and the corresponding password. +

Provides passwords for password authentication. The passwords + are used when someone tries to connect to the server and + public key user-authentication fails. The option provides + a list of valid usernames and the corresponding passwords.

-

Provide a global password that will authenticate any +

Provides a global password that authenticates any user. From a security perspective this option makes the server very vulnerable.

 boolean()}]]> -

Provide a function for password validation. This is called - with user and password as strings, and should return +

Provides a function for password validation. This function is called + with user and password as strings, and returns if the password is valid and otherwise.

 -

Max time in milliseconds for the authentication negotiation. The default value is 2 minutes. If the client fails to login within this time, the connection is closed. +

Maximum time in milliseconds for the authentication negotiation. + Defaults to 120000 (2 minutes). If the client fails to log in within this time, + the connection is closed.

-

The maximum number of simultaneous sessions that are accepted at any time for this daemon. This includes sessions that are being authorized. So if set to N, and N clients have connected but not started the login process, the N+1 connection attempt will be aborted. If N connections are authenticated and still logged in, no more loggins will be accepted until one of the existing ones log out. +

The maximum number of simultaneous sessions that are accepted at any time + for this daemon. This includes sessions that are being authorized. + Thus, if set to N, and N clients have connected but not started + the login process, connection attempt N+1 is aborted. + If N connections are authenticated and still logged in, no more logins + are accepted until one of the existing ones log out.

-

The counter is per listening port, so if two daemons are started, one with {max_sessions,N} and the other with {max_sessions,M} there will be in total N+M connections accepted for the whole ssh application. +

The counter is per listening port. Thus, if two daemons are started, one with + {max_sessions,N} and the other with {max_sessions,M}, in total + N+M connections are accepted for the whole ssh application.

-

Note that if parallel_login is false, only one client at a time may be in the authentication phase. +

Notice that if parallel_login is false, only one client + at a time can be in the authentication phase.

-

As default, the option is not set. This means that the number is not limited. +

By default, this option is not set. This means that the number is not limited.

-

If set to false (the default value), only one login is handled a time. If set to true, an unlimited number of login attempts will be allowed simultanously. +

If set to false (the default value), only one login is handled at a time. + If set to true, an unlimited number of login attempts are allowed simultaneously.

-

If the max_sessions option is set to N and parallel_login is set to true, the max number of simultaneous login attempts at any time is limited to N-K where K is the number of authenticated connections present at this daemon. +

If the max_sessions option is set to N and parallel_login + is set to true, the maximum number of simultaneous login attempts at any time is + limited to N-K, where K is the number of authenticated connections present + at this daemon.

-

Do not enable parallel_logins without protecting the server by other means, for example the max_sessions option or a firewall configuration. If set to true, there is no protection against DOS attacks.

+

Do not enable parallel_logins without protecting the server by other means, + for example, by the max_sessions option or a firewall configuration. If set to + true, there is no protection against DOS attacks.

 @@ -346,25 +385,28 @@ -

Module implementing the behaviour ssh_server_key_api. +

Module implementing the behaviour + ssh_server_key_api. Can be used to customize the handling of public keys.

-

Allow an existing file-descriptor to be used - (simply passed on to the transport protocol).

 - _}]]> +

Allows an existing file-descriptor to be used + (passed on to the transport protocol).

+ _}]]> -

Provide a fun to implement your own logging when a user fails to authenticate.

+

Provides a fun to implement your own logging when a user fails to authenticate.

 - _}]]> + _}]]> -

Provide a fun to implement your own logging when a user authenticates to the server.

+

Provides a fun to implement your own logging when a user authenticates to the server.

 _}]]> -

Provide a fun to implement your own logging when a user disconnects from the server.

+

Provides a fun to implement your own logging when a user disconnects from the server.

 @@ -375,16 +417,16 @@ shell(Host) -> shell(Host, Option) -> shell(Host, Port, Option) -> _ - + Starts an interactive shell over an SSH server. - Host = string() - Port = integer() - Options - see ssh:connect/3 + Host = string() + Port = integer() + Options - see ssh:connect/3 -

Starts an interactive shell via an SSH server on the +

Starts an interactive shell over an SSH server on the given Host. The function waits for user input, - and will not return until the remote shell is ended (i.e. + and does not return until the remote shell is ended (that is, exit from the shell).

@@ -393,28 +435,29 @@ start() -> start(Type) -> ok | {error, Reason} - Starts the SSH application. + Starts the SSH application. Type = permanent | transient | temporary Reason = term() -

Utility function that starts crypto, public_key and the SSH - application. Defult type is temporary. - See also application(3) -

+

Utility function that starts the applications crypto, public_key, + and ssh. Default type is temporary. + For more information, see the application(3) + manual page in kernel.

 stop() -> ok | {error, Reason} - Stops the SSH application. + Stops the ssh application. Reason = term() -

Stops the SSH application. See also - application(3)

+

Stops the ssh application. + For more information, see the application(3) + manual page in kernel.

 @@ -438,7 +481,7 @@ stop_listener(DaemonRef) -> stop_listener(Address, Port) -> ok Stops the listener, but leaves existing connections started - by the listener up and running. + by the listener operational. DaemonRef = ssh_daemon_ref() Address = ip_address() @@ -446,7 +489,7 @@

Stops the listener, but leaves existing connections started - by the listener up and running.

+ by the listener operational.

 -- cgit v1.2.3 From 0bf8c6a7954055d672c268f08be37596264a78c5 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Wed, 22 Apr 2015 16:00:13 +0200 Subject: ssh: Keep dependency info in only one place --- lib/ssh/doc/src/ssh.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index bb41a317e5..284d7febf8 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -37,7 +37,7 @@ SSH - SSH requires the crypto and public_key applications. + For application dependencies see ssh(6) Supported SSH version is 2.0. Supported MAC algorithms: hmac-sha2-256 and hmac-sha1. Supported encryption algorithms: aes128-ctr, aes128-cb and 3des-cbc. -- cgit v1.2.3 From 220ef7dbc2cfc30a8fd6f6d37c09a9f35bbc3797 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Thu, 23 Apr 2015 13:45:54 +0200 Subject: ssh: Removed missplaced empty paranthesis --- lib/ssh/doc/src/ssh.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index 284d7febf8..71d520b6ff 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -229,7 +229,7 @@ Value = [option_value()] option_value() = {{Major::integer(), Minor::integer()}, VersionString::string()} | User::string() | Peer::{inet:hostname(), {inet::ip_adress(), inet::port_number()}} | - Sockname::{inet::ip_adress(), inet::port_number()} () + Sockname::{inet::ip_adress(), inet::port_number()}

Retrieves information about a connection.

-- cgit v1.2.3 From 8e76d7b749a8c8d01f9567d75b8069ce1d8edefb Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Thu, 23 Apr 2015 13:46:34 +0200 Subject: ssh: Add line about supported kex algorithm(s) --- lib/ssh/doc/src/ssh.xml | 1 + 1 file changed, 1 insertion(+) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index 71d520b6ff..9034c5ee6d 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -41,6 +41,7 @@ Supported SSH version is 2.0. Supported MAC algorithms: hmac-sha2-256 and hmac-sha1. Supported encryption algorithms: aes128-ctr, aes128-cb and 3des-cbc. + Supported key exchange algorithms: diffie-hellman-group1-sha1. Supports unicode filenames if the emulator and the underlaying OS support it. See section DESCRIPTION in the file manual page in kernel -- cgit v1.2.3 From 5e7158109d659d6b8668250e308c3c4dd57f15ae Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Thu, 23 Apr 2015 15:31:04 +0200 Subject: ssh: Timeout unit and default added to some missing places --- lib/ssh/doc/src/ssh.xml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index 9034c5ee6d..35b5eb87cb 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -106,9 +106,9 @@ is default, the assigned well-known port number for SSH. Options = [{Option, Value}] - Timeout = infinity | integer(milliseconds) - Negotiation time-out. For connection time-out, use option - {connect_timeout, timeout()}. + Timeout = infinity | integer() + Negotiation time-out in milli-seconds. The default value is infinity. + For connection time-out, use option {connect_timeout, timeout()}.

Connects to an SSH server. No channel is started. This is done @@ -177,7 +177,8 @@

Sets a time-out on the transport layer - connection. Defaults to infinity.

+ connection. For gen_tcp the time is in milli-seconds and the default value is + infinity.

 -- cgit v1.2.3 From 66c06dc602594b263225b5481d2abba653a3b5e8 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Tue, 12 May 2015 11:21:20 +0200 Subject: ssh: Align "=" sign in type declarations to decided policy --- lib/ssh/doc/src/ssh.xml | 43 +++++++++++++++++++++---------------------- 1 file changed, 21 insertions(+), 22 deletions(-) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index d49d3ac2a7..7cca84432e 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -57,29 +57,28 @@ this module, or abstractions to indicate the intended use of the data type, or both:

- boolean() -

= true | false

 - string() -

= [byte()]

 - ssh_daemon_ref() -

Opaque to the user, - returned by ssh:daemon/[1,2,3]

 - ssh_connection_ref() -

Opaque to the user, - returned by ssh:connect/3

 - ip_address() + boolean() = +

true | false

 + string() = +

[byte()]

 + ssh_daemon_ref() = +

opaque() - + as returned by ssh:daemon/[1,2,3]

 + ssh_connection_ref() = +

opaque() - as returned by ssh:connect/3

 + ip_address() =

inet::ip_address

 - subsystem_spec() -

= {subsystem_name(), - {channel_callback(), channel_init_args()}}

 - subsystem_name() -

= string()

 - channel_callback() -

= atom() - Name of the Erlang module - implementing the subsystem using the ssh_channel behavior, see - ssh_channel(3)

 - channel_init_args() -

= list()

 + subsystem_spec() = +

{subsystem_name(), + {channel_callback(), channel_init_args()}}

 + subsystem_name() = +

string()

 + channel_callback() = +

atom() - Name of the Erlang module + implementing the subsystem using the ssh_channel behavior, see + ssh_channel(3)

 + channel_init_args() = +

list()

 -- cgit v1.2.3 From e5715f37dcfd9c21103232e699390d9736180923 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Wed, 13 May 2015 17:36:24 +0200 Subject: ssh: New option 'preferred_algorithms' This option enables the user to define which algorithms that are to be used as well as their precedences in the negotiation between server and client. --- lib/ssh/doc/src/ssh.xml | 100 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 99 insertions(+), 1 deletion(-) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index df13442fc6..3e7726c24d 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -35,13 +35,15 @@
SSH - + For application dependencies see ssh(6) Supported SSH version is 2.0. + Supported public key algorithms: ssh-rsa and ssh-dss. Supported MAC algorithms: hmac-sha2-256 and hmac-sha1. Supported encryption algorithms: aes128-ctr, aes128-cb and 3des-cbc. Supported key exchange algorithms: diffie-hellman-group1-sha1. + Supported compression algorithms: none, zlib, zlib@openssh.com, Supports unicode filenames if the emulator and the underlaying OS support it. See section DESCRIPTION in the file manual page in kernel @@ -79,6 +81,18 @@ ssh_channel(3)

 channel_init_args() =

list()

 + + algs_list() = +

list( alg_entry() )

 + + alg_entry() = +

{kex, simple_algs()} | {public_key, simple_algs()} | {cipher, double_algs()} | {mac, double_algs()} | {compression, double_algs()}

 + + simple_algs() = +

list( atom() )

 + + double_algs() = +

[{client2serverlist,simple_algs()},{server2client,simple_algs()}] | simple_algs()
@@ -160,19 +174,57 @@ and password. However, those optins are not always desirable to use from a security point of view.

 + + +

This option is kept for compatibility. It is ignored if the preferred_algorithms + option is used. The equivalence of {public_key_alg,'ssh-dss'} is + {preferred_algorithms, [{public_key,['ssh-dss','ssh-rsa']}]}.

+

Sets the preferred public key algorithm to use for user authentication. If the preferred algorithm fails, the other algorithm is tried. The default is to try first.

 + + +

This option is kept for compatibility. It is ignored if the preferred_algorithms + option is used. The equivalence of {pref_public_key_algs,['ssh-dss']} is + {preferred_algorithms, [{public_key,['ssh-dss']}]}.

+

List of public key algorithms to try to use. 'ssh-rsa' and 'ssh-dss' are available. Overrides

+ + + +

List of algorithms to use in the algorithm negotiation. The default algs_list() can + be obtained from default_algorithms/0. +

+

Here is an example of this option:

+ +{preferred_algorithms, + [{public_key,['ssh-rsa','ssh-dss']}, + {cipher,[{client2server,['aes128-ctr']}, + {server2client,['aes128-cbc','3des-cbc']}]}, + {mac,['hmac-sha2-256','hmac-sha1']}, + {compression,[none,zlib]} +} + +

Note that we want different algorithms in the two directions for cipher, but the same in + both directions for mac and compression. We keep the default for kex and + public_key but has given the default value explicitly for public_key

+ +

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 + are not supposed to change them

+ + +

Sets a time-out on the transport layer @@ -341,6 +393,32 @@ user. From a security perspective this option makes the server very vulnerable.

 + + + +

List of algorithms to use in the algorithm negotiation. The default algs_list() can + be obtained from default_algorithms/0. +

+

Here is an example of this option:

+ +{preferred_algorithms, + [{public_key,['ssh-rsa','ssh-dss']}, + {cipher,[{client2server,['aes128-ctr']}, + {server2client,['aes128-cbc','3des-cbc']}]}, + {mac,['hmac-sha2-256','hmac-sha1']}, + {compression,[none,zlib]} +} + +

Note that we want different algorithms in the two directions for cipher, but the same in + both directions for mac and compression. We keep the default for kex and + public_key but has given the default value explicitly for public_key

+ +

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 + are not supposed to change them

+ + + boolean()}]]>

Provides a function for password validation. This function is called @@ -445,6 +523,26 @@ + + default_algorithms() -> algs_list() + Get a list declaring the supported algorithms + +

Returns a key-value list, where the keys are the different types of algorithms and the values are the + algorithms themselves. An example:

+ +20> ssh:default_algorithms(). +[{kex,['diffie-hellman-group1-sha1']}, + {public_key,['ssh-rsa','ssh-dss']}, + {cipher,[{client2server,['aes128-ctr','aes128-cbc','3des-cbc']}, + {server2client,['aes128-ctr','aes128-cbc','3des-cbc']}]}, + {mac,[{client2server,['hmac-sha2-256','hmac-sha1']}, + {server2client,['hmac-sha2-256','hmac-sha1']}]}, + {compression,[{client2server,[none,zlib]}, + {server2client,[none,zlib]}]}] +21> + + + shell(Host) -> -- cgit v1.2.3 From 946425be714a72b1dec0a67966679ef7a5c3e39d Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Thu, 21 May 2015 17:44:03 +0200 Subject: ssh: Algorithms test case added --- lib/ssh/doc/src/ssh.xml | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index 3e7726c24d..cf58806aa8 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -215,13 +215,14 @@ {compression,[none,zlib]} } -

Note that we want different algorithms in the two directions for cipher, but the same in - both directions for mac and compression. We keep the default for kex and - public_key but has given the default value explicitly for public_key

+

The example specifies different algorithms in the two directions (client2server and server2client), for cipher but specifies the same +algorithms for mac and compression in both directions. The kex (key exchange) and public key algorithms are set to their default values, +kex is implicit but public_key is set explicitly.

+

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 - are not supposed to change them

+ are not supposed to change them.

 @@ -409,13 +410,14 @@ {compression,[none,zlib]} } -

Note that we want different algorithms in the two directions for cipher, but the same in - both directions for mac and compression. We keep the default for kex and - public_key but has given the default value explicitly for public_key

+

The example specifies different algorithms in the two directions (client2server and server2client), for cipher but specifies the same +algorithms for mac and compression in both directions. The kex (key exchange) and public key algorithms are set to their default values, +kex is implicit but public_key is set explicitly.

+

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 - are not supposed to change them

+ are not supposed to change them.

 -- cgit v1.2.3 From 051a662cdc5cfc2aa93d86119688c14743837a5f Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Tue, 2 Jun 2015 09:14:18 +0200 Subject: ssh: Add profile option To enable the ssh daemon to run in a virtualized environment, where there can be more that one server that has the same ip-address and port, we add a new option profile. The profile name will be used in concatenation with ip-address and port to identify the ssh daemon instance. The name profile was chosen as there is a similar concept in the HTTP client in inets where profile names can be used to instantiate client configurations. Also the same type of option has been added to the HTTP server in inets. --- lib/ssh/doc/src/ssh.xml | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index cf58806aa8..b6533099c8 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -495,6 +495,19 @@ kex is implicit but public_key is set explicitly.

Can be used to customize the handling of public keys.

+ + {profile, atom()} + +

Used together with ip-address and port to + uniquely identify a ssh daemon. This can be useful in a + virtualized environment, where there can be more that one + server that has the same ip-address and + port. If this property is not explicitly set, it is + assumed that the the ip-address and port + uniquely identifies the SSH daemon. +

+ +

Allows an existing file-descriptor to be used -- cgit v1.2.3 From 04653b8c66c2b8d1453b32ca28d66ef1863dbd75 Mon Sep 17 00:00:00 2001 From: Hans Date: Thu, 4 Jun 2015 13:30:58 +0200 Subject: ssh: make disconnectfun work for both server&client --- lib/ssh/doc/src/ssh.xml | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index cf58806aa8..0516945c0e 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -175,6 +175,11 @@ to use from a security point of view.

 + _}]]> + +

Provides a fun to implement your own logging when a server disconnects the client.

+ + -- cgit v1.2.3 From 2ce77297d3475448d2f969b851ddaaa6c4c2e4e2 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Mon, 8 Jun 2015 13:59:20 +0200 Subject: ssh: add missing doc for option auth_method_kb_interactive_data --- lib/ssh/doc/src/ssh.xml | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index 0516945c0e..4d2d68f460 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -360,7 +360,7 @@ kex is implicit but public_key is set explicitly.

an own CLI channel. If set to no_cli, the CLI channels are disabled and only subsystem channels are allowed.

 - +

Sets the user directory. That is, the directory containing ssh configuration files for the user, such as @@ -377,6 +377,7 @@ kex is implicit but public_key is set explicitly.

. For security reasons, this directory is normally accessible only to the root user.

 +

Comma-separated string that determines which @@ -384,6 +385,19 @@ kex is implicit but public_key is set explicitly.

in what order they are tried. Defaults to

+ + +
where: +
PromptTexts = kb_int_tuple() | fun(PeerName::string(), User::string(), Service::string()) -> kb_int_tuple() +
kb_int_tuple() = {Name::string(), Instruction::string(), Prompt::string(), Echo::boolean()} + + +

Sets the text strings that the daemon sends to the client for presentation to the user when using keyboar-interactive authentication. If the fun/3 is used, it is called when the actual authentication occurs and may therefore return dynamic data like time, remote ip etc.

+

The parameter Echo guides the client about need to hide the password.

+

The default value is: + {auth_method_kb_interactive_data, {"SSH server", "Enter password for \""++User++"\"", "pwd: ", false}>

+ + -- cgit v1.2.3 From 3cb23ddc6bea946a729630def0f76d06a37ec63d Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Tue, 9 Jun 2015 15:02:35 +0200 Subject: ssh: doc change for keyboard-interaction, pwd->password --- lib/ssh/doc/src/ssh.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index 5edd790400..878dcb33d0 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -388,14 +388,14 @@ kex is implicit but public_key is set explicitly.


where: -
PromptTexts = kb_int_tuple() | fun(PeerName::string(), User::string(), Service::string()) -> kb_int_tuple() +
PromptTexts = kb_int_tuple() | fun(Peer::{IP::tuple(),Port::integer()}, User::string(), Service::string()) -> kb_int_tuple()
kb_int_tuple() = {Name::string(), Instruction::string(), Prompt::string(), Echo::boolean()}

Sets the text strings that the daemon sends to the client for presentation to the user when using keyboar-interactive authentication. If the fun/3 is used, it is called when the actual authentication occurs and may therefore return dynamic data like time, remote ip etc.

The parameter Echo guides the client about need to hide the password.

The default value is: - {auth_method_kb_interactive_data, {"SSH server", "Enter password for \""++User++"\"", "pwd: ", false}>

+ {auth_method_kb_interactive_data, {"SSH server", "Enter password for \""++User++"\"", "password: ", false}>

 Date: Tue, 9 Jun 2015 16:31:01 +0200 Subject: ssh: Option unexpectedfun for ssh:daemon and ssh:connect This option has a fun as value. The fun will be called when an unexpected message arrives. The fun returns either 'skip' or 'report' to guide the connection_handler what to do. One usage is to filter out messages that are not wanted in the error logger as info reports. An example of such a message is the 'etimedout' tcp error message that will be received if a connection has keep_alive and the peer is restarted. --- lib/ssh/doc/src/ssh.xml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index 5402d91e03..b39ca0852c 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -180,6 +180,14 @@

Provides a fun to implement your own logging when a server disconnects the client.

 + report | skip }]]> + +

Provides a fun to implement your own logging or other action when an unexpected message arrives. + If the fun returns report the usual info report is issued but if skip is returned no + report is generated.

+

Peer is in the format of {Host,Port}.

+ + @@ -532,6 +540,14 @@ kex is implicit but public_key is set explicitly.

Provides a fun to implement your own logging when a user disconnects from the server.

 + report | skip }]]> + +

Provides a fun to implement your own logging or other action when an unexpected message arrives. + If the fun returns report the usual info report is issued but if skip is returned no + report is generated.

+

Peer is in the format of {Host,Port}.

+ + _}]]>

Provide a fun to implement your own logging of the SSH message SSH_MSG_DEBUG. The last three parameters are from the message, see RFC4253, section 11.3. The ConnectionRef is the reference to the connection on which the message arrived. The return value from the fun is not checked.

-- cgit v1.2.3 From 738c34d4bb8f1a3811acd00af8c6c12107f8315b Mon Sep 17 00:00:00 2001 From: Bruce Yinhe Date: Thu, 18 Jun 2015 11:31:02 +0200 Subject: Change license text to APLv2 --- lib/ssh/doc/src/ssh.xml | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index c1235715cc..d24025ca4d 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -8,16 +8,17 @@ Ericsson AB. All Rights Reserved. - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. - - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. + 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. -- cgit v1.2.3 From 25db64119ec6369156129a77330c64753a6706eb Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Wed, 5 Aug 2015 13:41:35 +0200 Subject: ssh: document new options in doc/ssh.xml --- lib/ssh/doc/src/ssh.xml | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index d24025ca4d..cf5e8f1aff 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -43,7 +43,7 @@ Supported public key algorithms: ssh-rsa and ssh-dss. Supported MAC algorithms: hmac-sha2-256 and hmac-sha1. Supported encryption algorithms: aes128-ctr, aes128-cb and 3des-cbc. - Supported key exchange algorithms: diffie-hellman-group1-sha1. + Supported key exchange algorithms: diffie-hellman-group1-sha1, diffie-hellman-group14-sha1, diffie-hellman-group-exchange-sha1 and diffie-hellman-group-exchange-sha256. Supported compression algorithms: none, zlib, zlib@openssh.com, Supports unicode filenames if the emulator and the underlaying OS support it. See section DESCRIPTION in the @@ -240,6 +240,13 @@ kex is implicit but public_key is set explicitly.

 + + +

Sets the three diffie-hellman-group-exchange parameters that guides the connected server in choosing a group. + See RFC 4419 for the function of thoose. The default value is {512, 1024, 4096}. +

+ +

Sets a time-out on the transport layer @@ -449,6 +456,15 @@ kex is implicit but public_key is set explicitly.

 + + +

Sets the groups that the server may choose among when diffie-hellman-group-exchange is negotiated. + See RFC 4419 for details. +

+

If the parameter is {file,filename()}, the file must exist and have one or more three-tuples terminated by a dot. The interpretation is as if the tuples had been given directly in the option. The file is read when the daemon starts. +

+ + boolean()}]]>

Provides a function for password validation. This function is called -- cgit v1.2.3