diff options
Diffstat (limited to 'lib/ssh/doc/src')
| -rw-r--r-- | lib/ssh/doc/src/Makefile | 7 | ||||
| -rw-r--r-- | lib/ssh/doc/src/introduction.xml | 2 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ref_man.xml | 16 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh.xml | 28 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_app.xml | 6 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_channel.xml | 109 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_client_key_api.xml | 124 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_connection.xml | 4 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_protocol.xml | 20 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_server_key_api.xml | 90 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_sftp.xml | 5 | ||||
| -rw-r--r-- | lib/ssh/doc/src/using_ssh.xml | 34 |
12 files changed, 346 insertions, 99 deletions
diff --git a/lib/ssh/doc/src/Makefile b/lib/ssh/doc/src/Makefile index fc9600f6cd..0e79d9979f 100644 --- a/lib/ssh/doc/src/Makefile +++ b/lib/ssh/doc/src/Makefile @@ -37,10 +37,11 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) # Target Specs # ---------------------------------------------------- XML_APPLICATION_FILES = ref_man.xml -XML_REF3_FILES = \ - ssh.xml \ +XML_REF3_FILES = ssh.xml \ ssh_channel.xml \ - ssh_connection.xml\ + ssh_connection.xml \ + ssh_client_key_api.xml \ + ssh_server_key_api.xml \ ssh_sftp.xml \ ssh_sftpd.xml \ diff --git a/lib/ssh/doc/src/introduction.xml b/lib/ssh/doc/src/introduction.xml index 837644330f..aac8de0f76 100644 --- a/lib/ssh/doc/src/introduction.xml +++ b/lib/ssh/doc/src/introduction.xml @@ -40,7 +40,7 @@ protocol in Erlang which offers API functions to write customized SSH clients and servers as well as making the Erlang shell available via SSH. Also included in the SSH application are an - SFTP (Secret File Transfer Protocol) client <seealso + SFTP (SSH File Transfer Protocol) client <seealso marker="ssh_sftp">ssh_sftp</seealso> and server <seealso marker="ssh_sftp">ssh_sftpd</seealso>.</p> </section> diff --git a/lib/ssh/doc/src/ref_man.xml b/lib/ssh/doc/src/ref_man.xml index 0bd8479343..88203b5034 100644 --- a/lib/ssh/doc/src/ref_man.xml +++ b/lib/ssh/doc/src/ref_man.xml @@ -31,12 +31,14 @@ <p>The SSH application is an erlang implementation of the secure shell protocol (SSH) as defined by RFC 4250 - 4254</p> - </description>' - <xi:include href="ssh_app.xml"/> - <xi:include href="ssh.xml"/> - <xi:include href="ssh_channel.xml"/> - <xi:include href="ssh_connection.xml"/> - <xi:include href="ssh_sftp.xml"/> - <xi:include href="ssh_sftpd.xml"/> + </description> + <xi:include href="ssh_app.xml"/> + <xi:include href="ssh.xml"/> + <xi:include href="ssh_channel.xml"/> + <xi:include href="ssh_connection.xml"/> + <xi:include href="ssh_client_key_api.xml"/> + <xi:include href="ssh_server_key_api.xml"/> + <xi:include href="ssh_sftp.xml"/> + <xi:include href="ssh_sftpd.xml"/> </application> diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index 907d0efc5c..517cbf1ef9 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -48,7 +48,7 @@ this module and/or abstractions to indicate the intended use of the data type:</p> <p><c>boolean() = true | false </c></p> - <p><c>string() = list of ASCII characters</c></p> + <p><c>string() = [byte()]</c></p> <p><c>ssh_daemon_ref() - opaque to the user returned by ssh:daemon/[1,2,3]</c></p> <p><c>ssh_connection_ref() - opaque to the user @@ -134,7 +134,7 @@ password. Do note that it may not always be desirable to use those options from a security point of view.</p> </item> - <tag><c><![CDATA[{public_key_alg, ssh_rsa | ssh_dsa}]]></c></tag> + <tag><c><![CDATA[{public_key_alg, 'ssh-rsa' | 'ssh-dss'}]]></c></tag> <item> <p>Sets the preferred public key algorithm to use for user authentication. If the the preferred algorithm fails for @@ -143,15 +143,15 @@ </item> <tag><c><![CDATA[{pref_public_key_algs, list()}]]></c></tag> <item> - <p>List of public key algorithms to try to use, ssh_rsa and ssh_dsa available. - Will override <c><![CDATA[{public_key_alg, ssh_rsa | ssh_dsa}]]></c></p> + <p>List of public key algorithms to try to use, 'ssh-rsa' and 'ssh-dss' available. + Will override <c><![CDATA[{public_key_alg, 'ssh-rsa' | 'ssh-dss'}]]></c></p> </item> <tag><c><![CDATA[{connect_timeout, timeout()}]]></c></tag> <item> <p>Sets a timeout on the transport layer - connection. Defaults to infinity.</p> + connection. Defaults to <c>infinity</c>.</p> </item> - <tag><c><![CDATA[{user, String}]]></c></tag> + <tag><c><![CDATA[{user, string()}]]></c></tag> <item> <p>Provides a user name. If this option is not given, ssh reads from the environment (<c><![CDATA[LOGNAME]]></c> or @@ -165,9 +165,11 @@ password if the password authentication method is attempted.</p> </item> - <tag><c><![CDATA[{key_cb, atom() = KeyCallbackModule}]]></c></tag> + <tag><c><![CDATA[{key_cb, atom()}]]></c></tag> <item> - <p>TODO:</p> + <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> </item> <tag><c><![CDATA[{quiet_mode, atom() = boolean()}]]></c></tag> <item> @@ -177,7 +179,7 @@ <item> <p>Allow an existing file descriptor to be used (simply passed on to the transport protocol).</p></item> - <tag><c><![CDATA[{ip_v6_disabled, boolean()}]]></c></tag> + <tag><c><![CDATA[{ipv6_disabled, boolean()}]]></c></tag> <item> <p>Determines if SSH shall use IPv6 or not.</p></item> <tag><c><![CDATA[{idle_time, timeout()}]]></c></tag> @@ -293,6 +295,12 @@ <c><![CDATA[true]]></c> if the password is valid and <c><![CDATA[false]]></c> otherwise.</p> </item> + <tag><c><![CDATA[{key_cb, atom()}]]></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> + </item> <tag><c><![CDATA[{fd, file_descriptor()}]]></c></tag> <item> <p>Allow an existing file-descriptor to be used @@ -347,7 +355,7 @@ <desc> <p>Utility function that starts crypto, public_key and the SSH application. Defult type is temporary. - <seealso marker="kernel:application">application(3)</seealso> + See also <seealso marker="kernel:application">application(3)</seealso> </p> </desc> </func> diff --git a/lib/ssh/doc/src/ssh_app.xml b/lib/ssh/doc/src/ssh_app.xml index 51544d3890..c01f44936a 100644 --- a/lib/ssh/doc/src/ssh_app.xml +++ b/lib/ssh/doc/src/ssh_app.xml @@ -22,7 +22,7 @@ </legalnotice> <title>SSH</title> - <file>ssh_app.sgml</file> + <file>ssh_app.xml</file> </header> <app>SSH</app> <appsummary>The ssh application implements the SSH (Secure Shell) protocol and @@ -50,7 +50,9 @@ and authorized_keys in ~/.ssh, and the host key files in /etc/ssh . These locations may be changed by the options user_dir and system_dir. Public key handling may also be customized by - providing a callback module implementing the behavior ssh_key_api. + providing a callback module implementing the behaviors + <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso> and + <seealso marker="ssh_server_key_api">ssh_server_key_api</seealso>. </p> <section> diff --git a/lib/ssh/doc/src/ssh_channel.xml b/lib/ssh/doc/src/ssh_channel.xml index 342de97a1b..f0083ae8d1 100644 --- a/lib/ssh/doc/src/ssh_channel.xml +++ b/lib/ssh/doc/src/ssh_channel.xml @@ -25,7 +25,7 @@ <title>ssh_channel</title> </header> <module>ssh_channel</module> - <modulesummary>Generic Ssh Channel Behavior + <modulesummary>-behaviour(ssh_channel). </modulesummary> <description> <p>SSH services (clients and servers) are implemented as channels @@ -41,15 +41,12 @@ the SSH applications supervisor tree. </p> - <p>The functions init/1, terminate/2, handle_ssh_msg/2 and - handle_msg/2 are the functions that are required - to provide the implementation for a server side channel, such as - an SSH subsystem channel that can be plugged into the Erlang ssh - daemon see <seealso marker="ssh#daemon-3">ssh:daemon/[2, - 3]</seealso>. - The handle_call/3, handle_cast/2, code_change/3 and enter_loop/1 - functions are only relevant when implementing a client side - channel.</p> + <note> When implementing a SSH subsystem use the + <c>-behaviour(ssh_subsystem).</c> instead of <c>-behaviour(ssh_channel).</c> + as the only relevant callback functions for subsystems are + init/1, handle_ssh_msg/2, handle_msg/2 and terminate/2, so the ssh_subsystem + behaviour is limited version of the ssh_channel behaviour. + </note> </description> <section> @@ -72,20 +69,22 @@ <funcs> <func> <name>call(ChannelRef, Msg) -></name> - <name>call(ChannelRef, Msg, timeout()) -> Reply | {error, Reason}</name> + <name>call(ChannelRef, Msg, Timeout) -> Reply | {error, Reason}</name> <fsummary> Makes a synchronous call to a channel.</fsummary> <type> <v>ChannelRef = pid() </v> <d>As returned by start_link/4 </d> <v>Msg = term() </v> + <v>Timeout = timeout() </v> <v>Reply = term() </v> <v>Reason = closed | timeout </v> + </type> <desc> <p>Makes a synchronous call to the channel process by sending a message and waiting until a reply arrives or a timeout occurs. The channel will call <seealso mark = - "#CallbackModule:handle_call-3">CallbackModule:handle_call/3</seealso> + "#Module:handle_call-3">Module:handle_call/3</seealso> to handle the message. If the channel process does not exist <c>{error, closed}</c> is returned. </p> @@ -105,7 +104,7 @@ <p>Sends an asynchronous message to the channel process and returns ok immediately, ignoring if the destination node or channel process does not exist. The channel will call - <seealso mark = "#CallbackModule:handle_cast-3">CallbackModule:handle_cast/2</seealso> + <seealso mark = "#Module:handle_cast-3">Module:handle_cast/2</seealso> to handle the message. </p> </desc> @@ -131,10 +130,13 @@ </func> <func> - <name>init(Options) -> {ok, State} | {ok, State, timeout()} | {stop, Reason} </name> + <name>init(Options) -> {ok, State} | {ok, State, Timeout} | {stop, Reason} </name> <fsummary> Initiates a ssh_channel process.</fsummary> <type> - <v> Options = [{Option, Value}]</v> + <v>Options = [{Option, Value}]</v> + <v>State = term()</v> + <v>Timeout = timeout() </v> + <v>Reason = term() </v> </type> <desc> <p> @@ -178,7 +180,7 @@ <p>This function can be used by a channel to explicitly send a reply to a client that called <c>call/[2,3]</c> when the reply cannot be defined in the return value of - <seealso marker ="#CallbackModule:handle_call-3">CallbackModule:handle_call/3</seealso>.</p> + <seealso marker ="#Module:handle_call-3">Module:handle_call/3</seealso>.</p> <p><c>Client</c> must be the <c>From</c> argument provided to the callback function <c>handle_call/3</c>. <c>Reply</c> is an arbitrary term, @@ -221,53 +223,56 @@ <p>The timeout values that may be returned by the callback functions has the same semantics as in a <seealso marker="stdlib#gen_server">gen_server</seealso> - If the timout occurs <seealso marker="#handle_msg">handle_msg/2</seealso> + If the timeout occurs <seealso marker="#handle_msg">handle_msg/2</seealso> will be called as <c>handle_msg(timeout, State). </c></p> </section> <funcs> <func> - <name>CallbackModule:code_change(OldVsn, State, Extra) -> {ok, + <name>Module:code_change(OldVsn, State, Extra) -> {ok, NewState}</name> <fsummary> Converts process state when code is changed.</fsummary> <type> - <v> Converts process state when code is changed.</v> + <v>OldVsn = term()</v> + <d>In the case of an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and + in the case of a downgrade, <c>OldVsn</c> is + <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the <c>vsn</c> + attribute(s) of the old version of the callback module + <c>Module</c>. If no such attribute is defined, the version is + the checksum of the BEAM file.</d> + <v>State = term()</v> + <d>The internal state of the channel.</d> + <v>Extra = term()</v> + <d>Passed as-is from the <c>{advanced,Extra}</c> + part of the update instruction.</d> </type> <desc> - <p>This function is called by a client side channel when it - should update its internal state during a release - upgrade/downgrade, i.e. when the instruction - <c>{update,Module,Change,...}</c> where - <c>Change={advanced,Extra}</c> is given in the <c>appup</c> - file. See <seealso marker="doc/design_principles:release_handling#instr">OTP - Design Principles</seealso> for more information. - </p> + <p> Converts process state when code is changed.</p> - <note><p>Soft upgrade according to the OTP release concept - is not straight forward for the server side, as subsystem - channel processes are spawned by the SSH application and - hence added to its supervisor tree. It could be possible to - upgrade the subsystem channels, when upgrading the user - application, if the callback functions can handle two - versions of the state, but this function can not be used in - the normal way.</p> - </note> + <p>This function is called by a client side channel when it + should update its internal state during a release + upgrade/downgrade, i.e. when the instruction + <c>{update,Module,Change,...}</c> where + <c>Change={advanced,Extra}</c> is given in the <c>appup</c> + file. See <seealso marker="doc/design_principles:release_handling#instr">OTP + Design Principles</seealso> for more information. + </p> + + <note><p>Soft upgrade according to the OTP release concept + is not straight forward for the server side, as subsystem + channel processes are spawned by the SSH application and + hence added to its supervisor tree. It could be possible to + upgrade the subsystem channels, when upgrading the user + application, if the callback functions can handle two + versions of the state, but this function can not be used in + the normal way.</p> + </note> - <p>In the case of an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and - in the case of a downgrade, <c>OldVsn</c> is - <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the <c>vsn</c> - attribute(s) of the old version of the callback module - <c>Module</c>. If no such attribute is defined, the version - is the checksum of the BEAM file.</p> - <p><c>State</c> is the internal state of the channel.</p> - <p><c>Extra</c> is passed as-is from the <c>{advanced,Extra}</c> - part of the update instruction.</p> - <p>The function should return the updated internal state.</p> </desc> </func> <func> - <name>CallbackModule:init(Args) -> {ok, State} | {ok, State, timeout()} | + <name>Module:init(Args) -> {ok, State} | {ok, State, timeout()} | {stop, Reason}</name> <fsummary> Makes necessary initializations and returns the initial channel state if the initializations succeed.</fsummary> @@ -287,7 +292,7 @@ </func> <func> - <name>CallbackModule:handle_call(Msg, From, State) -> Result</name> + <name>Module:handle_call(Msg, From, State) -> Result</name> <fsummary> Handles messages sent by calling <c>ssh_channel:call/[2,3]</c></fsummary> <type> @@ -312,7 +317,7 @@ </func> <func> - <name>CallbackModule:handle_cast(Msg, State) -> Result</name> + <name>Module:handle_cast(Msg, State) -> Result</name> <fsummary> Handles messages sent by calling <c>ssh_channel:cact/2</c></fsummary> <type> @@ -334,7 +339,7 @@ </func> <func> - <name>CallbackModule:handle_msg(Msg, State) -> {ok, State} | + <name>Module:handle_msg(Msg, State) -> {ok, State} | {stop, ChannelId, State}</name> <fsummary> Handle other messages than ssh connection protocol, @@ -368,7 +373,7 @@ </func> <func> - <name>CallbackModule:handle_ssh_msg(Msg, State) -> {ok, State} | {stop, + <name>Module:handle_ssh_msg(Msg, State) -> {ok, State} | {stop, ssh_channel_id(), State}</name> <fsummary> Handles ssh connection protocol messages. </fsummary> <type> @@ -393,7 +398,7 @@ </func> <func> - <name>CallbackModule:terminate(Reason, State) -> _</name> + <name>Module:terminate(Reason, State) -> _</name> <fsummary> </fsummary> <type> <v>Reason = term()</v> diff --git a/lib/ssh/doc/src/ssh_client_key_api.xml b/lib/ssh/doc/src/ssh_client_key_api.xml new file mode 100644 index 0000000000..abc1070e78 --- /dev/null +++ b/lib/ssh/doc/src/ssh_client_key_api.xml @@ -0,0 +1,124 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2012</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + 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. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + <title>ssh_client_key_api</title> + </header> + <module>ssh_client_key_api</module> + <modulesummary> + -behaviour(ssh_client_key_api). + </modulesummary> + <description> + <p> Behavior describing the API for an SSH client's public key handling. + By implementing the callbacks defined. + in this behavior it is possible to customize the SSH client's public key + handling. By default the SSH application implements this behavior + with help of the standard openssh files, see <seealso marker="SSH_app"> ssh(6)</seealso>. </p> + </description> + + <section> + <title>DATA TYPES </title> + + <p>Type definitions that are used more than once in this module + and/or abstractions to indicate the intended use of the data + type:</p> + + <p> boolean() = true | false</p> + <p> string() = [byte()] </p> + <p> public_key() = #'RSAPublicKey'{}| {integer(), #'Dss-Parms'{}}| term()</p> + <p> private_key() = #'RSAPublicKey'{}| {integer(), #'Dss-Parms'{}}| term()</p> + <p> public_key_algorithm() = 'ssh-rsa'| 'ssh-dss' | atom()</p> + + </section> + + <funcs> + <func> + <name>Module:add_host_key(HostNames, Key, ConnectOptions) -> ok | {error, Reason}</name> + <fsummary>Adds a host key to the set of trusted host keys</fsummary> + <type> + <v>HostNames = string()</v> + <d>Description of the host that owns the <c>PublicKey</c></d> + + <v>Key = public_key() </v> + <d> Normally an RSA or DSA public key but handling of other public keys can be added</d> + + <v>ConnectOptions = proplists:proplist() </v> + <d>Options provided to <seealso marker="ssh#daemon">ssh:connect/[3,4]</seealso></d> + <v>Reason = term() </v> + </type> + <desc> + <p> Adds a host key to the set of trusted host keys</p> + </desc> + </func> + + <func> + <name>Module:is_host_key(Key, Host, Algorithm, ConnectOptions) -> Result</name> + <fsummary>Checks if a host key is trusted</fsummary> + <type> + <v>Key = public_key() </v> + <d> Normally an RSA or DSA public key but handling of other public keys can be added</d> + + <v>Host = string()</v> + <d>Description of the host</d> + + <v>Algorithm = public_key_algorithm()</v> + <d> Host key algorithm. Should support 'ssh-rsa'| 'ssh-dss' but additional algorithms + can be handled.</d> + + <v> ConnectOptions = proplists:proplist() </v> + <d>Options provided to <seealso marker="ssh#daemon">ssh:connect/[3,4]</seealso></d> + + <v> Result = boolean()</v> + </type> + <desc> + <p>Checks if a host key is trusted</p> + </desc> + </func> + + <func> + <name>Module:user_key(Algorithm, ConnectOptions) -> + {ok, PrivateKey} | {error, Reason}</name> + <fsummary>Fetches the users "public key" matching the <c>Algorithm</c>.</fsummary> + <type> + <v>Algorithm = public_key_algorithm()</v> + <d> Host key algorithm. Should support 'ssh-rsa'| 'ssh-dss' but additional algorithms + can be handled.</d> + + <v> ConnectOptions = proplists:proplist() </v> + <d>Options provided to <seealso marker="ssh#daemon">ssh:connect/[3,4]</seealso></d> + + <v> PrivateKey = private_key()</v> + <d> The private key of the user matching the <c>Algorithm</c></d> + + <v>Reason = term() </v> + </type> + + <desc> + <p>Fetches the users "public key" matching the <c>Algorithm</c>. + <note>The private key contains the public key</note> + </p> + </desc> + </func> + + </funcs> + +</erlref> diff --git a/lib/ssh/doc/src/ssh_connection.xml b/lib/ssh/doc/src/ssh_connection.xml index 4480f0a093..c66622307f 100644 --- a/lib/ssh/doc/src/ssh_connection.xml +++ b/lib/ssh/doc/src/ssh_connection.xml @@ -91,7 +91,7 @@ refered to are on OS-level and not something generated by an Erlang program.</item> - <tag><c><![CDATA[{exit_signal, ssh_channel_id(), string() = exit_signal, string() = ErrorMsg, + <tag><c><![CDATA[{exit_signal, ssh_channel_id(), string() = ExitSignal, string() = ErrorMsg, string() = LanguageString}]]></c></tag> <item>A remote execution may terminate violently due to a signal @@ -274,7 +274,7 @@ </func> <func> - <name>reply_request(ConnectionRef, WantReply, Status, CannelId) -> ok</name> + <name>reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok</name> <fsummary>Send status replies to requests that want such replies. </fsummary> <type> <v> ConnectionRef = ssh_connection_ref() </v> diff --git a/lib/ssh/doc/src/ssh_protocol.xml b/lib/ssh/doc/src/ssh_protocol.xml index 529558759e..6a253c43eb 100644 --- a/lib/ssh/doc/src/ssh_protocol.xml +++ b/lib/ssh/doc/src/ssh_protocol.xml @@ -37,7 +37,7 @@ authentication and integrity protection. Currently, only a minimum of MAC- (message authentication code, a short piece of information used to authenticate a message) and encryption - algorithms see <seealso marker="ssh">ssh(3)</seealso> + algorithms are supported see <seealso marker="ssh">ssh(3)</seealso> </p> </section> @@ -52,10 +52,18 @@ interactive authentication. This method is suitable for interactive authentication methods that do not need any special software support on the client side. Instead, all authentication - data should be entered via the keyboad. It is also possible + data should be entered via the keyboard. It is also possible to use a pure password based authentication scheme, note that in - this case the the plain text password will be encrypted befor sent - over the network. + this case the the plain text password will be encrypted before sent + over the network. There are several configuration options for + authentication handling available in + <seealso marker="ssh#connect-3">ssh:connect/[3,4]</seealso> + and <seealso marker="ssh#daemon-2">ssh:daemon/[2,3]</seealso> + It is also possible to customize the public key handling + by implementing the behaviours <seealso + marker="ssh_client_key_api">ssh_client_key_api</seealso> and + <seealso + marker="ssh_server_key_api">ssh_server_key_api</seealso> </p> </section> @@ -82,7 +90,7 @@ channel. The <seealso marker="ssh_channel">ssh_channel</seealso> behaviour makes it easy to write your own SSH client/server processes that use flow - control. It handles generic parts of SSH channel managment and + control. It handles generic parts of SSH channel management and lets you focus on the application logic. </p> @@ -91,7 +99,7 @@ <list type="bulleted"> <item><em>Subsystem</em> - named services that can be run as part of an SSH server such as SFTP <seealso - marker="ssh_sftp">ssh_sftp</seealso>, that is built in to the + marker="ssh_sftpd">ssh_sftpd</seealso>, that is built in to the SSH daemon (server) by default but may be disabled. The Erlang SSH daemon may be configured to run any Erlang implemented SSH subsystem. diff --git a/lib/ssh/doc/src/ssh_server_key_api.xml b/lib/ssh/doc/src/ssh_server_key_api.xml new file mode 100644 index 0000000000..78ff105387 --- /dev/null +++ b/lib/ssh/doc/src/ssh_server_key_api.xml @@ -0,0 +1,90 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2012</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + 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. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + <title>ssh_server_key_api</title> + </header> + <module>ssh_server_key_api</module> + <modulesummary> + -behaviour(ssh_server_key_api). + </modulesummary> + <description> + <p> Behaviour describing the API for an SSH server's public key handling.By implementing the callbacks defined + in this behavior it is possible to customize the SSH server's public key + handling. By default the SSH application implements this behavior + with help of the standard openssh files, see <seealso marker="SSH_app"> ssh(6)</seealso>.</p> + </description> + + <section> + <title>DATA TYPES </title> + + <p>Type definitions that are used more than once in this module + and/or abstractions to indicate the intended use of the data + type:</p> + + <p> boolean() = true | false</p> + <p> string() = [byte()]</p> + <p> public_key() = #'RSAPublicKey'{}| {integer(), #'Dss-Parms'{}}| term()</p> + <p> private_key() = #'RSAPublicKey'{}| {integer(), #'Dss-Parms'{}}| term()</p> + <p> public_key_algorithm() = 'ssh-rsa'| 'ssh-dss' | atom()</p> + </section> + + <funcs> + <func> + <name>Module:host_key(Algorithm, DaemonOptions) -> + {ok, Key} | {error, Reason}</name> + <fsummary>Fetches the hosts private key </fsummary> + <type> + <v>Algorithm = public_key_algorithm()</v> + <d> Host key algorithm. Should support 'ssh-rsa'| 'ssh-dss' but additional algorithms + can be handled.</d> + <v> DaemonOptions = proplists:proplist() </v> + <d>Options provided to <seealso marker="ssh#daemon">ssh:daemon/[2,3]</seealso></d> + <v> Key = private_key()</v> + <d> The private key of the host matching the <c>Algorithm</c></d> + <v>Reason = term() </v> + </type> + <desc> + <p>Fetches the hosts private key</p> + </desc> + </func> + + <func> + <name>Module:is_auth_key(Key, User, DaemonOptions) -> Result</name> + <fsummary> Checks if the user key is authorized</fsummary> + <type> + <v> Key = public_key() </v> + <d> Normally an RSA or DSA public key but handling of other public keys can be added</d> + <v> User = string()</v> + <d> The user owning the public key</d> + <v> DaemonOptions = proplists:proplist() </v> + <d> Options provided to <seealso marker="ssh#daemon">ssh:daemon/[2,3]</seealso></d> + <v> Result = boolean()</v> + </type> + <desc> + <p> Checks if the user key is authorized </p> + </desc> + </func> + + </funcs> + +</erlref> diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml index 28576c9ef0..0d61e57edb 100644 --- a/lib/ssh/doc/src/ssh_sftp.xml +++ b/lib/ssh/doc/src/ssh_sftp.xml @@ -486,8 +486,9 @@ <v>Reason = term()</v> </type> <desc> - <p>Deletes a directory specified by <c><![CDATA[Name]]></c>. The directory - should be empty.</p> + <p>Deletes a directory specified by <c><![CDATA[Name]]></c>. + Note that the directory must be empty before it can be successfully deleted + </p> </desc> </func> diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml index db17c6fd1c..1a54f3f964 100644 --- a/lib/ssh/doc/src/using_ssh.xml +++ b/lib/ssh/doc/src/using_ssh.xml @@ -37,7 +37,7 @@ nothing else is stated it is persumed that the otptest user has an entry in tarlop's authorized_keys file (may log in via ssh without entering a password). Also tarlop is a known host in the user - otptests known_hosts file so that host verification can be done + otptest's known_hosts file so that host verification can be done without user interaction. </p> </section> @@ -72,12 +72,12 @@ marker="ssh_app">ssh(6)</seealso>. </p> - <note><p>Normaly the /etc/ssh directory is only readable by root. </p> + <note><p>Normally the /etc/ssh directory is only readable by root. </p> </note> <p> The option user_dir defaults to the users ~/.ssh directory</p> - <p>In the following exampel we have generate new keys and host keys as + <p>In the following example we generate new keys and host keys as to be able to run the example without having root privilages</p> <code> @@ -87,12 +87,13 @@ [...] </code> - <p>And add the public hostkey to the known_hosts file of the user otptest. Then we can do</p> + <p>Create the file /tmp/otptest_user/.ssh/authrized_keys and add the content + of /tmp/otptest_user/.ssh/id_rsa.pub Now we can do</p> <code type="erl"> 1> ssh:start(). ok - 2> {ok, Sshd} = ssh:daemon(8989, [{system_dir, "/tmp/ssh_daemon/ssh_host_rsa_key"}, + 2> {ok, Sshd} = ssh:daemon(8989, [{system_dir, "/tmp/ssh_daemon"}, {user_dir, "/tmp/otptest_user/.ssh"}]). {ok,<0.54.0>} 3> @@ -101,12 +102,16 @@ <p>Use the openssh client from a shell to connect to the Erlang ssh daemon.</p> <code> - $bash> ssh tarlop -p 8989 -i /tmp/otptest_user/.ssh/id_rsa + $bash> ssh tarlop -p 8989 -i /tmp/otptest_user/.ssh/id_rsa -o UserKnownHostsFile=/tmp/otptest_user/.ssh/known_hosts + The authenticity of host 'tarlop' can't be established. + RSA key fingerprint is 14:81:80:50:b1:1f:57:dd:93:a8:2d:2f:dd:90:ae:a8. + Are you sure you want to continue connecting (yes/no)? yes + Warning: Permanently added 'tarlop' (RSA) to the list of known hosts. Eshell V5.10 (abort with ^G) 1> </code> - <p>There is two ways of shuting down an SSH daemon</p> + <p>There are two ways of shutting down an SSH daemon</p> <p>1: Stops the listener, but leaves existing connections started by the listener up and running.</p> @@ -169,7 +174,7 @@ <code type="erl" > 1> ssh:start(). ok - 2> ssh:daemon(8989, [{system_dir, "."}, + 2> ssh:daemon(8989, [{system_dir, "/tmp/ssh_daemon"}, {user_dir, "/tmp/otptest_user/.ssh"}, {subsystems, [ssh_sftpd:subsystem_spec([{cwd, "/tmp/sftp/example"}])]}]). {ok,<0.54.0>} 3> @@ -178,7 +183,7 @@ <p> Run the openssh sftp client</p> <code type="erl"> - $bash> sftp -oPort=8989 tarlop + $bash> sftp -oPort=8989 -o IdentityFile=/tmp/otptest_user/.ssh/id_rsa -o UserKnownHostsFile=/tmp/otptest_user/.ssh/known_hosts tarlop Connecting to tarlop... sftp> pwd Remote working directory: /tmp/sftp/example @@ -202,11 +207,12 @@ <section> <title>Creating a subsystem</title> - <p>A very small SSH subsystem that echos N bytes could be implemented like this.</p> + <p>A very small SSH subsystem that echos N bytes could be implemented like this. + See also <seealso marker="ssh_channel"> ssh_channel(3)</seealso> </p> <code type="erl" > -module(ssh_echo_server). --behaviour(ssh_channel). +-behaviour(ssh_subsystem). -record(state, { n, id, @@ -261,7 +267,7 @@ terminate(_Reason, _State) -> <code type="erl" > 1> ssh:start(). ok - 2> ssh:daemon(8989, [{system_dir, "/tmp/ssh_daemon/ssh_host_rsa_key"}, + 2> ssh:daemon(8989, [{system_dir, "/tmp/ssh_daemon"}, {user_dir, "/tmp/otptest_user/.ssh"} {subsystems, [{"echo_n", {ssh_echo_server, [10]}}]}]). {ok,<0.54.0>} @@ -275,12 +281,12 @@ terminate(_Reason, _State) -> {ok,<0.57.0>} 3>{ok, ChannelId} = ssh_connection:session_channel(ConnectionRef, infinity). 4> success = ssh_connection:subsystem(ConnectionRef, ChannelId, "echo_n", infinity). - 5> ok = ssh_connection:send(ConnectionRef, ChannelId, "0123456789", infinity), + 5> ok = ssh_connection:send(ConnectionRef, ChannelId, "0123456789", infinity). 6> flush(). {ssh_msg, <0.57.0>, {data, 0, 1, "0123456789"}} {ssh_msg, <0.57.0>, {eof, 0}} {ssh_msg, <0.57.0>, {closed, 0}} - 7> {error, closed} = ssh_connection:send(ConnectionRef, ChannelId, "10", infinity), + 7> {error, closed} = ssh_connection:send(ConnectionRef, ChannelId, "10", infinity). </code> </section> |