Started to add the tutorial to doxygen.

doc/tutorial.dox

@@ -0,0 +1,68 @@
+/**
+ * @page tutorial The Tutorial
+ *
+ * @section introduction Introduction
+ *
+ * Before inserting ssh hooks into your programs, you must know some basics
+ * about the ssh protocol, and understand why the ssh library must implement
+ * them. Lot of the protocols specifications are hidden by the ssh library API
+ * (of course !) but some still needs an attention from the end-user
+ * programmer. Note that libssh is still an alpha product, and the API may vary
+ * from one version to another. The only guess I can make is that the API won't
+ * radically change.
+ *
+ * The SSH protocol was designed for some goals which I resume here :
+ *
+ *   - Privacy of data
+ *   - Security
+ *   - Authentication of the server
+ *   - Authentication of the client
+ *
+ * The client MUST be sure who's speaking to before entering into any
+ * authentication way. That's where the end programmer must ensure the given
+ * fingerprints *are* from the legitimate server. A ssh connection must follow
+ * the following steps:
+ *
+ *  - Before connecting the socket, you can set up if you wish one or other
+ *  server public key authentication ie. DSA or RSA. You can choose
+ *  cryptographic algorithms you trust and compression algorithms if any.
+ *
+ *  - The connection is made. A secure handshake is made, and resulting from
+ *  it, a public key from the server is gained. You MUST verify that the public
+ *  key is legitimate.
+
+ *  - The client must authenticate : the two implemented ways are password, and
+ *  public keys (from dsa and rsa key-pairs generated by openssh). It is
+ *  harmless to authenticate to a fake server with these keys because the
+ *  protocol ensures the data you sign can't be used twice. It just avoids
+ *  man-in-the-middle attacks.
+ *
+ *   - Now that the user has been authenticated, you must open one or several
+ *   channels. channels are different subways for information into a single ssh
+ *   connection. Each channel has a standard stream (stdout) and an error stream
+ *   (stderr). You can theoretically open an infinity of channel.
+ *
+ *   - With the channel you opened, you can do several things :
+ *     - Open a shell. You may want to request a pseudo virtual terminal before
+ *     - Execute a command. The virtual terminal is usable, too
+ *     - Invoke the sftp subsystem. (look at chapter 6)
+ *     - invoke your own subsystem. This is out the scope of this document but it is easy to do. 
+ *
+ *   - When everything is finished, just close the channels, and then the connection. 
+ *
+ * At every place, a function which returns an error code (typically -1 for int
+ * values, NULL for pointers) also sets an error message and an error code. I
+ * high-lined the main steps, now that's you to follow them :) 
+ *
+ * @section setup Creating the session and setting options
+ *
+ * TODO
+ *
+ * @section connect Connecting to the server
+ *
+ * TODO
+ *
+ * @section auth Authentication
+ *
+ * TODO
+ */