diff options
Diffstat (limited to 'lib/ssh/doc/src')
| -rw-r--r-- | lib/ssh/doc/src/notes.xml | 19 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh.xml | 164 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_channel.xml | 32 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_client_key_api.xml | 20 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_connection.xml | 42 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_server_key_api.xml | 24 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_sftp.xml | 4 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_sftpd.xml | 16 | 
8 files changed, 227 insertions, 94 deletions
| diff --git a/lib/ssh/doc/src/notes.xml b/lib/ssh/doc/src/notes.xml index 41885c684c..579a3ae4a8 100644 --- a/lib/ssh/doc/src/notes.xml +++ b/lib/ssh/doc/src/notes.xml @@ -29,6 +29,25 @@      <file>notes.xml</file>    </header> +<section><title>Ssh 3.2.3</title> + +    <section><title>Fixed Bugs and Malfunctions</title> +      <list> +        <item> +          <p> +	    A new option for handling the SSH_MSG_DEBUG message's +	    printouts. A fun could be given in the options that will +	    be called whenever the SSH_MSG_DEBUG message arrives. +	    This enables the user to format the printout or just +	    discard it.</p> +          <p> +	    Own Id: OTP-12738 Aux Id: seq12860 </p> +        </item> +      </list> +    </section> + +</section> +  <section><title>Ssh 3.2.2</title>      <section><title>Improvements and New Features</title> diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index d49d3ac2a7..cf58806aa8 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -35,13 +35,15 @@     <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> @@ -57,29 +59,40 @@      this module, or abstractions to indicate the intended use of the data      type, or both:</p>      <taglist> -      <tag><c>boolean()</c></tag> -      <item><p>= <c>true | false</c></p></item> -      <tag><c>string()</c></tag> -      <item><p>= <c>[byte()]</c></p></item> -      <tag><c>ssh_daemon_ref()</c></tag> -      <item><p>Opaque to the user, -    returned by <c>ssh:daemon/[1,2,3]</c></p></item> -      <tag><c>ssh_connection_ref()</c></tag> -      <item><p>Opaque to the user, -    returned by <c>ssh:connect/3</c></p></item> -      <tag><c>ip_address()</c></tag> +      <tag><c>boolean() =</c></tag> +      <item><p><c>true | false</c></p></item> +      <tag><c>string() =</c></tag> +      <item><p><c>[byte()]</c></p></item> +      <tag><c>ssh_daemon_ref() =</c></tag> +      <item><p>opaque() - +      as returned by <c>ssh:daemon/[1,2,3]</c></p></item> +      <tag><c>ssh_connection_ref() =</c></tag> +      <item><p>opaque() - as returned by <c>ssh:connect/3</c></p></item> +      <tag><c>ip_address() =</c></tag>        <item><p><c>inet::ip_address</c></p></item> -      <tag><c>subsystem_spec()</c></tag> -      <item><p>= <c>{subsystem_name(), -    {channel_callback(), channel_init_args()}}</c></p></item> -      <tag><c>subsystem_name()</c></tag> -      <item><p>= <c>string()</c></p></item> -      <tag><c>channel_callback()</c></tag> -      <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>channel_init_args()</c></tag> -      <item><p>= <c>list()</c></p></item> +      <tag><c>subsystem_spec() =</c></tag> +      <item><p><c>{subsystem_name(), +      {channel_callback(), channel_init_args()}}</c></p></item> +      <tag><c>subsystem_name() =</c></tag> +      <item><p><c>string()</c></p></item> +      <tag><c>channel_callback() =</c></tag> +      <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>channel_init_args() =</c></tag> +      <item><p><c>list()</c></p></item> + +      <tag><c>algs_list() =</c></tag> +      <item><p><c>list( alg_entry() )</c></p></item> + +      <tag><c>alg_entry() =</c></tag> +      <item><p><c>{kex, simple_algs()} | {public_key, simple_algs()} | {cipher, double_algs()} | {mac, double_algs()} | {compression, double_algs()}</c></p></item> + +      <tag><c>simple_algs() =</c></tag> +      <item><p><c>list( atom() )</c></p></item> +       +      <tag><c>double_algs() =</c></tag> +      <item><p><c>[{client2serverlist,simple_algs()},{server2client,simple_algs()}] | simple_algs()</c></p></item>       </taglist>  </section> @@ -161,19 +174,58 @@  	    and <c>password</c>. However, those optins are not always desirable  	    to use from a security point of view.</p>  	  </item> +  	  <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> +	    </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>  	  </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>  	  </item> + +	  <tag><c><![CDATA[{preferred_algorithms, algs_list()}]]></c></tag> +	  <item> +            <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>Here is an example of this option:</p> +	<code> +{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]} +} +</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> + +        <warning> +	  <p>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.</p> +	</warning> +	  </item> +  	  <tag><c><![CDATA[{connect_timeout, timeout()}]]></c></tag>  	  <item>  	    <p>Sets a time-out on the transport layer @@ -227,6 +279,13 @@  	  <item>  	  <p>Sets a time-out on a connection when no channels are active.  	  Defaults to <c>infinity</c>.</p></item> +	  <tag><c><![CDATA[{ssh_msg_debug_fun, fun(ConnectionRef::ssh_connection_ref(), AlwaysDisplay::boolean(), Msg::binary(), LanguageTag::binary()) -> _}]]></c></tag> +	  <item> +	    <p>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 <c>ConnectionRef</c> is the reference to the connection on which the message arrived. The return value from the fun is not checked.</p> +	    <p>The default behaviour is ignore the message. +	    To get a printout for each message with <c>AlwaysDisplay = true</c>, use for example <c>{ssh_msg_debug_fun, fun(_,true,M,_)-> io:format("DEBUG: ~p~n", [M]) end}</c></p> +	  </item> +  	</taglist>        </desc>         </func> @@ -335,6 +394,33 @@                user. From a security perspective this option makes  	      the server very vulnerable.</p>  	  </item> + +	  <tag><c><![CDATA[{preferred_algorithms, algs_list()}]]></c></tag> +	  <item> +            <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>Here is an example of this option:</p> +	<code> +{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]} +} +</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> + +        <warning> +	  <p>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.</p> +	</warning> +	  </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 @@ -427,10 +513,38 @@  	  <item>  	    <p>Provides a fun to implement your own logging when a user disconnects from the server.</p>  	  </item> -        </taglist> -      </desc> + +	  <tag><c><![CDATA[{ssh_msg_debug_fun, fun(ConnectionRef::ssh_connection_ref(), AlwaysDisplay::boolean(), Msg::binary(), LanguageTag::binary()) -> _}]]></c></tag> +	  <item> +	    <p>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 <c>ConnectionRef</c> is the reference to the connection on which the message arrived. The return value from the fun is not checked.</p> +	    <p>The default behaviour is ignore the message. +	    To get a printout for each message with <c>AlwaysDisplay = true</c>, use for example <c>{ssh_msg_debug_fun, fun(_,true,M,_)-> io:format("DEBUG: ~p~n", [M]) end}</c></p> +	  </item> + +	</taglist> +      </desc>         </func> +    <func> +      <name>default_algorithms() -> algs_list()</name> +      <fsummary>Get a list declaring the supported algorithms</fsummary> +      <desc> +	<p>Returns a key-value list, where the keys are the different types of algorithms and the values are the +	algorithms themselves. An example:</p> +	<code> +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>  +</code> +      </desc> +    </func>      <func>        <name>shell(Host) -> </name> diff --git a/lib/ssh/doc/src/ssh_channel.xml b/lib/ssh/doc/src/ssh_channel.xml index b8a03c350a..2fdecf9072 100644 --- a/lib/ssh/doc/src/ssh_channel.xml +++ b/lib/ssh/doc/src/ssh_channel.xml @@ -62,22 +62,22 @@      type, or both:</p>      <taglist> -      <tag><c>boolean()</c></tag> -      <item><p>= <c>true | false</c></p></item> -      <tag><c>string()</c></tag> -      <item><p>= list of ASCII characters</p></item> -      <tag><c>timeout()</c></tag> -      <item><p>= <c>infinity | integer()</c> in milliseconds</p></item> -      <tag><c>ssh_connection_ref()</c></tag> -      <item><p>Opaque to the user, returned by -    <c>ssh:connect/3</c> or sent to an SSH channel process</p></item> -      <tag><c>ssh_channel_id()</c></tag> -      <item><p>= <c>integer()</c></p></item> -      <tag><c>ssh_data_type_code()</c></tag> -      <item><p>= <c>1</c> ("stderr") | <c>0</c> ("normal") are -    the valid values, -    see <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url> -    Section 5.2</p></item> +      <tag><c>boolean() =</c></tag> +      <item><p><c>true | false</c></p></item> +      <tag><c>string() =</c></tag> +      <item><p>list of ASCII characters</p></item> +      <tag><c>timeout() =</c></tag> +      <item><p><c>infinity | integer()</c> in milliseconds</p></item> +      <tag><c>ssh_connection_ref() =</c></tag> +      <item><p>opaque() -as returned by +      <c>ssh:connect/3</c> or sent to an SSH channel process</p></item> +      <tag><c>ssh_channel_id() =</c></tag> +      <item><p><c>integer()</c></p></item> +      <tag><c>ssh_data_type_code() =</c></tag> +      <item><p><c>1</c> ("stderr") | <c>0</c> ("normal") are +      the valid values, +      see <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url> +      Section 5.2</p></item>      </taglist>    </section> diff --git a/lib/ssh/doc/src/ssh_client_key_api.xml b/lib/ssh/doc/src/ssh_client_key_api.xml index a8dda042c9..9a892d71fd 100644 --- a/lib/ssh/doc/src/ssh_client_key_api.xml +++ b/lib/ssh/doc/src/ssh_client_key_api.xml @@ -50,16 +50,16 @@      <seealso marker="public_key:public_key_records"> public_key user's guide:</seealso>      </p>      <taglist> -      <tag><c>boolean()</c></tag> -      <item><p>= <c>true | false</c></p></item> -      <tag><c>string()</c></tag> -      <item><p>= <c>[byte()]</c></p></item> -      <tag><c>public_key()</c></tag> -      <item><p>= <c>#'RSAPublicKey'{}| {integer(),  #'Dss-Parms'{}}| term()</c></p></item> -      <tag><c>private_key()</c></tag> -      <item><p>= <c>#'RSAPrivateKey'{} | #'DSAPrivateKey'{} | term()</c></p></item> -      <tag><c>public_key_algorithm()</c></tag> -      <item><p>= <c>'ssh-rsa'| 'ssh-dss' | atom()</c></p></item> +      <tag><c>boolean() =</c></tag> +      <item><p><c>true | false</c></p></item> +      <tag><c>string() =</c></tag> +      <item><p><c>[byte()]</c></p></item> +      <tag><c>public_key() =</c></tag> +      <item><p><c>#'RSAPublicKey'{}| {integer(),  #'Dss-Parms'{}}| term()</c></p></item> +      <tag><c>private_key() =</c></tag> +      <item><p><c>#'RSAPrivateKey'{} | #'DSAPrivateKey'{} | term()</c></p></item> +      <tag><c>public_key_algorithm() =</c></tag> +      <item><p><c>'ssh-rsa'| 'ssh-dss' | atom()</c></p></item>      </taglist>    </section> diff --git a/lib/ssh/doc/src/ssh_connection.xml b/lib/ssh/doc/src/ssh_connection.xml index 669a361db9..5422633dc3 100644 --- a/lib/ssh/doc/src/ssh_connection.xml +++ b/lib/ssh/doc/src/ssh_connection.xml @@ -56,29 +56,29 @@      type, or both:</p>      <taglist> -      <tag><c>boolean()</c></tag> -      <item><p>= <c>true | false </c></p></item> -      <tag><c>string()</c></tag> -      <item><p>= list of ASCII characters</p></item> -      <tag><c>timeout()</c></tag> -      <item><p>= <c>infinity | integer()</c> in milliseconds</p></item> -      <tag><c>ssh_connection_ref()</c></tag> -      <item><p>Opaque to the user, returned by -    <c>ssh:connect/3</c> or sent to an SSH channel processes</p></item> -      <tag><c>ssh_channel_id()</c></tag> -      <item><p>= <c>integer()</c></p></item> -      <tag><c>ssh_data_type_code()</c></tag> -      <item><p>= <c>1</c> ("stderr") | <c>0</c> ("normal") are +      <tag><c>boolean() =</c></tag> +      <item><p><c>true | false </c></p></item> +      <tag><c>string() =</c></tag> +      <item><p>list of ASCII characters</p></item> +      <tag><c>timeout() =</c></tag> +      <item><p><c>infinity | integer()</c> in milliseconds</p></item> +      <tag><c>ssh_connection_ref() =</c></tag> +      <item><p>opaque() -as returned by +      <c>ssh:connect/3</c> or sent to an SSH channel processes</p></item> +      <tag><c>ssh_channel_id() =</c></tag> +      <item><p><c>integer()</c></p></item> +      <tag><c>ssh_data_type_code() =</c></tag> +      <item><p><c>1</c> ("stderr") | <c>0</c> ("normal") are        valid values, see        <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url> Section 5.2.</p></item> -      <tag><c>ssh_request_status() ssh_request_status()</c></tag> -      <item><p>= <c>success | failure</c></p></item> -      <tag><c>event()</c></tag> -      <item><p>= <c>{ssh_cm, ssh_connection_ref(), ssh_event_msg()}</c></p></item> -      <tag><c>ssh_event_msg()</c></tag> -      <item><p>= <c>data_events() | status_events() | terminal_events()</c></p></item> -      <tag><c>reason()</c></tag> -      <item><p>= <c>timeout | closed</c></p></item> +      <tag><c>ssh_request_status() =</c></tag> +      <item><p> <c>success | failure</c></p></item> +      <tag><c>event() =</c></tag> +      <item><p><c>{ssh_cm, ssh_connection_ref(), ssh_event_msg()}</c></p></item> +      <tag><c>ssh_event_msg() =</c></tag> +      <item><p><c>data_events() | status_events() | terminal_events()</c></p></item> +      <tag><c>reason() =</c></tag> +      <item><p><c>timeout | closed</c></p></item>      </taglist>      <taglist> diff --git a/lib/ssh/doc/src/ssh_server_key_api.xml b/lib/ssh/doc/src/ssh_server_key_api.xml index 34ce7f7660..73dd90c962 100644 --- a/lib/ssh/doc/src/ssh_server_key_api.xml +++ b/lib/ssh/doc/src/ssh_server_key_api.xml @@ -50,20 +50,20 @@      <seealso marker="public_key:public_key_records"> public_key user's guide</seealso>.      </p> -<taglist> -      <tag><c>boolean()</c></tag> -      <item><p>= <c>true | false</c></p></item> -      <tag><c>string()</c></tag> -      <item><p>= <c>[byte()]</c></p></item> -      <tag><c>public_key()</c></tag> -      <item><p>= <c>#'RSAPublicKey'{}| {integer(),  #'Dss-Parms'{}}| term()</c></p></item> -      <tag><c>private_key()</c></tag> -      <item><p>= <c>#'RSAPrivateKey'{} | #'DSAPrivateKey'{} | term()</c></p></item> -      <tag><c>public_key_algorithm()</c></tag> -      <item><p>= <c>'ssh-rsa'| 'ssh-dss' | atom()</c></p></item> +    <taglist> +      <tag><c>boolean() =</c></tag> +      <item><p><c>true | false</c></p></item> +      <tag><c>string() =</c></tag> +      <item><p><c>[byte()]</c></p></item> +      <tag><c>public_key() =</c></tag> +      <item><p><c>#'RSAPublicKey'{}| {integer(),  #'Dss-Parms'{}}| term()</c></p></item> +      <tag><c>private_key() =</c></tag> +      <item><p><c>#'RSAPrivateKey'{} | #'DSAPrivateKey'{} | term()</c></p></item> +      <tag><c>public_key_algorithm() =</c></tag> +      <item><p><c>'ssh-rsa'| 'ssh-dss' | atom()</c></p></item>      </taglist>    </section> - +      <funcs>      <func>        <name>Module:host_key(Algorithm, DaemonOptions) -> diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml index 643130fe6b..fc418bc934 100644 --- a/lib/ssh/doc/src/ssh_sftp.xml +++ b/lib/ssh/doc/src/ssh_sftp.xml @@ -43,8 +43,8 @@      </p>      <taglist> -      <tag><c>ssh_connection_ref()</c></tag> -      <item><p>Opaque to the user, returned by <c>ssh:connect/3</c></p></item> +      <tag><c>ssh_connection_ref() =</c></tag> +      <item><p>opaque() - as returned by <c>ssh:connect/3</c></p></item>        <tag><c>timeout()</c></tag>        <item><p>= <c>infinity | integer() in milliseconds. Default infinity.</c></p></item>      </taglist> diff --git a/lib/ssh/doc/src/ssh_sftpd.xml b/lib/ssh/doc/src/ssh_sftpd.xml index bc2660f595..8b2497e6a3 100644 --- a/lib/ssh/doc/src/ssh_sftpd.xml +++ b/lib/ssh/doc/src/ssh_sftpd.xml @@ -37,16 +37,16 @@    <section>      <title>DATA TYPES</title>      <taglist> -      <tag><c>subsystem_spec()</c></tag> -      <item><p>= <c>{subsystem_name(), {channel_callback(), channel_init_args()}}</c></p></item> -      <tag><c>subsystem_name()</c></tag> -      <item><p>= <c>"sftp"</c></p></item> -      <tag><c>channel_callback()</c></tag> -      <item><p>= <c>atom()</c> - Name of the Erlang module implementing the subsystem using the +      <tag><c>subsystem_spec() =</c></tag> +      <item><p><c>{subsystem_name(), {channel_callback(), channel_init_args()}}</c></p></item> +      <tag><c>subsystem_name() =</c></tag> +      <item><p><c>"sftp"</c></p></item> +      <tag><c>channel_callback() =</c></tag> +      <item><p><c>atom()</c> - Name of the Erlang module implementing the subsystem using the        <c>ssh_channel</c> behavior, see the        <seealso marker="ssh_channel">ssh_channel(3)</seealso> manual page.</p></item> -      <tag><c>channel_init_args()</c></tag> -      <item><p>= <c>list()</c> - The one given as argument to function <c>subsystem_spec/1</c>.</p></item> +      <tag><c>channel_init_args() =</c></tag> +      <item><p><c>list()</c> - The one given as argument to function <c>subsystem_spec/1</c>.</p></item>      </taglist>    </section>    <funcs> | 
