1 files changed, 141 insertions, 0 deletions
diff --git a/doc/tutorial2.tex b/doc/tutorial2.tex
new file mode 100644
index 000000000..840679d10
--- /dev/null
+++ b/doc/tutorial2.tex
@@ -0,0 +1,141 @@
+\documentclass{article}
+
+\setlength{\textwidth}{6.5in} % 1 inch side margins
+\setlength{\textheight}{9in} % ~1 inch top and bottom margins
+
+\setlength{\headheight}{0in}
+\setlength{\topmargin}{0in}
+\setlength{\headsep}{0in}
+
+\setlength{\oddsidemargin}{0in}
+\setlength{\evensidemargin}{0in}
+
+\title{\textbf{Botan Tutorial}}
+\author{Jack Lloyd \\
+        \texttt{[email protected]}}
+\date{2010/08/07}
+
+\newcommand{\filename}[1]{\texttt{#1}}
+\newcommand{\manpage}[2]{\texttt{#1}(#2)}
+
+\newcommand{\macro}[1]{\texttt{#1}}
+
+\newcommand{\function}[1]{\textbf{#1}}
+\newcommand{\type}[1]{\texttt{#1}}
+\renewcommand{\arg}[1]{\textsl{#1}}
+\newcommand{\variable}[1]{\textsl{#1}}
+
+\begin{document}
+
+\maketitle
+
+\tableofcontents
+
+\parskip=5pt
+\pagebreak
+
+\section{Introduction}
+
+This document essentially sets up various simple scenarios and then
+shows how to solve the problems using botan. It's fairly simple, and
+doesn't cover many of the available APIs and algorithms, especially
+the more obscure or unusual ones. It is a supplement to the API
+documentation and the example applications, which are included in the
+distribution.
+
+\section{Initializing the Library}
+
+The first step to using botan is to create a \type{LibraryInitializer}
+object, which handles creating various internal structures, and also
+destroying them at shutdown.
+
+\begin{verbatim}
+#include <botan/botan.h>
+
+int main()
+   {
+   Botan::LibraryInitializer init;
+   return 0;
+   }
+\end{verbatim}
+
+If your application is multi-threaded, you need to tell botan this so
+that it will use locking where necessary. This is done by passing a
+string to the constructor of \type{LibraryInitializer}:
+
+\begin{verbatim}
+    Botan::LibraryInitializer init("thread_safe=yes");
+\end{verbatim}
+
+\section{Introduction to Pipe}
+
+Most operations in botan are specified in terms of transformations on
+streams. The class that handles the I/O and management for these
+streams is called \type{Pipe}. You can construct a \type{Pipe} with
+one or more \type{Filter}s, which sequentially process messages. You
+can only update a single message at a time, but you can leave the
+final output contents in a \type{Pipe} and read them out as desired.
+
+Here is how you might hex encode two messages:
+
+\begin{verbatim}
+   std::string message1 = "this is the first message";
+   const byte message2[] = "a second message";
+   Pipe pipe(new Hex_Encoder);
+
+   pipe.start_msg(); // must be called before writing to the pipe
+   pipe.write(message1);
+   pipe.end_msg(); // must be called to signal completion
+
+   /*
+   process_msg(x) is equivalent to calling
+      start_msg(); write(x); end_msg();
+   */
+   pipe.process_msg(message2);
+
+   Pipe::message_id n = pipe.message_count(); // returns 2
+
+   /* you can read a message as a string, here we read message 0 */
+   std::string first_result = pipe.read_all_as_string(0);
+
+   /* or a piece at a time using array/length, now we'll read the
+      second message (message id 1)
+   */
+
+   byte output[4096] = { 0 };
+   u32bit got = read(output, sizeof(output), 1);
+   if(got >= sizeof(output))
+     // have to read again to get more of the message
+\end{verbatim}
+
+You can also read output while the message is still active (before the
+call to \function{end\_msg}), using the same interfaces. You can find
+out how much data is currently available for a particular \type{Pipe}
+by calling the member function \function{remaining}, which takes a
+message sequence number and returns the number of bytes that are
+currently available to read from that message.
+
+\section{Hashing a File}
+
+Hashing a file is done using a \type{Hash\_Filter}, which takes a string
+which specifies which hash function you want to use:
+
+\begin{verbatim}
+   Pipe pipe(new Hash_Filter("SHA-256"));
+\end{verbatim}
+
+The output of a \type{Hash\_Filter} is raw binary. The filter will not
+produce any output at all until you call \function{end\_msg}.
+
+\section{Symmetric Cryptography}
+
+
+
+\subsection{Authentication}
+
+\subsection{User Authentication}
+
+\section{Public Key Cryptography}
+
+
+\end{document}