aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssh/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ssh/doc')
-rw-r--r--lib/ssh/doc/src/notes.xml97
-rw-r--r--lib/ssh/doc/src/ssh_connection.xml59
-rw-r--r--lib/ssh/doc/src/ssh_sftp.xml125
3 files changed, 273 insertions, 8 deletions
diff --git a/lib/ssh/doc/src/notes.xml b/lib/ssh/doc/src/notes.xml
index 0b587db810..f3db05192e 100644
--- a/lib/ssh/doc/src/notes.xml
+++ b/lib/ssh/doc/src/notes.xml
@@ -29,6 +29,103 @@
<file>notes.xml</file>
</header>
+<section><title>Ssh 3.0.8</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Fixes of login blocking after port scanning.</p>
+ <p>
+ Own Id: OTP-12247 Aux Id: seq12726 </p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Ssh 3.0.7</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Add option sftp_vsn to SFTP</p>
+ <p>
+ Own Id: OTP-12227</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Fix option user_interaction to work as expected. When
+ password authentication is implemented with ssh
+ keyboard-interactive method and the password is already
+ supplied, so that we do not need to query user, then
+ connections should succeed even though user_interaction
+ option is set to false.</p>
+ <p>
+ Own Id: OTP-11329 Aux Id: seq12420, seq12335 </p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Ssh 3.0.6</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Gracefully handle bad data from the client when expecting
+ ssh version exchange.</p>
+ <p>
+ Own Id: OTP-12157 Aux Id: seq12706 </p>
+ </item>
+ <item>
+ <p>
+ When restarting an ssh daemon, that was stopped with
+ ssh:stop_listner/ [1,2] new options given shall replace
+ old ones.</p>
+ <p>
+ Own Id: OTP-12168 Aux Id: seq12711 </p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ ssh now has a format_status function to avoid printing
+ sensitive information in error loggs.</p>
+ <p>
+ Own Id: OTP-12030</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Known Bugs and Problems</title>
+ <list>
+ <item>
+ <p>
+ The option <c>parallel_login</c> didn't work with the
+ value <c>true</c>. All logins were serial.</p>
+ <p>
+ Own Id: OTP-12194</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
<section><title>Ssh 3.0.5</title>
<section><title>Fixed Bugs and Malfunctions</title>
diff --git a/lib/ssh/doc/src/ssh_connection.xml b/lib/ssh/doc/src/ssh_connection.xml
index 72e7252536..ff72cf7ee0 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>2013</year>
+ <year>2014</year>
<holder>Ericsson AB, All Rights Reserved</holder>
</copyright>
<legalnotice>
@@ -137,7 +137,7 @@
<tag><c><![CDATA[{pty, ssh_channel_id(),
boolean() = WantReply, {string() = Terminal, integer() = CharWidth,
- integer() = RowHeight, integer() = PixelWidth, integer() = PixelHight,
+ integer() = RowHeight, integer() = PixelWidth, integer() = PixelHeight,
[{atom() | integer() = Opcode,
integer() = Value}] = TerminalModes}}]]></c></tag>
<item>A pseudo-terminal has been requested for the
@@ -148,11 +148,11 @@
drawable area of the window. The <c>Opcode</c> in the
<c>TerminalModes</c> list is the mnemonic name, represented
as an lowercase erlang atom, defined in
- <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254 </url> section 8,
- or the opcode if the mnemonic name is not listed in the
+ <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254 </url> section 8.
+ It may also be an opcode if the mnemonic name is not listed in the
RFC. Example <c>OP code: 53, mnemonic name ECHO erlang atom:
- echo</c>. There is currently no API function to generate this
- event.</item>
+ echo</c>.This event is sent as result of calling <seealso
+ marker="ssh_connection#ptty_alloc/4">ssh_connection:ptty_alloc/4</seealso></item>
<tag><c><![CDATA[{shell, boolean() = WantReply}]]></c></tag>
<item> This message will request that the user's default shell
@@ -273,7 +273,52 @@
</desc>
</func>
- <func>
+ <func>
+ <name>ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> success | failure</name>
+ <fsummary>Send status replies to requests that want such replies. </fsummary>
+ <type>
+ <v> ConnectionRef = ssh_connection_ref() </v>
+ <v> ChannelId = ssh_channel_id()</v>
+ <v> Options = proplists:proplist()</v>
+ </type>
+ <desc>
+ <p> Sends a SSH Connection Protocol pty_req, to allocate a pseudo tty.
+ Should be called by a SSH client process.
+ Options are:
+ </p>
+
+ <taglist>
+ <tag>{term, string()}</tag>
+ <item>
+ Defaults to os:getenv("TERM") or "vt100" if it is undefined.
+ </item>
+ <tag>{width, integer()}</tag>
+ <item>
+ Defaults to 80 if pixel_width is not defined.
+ </item>
+ <tag>{height, integer()}</tag>
+ <item>
+ Defaults to 24 if pixel_height is not defined.
+ </item>
+ <tag>{pixel_width, integer()}</tag>
+ <item>
+ Is disregarded if width is defined.
+ </item>
+ <tag>{pixel_height, integer()}</tag>
+ <item>
+ Is disregarded if height is defined.
+ </item>
+ <tag>{pty_opts, [{posix_atom(), integer()}]}</tag>
+ <item>
+ Option may be an empty list, otherwise
+ see possible POSIX names in section 8 in <url href="http://www.ietf.org/rfc/rfc4254.txt"> RFC 4254</url>.
+ </item>
+ </taglist>
+
+ </desc>
+ </func>
+
+ <func>
<name>reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok</name>
<fsummary>Send status replies to requests that want such replies. </fsummary>
<type>
diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml
index e55d092fe2..ab111562f9 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>2013</year>
+ <year>2005</year><year>2014</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -81,6 +81,17 @@
<p>The timeout is passed to the ssh_channel start function,
and defaults to infinity.</p>
</item>
+ <tag>
+ <p><c><![CDATA[{sftp_vsn, integer()}]]></c></p>
+ </tag>
+ <item>
+ <p>
+ Desired SFTP protocol version.
+ The actual version will be the minimum of
+ the desired version and the maximum supported
+ versions by the SFTP server.
+ </p>
+ </item>
</taglist>
<p>All other options are directly passed to
<seealso marker="ssh">ssh:connect/3</seealso> or ignored if a
@@ -183,6 +194,118 @@
can be used for reading directory contents.</p>
</desc>
</func>
+
+ <func>
+ <name>open_tar(ChannelPid, Path, Mode) -></name>
+ <name>open_tar(ChannelPid, Path, Mode, Timeout) -> {ok, Handle} | {error, Reason}</name>
+ <fsummary>Opens a tar file on the server to which <v>ChannelPid</v> is connected and returns a handle</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Path = string()</v>
+ <v>Mode = [read] | [write] | [read,EncryptOpt] | [write,DecryptOpt] </v>
+ <v>EncryptOpt = {crypto,{InitFun,EncryptFun,CloseFun}}</v>
+ <v>DecryptOpt = {crypto,{InitFun,DecryptFun}}</v>
+ <v>InitFun = (fun() -> {ok,CryptoState}) | (fun() -> {ok,CryptoState,ChunkSize}) </v>
+ <v>CryptoState = any()</v>
+ <v>ChunkSize = undefined | pos_integer()</v>
+ <v>EncryptFun = (fun(PlainBin,CryptoState) -> EncryptResult)</v>
+ <v>EncryptResult = {ok,EncryptedBin,CryptoState} | {ok,EncryptedBin,CryptoState,ChunkSize}</v>
+ <v>PlainBin = binary()</v>
+ <v>EncryptedBin = binary()</v>
+ <v>DecryptFun = (fun(EncryptedBin,CryptoState) -> DecryptResult)</v>
+ <v>DecryptResult = {ok,PlainBin,CryptoState} | {ok,PlainBin,CryptoState,ChunkSize}</v>
+ <v>CloseFun = (fun(PlainBin,CryptoState) -> {ok,EncryptedBin})</v>
+ <v>Timeout = timeout()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Opens a handle to a tar file on the server associated with <c>ChannelPid</c>. The handle
+ can be used for remote tar creation and extraction as defined by the
+ <seealso marker="stdlib:erl_tar#init/3">erl_tar:init/3</seealso> function.
+ </p>
+ <p>An example of writing and then reading a tar file:</p>
+ <code type="none">
+ {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write]),
+ ok = erl_tar:add(HandleWrite, .... ),
+ ok = erl_tar:add(HandleWrite, .... ),
+ ...
+ ok = erl_tar:add(HandleWrite, .... ),
+ ok = erl_tar:close(HandleWrite),
+
+ %% And for reading
+ {ok,HandleRead} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [read]),
+ {ok,NameValueList} = erl_tar:extract(HandleRead,[memory]),
+ ok = erl_tar:close(HandleRead),
+ </code>
+
+ <p>The <c>crypto</c> mode option is applied to the generated stream of bytes just prior to sending
+ them to the sftp server. This is intended for encryption but could of course be used for other
+ purposes.
+ </p>
+ <p>The <c>InitFun</c> is applied once
+ prior to any other crypto operation. The returned <c>CryptoState</c> is then folded into
+ repeated applications of the <c>EncryptFun</c> or <c>DecryptFun</c>. The binary returned
+ from those Funs are sent further to the remote sftp server. Finally - if doing encryption
+ - the <c>CloseFun</c> is applied to the last piece of data. The <c>CloseFun</c> is
+ responsible for padding (if needed) and encryption of that last piece.
+ </p>
+ <p>The <c>ChunkSize</c> defines the size of the <c>PlainBin</c>s that <c>EncodeFun</c> is applied
+ to. If the <c>ChunkSize</c> is <c>undefined</c> the size of the <c>PlainBin</c>s varies because
+ this is inteded for stream crypto while a fixed <c>ChunkSize</c> is intended for block crypto. It
+ is possible to change the <c>ChunkSize</c>s in the return from the <c>EncryptFun</c> or
+ <c>DecryptFun</c>. It is in fact possible to change the value between <c>pos_integer()</c> and
+ <c>undefined</c>.
+ </p>
+ <p>The write and read example above can be extended with encryption and decryption:</p>
+ <code type="none">
+ %% First three parameters depending on which crypto type we select:
+ Key = &lt;&lt;"This is a 256 bit key. abcdefghi">>,
+ Ivec0 = crypto:rand_bytes(16),
+ DataSize = 1024, % DataSize rem 16 = 0 for aes_cbc
+
+ %% Initialization of the CryptoState, in this case it is the Ivector.
+ InitFun = fun() -> {ok, Ivec0, DataSize} end,
+
+ %% How to encrypt:
+ EncryptFun =
+ fun(PlainBin,Ivec) ->
+ EncryptedBin = crypto:block_encrypt(aes_cbc256, Key, Ivec, PlainBin),
+ {ok, EncryptedBin, crypto:next_iv(aes_cbc,EncryptedBin)}
+ end,
+
+ %% What to do with the very last block:
+ CloseFun =
+ fun(PlainBin, Ivec) ->
+ EncryptedBin = crypto:block_encrypt(aes_cbc256, Key, Ivec,
+ pad(16,PlainBin) %% Last chunk
+ ),
+ {ok, EncryptedBin}
+ end,
+
+ Cw = {InitFun,EncryptFun,CloseFun},
+ {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write,{crypto,Cw}]),
+ ok = erl_tar:add(HandleWrite, .... ),
+ ok = erl_tar:add(HandleWrite, .... ),
+ ...
+ ok = erl_tar:add(HandleWrite, .... ),
+ ok = erl_tar:close(HandleWrite),
+
+ %% And for decryption (in this crypto example we could use the same InitFun
+ %% as for encryption):
+ DecryptFun =
+ fun(EncryptedBin,Ivec) ->
+ PlainBin = crypto:block_decrypt(aes_cbc256, Key, Ivec, EncryptedBin),
+ {ok, PlainBin, crypto:next_iv(aes_cbc,EncryptedBin)}
+ end,
+
+ Cr = {InitFun,DecryptFun},
+ {ok,HandleRead} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [read,{crypto,Cw}]),
+ {ok,NameValueList} = erl_tar:extract(HandleRead,[memory]),
+ ok = erl_tar:close(HandleRead),
+ </code>
+ </desc>
+ </func>
+
<func>
<name>close(ChannelPid, Handle) -> </name>
<name>close(ChannelPid, Handle, Timeout) -> ok | {error, Reason}</name>
generated by cgit v1.2.3 (git 2.25.1) at 2024-08-13 07:24:34 +0000