From 6509b6e7421f480e481d087d613f334779cfb38b Mon Sep 17 00:00:00 2001 From: Andreas Schneider Date: Sat, 19 Dec 2009 00:31:47 +0100 Subject: Started to add the tutorial to doxygen. --- doc/tutorial.dox | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 doc/tutorial.dox (limited to 'doc') 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 + */ -- cgit v1.2.3