ssh: Move code example to Users Guide

1 files changed, 67 insertions, 0 deletions

diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml
index 64477cb493..9da839d072 100644
--- a/lib/ssh/doc/src/using_ssh.xml
+++ b/lib/ssh/doc/src/using_ssh.xml
@@ -229,6 +229,73 @@
   </section>
 
   <section>
+    <title>SFTP Client with TAR Compression and Encryption</title>
+
+    <p>Example of writing and then reading a tar file follows:</p>
+    <code type="erlang">
+      {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 previous write and read example can be extended with encryption and decryption as follows:</p>
+    <code type="erlang">
+      %% 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>
+  </section>
+
+  <section>
     <title>Creating a Subsystem</title>
 
     <p>A small <c>ssh</c> subsystem that echoes N bytes can be implemented as shown