diff options
Diffstat (limited to 'lib/ssh/doc/src')
| -rw-r--r-- | lib/ssh/doc/src/notes.xml | 94 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_connection.xml | 14 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_sftp.xml | 112 |
3 files changed, 214 insertions, 6 deletions
diff --git a/lib/ssh/doc/src/notes.xml b/lib/ssh/doc/src/notes.xml index f3db05192e..3aa61aa9ec 100644 --- a/lib/ssh/doc/src/notes.xml +++ b/lib/ssh/doc/src/notes.xml @@ -29,6 +29,100 @@ <file>notes.xml</file> </header> +<section><title>Ssh 3.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Make sure the clean rule for ssh, ssl, eunit and otp_mibs + actually removes generated files.</p> + <p> + Own Id: OTP-12200</p> + </item> + <item> + <p> + Improved Property Tests (Thanks to Thomas, John and + Tobias at QuviQ)</p> + <p> + Own Id: OTP-12256</p> + </item> + <item> + <p> + Correct typo of renegotiate that could cause rekeying to + fail</p> + <p> + Own Id: OTP-12277 Aux Id: seq12736 </p> + </item> + <item> + <p> + The {timeout, Timeout} option passed to + ssh_sftp:start_channel was not applied to the early + phases of the SSH protocol. This patch passes the Timeout + through to ssh:connect. In case the timeout occurs during + these phases, {error, timeout} is returned. (Thanks to + Simon Cornish)</p> + <p> + Own Id: OTP-12306</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Added API functions ptty_alloc/3 and ptty_alloc/4, to + allocate a pseudo tty.</p> + <p> + Own Id: OTP-11542 Aux Id: seq12493, OTP-11631 </p> + </item> + <item> + <p> + Supports tar file creation on other media than file + systems mounted on the local machine.</p> + <p> + The <c>erl_tar</c> api is extended with + <c>erl_tar:init/3</c> that enables usage of user provided + media storage routines. A ssh-specific set of such + routines is hidden in the new function + <c>ssh_sftp:open_tar/3</c> to simplify creating a tar + archive on a remote ssh server.</p> + <p> + A chunked file reading option is added to + <c>erl_tar:add/3,4</c> to save memory on e.g small + embedded systems. The size of the slices read from a file + in that case can be specified.</p> + <p> + Own Id: OTP-12180 Aux Id: seq12715 </p> + </item> + <item> + <p> + Always send SSH_DISCONNECT protocol messages when peer + sends corrupt messages.</p> + <p> + Own Id: OTP-12185</p> + </item> + <item> + <p> + Hooks for funs that can change binaries sent to remote + sites from erl_tar for renote tar file creation are + added. See <c>ssh_sftp:open_tar/3,4</c> for details. The + hooks could also be used to read remote tar files that + need transformation before file extraction.</p> + <p> + Those hooks are intended for encryption and decryption of + tar files. Effort is put into memory, disk and network + resource economy.</p> + <p> + Own Id: OTP-12312 Aux Id: OTP-12180 </p> + </item> + </list> + </section> + +</section> + <section><title>Ssh 3.0.8</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 ff72cf7ee0..5e2926dfa6 100644 --- a/lib/ssh/doc/src/ssh_connection.xml +++ b/lib/ssh/doc/src/ssh_connection.xml @@ -62,6 +62,7 @@ <p><c>ssh_request_status() = success | failure</c></p> <p><c>event() = {ssh_cm, ssh_connection_ref(), ssh_event_msg()} </c></p> <p><c>ssh_event_msg() = data_events() | status_events() | terminal_events() </c></p> + <p><c>reason() = timeout | closed </c></p> <taglist> <tag><b>data_events()</b></tag> @@ -218,7 +219,7 @@ </func> <func> - <name>exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() </name> + <name>exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() | {error, reason()} </name> <fsummary>Request that the server start the execution of the given command. </fsummary> <type> <v> ConnectionRef = ssh_connection_ref() </v> @@ -274,7 +275,8 @@ </func> <func> - <name>ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> success | failure</name> + <name>ptty_alloc(ConnectionRef, ChannelId, Options) -> </name> + <name>ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> > ssh_request_status() | {error, reason()} </name> <fsummary>Send status replies to requests that want such replies. </fsummary> <type> <v> ConnectionRef = ssh_connection_ref() </v> @@ -374,7 +376,7 @@ <func> <name>session_channel(ConnectionRef, Timeout) -> </name> <name>session_channel(ConnectionRef, InitialWindowSize, - MaxPacketSize, Timeout) -> {ok, ssh_channel_id()} | {error, Reason}</name> + MaxPacketSize, Timeout) -> {ok, ssh_channel_id()} | {error, reason()}</name> <fsummary>Opens a channel for a ssh session. </fsummary> <type> <v> ConnectionRef = ssh_connection_ref()</v> @@ -391,7 +393,7 @@ </func> <func> - <name>setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status()</name> + <name>setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status() | {error, reason()} </name> <fsummary> Environment variables may be passed to the shell/command to be started later.</fsummary> <type> @@ -409,7 +411,7 @@ </func> <func> - <name>shell(ConnectionRef, ChannelId) -> ssh_request_status() + <name>shell(ConnectionRef, ChannelId) -> ssh_request_status() | {error, closed} </name> <fsummary> Requests that the user's default shell (typically defined in /etc/passwd in UNIX systems) shall be executed at the server @@ -426,7 +428,7 @@ </func> <func> - <name>subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status()</name> + <name>subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status() | {error, reason()} </name> <fsummary> </fsummary> <type> <v> ConnectionRef = ssh_connection_ref() </v> diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml index f1091e9eca..ab111562f9 100644 --- a/lib/ssh/doc/src/ssh_sftp.xml +++ b/lib/ssh/doc/src/ssh_sftp.xml @@ -194,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 = <<"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> |