1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
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{lloyd@randombit.net}}
\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}
|
