diff options
Diffstat (limited to 'lib/ssh/doc/src')
| -rw-r--r-- | lib/ssh/doc/src/notes.xml | 363 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh.xml | 209 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_app.xml | 214 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_connection.xml | 20 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_server_key_api.xml | 4 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_sftp.xml | 31 | ||||
| -rw-r--r-- | lib/ssh/doc/src/using_ssh.xml | 6 |
7 files changed, 756 insertions, 91 deletions
diff --git a/lib/ssh/doc/src/notes.xml b/lib/ssh/doc/src/notes.xml index 9d498c0fdc..75e1615c09 100644 --- a/lib/ssh/doc/src/notes.xml +++ b/lib/ssh/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2014</year> + <year>2004</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -30,6 +30,359 @@ <file>notes.xml</file> </header> +<section><title>Ssh 4.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The authentication method 'keyboard-interactive' failed + in the Erlang client when the server after successful + authentication continued by asking for zero more + passwords.</p> + <p> + Own Id: OTP-13225</p> + </item> + </list> + </section> + +</section> + +<section><title>Ssh 4.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Better error handling in ssh_file. There was some rare + errors when a NFS-mounted file was opened by ssh_file and + then remotely deleted during reading. That caused an + endless loop. </p> + <p> + That bug is now fixed.</p> + <p> + Own Id: OTP-12699 Aux Id: OTP-11688 </p> + </item> + <item> + <p> + Fixed a bug in the compression algorithm + [email protected].</p> + <p> + Own Id: OTP-12759</p> + </item> + <item> + <p> + It is now possible to start more than one daemon with a + file descriptor given in option fd. Each daemon must of + course have a unique file descriptor.</p> + <p> + Own Id: OTP-12966 Aux Id: seq12945 </p> + </item> + <item> + <p> + Fixed a bug that caused the option <c>dh_gex_limit</c> to + be ignored.</p> + <p> + Own Id: OTP-13029</p> + </item> + <item> + <p> + A problem is fixed with the <c>ssh:connect</c> option + <c>pref_public_key_algs</c> specifying user keys.</p> + <p> + Own Id: OTP-13158</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Document updates in the ssh reference manual: app doc + file and ssh_connection.</p> + <p> + Own Id: OTP-12003</p> + </item> + <item> + <p> + The authorization phase is made stateful to prevent ssh + acting on messages sent in wrong order.</p> + <p> + Own Id: OTP-12787</p> + </item> + <item> + <p> + Testcases for bad message lengths and for bad subfield + lengths added.</p> + <p> + Own Id: OTP-12792 Aux Id: Codenomicon #5214, 6166 </p> + </item> + <item> + <p> + The 'ecdsa-sha2-nistp256', 'ecdsa-sha2-nistp384' and + 'ecdsa-sha2-nistp521' signature algorithms for ssh are + implemented. See RFC 5656.</p> + <p> + Own Id: OTP-12936</p> + </item> + <item> + <p> + The crypto algorithms 'aes192-ctr' and 'aes256-ctr' are + implemented. See RFC 4344.</p> + <p> + Own Id: OTP-12939</p> + </item> + <item> + <p> + The ciphers and macs AEAD_AES_128_GCM and + AEAD_AES_256_GCM are implemented but not enabled per + default. See the SSH App Reference Manual and RFC5647 for + details.</p> + <p> + The ciphers [email protected] and + [email protected] are also implemented and available + in the default configuration.</p> + <p> + Own Id: OTP-13018</p> + </item> + <item> + <p> + The ssh:daemon option dh_gex_groups is extended to read a + user provided ssh moduli file with generator-modulus + pairs. The file is in openssh format.</p> + <p> + Own Id: OTP-13052 Aux Id: OTP-13054 </p> + </item> + <item> + <p> + There is now a file (public_key/priv/moduli) which lists + size-generator-modulus triples. The purpose is to give + servers the possibility to select the crypto primes + randomly among a list of pregenerated triples. This + reduces the risk for some attacks on diffie-hellman + negotiation.</p> + <p> + See the reference manual for public_key:dh_gex_group/4 + where the handling of this is described.</p> + <p> + The ssh server (ssh:daemon) uses this.</p> + <p> + Own Id: OTP-13054 Aux Id: OTP-13052 </p> + </item> + <item> + <p> + The ssh:daemon option pwdfun now also takes a fun/4. This + enables the user to 1) check userid-password in another + way than the builtin algorithm, 2) implement rate + limiting per user or source IP or IP+Port, and 3) + implement blocking of missbehaving peers.</p> + <p> + The old fun/2 still works as previously.</p> + <p> + Own Id: OTP-13055 Aux Id: OTP-13053 </p> + </item> + <item> + <p> + There is now a new option to make the server limit the + size range of moduli available for the diffie-hellman + group exchange negotiation. See option <c> + {dh_gex_limits,{Min,Max}}</c> in ssh:daemon/3.</p> + <p> + Own Id: OTP-13066</p> + </item> + <item> + <p> + Ecdh key exchange now validates compressed and + uncompressed keys as defined in rfc5656</p> + <p> + Own Id: OTP-13067</p> + </item> + <item> + <p> + Search order for the .ssh directory are changed so + <c>$HOME</c> is tried before + <c>init:get_argument(home)</c>.</p> + <p> + Own Id: OTP-13109</p> + </item> + <item> + <p> + The sftp receive window handling is optimized so it will + not update the remote end too often. This makes "sftp + mget" considerable faster.</p> + <p> + Own Id: OTP-13130</p> + </item> + <item> + <p> + The option <c>key_cb</c> is extended to take an optional + list that is passed to the callback module as an option. + With this it is possible to have different keys depending + on which host that is connected. Another possibility is + to write a callback module that fetches keys etc from a + database.</p> + <p> + Thanks to Vipin Nair.</p> + <p> + Own Id: OTP-13156</p> + </item> + </list> + </section> + +</section> + +<section><title>Ssh 4.1.3</title> + + <section><title>Known Bugs and Problems</title> + <list> + <item> + <p> + SSH_MSG_KEX_DH_GEX_REQUEST_OLD implemented to make PuTTY + work with erl server.</p> + <p> + Own Id: OTP-13140</p> + </item> + </list> + </section> + +</section> + +<section><title>Ssh 4.1.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Add a 1024 group to the list of key group-exchange groups</p> + <p> + Own Id: OTP-13046</p> + </item> + </list> + </section> + +</section> + +<section><title>Ssh 4.1.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + A new option <c>max_channels</c> limits the number of + channels with active server-side subsystems that are + accepted.</p> + <p> + Own Id: OTP-13036</p> + </item> + </list> + </section> + +</section> + +<section><title>Ssh 4.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Send an understandable disconnect message when the key + exchange phase can't find a common algorithm. There are + also some test cases added.</p> + <p> + Own Id: OTP-11531</p> + </item> + <item> + <p> + The third parameter in <c>ssh_sftp:write_file</c> is now + accepting iolists again. Unicode handling adjusted.</p> + <p> + Own Id: OTP-12853 Aux Id: seq12891 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + First part of ssh test suite re-organization and + extension.</p> + <p> + Own Id: OTP-12230</p> + </item> + <item> + <p> + The key exchange algorithms 'ecdh-sha2-nistp256', + 'ecdh-sha2-nistp384' and 'ecdh-sha2-nistp521' are + implemented. See RFC 5656.</p> + <p> + This raises the security level considerably.</p> + <p> + Own Id: OTP-12622 Aux Id: OTP-12671, OTP-12672 </p> + </item> + <item> + <p> + The key exchange algorithm 'diffie-hellman-group14-sha1' + is implemented. See RFC 4253.</p> + <p> + This raises the security level.</p> + <p> + Own Id: OTP-12671 Aux Id: OTP-12672, OTP-12622 </p> + </item> + <item> + <p> + The key exchange algorithms + 'diffie-hellman-group-exchange-sha1' and + 'diffie-hellman-group-exchange-sha256' are implemented. + See RFC 4419.</p> + <p> + This raises the security level.</p> + <p> + Own Id: OTP-12672 Aux Id: OTP-12671, OTP-12622 </p> + </item> + <item> + <p> + Adding random length extra padding as recommended in RFC + 4253 section 6.</p> + <p> + Own Id: OTP-12831</p> + </item> + <item> + <p> + New test library for low-level protocol testing. There is + also a test suite using it for some preliminary tests. + The intention is to build on that for more testing of + individual ssh messages. See + <c>lib/ssh/test/ssh_trpt_test_lib.erl</c> and + <c>ssh_protocol_SUITE.erl</c> in the same directory.</p> + <p> + Own Id: OTP-12858</p> + </item> + <item> + <p> + Increased default values for + diffie-hellman-group-exchange-sha* to Min = 1024, N = + 6144, Max = 8192.</p> + <p> + Added 6144 and 8192 bit default gex groups.</p> + <p> + Own Id: OTP-12937</p> + </item> + <item> + <p> + The mac algorithm 'hmac-sha2-512' is implemented. See RFC + 6668.</p> + <p> + Own Id: OTP-12938</p> + </item> + </list> + </section> + +</section> + <section><title>Ssh 4.0</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -82,9 +435,9 @@ <p> Thanks to Simon Cornish</p> <p> - Own Id: OTP-12760 Aux Id: <a + Own Id: OTP-12760 Aux Id: <url href="https://github.com/erlang/otp/pull/715">pull req - 715</a> </p> + 715</url> </p> </item> <item> <p> @@ -250,13 +603,13 @@ </item> <item> <p> - Made Codenomicon Defensics test suite pass: <list> + Made Codenomicon Defensics test suite pass:</p> <list> <item>limit number of algorithms in kexinit message</item> <item>check 'e' and 'f' parameters in kexdh</item> <item>implement 'keyboard-interactive' user authentication on server side</item> <item> return plain text message to bad version exchange message</item> - </list></p> + </list> <p> Own Id: OTP-12784</p> </item> diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index d24025ca4d..850557444d 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2004</year><year>2014</year> + <year>2004</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,28 +32,33 @@ <modulesummary>Main API of the ssh application</modulesummary> <description> <p>Interface module for the <c>ssh</c> application.</p> + <p>See <seealso marker="ssh:SSH_app#supported">ssh(6)</seealso> for details of supported version, + algorithms and unicode support.</p> </description> - <section> - <title>SSH</title> - <marker id="supported"/> - <list type="bulleted"> - <item>For application dependencies see <seealso marker="SSH_app"> ssh(6)</seealso> </item> - <item>Supported SSH version is 2.0.</item> - <item>Supported public key algorithms: ssh-rsa and ssh-dss.</item> - <item>Supported MAC algorithms: hmac-sha2-256 and hmac-sha1.</item> - <item>Supported encryption algorithms: aes128-ctr, aes128-cb and 3des-cbc.</item> - <item>Supported key exchange algorithms: diffie-hellman-group1-sha1.</item> - <item>Supported compression algorithms: none, zlib, [email protected],</item> - <item>Supports unicode filenames if the emulator and the underlaying OS support it. - See section DESCRIPTION in the - <seealso marker="kernel:file">file</seealso> manual page in <c>kernel</c> - for information about this subject.</item> - <item>Supports unicode in shell and CLI.</item> - </list> - + <section> + <title>OPTIONS</title> + <p>The exact behaviour of some functions can be adjusted with the use of options which are documented together + with the functions. Generally could each option be used at most one time in each function call. If given two or more + times, the effect is not predictable unless explicitly documented.</p> + <p>The options are of different kinds:</p> + <taglist> + <tag>Limits</tag> + <item><p>which alters limits in the system, for example number of simultaneous login attempts.</p></item> + + <tag>Timeouts</tag> + <item><p>which give some defined behaviour if too long time elapses before a given event or action, + for example time to wait for an answer.</p></item> + + <tag>Callbacks</tag> + <item><p>which gives the caller of the function the possibility to execute own code on some events, + for example calling an own logging function or to perform an own login function</p></item> + + <tag>Behaviour</tag> + <item><p>which changes the systems behaviour.</p></item> + </taglist> </section> - + <section> <title>DATA TYPES</title> <p>Type definitions that are used more than once in @@ -80,6 +85,15 @@ <item><p><c>atom()</c> - Name of the Erlang module implementing the subsystem using the <c>ssh_channel</c> behavior, see <seealso marker="ssh_channel">ssh_channel(3)</seealso></p></item> + <tag><c>key_cb() =</c></tag> + <item> + <p><c>atom() | {atom(), list()}</c></p> + <p><c>atom()</c> - Name of the erlang module implementing the behaviours + <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso> or + <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso> as the + case maybe.</p> + <p><c>list()</c> - List of options that can be passed to the callback module.</p> + </item> <tag><c>channel_init_args() =</c></tag> <item><p><c>list()</c></p></item> @@ -192,26 +206,25 @@ <tag><c><![CDATA[{public_key_alg, 'ssh-rsa' | 'ssh-dss'}]]></c></tag> <item> <note> - <p>This option is kept for compatibility. It is ignored if the <c>preferred_algorithms</c> - option is used. The equivalence of <c>{public_key_alg,'ssh-dss'}</c> is - <c>{preferred_algorithms, [{public_key,['ssh-dss','ssh-rsa']}]}</c>.</p> + <p>This option will be removed in OTP 20, but is kept for compatibility. It is ignored if + the preferred <c>pref_public_key_algs</c> option is used.</p> </note> <p>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 <c><![CDATA['ssh-rsa']]></c> first.</p> + the other algorithm is tried. If <c>{public_key_alg, 'ssh-rsa'}</c> is set, it is translated + to <c>{pref_public_key_algs, ['ssh-rsa','ssh-dss']}</c>. If it is + <c>{public_key_alg, 'ssh-dss'}</c>, it is translated + to <c>{pref_public_key_algs, ['ssh-dss','ssh-rsa']}</c>. + </p> </item> <tag><c><![CDATA[{pref_public_key_algs, list()}]]></c></tag> <item> - <note> - <p>This option is kept for compatibility. It is ignored if the <c>preferred_algorithms</c> - option is used. The equivalence of <c>{pref_public_key_algs,['ssh-dss']}</c> is - <c>{preferred_algorithms, [{public_key,['ssh-dss']}]}</c>.</p> - </note> - <p>List of public key algorithms to try to use. - <c>'ssh-rsa'</c> and <c>'ssh-dss'</c> are available. - Overrides <c><![CDATA[{public_key_alg, 'ssh-rsa' | 'ssh-dss'}]]></c></p> + <p>List of user (client) public key algorithms to try to use.</p> + <p>The default value is + <c><![CDATA[['ssh-rsa','ssh-dss','ecdsa-sha2-nistp256','ecdsa-sha2-nistp384','ecdsa-sha2-nistp521'] ]]></c> + </p> + <p>If there is no public key of a specified type available, the corresponding entry is ignored.</p> </item> <tag><c><![CDATA[{preferred_algorithms, algs_list()}]]></c></tag> @@ -219,6 +232,7 @@ <p>List of algorithms to use in the algorithm negotiation. The default <c>algs_list()</c> can be obtained from <seealso marker="#default_algorithms/0">default_algorithms/0</seealso>. </p> + <p>If an alg_entry() is missing in the algs_list(), the default value is used for that entry.</p> <p>Here is an example of this option:</p> <code> {preferred_algorithms, @@ -229,9 +243,9 @@ {compression,[none,zlib]} } </code> - <p>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.</p> + <p>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) is implicit but public_key is set explicitly.</p> <warning> <p>Changing the values can make a connection less secure. Do not change unless you @@ -240,6 +254,13 @@ kex is implicit but public_key is set explicitly.</p> </warning> </item> + <tag><c><![CDATA[{dh_gex_limits,{Min=integer(),I=integer(),Max=integer()}}]]></c></tag> + <item> + <p>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 <c>{1024, 6144, 8192}</c>. + </p> + </item> + <tag><c><![CDATA[{connect_timeout, timeout()}]]></c></tag> <item> <p>Sets a time-out on the transport layer @@ -260,11 +281,13 @@ kex is implicit but public_key is set explicitly.</p> password, if the password authentication method is attempted.</p> </item> - <tag><c><![CDATA[{key_cb, atom()}]]></c></tag> + <tag><c><![CDATA[{key_cb, key_cb()}]]></c></tag> <item> - <p>Module implementing the behaviour - <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso>. - Can be used to customize the handling of public keys. + <p>Module implementing the behaviour <seealso + marker="ssh_client_key_api">ssh_client_key_api</seealso>. Can be used to + customize the handling of public keys. If callback options are provided + along with the module name, they are made available to the callback + module via the options passed to it under the key 'key_cb_private'. </p> </item> <tag><c><![CDATA[{quiet_mode, atom() = boolean()}]]></c></tag> @@ -395,10 +418,10 @@ kex is implicit but public_key is set explicitly.</p> <c><![CDATA["publickey,keyboard-interactive,password"]]></c></p> </item> - <tag><c><![CDATA[{auth_method_kb_interactive_data, PromptTexts}]]> - <br/>where: - <br/>PromptTexts = kb_int_tuple() | fun(Peer::{IP::tuple(),Port::integer()}, User::string(), Service::string()) -> kb_int_tuple() - <br/>kb_int_tuple() = {Name::string(), Instruction::string(), Prompt::string(), Echo::boolean()}</c> + <tag><c><![CDATA[{auth_method_kb_interactive_data, PromptTexts}]]></c> + <br/><c>where:</c> + <br/><c>PromptTexts = kb_int_tuple() | fun(Peer::{IP::tuple(),Port::integer()}, User::string(), Service::string()) -> kb_int_tuple()</c> + <br/><c>kb_int_tuple() = {Name::string(), Instruction::string(), Prompt::string(), Echo::boolean()}</c> </tag> <item> <p>Sets the text strings that the daemon sends to the client for presentation to the user when using <c>keyboar-interactive</c> 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.</p> @@ -428,6 +451,7 @@ kex is implicit but public_key is set explicitly.</p> <p>List of algorithms to use in the algorithm negotiation. The default <c>algs_list()</c> can be obtained from <seealso marker="#default_algorithms/0">default_algorithms/0</seealso>. </p> + <p>If an alg_entry() is missing in the algs_list(), the default value is used for that entry.</p> <p>Here is an example of this option:</p> <code> {preferred_algorithms, @@ -438,9 +462,9 @@ kex is implicit but public_key is set explicitly.</p> {compression,[none,zlib]} } </code> - <p>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.</p> + <p>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) is implicit but public_key is set explicitly.</p> <warning> <p>Changing the values can make a connection less secure. Do not change unless you @@ -449,12 +473,82 @@ kex is implicit but public_key is set explicitly.</p> </warning> </item> - <tag><c><![CDATA[{pwdfun, fun(User::string(), password::string()) -> boolean()}]]></c></tag> + <tag><c><![CDATA[{dh_gex_groups, [{Size=integer(),G=integer(),P=integer()}] | {file,filename()} {ssh_moduli_file,filename()} }]]></c></tag> + <item> + <p>Defines the groups the server may choose among when diffie-hellman-group-exchange is negotiated. + See RFC 4419 for details. The three variants of this option are: + </p> + <taglist> + <tag><c>{Size=integer(),G=integer(),P=integer()}</c></tag> + <item>The groups are given explicitly in this list. There may be several elements with the same <c>Size</c>. + In such a case, the server will choose one randomly in the negotiated Size. + </item> + <tag><c>{file,filename()}</c></tag> + <item>The file must have one or more three-tuples <c>{Size=integer(),G=integer(),P=integer()}</c> + terminated by a dot. The file is read when the daemon starts. + </item> + <tag><c>{ssh_moduli_file,filename()}</c></tag> + <item>The file must be in + <seealso marker="public_key:public_key#dh_gex_group/4">ssh-keygen moduli file format</seealso>. + The file is read when the daemon starts. + </item> + </taglist> + <p>The default list is fetched from the + <seealso marker="public_key:public_key#dh_gex_group/4">public_key</seealso> application. + </p> + </item> + + <tag><c><![CDATA[{dh_gex_limits,{Min=integer(),Max=integer()}}]]></c></tag> + <item> + <p>Limits what a client can ask for in diffie-hellman-group-exchange. + The limits will be + <c>{MaxUsed = min(MaxClient,Max), MinUsed = max(MinClient,Min)}</c> where <c>MaxClient</c> and + <c>MinClient</c> are the values proposed by a connecting client. + </p> + <p>The default value is <c>{0,infinity}</c>. + </p> + <p>If <c>MaxUsed < MinUsed</c> in a key exchange, it will fail with a disconnect. + </p> + <p>See RFC 4419 for the function of the Max and Min values.</p> + </item> + + <tag><c><![CDATA[{pwdfun, fun(User::string(), Password::string(), PeerAddress::{ip_adress(),port_number()}, State::any()) -> boolean() | disconnect | {boolean(),any()} }]]></c></tag> + <item> + <p>Provides a function for password validation. This could used for calling an external system or if + passwords should be stored as a hash. The fun returns: + </p> + <list type="bulleted"> + <item><c>true</c> if the user and password is valid and</item> + <item><c>false</c> otherwise.</item> + </list> + <p>This fun can also be used to make delays in authentication tries for example by calling + <seealso marker="stdlib:timer#sleep/1">timer:sleep/1</seealso>. To facilitate counting of failed tries + the <c>State</c> variable could be used. This state is per connection only. The first time the pwdfun + is called for a connection, the <c>State</c> variable has the value <c>undefined</c>. + The pwdfun can return - in addition to the values above - a new state + as: + </p> + <list type="bulleted"> + <item><c>{true, NewState:any()}</c> if the user and password is valid or</item> + <item><c>{false, NewState:any()}</c> if the user or password is invalid</item> + </list> + <p>A third usage is to block login attempts from a missbehaving peer. The <c>State</c> described above + can be used for this. In addition to the responses above, the following return value is introduced: + </p> + <list type="bulleted"> + <item><c>disconnect</c> if the connection should be closed immediately after sending a SSH_MSG_DISCONNECT + message.</item> + </list> + </item> + + <tag><c><![CDATA[{pwdfun, fun(User::string(), Password::string()) -> boolean()}]]></c></tag> <item> <p>Provides a function for password validation. This function is called with user and password as strings, and returns <c><![CDATA[true]]></c> if the password is valid and <c><![CDATA[false]]></c> otherwise.</p> + <p>This option (<c>{pwdfun,fun/2}</c>) is the same as a subset of the previous + (<c>{pwdfun,fun/4}</c>). It is kept for compatibility.</p> </item> <tag><c><![CDATA[{negotiation_timeout, integer()}]]></c></tag> @@ -485,6 +579,15 @@ kex is implicit but public_key is set explicitly.</p> </p> </item> + <tag><c><![CDATA[{max_channels, pos_integer()}]]></c></tag> + <item> + <p>The maximum number of channels with active remote subsystem that are accepted for + each connection to this daemon</p> + <p>By default, this option is not set. This means that the number is not limited. + </p> + </item> + + <tag><c><![CDATA[{parallel_login, boolean()}]]></c></tag> <item> <p>If set to false (the default value), only one login is handled at a time. @@ -516,11 +619,13 @@ kex is implicit but public_key is set explicitly.</p> </p> </item> - <tag><c><![CDATA[{key_cb, atom()}]]></c></tag> + <tag><c><![CDATA[{key_cb, key_cb()}]]></c></tag> <item> - <p>Module implementing the behaviour - <seealso marker="ssh_server_key_api">ssh_server_key_api</seealso>. - Can be used to customize the handling of public keys. + <p>Module implementing the behaviour <seealso + marker="ssh_server_key_api">ssh_server_key_api</seealso>. Can be used to + customize the handling of public keys. If callback options are provided + along with the module name, they are made available to the callback + module via the options passed to it under the key 'key_cb_private'. </p> </item> diff --git a/lib/ssh/doc/src/ssh_app.xml b/lib/ssh/doc/src/ssh_app.xml index 4c85585820..f6ce44c015 100644 --- a/lib/ssh/doc/src/ssh_app.xml +++ b/lib/ssh/doc/src/ssh_app.xml @@ -4,7 +4,7 @@ <appref> <header> <copyright> - <year>2012</year><year>2013</year> + <year>2012</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -41,15 +41,18 @@ <section> <title>DEPENDENCIES</title> - <p>The <c>ssh</c> application uses the applications <c>public_key</c> and - <c>crypto</c> to handle public keys and encryption. Hence, these + <p>The <c>ssh</c> application uses the applications + <seealso marker="public_key:public_key">public_key</seealso> and + <seealso marker="crypto:crypto">crypto</seealso> + to handle public keys and encryption. Hence, these applications must be loaded for the <c>ssh</c> application to work. In an embedded environment this means that they must be started with - <c>application:start/[1,2]</c> before the <c>ssh</c> application is started. + <seealso marker="kernel:application#start/1">application:start/1,2</seealso> before the + <c>ssh</c> application is started. </p> </section> - <section> + <section> <title>CONFIGURATION</title> <p>The <c>ssh</c> application does not have an application- @@ -62,10 +65,13 @@ <item><c>authorized_keys2</c></item> <item><c>id_dsa</c></item> <item><c>id_rsa</c></item> + <item><c>id_ecdsa</c></item> <item><c>ssh_host_dsa_key</c></item> <item><c>ssh_host_rsa_key</c></item> + <item><c>ssh_host_ecdsa_key</c></item> </list> <p>By default, <c>ssh</c> looks for <c>id_dsa</c>, <c>id_rsa</c>, + <c>id_ecdsa_key</c>, <c>known_hosts</c>, and <c>authorized_keys</c> in ~/.ssh, and for the host key files in <c>/etc/ssh</c>. These locations can be changed by the options <c>user_dir</c> and <c>system_dir</c>. @@ -79,7 +85,7 @@ </section> <section> <title>Public Keys</title> - <p><c>id_dsa</c> and <c>id_rsa</c> are the users private key files. + <p><c>id_dsa</c>, <c>id_rsa</c> and <c>id_ecdsa</c> are the users private key files. Notice that the public key is part of the private key so the <c>ssh</c> application does not use the <c>id_<*>.pub</c> files. These are for the user's convenience when it is needed to convey the user's @@ -104,8 +110,8 @@ <section> <title>Host Keys</title> <p>RSA and DSA host keys are supported and are - expected to be found in files named <c>ssh_host_rsa_key</c> and - <c>ssh_host_dsa_key</c>. + expected to be found in files named <c>ssh_host_rsa_key</c>, + <c>ssh_host_dsa_key</c> and <c>ssh_host_ecdsa_key</c>. </p> </section> <section> @@ -114,6 +120,198 @@ </section> <section> + <marker id="supported"/> + <title>SUPPORTED SPECIFICATIONS AND STANDARDS</title> + <p>The supported SSH version is 2.0.</p> + </section> + <section> + <title>Algorithms</title> + <p>The actual set of algorithms may vary depending on which OpenSSL crypto library that is installed on the machine. + For the list on a particular installation, use the command + <seealso marker="ssh:ssh#default_algorithms/0">ssh:default_algorithms/0</seealso>. + The user may override the default algorithm configuration both on the server side and the client side. + See the option <c>preferred_algorithms</c> in the <seealso marker="ssh:ssh#daemon/1">ssh:daemon/1,2,3</seealso> and + <seealso marker="ssh:ssh#connect/3">ssh:connect/3,4</seealso> functions. + </p> + + <p>Supported algorithms are:</p> + + <taglist> + <tag>Key exchange algorithms</tag> + <item> + <list type="bulleted"> + <item>ecdh-sha2-nistp256</item> + <item>ecdh-sha2-nistp384</item> + <item>ecdh-sha2-nistp521</item> + <item>diffie-hellman-group-exchange-sha1</item> + <item>diffie-hellman-group-exchange-sha256</item> + <item>diffie-hellman-group14-sha1</item> + <item>diffie-hellman-group1-sha1</item> + </list> + </item> + + <tag>Public key algorithms</tag> + <item> + <list type="bulleted"> + <item>ecdsa-sha2-nistp256</item> + <item>ecdsa-sha2-nistp384</item> + <item>ecdsa-sha2-nistp521</item> + <item>ssh-rsa</item> + <item>ssh-dss</item> + </list> + </item> + + <tag>MAC algorithms</tag> + <item> + <list type="bulleted"> + <item>hmac-sha2-256</item> + <item>hmac-sha2-512</item> + <item>hmac-sha1</item> + </list> + </item> + + <tag>Encryption algorithms (ciphers)</tag> + <item> + <list type="bulleted"> + <item>[email protected] (AEAD_AES_128_GCM)</item> + <item>[email protected] (AEAD_AES_256_GCM)</item> + <item>aes128-ctr</item> + <item>aes192-ctr</item> + <item>aes256-ctr</item> + <item>aes128-cbc</item> + <item>3des-cbc</item> + </list> + <p>Following the internet de-facto standard, the cipher and mac algorithm AEAD_AES_128_GCM is selected when the + cipher [email protected] is negotiated. The cipher and mac algorithm AEAD_AES_256_GCM is selected when the + cipher [email protected] is negotiated. + </p> + <p>See the text at the description of <seealso marker="#rfc5647_note">the rfc 5647 further down</seealso> + for more information. + </p> + </item> + + <tag>Compression algorithms</tag> + <item> + <list type="bulleted"> + <item>none</item> + <item>[email protected]</item> + <item>zlib</item> + </list> + </item> + </taglist> + </section> + <section> + <title>Unicode support</title> + <p>Unicode filenames are supported if the emulator and the underlaying OS support it. See section DESCRIPTION in the + <seealso marker="kernel:file">file</seealso> manual page in <c>kernel</c> for information about this subject. + </p> + <p>The shell and the cli both support unicode. + </p> + </section> + + <section> + <title>Rfcs</title> + <p>The following rfc:s are supported:</p> + <list type="bulleted"> + <item><url href="https://tools.ietf.org/html/rfc4251">RFC 4251</url>, The Secure Shell (SSH) Protocol Architecture. + <p>Except</p> + <list type="bulleted"> + <item>9.4.6 Host-Based Authentication</item> + <item>9.5.2 Proxy Forwarding</item> + <item>9.5.3 X11 Forwarding</item> + </list> + <p/> + </item> + + <item><url href="https://tools.ietf.org/html/rfc4252">RFC 4252</url>, The Secure Shell (SSH) Authentication Protocol. + <p>Except</p> + <list type="bulleted"> + <item>9. Host-Based Authentication: "hostbased"</item> + </list> + <p/> + </item> + + <item><url href="https://tools.ietf.org/html/rfc4253">RFC 4253</url>, The Secure Shell (SSH) Transport Layer Protocol. + <p></p> + </item> + + <item><url href="https://tools.ietf.org/html/rfc4254">RFC 4254</url>, The Secure Shell (SSH) Connection Protocol. + <p>Except</p> + <list type="bulleted"> + <item>6.3. X11 Forwarding</item> + <item>7. TCP/IP Port Forwarding</item> + </list> + <p/> + </item> + + <item><url href="https://tools.ietf.org/html/rfc4256">RFC 4256</url>, Generic Message Exchange Authentication for + the Secure Shell Protocol (SSH). + <p>Except</p> + <list type="bulleted"> + <item><c>num-prompts > 1</c></item> + <item>password changing</item> + <item>other identification methods than userid-password</item> + </list> + <p/> + </item> + + <item><url href="https://tools.ietf.org/html/rfc4419">RFC 4419</url>, Diffie-Hellman Group Exchange for + the Secure Shell (SSH) Transport Layer Protocol. + <p/> + </item> + + <item><url href="https://tools.ietf.org/html/rfc4716">RFC 4716</url>, The Secure Shell (SSH) Public Key File Format. + <p/> + </item> + + <item><url href="https://tools.ietf.org/html/rfc5647">RFC 5647</url>, AES Galois Counter Mode for + the Secure Shell Transport Layer Protocol. + <p><marker id="rfc5647_note"/>There is an ambiguity in the synchronized selection of cipher and mac algorithm. + This is resolved by OpenSSH in the ciphers [email protected] and [email protected] which are implemented. + If the explicit ciphers and macs AEAD_AES_128_GCM or AEAD_AES_256_GCM are needed, + they could be enabled with the option preferred_algorithms. + </p> + <warning> + <p> + If the client or the server is not Erlang/OTP, it is the users responsibility to check that + other implementation has the same interpretation of AEAD_AES_*_GCM as the Erlang/OTP SSH before + enabling them. The aes*[email protected] variants are always safe to use since they lack the + ambiguity. + </p> + </warning> + <p>The second paragraph in section 5.1 is resolved as:</p> + <list type="ordered"> + <item>If the negotiated cipher is AEAD_AES_128_GCM, the mac algorithm is set to AEAD_AES_128_GCM.</item> + <item>If the negotiated cipher is AEAD_AES_256_GCM, the mac algorithm is set to AEAD_AES_256_GCM.</item> + <item>If the mac algorithm is AEAD_AES_128_GCM, the cipher is set to AEAD_AES_128_GCM.</item> + <item>If the mac algorithm is AEAD_AES_256_GCM, the cipher is set to AEAD_AES_256_GCM.</item> + </list> + <p>The first rule that matches when read in order from the top is applied</p> + </item> + + <item><url href="https://tools.ietf.org/html/rfc5656">RFC 5656</url>, Elliptic Curve Algorithm Integration in + the Secure Shell Transport Layer. + <p>Except</p> + <list type="bulleted"> + <item>5. ECMQV Key Exchange</item> + <item>6.4. ECMQV Key Exchange and Verification Method Name</item> + <item>7.2. ECMQV Message Numbers</item> + <item>10.2. Recommended Curves</item> + </list> + <p/> + </item> + + <item><url href="https://tools.ietf.org/html/rfc6668">RFC 6668</url>, SHA-2 Data Integrity Verification for + the Secure Shell (SSH) Transport Layer Protocol + <p>Comment: Defines hmac-sha2-256 and hmac-sha2-512 + </p> + </item> + + </list> + + </section> + + <section> <title>SEE ALSO</title> <p><seealso marker="kernel:application">application(3)</seealso></p> </section> diff --git a/lib/ssh/doc/src/ssh_connection.xml b/lib/ssh/doc/src/ssh_connection.xml index 9a7bb09b12..150d46a9a2 100644 --- a/lib/ssh/doc/src/ssh_connection.xml +++ b/lib/ssh/doc/src/ssh_connection.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2008</year> - <year>2014</year> + <year>2015</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -31,15 +31,15 @@ <rev></rev> </header> <module>ssh_connection</module> - <modulesummary>This module provides API functions to send - <url href="http://www.ietf.org/rfc/rfc4254.txt"> SSH Connection Protocol </url> - events to the other side of an SSH channel. + <modulesummary> + This module provides API functions to send SSH Connection Protocol + events to the other side of an SSH channel. </modulesummary> <description> - <p>The SSH Connection Protocol is used by clients and servers, - that is, SSH channels, to communicate over the SSH connection. The - API functions in this module send SSH Connection Protocol events, + <p>The <url href="http://www.ietf.org/rfc/rfc4254.txt">SSH Connection Protocol</url> + is used by clients and servers, that is, SSH channels, to communicate over the + SSH connection. The API functions in this module send SSH Connection Protocol events, which are received as messages by the remote channel. If the receiving channel is an Erlang process, the messages have the format @@ -373,6 +373,9 @@ <desc> <p>Is to be called by client- and server-channel processes to send data to each other. </p> + <p>The function <seealso marker="ssh:ssh_connection#subsystem/4">subsystem/4</seealso> and subsequent + calls of <c>send/3,4,5</c> must be executed in the same process. + </p> </desc> </func> @@ -454,6 +457,9 @@ <p>Is to be called by a client-channel process for requesting to execute a predefined subsystem on the server. </p> + <p>The function <c>subsystem/4</c> and subsequent calls of + <seealso marker="ssh:ssh_connection#send/3">send/3,4,5</seealso> must be executed in the same process. + </p> </desc> </func> diff --git a/lib/ssh/doc/src/ssh_server_key_api.xml b/lib/ssh/doc/src/ssh_server_key_api.xml index efb2c436e8..a0694ca8d9 100644 --- a/lib/ssh/doc/src/ssh_server_key_api.xml +++ b/lib/ssh/doc/src/ssh_server_key_api.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2012</year> - <year>2013</year> + <year>2015</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -75,7 +75,7 @@ <d>Host key algorithm. Is to support <c>'ssh-rsa' | 'ssh-dss'</c>, but more algorithms can be handled.</d> <v>DaemonOptions = proplists:proplist()</v> - <d>Options provided to <seealso marker="ssh#daemon-2">ssh:daemon/[2,3]</seealso>.</d> + <d>Options provided to <seealso marker="ssh#daemon-2">ssh:daemon/[2,3]</seealso>.</d> <v>Key = private_key()</v> <d>Private key of the host matching the <c>Algorithm</c>.</d> <v>Reason = term()</v> diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml index 17800fac5d..c6ca0f161a 100644 --- a/lib/ssh/doc/src/ssh_sftp.xml +++ b/lib/ssh/doc/src/ssh_sftp.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2005</year><year>2014</year> + <year>2005</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -61,20 +61,23 @@ <funcs> <func> - <name>apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Error}</name> - <v>ChannelPid = pid()</v> - <v>Handle = term()</v> - <v>Position = integer()</v> - <v>Len = integer()</v> - <v>N = term()</v> - <v>Reason = term()</v> - - <desc><p>The <c><![CDATA[apread]]></c> function reads from a specified position, - combining the <c><![CDATA[position]]></c> and <c><![CDATA[aread]]></c> functions.</p> + <name>apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Reason}</name> + <fsummary>Reads asynchronously from an open file.</fsummary> + <type> + <v>ChannelPid = pid()</v> + <v>Handle = term()</v> + <v>Position = integer()</v> + <v>Len = integer()</v> + <v>N = term()</v> + <v>Reason = term()</v> + </type> + + <desc><p>The <c><![CDATA[apread]]></c> function reads from a specified position, + combining the <c><![CDATA[position]]></c> and <c><![CDATA[aread]]></c> functions.</p> <p><seealso marker="#apread-4">ssh_sftp:apread/4</seealso></p> </desc> - </func> - - <func> + </func> + + <func> <name>apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason}</name> <fsummary>Writes asynchronously to an open file.</fsummary> <type> diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml index 91185a0f6e..6826f20fb3 100644 --- a/lib/ssh/doc/src/using_ssh.xml +++ b/lib/ssh/doc/src/using_ssh.xml @@ -234,7 +234,7 @@ <title>SFTP Client with TAR Compression and Encryption</title> <p>Example of writing and then reading a tar file follows:</p> - <code type="erlang"> + <code type="erl"> {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write]), ok = erl_tar:add(HandleWrite, .... ), ok = erl_tar:add(HandleWrite, .... ), @@ -249,10 +249,10 @@ </code> <p>The previous write and read example can be extended with encryption and decryption as follows:</p> - <code type="erlang"> + <code type="erl"> %% First three parameters depending on which crypto type we select: Key = <<"This is a 256 bit key. abcdefghi">>, -Ivec0 = crypto:rand_bytes(16), +Ivec0 = crypto:strong_rand_bytes(16), DataSize = 1024, % DataSize rem 16 = 0 for aes_cbc %% Initialization of the CryptoState, in this case it is the Ivector. |