aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/tutorial.dox68
1 files changed, 68 insertions, 0 deletions
diff --git a/doc/tutorial.dox b/doc/tutorial.dox
new file mode 100644
index 00000000..700d41c4
--- /dev/null
+++ b/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
+ */