Mercurial > dropbear
annotate crypt.tex @ 381:999a5eb4ed10 libtomcrypt-dropbear
propagate from branch 'au.asn.ucc.matt.ltc.orig' (head 52840647ac7f5c707c3bd158d119a15734a7ef28)
to branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
| author | Matt Johnston <matt@ucc.asn.au> |
|---|---|
| date | Thu, 11 Jan 2007 02:39:21 +0000 |
| parents | d5faf4814ddb |
| children |
| rev | line source |
|---|---|
| 380 | 1 \documentclass[synpaper]{book} |
| 2 \usepackage[dvips]{geometry} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3 \usepackage{hyperref} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4 \usepackage{makeidx} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5 \usepackage{amssymb} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
6 \usepackage{color} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
7 \usepackage{alltt} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
8 \usepackage{graphicx} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
9 \usepackage{layout} |
| 380 | 10 \usepackage{fancyhdr} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
11 \def\union{\cup} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
12 \def\intersect{\cap} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
13 \def\getsrandom{\stackrel{\rm R}{\gets}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
14 \def\cross{\times} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
15 \def\cat{\hspace{0.5em} \| \hspace{0.5em}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
16 \def\catn{$\|$} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
17 \def\divides{\hspace{0.3em} | \hspace{0.3em}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
18 \def\nequiv{\not\equiv} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
19 \def\approx{\raisebox{0.2ex}{\mbox{\small $\sim$}}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
20 \def\lcm{{\rm lcm}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
21 \def\gcd{{\rm gcd}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
22 \def\log{{\rm log}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
23 \def\ord{{\rm ord}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
24 \def\abs{{\mathit abs}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
25 \def\rep{{\mathit rep}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
26 \def\mod{{\mathit\ mod\ }} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
27 \renewcommand{\pmod}[1]{\ ({\rm mod\ }{#1})} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
28 \newcommand{\floor}[1]{\left\lfloor{#1}\right\rfloor} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
29 \newcommand{\ceil}[1]{\left\lceil{#1}\right\rceil} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
30 \def\Or{{\rm\ or\ }} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
31 \def\And{{\rm\ and\ }} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
32 \def\iff{\hspace{1em}\Longleftrightarrow\hspace{1em}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
33 \def\implies{\Rightarrow} |
| 380 | 34 \def\undefined{{\rm \textit{undefined}}} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
35 \def\Proof{\vspace{1ex}\noindent {\bf Proof:}\hspace{1em}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
36 \let\oldphi\phi |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
37 \def\phi{\varphi} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
38 \def\Pr{{\rm Pr}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
39 \newcommand{\str}[1]{{\mathbf{#1}}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
40 \def\F{{\mathbb F}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
41 \def\N{{\mathbb N}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
42 \def\Z{{\mathbb Z}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
43 \def\R{{\mathbb R}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
44 \def\C{{\mathbb C}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
45 \def\Q{{\mathbb Q}} |
| 380 | 46 \definecolor{DGray}{gray}{0.5} |
| 47 \newcommand{\emailaddr}[1]{\mbox{$<${#1}$>$}} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
48 \def\twiddle{\raisebox{0.3ex}{\mbox{\tiny $\sim$}}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
49 \def\gap{\vspace{0.5ex}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
50 \makeindex |
| 380 | 51 \newcommand{\mysection}[1] % Re-define the chaptering command to use |
| 52 { % THESE headers. | |
| 53 \section{#1} | |
| 54 \markboth{\textsf{www.libtom.org}}{\thesection ~ {#1}} | |
| 55 } | |
| 56 | |
| 57 \newcommand{\mystarsection}[1] % Re-define the chaptering command to use | |
| 58 { % THESE headers. | |
| 59 \section*{#1} | |
| 60 \markboth{\textsf{www.libtom.org}}{{#1}} | |
| 61 } | |
| 62 \pagestyle{empty} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
63 \begin{document} |
| 380 | 64 \frontmatter |
| 65 \pagestyle{empty} | |
| 66 | |
| 67 ~ | |
| 68 | |
| 69 \vspace{2in} | |
| 70 | |
| 71 ~ | |
| 72 | |
| 73 \begin{center} | |
| 74 \begin{Huge}LibTomCrypt\end{Huge} | |
| 75 | |
| 76 ~ | |
| 77 | |
| 78 \begin{large}Developer Manual\end{large} | |
| 79 | |
| 80 ~ | |
| 81 | |
| 82 \vspace{15mm} | |
| 83 | |
| 84 | |
| 85 \begin{tabular}{c} | |
| 86 Tom St Denis \\ | |
| 87 LibTom Projects | |
| 88 \end{tabular} | |
| 89 \end{center} | |
| 90 \vfil | |
| 91 \newpage | |
| 92 This document is part of the LibTomCrypt package and is hereby released into the public domain. | |
| 93 | |
| 94 ~ | |
| 95 | |
| 96 Open Source. Open Academia. Open Minds. | |
| 97 | |
| 98 ~ | |
| 99 | |
| 100 \begin{flushright} | |
| 101 Tom St Denis | |
| 102 ~ | |
| 103 | |
| 104 Ottawa, Ontario | |
| 105 ~ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
106 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
107 Canada |
| 380 | 108 ~ |
| 109 \vfil | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
110 \end{flushright} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
111 \newpage |
| 380 | 112 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
113 \tableofcontents |
| 380 | 114 \listoffigures |
| 115 \pagestyle{myheadings} | |
| 116 \mainmatter | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
117 \chapter{Introduction} |
| 380 | 118 \mysection{What is the LibTomCrypt?} |
| 119 LibTomCrypt is a portable ISO C cryptographic library meant to be a tool set for cryptographers who are | |
| 120 designing cryptosystems. It supports symmetric ciphers, one-way hashes, pseudo-random number generators, | |
| 121 public key cryptography (via PKCS \#1 RSA, DH or ECCDH), and a plethora of support routines. | |
| 122 | |
| 123 The library was designed such that new ciphers/hashes/PRNGs can be added at run-time and the existing API | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
124 (and helper API functions) are able to use the new designs automatically. There exists self-check functions for each |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
125 block cipher and hash function to ensure that they compile and execute to the published design specifications. The library |
| 380 | 126 also performs extensive parameter error checking to prevent any number of run-time exploits or errors. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
127 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
128 \subsection{What the library IS for?} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
129 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
130 The library serves as a toolkit for developers who have to solve cryptographic problems. Out of the box LibTomCrypt |
| 380 | 131 does not process SSL or OpenPGP messages, it doesn't read X.509 certificates, or write PEM encoded data. It does, however, |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
132 provide all of the tools required to build such functionality. LibTomCrypt was designed to be a flexible library that |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
133 was not tied to any particular cryptographic problem. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
134 |
| 380 | 135 \mysection{Why did I write it?} |
| 136 You may be wondering, \textit{Tom, why did you write a crypto library. I already have one.} Well the reason falls into | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
137 two categories: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
138 \begin{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
139 \item I am too lazy to figure out someone else's API. I'd rather invent my own simpler API and use that. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
140 \item It was (still is) good coding practice. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
141 \end{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
142 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
143 The idea is that I am not striving to replace OpenSSL or Crypto++ or Cryptlib or etc. I'm trying to write my |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
144 {\bf own} crypto library and hopefully along the way others will appreciate the work. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
145 |
| 380 | 146 With this library all core functions (ciphers, hashes, prngs, and bignum) have the same prototype definition. They all load |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
147 and store data in a format independent of the platform. This means if you encrypt with Blowfish on a PPC it should decrypt |
| 380 | 148 on an x86 with zero problems. The consistent API also means that if you learn how to use Blowfish with the library you |
| 149 know how to use Safer+, RC6, or Serpent as well. With all of the core functions there are central descriptor tables | |
| 150 that can be used to make a program automatically pick between ciphers, hashes and PRNGs at run-time. That means your | |
| 151 application can support all ciphers/hashes/prngs/bignum without changing the source code. | |
| 152 | |
| 153 Not only did I strive to make a consistent and simple API to work with but I also attempted to make the library | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
154 configurable in terms of its build options. Out of the box the library will build with any modern version of GCC |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
155 without having to use configure scripts. This means that the library will work with platforms where development |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
156 tools may be limited (e.g. no autoconf). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
157 |
| 380 | 158 On top of making the build simple and the API approachable I've also attempted for a reasonably high level of |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
159 robustness and efficiency. LibTomCrypt traps and returns a series of errors ranging from invalid |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
160 arguments to buffer overflows/overruns. It is mostly thread safe and has been clocked on various platforms |
| 380 | 161 with \textit{cycles per byte} timings that are comparable (and often favourable) to other libraries such as OpenSSL and |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
162 Crypto++. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
163 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
164 \subsection{Modular} |
| 380 | 165 The LibTomCrypt package has also been written to be very modular. The block ciphers, one--way hashes, |
| 166 pseudo--random number generators (PRNG), and bignum math routines are all used within the API through \textit{descriptor} tables which | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
167 are essentially structures with pointers to functions. While you can still call particular functions |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
168 directly (\textit{e.g. sha256\_process()}) this descriptor interface allows the developer to customize their |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
169 usage of the library. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
170 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
171 For example, consider a hardware platform with a specialized RNG device. Obviously one would like to tap |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
172 that for the PRNG needs within the library (\textit{e.g. making a RSA key}). All the developer has to do |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
173 is write a descriptor and the few support routines required for the device. After that the rest of the |
| 380 | 174 API can make use of it without change. Similarly imagine a few years down the road when AES2 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
175 (\textit{or whatever they call it}) has been invented. It can be added to the library and used within applications |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
176 with zero modifications to the end applications provided they are written properly. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
177 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
178 This flexibility within the library means it can be used with any combination of primitive algorithms and |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
179 unlike libraries like OpenSSL is not tied to direct routines. For instance, in OpenSSL there are CBC block |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
180 mode routines for every single cipher. That means every time you add or remove a cipher from the library |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
181 you have to update the associated support code as well. In LibTomCrypt the associated code (\textit{chaining modes in this case}) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
182 are not directly tied to the ciphers. That is a new cipher can be added to the library by simply providing |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
183 the key setup, ECB decrypt and encrypt and test vector routines. After that all five chaining mode routines |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
184 can make use of the cipher right away. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
185 |
| 380 | 186 \mysection{License} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
187 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
188 The project is hereby released as public domain. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
189 |
| 380 | 190 \mysection{Patent Disclosure} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
191 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
192 The author (Tom St Denis) is not a patent lawyer so this section is not to be treated as legal advice. To the best |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
193 of the authors knowledge the only patent related issues within the library are the RC5 and RC6 symmetric block ciphers. |
| 380 | 194 They can be removed from a build by simply commenting out the two appropriate lines in \textit{tomcrypt\_custom.h}. The rest |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
195 of the ciphers and hashes are patent free or under patents that have since expired. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
196 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
197 The RC2 and RC4 symmetric ciphers are not under patents but are under trademark regulations. This means you can use |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
198 the ciphers you just can't advertise that you are doing so. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
199 |
| 380 | 200 \mysection{Thanks} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
201 I would like to give thanks to the following people (in no particular order) for helping me develop this project from |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
202 early on: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
203 \begin{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
204 \item Richard van de Laarschot |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
205 \item Richard Heathfield |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
206 \item Ajay K. Agrawal |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
207 \item Brian Gladman |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
208 \item Svante Seleborg |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
209 \item Clay Culver |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
210 \item Jason Klapste |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
211 \item Dobes Vandermeer |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
212 \item Daniel Richards |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
213 \item Wayne Scott |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
214 \item Andrew Tyler |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
215 \item Sky Schulz |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
216 \item Christopher Imes |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
217 \end{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
218 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
219 There have been quite a few other people as well. Please check the change log to see who else has contributed from |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
220 time to time. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
221 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
222 \chapter{The Application Programming Interface (API)} |
| 380 | 223 \mysection{Introduction} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
224 \index{CRYPT\_ERROR} \index{CRYPT\_OK} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
225 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
226 In general the API is very simple to memorize and use. Most of the functions return either {\bf void} or {\bf int}. Functions |
| 380 | 227 that return {\bf int} will return {\bf CRYPT\_OK} if the function was successful, or one of the many error codes |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
228 if it failed. Certain functions that return int will return $-1$ to indicate an error. These functions will be explicitly |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
229 commented upon. When a function does return a CRYPT error code it can be translated into a string with |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
230 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
231 \index{error\_to\_string()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
232 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
233 const char *error_to_string(int err); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
234 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
235 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
236 An example of handling an error is: |
| 380 | 237 \begin{small} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
238 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
239 void somefunc(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
240 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
241 int err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
242 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
243 /* call a cryptographic function */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
244 if ((err = some_crypto_function(...)) != CRYPT_OK) { |
| 380 | 245 printf("A crypto error occurred, %s\n", error_to_string(err)); |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
246 /* perform error handling */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
247 } |
| 380 | 248 /* continue on if no error occurred */ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
249 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
250 \end{verbatim} |
| 380 | 251 \end{small} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
252 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
253 There is no initialization routine for the library and for the most part the code is thread safe. The only thread |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
254 related issue is if you use the same symmetric cipher, hash or public key state data in multiple threads. Normally |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
255 that is not an issue. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
256 |
| 380 | 257 To include the prototypes for \textit{LibTomCrypt.a} into your own program simply include \textit{tomcrypt.h} like so: |
| 258 \begin{small} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
259 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
260 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
261 int main(void) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
262 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
263 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
264 \end{verbatim} |
| 380 | 265 \end{small} |
| 266 | |
| 267 The header file \textit{tomcrypt.h} also includes \textit{stdio.h}, \textit{string.h}, \textit{stdlib.h}, \textit{time.h} and \textit{ctype.h}. | |
| 268 | |
| 269 \mysection{Macros} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
270 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
271 There are a few helper macros to make the coding process a bit easier. The first set are related to loading and storing |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
272 32/64-bit words in little/big endian format. The macros are: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
273 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
274 \index{STORE32L} \index{STORE64L} \index{LOAD32L} \index{LOAD64L} \index{STORE32H} \index{STORE64H} \index{LOAD32H} \index{LOAD64H} \index{BSWAP} |
| 380 | 275 \newpage |
| 276 \begin{figure}[hpbt] | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
277 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
278 \begin{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
279 \begin{tabular}{|c|c|c|} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
280 \hline STORE32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 3]$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
281 \hline STORE64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 7]$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
282 \hline LOAD32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[0 \ldots 3] \to x$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
283 \hline LOAD64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[0 \ldots 7] \to x$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
284 \hline STORE32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[3 \ldots 0]$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
285 \hline STORE64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[7 \ldots 0]$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
286 \hline LOAD32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[3 \ldots 0] \to x$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
287 \hline LOAD64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[7 \ldots 0] \to x$ \\ |
| 380 | 288 \hline BSWAP(x) & {\bf unsigned long} x & Swap bytes \\ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
289 \hline |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
290 \end{tabular} |
| 380 | 291 \caption{Load And Store Macros} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
292 \end{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
293 \end{small} |
| 380 | 294 \end{figure} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
295 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
296 There are 32 and 64-bit cyclic rotations as well: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
297 \index{ROL} \index{ROR} \index{ROL64} \index{ROR64} \index{ROLc} \index{RORc} \index{ROL64c} \index{ROR64c} |
| 380 | 298 \begin{figure}[hpbt] |
| 299 \begin{small} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
300 \begin{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
301 \begin{tabular}{|c|c|c|} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
302 \hline ROL(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x << y, 0 \le y \le 31$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
303 \hline ROLc(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x << y, 0 \le y \le 31$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
304 \hline ROR(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x >> y, 0 \le y \le 31$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
305 \hline RORc(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x >> y, 0 \le y \le 31$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
306 \hline && \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
307 \hline ROL64(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x << y, 0 \le y \le 63$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
308 \hline ROL64c(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x << y, 0 \le y \le 63$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
309 \hline ROR64(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x >> y, 0 \le y \le 63$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
310 \hline ROR64c(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x >> y, 0 \le y \le 63$ \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
311 \hline |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
312 \end{tabular} |
| 380 | 313 \caption{Rotate Macros} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
314 \end{center} |
| 380 | 315 \end{small} |
| 316 \end{figure} | |
| 317 | |
| 318 \mysection{Functions with Variable Length Output} | |
| 319 Certain functions such as (for example) \textit{rsa\_export()} give an output that is variable length. To prevent buffer overflows you | |
| 320 must pass it the length of the buffer where the output will be stored. For example: | |
| 321 \index{rsa\_export()} \index{error\_to\_string()} \index{variable length output} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
322 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
323 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
324 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
325 int main(void) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
326 rsa_key key; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
327 unsigned char buffer[1024]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
328 unsigned long x; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
329 int err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
330 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
331 /* ... Make up the RSA key somehow ... */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
332 |
| 380 | 333 /* lets export the key, set x to the size of the |
| 334 * output buffer */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
335 x = sizeof(buffer); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
336 if ((err = rsa_export(buffer, &x, PK_PUBLIC, &key)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
337 printf("Export error: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
338 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
339 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
340 |
| 380 | 341 /* if rsa_export() was successful then x will have |
| 342 * the size of the output */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
343 printf("RSA exported key takes %d bytes\n", x); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
344 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
345 /* ... do something with the buffer */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
346 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
347 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
348 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
349 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
350 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
351 In the above example if the size of the RSA public key was more than 1024 bytes this function would return an error code |
| 380 | 352 indicating a buffer overflow would have occurred. If the function succeeds, it stores the length of the output back into |
| 353 \textit{x} so that the calling application will know how many bytes were used. | |
| 354 | |
| 355 As of v1.13, most functions will update your length on failure to indicate the size required by the function. Not all functions | |
| 356 support this so please check the source before you rely on it doing that. | |
| 357 | |
| 358 \mysection{Functions that need a PRNG} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
359 \index{Pseudo Random Number Generator} \index{PRNG} |
| 380 | 360 Certain functions such as \textit{rsa\_make\_key()} require a Pseudo Random Number Generator (PRNG). These functions do not setup |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
361 the PRNG themselves so it is the responsibility of the calling function to initialize the PRNG before calling them. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
362 |
| 380 | 363 Certain PRNG algorithms do not require a \textit{prng\_state} argument (sprng for example). The \textit{prng\_state} argument |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
364 may be passed as \textbf{NULL} in such situations. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
365 |
| 380 | 366 \index{register\_prng()} \index{rsa\_make\_key()} |
| 367 \begin{small} | |
| 368 \begin{verbatim} | |
| 369 #include <tomcrypt.h> | |
| 370 int main(void) { | |
| 371 rsa_key key; | |
| 372 int err; | |
| 373 | |
| 374 /* register the system RNG */ | |
| 375 register_prng(&sprng_desc) | |
| 376 | |
| 377 /* make a 1024-bit RSA key with the system RNG */ | |
| 378 if ((err = rsa_make_key(NULL, find_prng("sprng"), 1024/8, 65537, &key)) | |
| 379 != CRYPT_OK) { | |
| 380 printf("make_key error: %s\n", error_to_string(err)); | |
| 381 return -1; | |
| 382 } | |
| 383 | |
| 384 /* use the key ... */ | |
| 385 | |
| 386 return 0; | |
| 387 } | |
| 388 \end{verbatim} | |
| 389 \end{small} | |
| 390 | |
| 391 \mysection{Functions that use Arrays of Octets} | |
| 392 Most functions require inputs that are arrays of the data type \textit{unsigned char}. Whether it is a symmetric key, IV | |
| 393 for a chaining mode or public key packet it is assumed that regardless of the actual size of \textit{unsigned char} only the | |
| 394 lower eight bits contain data. For example, if you want to pass a 256 bit key to a symmetric ciphers setup routine, you | |
| 395 must pass in (a pointer to) an array of 32 \textit{unsigned char} variables. Certain routines (such as SAFER+) take | |
| 396 special care to work properly on platforms where an \textit{unsigned char} is not eight bits. | |
| 397 | |
| 398 For the purposes of this library, the term \textit{byte} will refer to an octet or eight bit word. Typically an array of | |
| 399 type \textit{byte} will be synonymous with an array of type \textit{unsigned char.} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
400 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
401 \chapter{Symmetric Block Ciphers} |
| 380 | 402 \mysection{Core Functions} |
| 403 LibTomCrypt provides several block ciphers with an ECB block mode interface. It is important to first note that you | |
| 404 should never use the ECB modes directly to encrypt data. Instead you should use the ECB functions to make a chaining mode, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
405 or use one of the provided chaining modes. All of the ciphers are written as ECB interfaces since it allows the rest of |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
406 the API to grow in a modular fashion. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
407 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
408 \subsection{Key Scheduling} |
| 380 | 409 All ciphers store their scheduled keys in a single data type called \textit{symmetric\_key}. This allows all ciphers to |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
410 have the same prototype and store their keys as naturally as possible. This also removes the need for dynamic memory |
| 380 | 411 allocation, and allows you to allocate a fixed sized buffer for storing scheduled keys. All ciphers must provide six visible |
| 412 functions which are (given that XXX is the name of the cipher) the following: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
413 \index{Cipher Setup} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
414 \begin{verbatim} |
| 380 | 415 int XXX_setup(const unsigned char *key, |
| 416 int keylen, | |
| 417 int rounds, | |
| 418 symmetric_key *skey); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
419 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
420 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
421 The XXX\_setup() routine will setup the cipher to be used with a given number of rounds and a given key length (in bytes). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
422 The number of rounds can be set to zero to use the default, which is generally a good idea. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
423 |
| 380 | 424 If the function returns successfully the variable \textit{skey} will have a scheduled key stored in it. It's important to note |
| 425 that you should only used this scheduled key with the intended cipher. For example, if you call \textit{blowfish\_setup()} do not | |
| 426 pass the scheduled key onto \textit{rc5\_ecb\_encrypt()}. All built--in setup functions do not allocate memory off the heap so | |
| 427 when you are done with a key you can simply discard it (e.g. they can be on the stack). However, to maintain proper coding | |
| 428 practices you should always call the respective XXX\_done() function. This allows for quicker porting to applications with | |
| 429 externally supplied plugins. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
430 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
431 \subsection{ECB Encryption and Decryption} |
| 380 | 432 To encrypt or decrypt a block in ECB mode there are these two functions per cipher: |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
433 \index{Cipher Encrypt} \index{Cipher Decrypt} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
434 \begin{verbatim} |
| 380 | 435 int XXX_ecb_encrypt(const unsigned char *pt, |
| 436 unsigned char *ct, | |
| 437 symmetric_key *skey); | |
| 438 | |
| 439 int XXX_ecb_decrypt(const unsigned char *ct, | |
| 440 unsigned char *pt, | |
| 441 symmetric_key *skey); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
442 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
443 These two functions will encrypt or decrypt (respectively) a single block of text\footnote{The size of which depends on |
| 380 | 444 which cipher you are using.}, storing the result in the \textit{ct} buffer (\textit{pt} resp.). It is possible that the input and output buffer are |
| 445 the same buffer. For the encrypt function \textit{pt}\footnote{pt stands for plaintext.} is the input and | |
| 446 \textit{ct}\footnote{ct stands for ciphertext.} is the output. For the decryption function it's the opposite. They both | |
| 447 return \textbf{CRYPT\_OK} on success. To test a particular cipher against test vectors\footnote{As published in their design papers.} | |
| 448 call the following self-test function. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
449 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
450 \subsection{Self--Testing} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
451 \index{Cipher Testing} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
452 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
453 int XXX_test(void); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
454 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
455 This function will return {\bf CRYPT\_OK} if the cipher matches the test vectors from the design publication it is |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
456 based upon. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
457 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
458 \subsection{Key Sizing} |
| 380 | 459 For each cipher there is a function which will help find a desired key size. It is specified as follows: |
| 460 \index{Key Sizing} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
461 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
462 int XXX_keysize(int *keysize); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
463 \end{verbatim} |
| 380 | 464 Essentially, it will round the input keysize in \textit{keysize} down to the next appropriate key size. This function |
| 465 will return {\bf CRYPT\_OK} if the key size specified is acceptable. For example: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
466 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
467 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
468 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
469 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
470 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
471 int keysize, err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
472 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
473 /* now given a 20 byte key what keysize does Twofish want to use? */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
474 keysize = 20; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
475 if ((err = twofish_keysize(&keysize)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
476 printf("Error getting key size: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
477 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
478 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
479 printf("Twofish suggested a key size of %d\n", keysize); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
480 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
481 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
482 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
483 \end{small} |
| 380 | 484 This should indicate a keysize of sixteen bytes is suggested by storing 16 in \textit{keysize.} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
485 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
486 \subsection{Cipher Termination} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
487 When you are finished with a cipher you can de--initialize it with the done function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
488 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
489 void XXX_done(symmetric_key *skey); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
490 \end{verbatim} |
| 380 | 491 For the software based ciphers within LibTomCrypt, these functions will not do anything. However, user supplied |
| 492 cipher descriptors may require to be called for resource management purposes. To be compliant, all functions which call a cipher | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
493 setup function must also call the respective cipher done function when finished. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
494 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
495 \subsection{Simple Encryption Demonstration} |
| 380 | 496 An example snippet that encodes a block with Blowfish in ECB mode. |
| 497 | |
| 498 \index{blowfish\_setup()} \index{blowfish\_ecb\_encrypt()} \index{blowfish\_ecb\_decrypt()} \index{blowfish\_done()} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
499 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
500 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
501 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
502 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
503 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
504 unsigned char pt[8], ct[8], key[8]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
505 symmetric_key skey; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
506 int err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
507 |
| 380 | 508 /* ... key is loaded appropriately in key ... */ |
| 509 /* ... load a block of plaintext in pt ... */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
510 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
511 /* schedule the key */ |
| 380 | 512 if ((err = blowfish_setup(key, /* the key we will use */ |
| 513 8, /* key is 8 bytes (64-bits) long */ | |
| 514 0, /* 0 == use default # of rounds */ | |
| 515 &skey) /* where to put the scheduled key */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
516 ) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
517 printf("Setup error: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
518 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
519 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
520 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
521 /* encrypt the block */ |
| 380 | 522 blowfish_ecb_encrypt(pt, /* encrypt this 8-byte array */ |
| 523 ct, /* store encrypted data here */ | |
| 524 &skey); /* our previously scheduled key */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
525 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
526 /* now ct holds the encrypted version of pt */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
527 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
528 /* decrypt the block */ |
| 380 | 529 blowfish_ecb_decrypt(ct, /* decrypt this 8-byte array */ |
| 530 pt, /* store decrypted data here */ | |
| 531 &skey); /* our previously scheduled key */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
532 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
533 /* now we have decrypted ct to the original plaintext in pt */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
534 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
535 /* Terminate the cipher context */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
536 blowfish_done(&skey); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
537 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
538 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
539 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
540 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
541 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
542 |
| 380 | 543 \mysection{Key Sizes and Number of Rounds} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
544 \index{Symmetric Keys} |
| 380 | 545 As a general rule of thumb, do not use symmetric keys under 80 bits if you can help it. Only a few of the ciphers support smaller |
| 546 keys (mainly for test vectors anyways). Ideally, your application should be making at least 256 bit keys. This is not | |
| 547 because you are to be paranoid. It is because if your PRNG has a bias of any sort the more bits the better. For | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
548 example, if you have $\mbox{Pr}\left[X = 1\right] = {1 \over 2} \pm \gamma$ where $\vert \gamma \vert > 0$ then the |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
549 total amount of entropy in N bits is $N \cdot -log_2\left ({1 \over 2} + \vert \gamma \vert \right)$. So if $\gamma$ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
550 were $0.25$ (a severe bias) a 256-bit string would have about 106 bits of entropy whereas a 128-bit string would have |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
551 only 53 bits of entropy. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
552 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
553 The number of rounds of most ciphers is not an option you can change. Only RC5 allows you to change the number of |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
554 rounds. By passing zero as the number of rounds all ciphers will use their default number of rounds. Generally the |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
555 ciphers are configured such that the default number of rounds provide adequate security for the given block and key |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
556 size. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
557 |
| 380 | 558 \mysection{The Cipher Descriptors} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
559 \index{Cipher Descriptor} |
| 380 | 560 To facilitate automatic routines an array of cipher descriptors is provided in the array \textit{cipher\_descriptor}. An element |
| 561 of this array has the following (partial) format (See Section \ref{sec:cipherdesc}): | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
562 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
563 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
564 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
565 struct _cipher_descriptor { |
| 380 | 566 /** name of cipher */ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
567 char *name; |
| 380 | 568 |
| 569 /** internal ID */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
570 unsigned char ID; |
| 380 | 571 |
| 572 /** min keysize (octets) */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
573 int min_key_length, |
| 380 | 574 |
| 575 /** max keysize (octets) */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
576 max_key_length, |
| 380 | 577 |
| 578 /** block size (octets) */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
579 block_length, |
| 380 | 580 |
| 581 /** default number of rounds */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
582 default_rounds; |
| 380 | 583 ...<snip>... |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
584 }; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
585 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
586 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
587 |
| 380 | 588 Where \textit{name} is the lower case ASCII version of the name. The fields \textit{min\_key\_length} and \textit{max\_key\_length} |
| 589 are the minimum and maximum key sizes in bytes. The \textit{block\_length} member is the block size of the cipher | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
590 in bytes. As a good rule of thumb it is assumed that the cipher supports |
| 380 | 591 the min and max key lengths but not always everything in between. The \textit{default\_rounds} field is the default number |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
592 of rounds that will be used. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
593 |
| 380 | 594 For a plugin to be compliant it must provide at least each function listed before the accelerators begin. Accelerators are optional, |
| 595 and if missing will be emulated in software. | |
| 596 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
597 The remaining fields are all pointers to the core functions for each cipher. The end of the cipher\_descriptor array is |
| 380 | 598 marked when \textit{name} equals {\bf NULL}. |
| 599 | |
| 600 As of this release the current cipher\_descriptors elements are the following: | |
| 601 \vfil | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
602 \index{Cipher descriptor table} |
| 380 | 603 \index{blowfish\_desc} \index{xtea\_desc} \index{rc2\_desc} \index{rc5\_desc} \index{rc6\_desc} \index{saferp\_desc} \index{aes\_desc} \index{twofish\_desc} |
| 604 \index{des\_desc} \index{des3\_desc} \index{noekeon\_desc} \index{skipjack\_desc} \index{anubis\_desc} \index{khazad\_desc} \index{kseed\_desc} \index{kasumi\_desc} | |
| 605 \begin{figure}[hpbt] | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
606 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
607 \begin{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
608 \begin{tabular}{|c|c|c|c|c|c|} |
| 380 | 609 \hline \textbf{Name} & \textbf{Descriptor Name} & \textbf{Block Size} & \textbf{Key Range} & \textbf{Rounds} \\ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
610 \hline Blowfish & blowfish\_desc & 8 & 8 $\ldots$ 56 & 16 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
611 \hline X-Tea & xtea\_desc & 8 & 16 & 32 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
612 \hline RC2 & rc2\_desc & 8 & 8 $\ldots$ 128 & 16 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
613 \hline RC5-32/12/b & rc5\_desc & 8 & 8 $\ldots$ 128 & 12 $\ldots$ 24 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
614 \hline RC6-32/20/b & rc6\_desc & 16 & 8 $\ldots$ 128 & 20 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
615 \hline SAFER+ & saferp\_desc &16 & 16, 24, 32 & 8, 12, 16 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
616 \hline AES & aes\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
617 & aes\_enc\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
618 \hline Twofish & twofish\_desc & 16 & 16, 24, 32 & 16 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
619 \hline DES & des\_desc & 8 & 7 & 16 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
620 \hline 3DES (EDE mode) & des3\_desc & 8 & 21 & 16 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
621 \hline CAST5 (CAST-128) & cast5\_desc & 8 & 5 $\ldots$ 16 & 12, 16 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
622 \hline Noekeon & noekeon\_desc & 16 & 16 & 16 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
623 \hline Skipjack & skipjack\_desc & 8 & 10 & 32 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
624 \hline Anubis & anubis\_desc & 16 & 16 $\ldots$ 40 & 12 $\ldots$ 18 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
625 \hline Khazad & khazad\_desc & 8 & 16 & 8 \\ |
| 380 | 626 \hline SEED & kseed\_desc & 16 & 16 & 16 \\ |
| 627 \hline KASUMI & kasumi\_desc & 8 & 16 & 8 \\ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
628 \hline |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
629 \end{tabular} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
630 \end{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
631 \end{small} |
| 380 | 632 \caption{Built--In Software Ciphers} |
| 633 \end{figure} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
634 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
635 \subsection{Notes} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
636 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
637 \begin{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
638 \item |
| 380 | 639 For AES, (also known as Rijndael) there are four descriptors which complicate issues a little. The descriptors |
| 640 rijndael\_desc and rijndael\_enc\_desc provide the cipher named \textit{rijndael}. The descriptors aes\_desc and | |
| 641 aes\_enc\_desc provide the cipher name \textit{aes}. Functionally both \textit{rijndael} and \textit{aes} are the same cipher. The | |
| 642 only difference is when you call find\_cipher() you have to pass the correct name. The cipher descriptors with \textit{enc} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
643 in the middle (e.g. rijndael\_enc\_desc) are related to an implementation of Rijndael with only the encryption routine |
| 380 | 644 and tables. The decryption and self--test function pointers of both \textit{encrypt only} descriptors are set to \textbf{NULL} and |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
645 should not be called. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
646 |
| 380 | 647 The \textit{encrypt only} descriptors are useful for applications that only use the encryption function of the cipher. Algorithms such |
| 648 as EAX, PMAC and OMAC only require the encryption function. So far this \textit{encrypt only} functionality has only been implemented for | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
649 Rijndael as it makes the most sense for this cipher. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
650 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
651 \item |
| 380 | 652 Note that for \textit{DES} and \textit{3DES} they use 8 and 24 byte keys but only 7 and 21 [respectively] bytes of the keys are in |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
653 fact used for the purposes of encryption. My suggestion is just to use random 8/24 byte keys instead of trying to make a 8/24 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
654 byte string from the real 7/21 byte key. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
655 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
656 \item |
| 380 | 657 Note that \textit{Twofish} has additional configuration options (Figure \ref{fig:twofishopts}) that take place at build time. These options are found in |
| 658 the file \textit{tomcrypt\_cfg.h}. The first option is \textit{TWOFISH\_SMALL} which when defined will force the Twofish code | |
| 659 to not pre-compute the Twofish \textit{$g(X)$} function as a set of four $8 \times 32$ s-boxes. This means that a scheduled | |
| 660 key will require less ram but the resulting cipher will be slower. The second option is \textit{TWOFISH\_TABLES} which when | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
661 defined will force the Twofish code to use pre-computed tables for the two s-boxes $q_0, q_1$ as well as the multiplication |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
662 by the polynomials 5B and EF used in the MDS multiplication. As a result the code is faster and slightly larger. The |
| 380 | 663 speed increase is useful when \textit{TWOFISH\_SMALL} is defined since the s-boxes and MDS multiply form the heart of the |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
664 Twofish round function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
665 |
| 380 | 666 \begin{figure}[hpbt] |
| 667 \index{Twofish build options} \index{TWOFISH\_SMALL} \index{TWOFISH\_TABLES} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
668 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
669 \begin{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
670 \begin{tabular}{|l|l|l|} |
| 380 | 671 \hline \textbf{TWOFISH\_SMALL} & \textbf{TWOFISH\_TABLES} & \textbf{Speed and Memory (per key)} \\ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
672 \hline undefined & undefined & Very fast, 4.2KB of ram. \\ |
| 380 | 673 \hline undefined & defined & Faster key setup, larger code. \\ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
674 \hline defined & undefined & Very slow, 0.2KB of ram. \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
675 \hline defined & defined & Faster, 0.2KB of ram, larger code. \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
676 \hline |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
677 \end{tabular} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
678 \end{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
679 \end{small} |
| 380 | 680 \caption{Twofish Build Options} |
| 681 \label{fig:twofishopts} | |
| 682 \end{figure} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
683 \end{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
684 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
685 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
686 To work with the cipher\_descriptor array there is a function: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
687 \index{find\_cipher()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
688 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
689 int find_cipher(char *name) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
690 \end{verbatim} |
| 380 | 691 Which will search for a given name in the array. It returns $-1$ if the cipher is not found, otherwise it returns |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
692 the location in the array where the cipher was found. For example, to indirectly setup Blowfish you can also use: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
693 \begin{small} |
| 380 | 694 \index{register\_cipher()} \index{find\_cipher()} \index{error\_to\_string()} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
695 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
696 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
697 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
698 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
699 unsigned char key[8]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
700 symmetric_key skey; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
701 int err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
702 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
703 /* you must register a cipher before you use it */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
704 if (register_cipher(&blowfish_desc)) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
705 printf("Unable to register Blowfish cipher."); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
706 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
707 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
708 |
| 380 | 709 /* generic call to function (assuming the key |
| 710 * in key[] was already setup) */ | |
| 711 if ((err = | |
| 712 cipher_descriptor[find_cipher("blowfish")]. | |
| 713 setup(key, 8, 0, &skey)) != CRYPT_OK) { | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
714 printf("Error setting up Blowfish: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
715 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
716 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
717 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
718 /* ... use cipher ... */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
719 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
720 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
721 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
722 |
| 380 | 723 A good safety would be to check the return value of \textit{find\_cipher()} before accessing the desired function. In order |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
724 to use a cipher with the descriptor table you must register it first using: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
725 \index{register\_cipher()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
726 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
727 int register_cipher(const struct _cipher_descriptor *cipher); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
728 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
729 Which accepts a pointer to a descriptor and returns the index into the global descriptor table. If an error occurs such |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
730 as there is no more room (it can have 32 ciphers at most) it will return {\bf{-1}}. If you try to add the same cipher more |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
731 than once it will just return the index of the first copy. To remove a cipher call: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
732 \index{unregister\_cipher()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
733 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
734 int unregister_cipher(const struct _cipher_descriptor *cipher); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
735 \end{verbatim} |
| 380 | 736 Which returns {\bf CRYPT\_OK} if it removes the cipher, otherwise it returns {\bf CRYPT\_ERROR}. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
737 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
738 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
739 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
740 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
741 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
742 int err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
743 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
744 /* register the cipher */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
745 if (register_cipher(&rijndael_desc) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
746 printf("Error registering Rijndael\n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
747 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
748 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
749 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
750 /* use Rijndael */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
751 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
752 /* remove it */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
753 if ((err = unregister_cipher(&rijndael_desc)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
754 printf("Error removing Rijndael: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
755 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
756 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
757 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
758 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
759 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
760 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
761 \end{small} |
| 380 | 762 This snippet is a small program that registers Rijndael. |
| 763 | |
| 764 \mysection{Symmetric Modes of Operations} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
765 \subsection{Background} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
766 A typical symmetric block cipher can be used in chaining modes to effectively encrypt messages larger than the block |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
767 size of the cipher. Given a key $k$, a plaintext $P$ and a cipher $E$ we shall denote the encryption of the block |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
768 $P$ under the key $k$ as $E_k(P)$. In some modes there exists an initial vector denoted as $C_{-1}$. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
769 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
770 \subsubsection{ECB Mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
771 \index{ECB mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
772 ECB or Electronic Codebook Mode is the simplest method to use. It is given as: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
773 \begin{equation} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
774 C_i = E_k(P_i) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
775 \end{equation} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
776 This mode is very weak since it allows people to swap blocks and perform replay attacks if the same key is used more |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
777 than once. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
778 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
779 \subsubsection{CBC Mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
780 \index{CBC mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
781 CBC or Cipher Block Chaining mode is a simple mode designed to prevent trivial forms of replay and swap attacks on ciphers. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
782 It is given as: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
783 \begin{equation} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
784 C_i = E_k(P_i \oplus C_{i - 1}) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
785 \end{equation} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
786 It is important that the initial vector be unique and preferably random for each message encrypted under the same key. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
787 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
788 \subsubsection{CTR Mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
789 \index{CTR mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
790 CTR or Counter Mode is a mode which only uses the encryption function of the cipher. Given a initial vector which is |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
791 treated as a large binary counter the CTR mode is given as: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
792 \begin{eqnarray} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
793 C_{-1} = C_{-1} + 1\mbox{ }(\mbox{mod }2^W) \nonumber \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
794 C_i = P_i \oplus E_k(C_{-1}) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
795 \end{eqnarray} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
796 Where $W$ is the size of a block in bits (e.g. 64 for Blowfish). As long as the initial vector is random for each message |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
797 encrypted under the same key replay and swap attacks are infeasible. CTR mode may look simple but it is as secure |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
798 as the block cipher is under a chosen plaintext attack (provided the initial vector is unique). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
799 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
800 \subsubsection{CFB Mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
801 \index{CFB mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
802 CFB or Ciphertext Feedback Mode is a mode akin to CBC. It is given as: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
803 \begin{eqnarray} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
804 C_i = P_i \oplus C_{-1} \nonumber \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
805 C_{-1} = E_k(C_i) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
806 \end{eqnarray} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
807 Note that in this library the output feedback width is equal to the size of the block cipher. That is this mode is used |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
808 to encrypt whole blocks at a time. However, the library will buffer data allowing the user to encrypt or decrypt partial |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
809 blocks without a delay. When this mode is first setup it will initially encrypt the initial vector as required. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
810 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
811 \subsubsection{OFB Mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
812 \index{OFB mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
813 OFB or Output Feedback Mode is a mode akin to CBC as well. It is given as: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
814 \begin{eqnarray} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
815 C_{-1} = E_k(C_{-1}) \nonumber \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
816 C_i = P_i \oplus C_{-1} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
817 \end{eqnarray} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
818 Like the CFB mode the output width in CFB mode is the same as the width of the block cipher. OFB mode will also |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
819 buffer the output which will allow you to encrypt or decrypt partial blocks without delay. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
820 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
821 \subsection{Choice of Mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
822 My personal preference is for the CTR mode since it has several key benefits: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
823 \begin{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
824 \item No short cycles which is possible in the OFB and CFB modes. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
825 \item Provably as secure as the block cipher being used under a chosen plaintext attack. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
826 \item Technically does not require the decryption routine of the cipher. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
827 \item Allows random access to the plaintext. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
828 \item Allows the encryption of block sizes that are not equal to the size of the block cipher. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
829 \end{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
830 The CTR, CFB and OFB routines provided allow you to encrypt block sizes that differ from the ciphers block size. They |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
831 accomplish this by buffering the data required to complete a block. This allows you to encrypt or decrypt any size |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
832 block of memory with either of the three modes. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
833 |
| 380 | 834 The ECB and CBC modes process blocks of the same size as the cipher at a time. Therefore, they are less flexible than the |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
835 other modes. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
836 |
| 380 | 837 \subsection{Ciphertext Stealing} |
| 838 \index{Ciphertext stealing} | |
| 839 Ciphertext stealing is a method of dealing with messages in CBC mode which are not a multiple of the block length. This is accomplished | |
| 840 by encrypting the last ciphertext block in ECB mode, and XOR'ing the output against the last partial block of plaintext. LibTomCrypt does not | |
| 841 support this mode directly but it is fairly easy to emulate with a call to the cipher's ecb\_encrypt() callback function. | |
| 842 | |
| 843 The more sane way to deal with partial blocks is to pad them with zeroes, and then use CBC normally. | |
| 844 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
845 \subsection{Initialization} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
846 \index{CBC Mode} \index{CTR Mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
847 \index{OFB Mode} \index{CFB Mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
848 The library provides simple support routines for handling CBC, CTR, CFB, OFB and ECB encoded messages. Assuming the mode |
| 380 | 849 you want is XXX there is a structure called \textit{symmetric\_XXX} that will contain the information required to |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
850 use that mode. They have identical setup routines (except CTR and ECB mode): |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
851 \index{ecb\_start()} \index{cfb\_start()} \index{cbc\_start()} \index{ofb\_start()} \index{ctr\_start()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
852 \begin{verbatim} |
| 380 | 853 int XXX_start( int cipher, |
| 854 const unsigned char *IV, | |
| 855 const unsigned char *key, | |
| 856 int keylen, | |
| 857 int num_rounds, | |
| 858 symmetric_XXX *XXX); | |
| 859 | |
| 860 int ctr_start( int cipher, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
861 const unsigned char *IV, |
| 380 | 862 const unsigned char *key, |
| 863 int keylen, | |
| 864 int num_rounds, | |
| 865 int ctr_mode, | |
| 866 symmetric_CTR *ctr); | |
| 867 | |
| 868 int ecb_start( int cipher, | |
| 869 const unsigned char *key, | |
| 870 int keylen, | |
| 871 int num_rounds, | |
| 872 symmetric_ECB *ecb); | |
| 873 \end{verbatim} | |
| 874 | |
| 875 In each case, \textit{cipher} is the index into the cipher\_descriptor array of the cipher you want to use. The \textit{IV} value is | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
876 the initialization vector to be used with the cipher. You must fill the IV yourself and it is assumed they are the same |
| 380 | 877 length as the block size\footnote{In other words the size of a block of plaintext for the cipher, e.g. 8 for DES, 16 for AES, etc.} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
878 of the cipher you choose. It is important that the IV be random for each unique message you want to encrypt. The |
| 380 | 879 parameters \textit{key}, \textit{keylen} and \textit{num\_rounds} are the same as in the XXX\_setup() function call. The final parameter |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
880 is a pointer to the structure you want to hold the information for the mode of operation. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
881 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
882 |
| 380 | 883 In the case of CTR mode there is an additional parameter \textit{ctr\_mode} which specifies the mode that the counter is to be used in. |
| 884 If \textbf{CTR\_COUNTER\_ LITTLE\_ENDIAN} was specified then the counter will be treated as a little endian value. Otherwise, if | |
| 885 \textbf{CTR\_COUNTER\_BIG\_ENDIAN} was specified the counter will be treated as a big endian value. As of v1.15 the RFC 3686 style of | |
| 886 increment then encrypt is also supported. By OR'ing \textbf{LTC\_CTR\_RFC3686} with the CTR \textit{mode} value, ctr\_start() will increment | |
| 887 the counter before encrypting it for the first time. | |
| 888 | |
| 889 The routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise, they return an error code. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
890 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
891 \subsection{Encryption and Decryption} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
892 To actually encrypt or decrypt the following routines are provided: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
893 \index{ecb\_encrypt()} \index{ecb\_decrypt()} \index{cfb\_encrypt()} \index{cfb\_decrypt()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
894 \index{cbc\_encrypt()} \index{cbc\_decrypt()} \index{ofb\_encrypt()} \index{ofb\_decrypt()} \index{ctr\_encrypt()} \index{ctr\_decrypt()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
895 \begin{verbatim} |
| 380 | 896 int XXX_encrypt(const unsigned char *pt, |
| 897 unsigned char *ct, | |
| 898 unsigned long len, | |
| 899 symmetric_YYY *YYY); | |
| 900 | |
| 901 int XXX_decrypt(const unsigned char *ct, | |
| 902 unsigned char *pt, | |
| 903 unsigned long len, | |
| 904 symmetric_YYY *YYY); | |
| 905 \end{verbatim} | |
| 906 Where \textit{XXX} is one of $\lbrace ecb, cbc, ctr, cfb, ofb \rbrace$. | |
| 907 | |
| 908 In all cases, \textit{len} is the size of the buffer (as number of octets) to encrypt or decrypt. The CTR, OFB and CFB modes are order sensitive but not | |
| 909 chunk sensitive. That is you can encrypt \textit{ABCDEF} in three calls like \textit{AB}, \textit{CD}, \textit{EF} or two like \textit{ABCDE} and \textit{F} | |
| 910 and end up with the same ciphertext. However, encrypting \textit{ABC} and \textit{DABC} will result in different ciphertexts. All | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
911 five of the modes will return {\bf CRYPT\_OK} on success from the encrypt or decrypt functions. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
912 |
| 380 | 913 In the ECB and CBC cases, \textit{len} must be a multiple of the ciphers block size. In the CBC case, you must manually pad the end of your message (either with |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
914 zeroes or with whatever your protocol requires). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
915 |
| 380 | 916 To decrypt in either mode, perform the setup like before (recall you have to fetch the IV value you used), and use the decrypt routine on all of the blocks. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
917 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
918 \subsection{IV Manipulation} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
919 To change or read the IV of a previously initialized chaining mode use the following two functions. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
920 \index{cbc\_setiv()} \index{cbc\_getiv()} \index{ofb\_setiv()} \index{ofb\_getiv()} \index{cfb\_setiv()} \index{cfb\_getiv()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
921 \index{ctr\_setiv()} \index{ctr\_getiv()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
922 \begin{verbatim} |
| 380 | 923 int XXX_getiv(unsigned char *IV, |
| 924 unsigned long *len, | |
| 925 symmetric_XXX *XXX); | |
| 926 | |
| 927 int XXX_setiv(const unsigned char *IV, | |
| 928 unsigned long len, | |
| 929 symmetric_XXX *XXX); | |
| 930 \end{verbatim} | |
| 931 | |
| 932 The XXX\_getiv() functions will read the IV out of the chaining mode and store it into \textit{IV} along with the length of the IV | |
| 933 stored in \textit{len}. The XXX\_setiv will initialize the chaining mode state as if the original IV were the new IV specified. The length | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
934 of the IV passed in must be the size of the ciphers block size. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
935 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
936 The XXX\_setiv() functions are handy if you wish to change the IV without re--keying the cipher. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
937 |
| 380 | 938 What the \textit{setiv} function will do depends on the mode being changed. In CBC mode, the new IV replaces the existing IV as if it |
| 939 were the last ciphertext block. In CFB mode, the IV is encrypted as if it were the prior encrypted pad. In CTR mode, the IV is encrypted without | |
| 940 first incrementing it (regardless of the LTC\_RFC\_3686 flag presence). In F8 mode, the IV is encrypted and becomes the new pad. It does not change | |
| 941 the salted IV, and is only meant to allow seeking within a session. In LRW, it changes the tweak, forcing a computation of the tweak pad, allowing for | |
| 942 seeking within the session. In OFB mode, the IV is encrypted and becomes the new pad. | |
| 943 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
944 \subsection{Stream Termination} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
945 To terminate an open stream call the done function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
946 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
947 \index{ecb\_done()} \index{cbc\_done()}\index{cfb\_done()}\index{ofb\_done()} \index{ctr\_done()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
948 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
949 int XXX_done(symmetric_XXX *XXX); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
950 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
951 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
952 This will terminate the stream (by terminating the cipher) and return \textbf{CRYPT\_OK} if successful. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
953 |
| 380 | 954 \newpage |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
955 \subsection{Examples} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
956 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
957 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
958 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
959 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
960 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
961 unsigned char key[16], IV[16], buffer[512]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
962 symmetric_CTR ctr; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
963 int x, err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
964 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
965 /* register twofish first */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
966 if (register_cipher(&twofish_desc) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
967 printf("Error registering cipher.\n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
968 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
969 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
970 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
971 /* somehow fill out key and IV */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
972 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
973 /* start up CTR mode */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
974 if ((err = ctr_start( |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
975 find_cipher("twofish"), /* index of desired cipher */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
976 IV, /* the initial vector */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
977 key, /* the secret key */ |
| 380 | 978 16, /* length of secret key (16 bytes) */ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
979 0, /* 0 == default # of rounds */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
980 CTR_COUNTER_LITTLE_ENDIAN, /* Little endian counter */ |
| 380 | 981 &ctr) /* where to store the CTR state */ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
982 ) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
983 printf("ctr_start error: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
984 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
985 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
986 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
987 /* somehow fill buffer than encrypt it */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
988 if ((err = ctr_encrypt( buffer, /* plaintext */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
989 buffer, /* ciphertext */ |
| 380 | 990 sizeof(buffer), /* length of plaintext pt */ |
| 991 &ctr) /* CTR state */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
992 ) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
993 printf("ctr_encrypt error: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
994 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
995 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
996 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
997 /* make use of ciphertext... */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
998 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
999 /* now we want to decrypt so let's use ctr_setiv */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1000 if ((err = ctr_setiv( IV, /* the initial IV we gave to ctr_start */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1001 16, /* the IV is 16 bytes long */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1002 &ctr) /* the ctr state we wish to modify */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1003 ) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1004 printf("ctr_setiv error: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1005 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1006 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1007 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1008 if ((err = ctr_decrypt( buffer, /* ciphertext */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1009 buffer, /* plaintext */ |
| 380 | 1010 sizeof(buffer), /* length of plaintext */ |
| 1011 &ctr) /* CTR state */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1012 ) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1013 printf("ctr_decrypt error: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1014 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1015 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1016 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1017 /* terminate the stream */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1018 if ((err = ctr_done(&ctr)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1019 printf("ctr_done error: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1020 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1021 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1022 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1023 /* clear up and return */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1024 zeromem(key, sizeof(key)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1025 zeromem(&ctr, sizeof(ctr)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1026 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1027 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1028 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1029 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1030 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1031 |
| 380 | 1032 \subsection{LRW Mode} |
| 1033 LRW mode is a cipher mode which is meant for indexed encryption like used to handle storage media. It is meant to have efficient seeking and overcome the | |
| 1034 security problems of ECB mode while not increasing the storage requirements. It is used much like any other chaining mode except with two key differences. | |
| 1035 | |
| 1036 The key is specified as two strings the first key $K_1$ is the (normally AES) key and can be any length (typically 16, 24 or 32 octets long). The second key | |
| 1037 $K_2$ is the \textit{tweak} key and is always 16 octets long. The tweak value is \textbf{NOT} a nonce or IV value it must be random and secret. | |
| 1038 | |
| 1039 To initialize LRW mode use: | |
| 1040 | |
| 1041 \index{lrw\_start()} | |
| 1042 \begin{verbatim} | |
| 1043 int lrw_start( int cipher, | |
| 1044 const unsigned char *IV, | |
| 1045 const unsigned char *key, | |
| 1046 int keylen, | |
| 1047 const unsigned char *tweak, | |
| 1048 int num_rounds, | |
| 1049 symmetric_LRW *lrw); | |
| 1050 \end{verbatim} | |
| 1051 | |
| 1052 This will initialize the LRW context with the given (16 octet) \textit{IV}, cipher $K_1$ \textit{key} of length \textit{keylen} octets and the (16 octet) $K_2$ \textit{tweak}. | |
| 1053 While LRW was specified to be used only with AES, LibTomCrypt will allow any 128--bit block cipher to be specified as indexed by \textit{cipher}. The | |
| 1054 number of rounds for the block cipher \textit{num\_rounds} can be 0 to use the default number of rounds for the given cipher. | |
| 1055 | |
| 1056 To process data use the following functions: | |
| 1057 | |
| 1058 \index{lrw\_encrypt()} \index{lrw\_decrypt()} | |
| 1059 \begin{verbatim} | |
| 1060 int lrw_encrypt(const unsigned char *pt, | |
| 1061 unsigned char *ct, | |
| 1062 unsigned long len, | |
| 1063 symmetric_LRW *lrw); | |
| 1064 | |
| 1065 int lrw_decrypt(const unsigned char *ct, | |
| 1066 unsigned char *pt, | |
| 1067 unsigned long len, | |
| 1068 symmetric_LRW *lrw); | |
| 1069 \end{verbatim} | |
| 1070 | |
| 1071 These will encrypt (or decrypt) the plaintext to the ciphertext buffer (or vice versa). The length is specified by \textit{len} in octets but must be a multiple | |
| 1072 of 16. The LRW code uses a fast tweak update such that consecutive blocks are encrypted faster than if random seeking where used. | |
| 1073 | |
| 1074 To manipulate the IV use the following functions: | |
| 1075 | |
| 1076 \index{lrw\_getiv()} \index{lrw\_setiv()} | |
| 1077 \begin{verbatim} | |
| 1078 int lrw_getiv(unsigned char *IV, | |
| 1079 unsigned long *len, | |
| 1080 symmetric_LRW *lrw); | |
| 1081 | |
| 1082 int lrw_setiv(const unsigned char *IV, | |
| 1083 unsigned long len, | |
| 1084 symmetric_LRW *lrw); | |
| 1085 \end{verbatim} | |
| 1086 These will get or set the 16--octet IV. Note that setting the IV is the same as \textit{seeking} and unlike other modes is not a free operation. It requires | |
| 1087 updating the entire tweak which is slower than sequential use. Avoid seeking excessively in performance constrained code. | |
| 1088 | |
| 1089 To terminate the LRW state use the following: | |
| 1090 | |
| 1091 \index{lrw\_done()} | |
| 1092 \begin{verbatim} | |
| 1093 int lrw_done(symmetric_LRW *lrw); | |
| 1094 \end{verbatim} | |
| 1095 | |
| 1096 \subsection{F8 Mode} | |
| 1097 \index{F8 Mode} | |
| 1098 The F8 Chaining mode (see RFC 3711 for instance) is yet another chaining mode for block ciphers. It behaves much like CTR mode in that it XORs a keystream | |
| 1099 against the plaintext to encrypt. F8 mode comes with the additional twist that the counter value is secret, encrypted by a \textit{salt key}. We | |
| 1100 initialize F8 mode with the following function call: | |
| 1101 | |
| 1102 \index{f8\_start()} | |
| 1103 \begin{verbatim} | |
| 1104 int f8_start( int cipher, | |
| 1105 const unsigned char *IV, | |
| 1106 const unsigned char *key, | |
| 1107 int keylen, | |
| 1108 const unsigned char *salt_key, | |
| 1109 int skeylen, | |
| 1110 int num_rounds, | |
| 1111 symmetric_F8 *f8); | |
| 1112 \end{verbatim} | |
| 1113 This will start the F8 mode state using \textit{key} as the secret key, \textit{IV} as the counter. It uses the \textit{salt\_key} as IV encryption key | |
| 1114 (\textit{m} in the RFC 3711). The salt\_key can be shorter than the secret key but it should not be longer. | |
| 1115 | |
| 1116 To encrypt or decrypt data we use the following two functions: | |
| 1117 | |
| 1118 \index{f8\_encrypt()} \index{f8\_decrypt()} | |
| 1119 \begin{verbatim} | |
| 1120 int f8_encrypt(const unsigned char *pt, | |
| 1121 unsigned char *ct, | |
| 1122 unsigned long len, | |
| 1123 symmetric_F8 *f8); | |
| 1124 | |
| 1125 int f8_decrypt(const unsigned char *ct, | |
| 1126 unsigned char *pt, | |
| 1127 unsigned long len, | |
| 1128 symmetric_F8 *f8); | |
| 1129 \end{verbatim} | |
| 1130 These will encrypt or decrypt a variable length array of bytes using the F8 mode state specified. The length is specified in bytes and does not have to be a multiple | |
| 1131 of the ciphers block size. | |
| 1132 | |
| 1133 To change or retrieve the current counter IV value use the following functions: | |
| 1134 \index{f8\_getiv()} \index{f8\_setiv()} | |
| 1135 \begin{verbatim} | |
| 1136 int f8_getiv(unsigned char *IV, | |
| 1137 unsigned long *len, | |
| 1138 symmetric_F8 *f8); | |
| 1139 | |
| 1140 int f8_setiv(const unsigned char *IV, | |
| 1141 unsigned long len, | |
| 1142 symmetric_F8 *f8); | |
| 1143 \end{verbatim} | |
| 1144 These work with the current IV value only and not the encrypted IV value specified during the call to f8\_start(). The purpose of these two functions is to be | |
| 1145 able to seek within a current session only. If you want to change the session IV you will have to call f8\_done() and then start a new state with | |
| 1146 f8\_start(). | |
| 1147 | |
| 1148 To terminate an F8 state call the following function: | |
| 1149 | |
| 1150 \index{f8\_done()} | |
| 1151 \begin{verbatim} | |
| 1152 int f8_done(symmetric_F8 *f8); | |
| 1153 \end{verbatim} | |
| 1154 | |
| 1155 \vfil | |
| 1156 \mysection{Encrypt and Authenticate Modes} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1157 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1158 \subsection{EAX Mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1159 LibTomCrypt provides support for a mode called EAX\footnote{See |
| 380 | 1160 M. Bellare, P. Rogaway, D. Wagner, A Conventional Authenticated-Encryption Mode.} in a manner similar to the way it was intended to be used |
| 1161 by the designers. First, a short description of what EAX mode is before we explain how to use it. EAX is a mode that requires a cipher, | |
| 1162 CTR and OMAC support and provides encryption and | |
| 1163 authentication\footnote{Note that since EAX only requires OMAC and CTR you may use \textit{encrypt only} cipher descriptors with this mode.}. | |
| 1164 It is initialized with a random \textit{nonce} that can be shared publicly, a \textit{header} which can be fixed and public, and a random secret symmetric key. | |
| 1165 | |
| 1166 The \textit{header} data is meant to be meta--data associated with a stream that isn't private (e.g., protocol messages). It can | |
| 1167 be added at anytime during an EAX stream, and is part of the authentication tag. That is, changes in the meta-data can be detected by changes in the output tag. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1168 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1169 The mode can then process plaintext producing ciphertext as well as compute a partial checksum. The actual checksum |
| 380 | 1170 called a \textit{tag} is only emitted when the message is finished. In the interim, the user can process any arbitrary |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1171 sized message block to send to the recipient as ciphertext. This makes the EAX mode especially suited for streaming modes |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1172 of operation. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1173 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1174 The mode is initialized with the following function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1175 \index{eax\_init()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1176 \begin{verbatim} |
| 380 | 1177 int eax_init( eax_state *eax, |
| 1178 int cipher, | |
| 1179 const unsigned char *key, | |
| 1180 unsigned long keylen, | |
| 1181 const unsigned char *nonce, | |
| 1182 unsigned long noncelen, | |
| 1183 const unsigned char *header, | |
| 1184 unsigned long headerlen); | |
| 1185 \end{verbatim} | |
| 1186 | |
| 1187 Where \textit{eax} is the EAX state. The \textit{cipher} parameter is the index of the desired cipher in the descriptor table. | |
| 1188 The \textit{key} parameter is the shared secret symmetric key of length \textit{keylen} octets. The \textit{nonce} parameter is the | |
| 1189 random public string of length \textit{noncelen} octets. The \textit{header} parameter is the random (or fixed or \textbf{NULL}) header for the | |
| 1190 message of length \textit{headerlen} octets. | |
| 1191 | |
| 1192 When this function completes, the \textit{eax} state will be initialized such that you can now either have data decrypted or | |
| 1193 encrypted in EAX mode. Note: if \textit{headerlen} is zero you may pass \textit{header} as \textbf{NULL} to indicate there is no initial header data. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1194 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1195 To encrypt or decrypt data in a streaming mode use the following. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1196 \index{eax\_encrypt()} \index{eax\_decrypt()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1197 \begin{verbatim} |
| 380 | 1198 int eax_encrypt( eax_state *eax, |
| 1199 const unsigned char *pt, | |
| 1200 unsigned char *ct, | |
| 1201 unsigned long length); | |
| 1202 | |
| 1203 int eax_decrypt( eax_state *eax, | |
| 1204 const unsigned char *ct, | |
| 1205 unsigned char *pt, | |
| 1206 unsigned long length); | |
| 1207 \end{verbatim} | |
| 1208 The function \textit{eax\_encrypt} will encrypt the bytes in \textit{pt} of \textit{length} octets, and store the ciphertext in | |
| 1209 \textit{ct}. Note: \textit{ct} and \textit{pt} may be the same region in memory. This function will also send the ciphertext | |
| 1210 through the OMAC function. The function \textit{eax\_decrypt} decrypts \textit{ct}, and stores it in \textit{pt}. This also allows | |
| 1211 \textit{pt} and \textit{ct} to be the same region in memory. | |
| 1212 | |
| 1213 You cannot both encrypt or decrypt with the same \textit{eax} context. For bi--directional communication you will need to initialize | |
| 1214 two EAX contexts (preferably with different headers and nonces). | |
| 1215 | |
| 1216 Note: both of these functions allow you to send the data in any granularity but the order is important. While | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1217 the eax\_init() function allows you to add initial header data to the stream you can also add header data during the |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1218 EAX stream with the following. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1219 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1220 \index{eax\_addheader()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1221 \begin{verbatim} |
| 380 | 1222 int eax_addheader( eax_state *eax, |
| 1223 const unsigned char *header, | |
| 1224 unsigned long length); | |
| 1225 \end{verbatim} | |
| 1226 This will add the \textit{length} octet from \textit{header} to the given \textit{eax} header. Once the message is finished, the | |
| 1227 \textit{tag} (checksum) may be computed with the following function: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1228 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1229 \index{eax\_done()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1230 \begin{verbatim} |
| 380 | 1231 int eax_done( eax_state *eax, |
| 1232 unsigned char *tag, | |
| 1233 unsigned long *taglen); | |
| 1234 \end{verbatim} | |
| 1235 This will terminate the EAX state \textit{eax}, and store up to \textit{taglen} bytes of the message tag in \textit{tag}. The function | |
| 1236 then stores how many bytes of the tag were written out back in to \textit{taglen}. | |
| 1237 | |
| 1238 The EAX mode code can be tested to ensure it matches the test vectors by calling the following function: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1239 \index{eax\_test()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1240 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1241 int eax_test(void); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1242 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1243 This requires that the AES (or Rijndael) block cipher be registered with the cipher\_descriptor table first. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1244 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1245 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1246 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1247 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1248 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1249 int err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1250 eax_state eax; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1251 unsigned char pt[64], ct[64], nonce[16], key[16], tag[16]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1252 unsigned long taglen; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1253 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1254 if (register_cipher(&rijndael_desc) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1255 printf("Error registering Rijndael"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1256 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1257 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1258 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1259 /* ... make up random nonce and key ... */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1260 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1261 /* initialize context */ |
| 380 | 1262 if ((err = eax_init( &eax, /* context */ |
| 1263 find_cipher("rijndael"), /* cipher id */ | |
| 1264 nonce, /* the nonce */ | |
| 1265 16, /* nonce is 16 bytes */ | |
| 1266 "TestApp", /* example header */ | |
| 1267 7) /* header length */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1268 ) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1269 printf("Error eax_init: %s", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1270 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1271 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1272 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1273 /* now encrypt data, say in a loop or whatever */ |
| 380 | 1274 if ((err = eax_encrypt( &eax, /* eax context */ |
| 1275 pt, /* plaintext (source) */ | |
| 1276 ct, /* ciphertext (destination) */ | |
| 1277 sizeof(pt) /* size of plaintext */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1278 ) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1279 printf("Error eax_encrypt: %s", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1280 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1281 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1282 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1283 /* finish message and get authentication tag */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1284 taglen = sizeof(tag); |
| 380 | 1285 if ((err = eax_done( &eax, /* eax context */ |
| 1286 tag, /* where to put tag */ | |
| 1287 &taglen /* length of tag space */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1288 ) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1289 printf("Error eax_done: %s", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1290 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1291 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1292 |
| 380 | 1293 /* now we have the authentication tag in "tag" and |
| 1294 * it's taglen bytes long */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1295 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1296 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1297 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1298 You can also perform an entire EAX state on a block of memory in a single function call with the |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1299 following functions. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1300 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1301 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1302 \index{eax\_encrypt\_authenticate\_memory} \index{eax\_decrypt\_verify\_memory} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1303 \begin{verbatim} |
| 380 | 1304 int eax_encrypt_authenticate_memory( |
| 1305 int cipher, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1306 const unsigned char *key, unsigned long keylen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1307 const unsigned char *nonce, unsigned long noncelen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1308 const unsigned char *header, unsigned long headerlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1309 const unsigned char *pt, unsigned long ptlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1310 unsigned char *ct, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1311 unsigned char *tag, unsigned long *taglen); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1312 |
| 380 | 1313 int eax_decrypt_verify_memory( |
| 1314 int cipher, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1315 const unsigned char *key, unsigned long keylen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1316 const unsigned char *nonce, unsigned long noncelen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1317 const unsigned char *header, unsigned long headerlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1318 const unsigned char *ct, unsigned long ctlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1319 unsigned char *pt, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1320 unsigned char *tag, unsigned long taglen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1321 int *res); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1322 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1323 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1324 Both essentially just call eax\_init() followed by eax\_encrypt() (or eax\_decrypt() respectively) and eax\_done(). The parameters |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1325 have the same meaning as with those respective functions. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1326 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1327 The only difference is eax\_decrypt\_verify\_memory() does not emit a tag. Instead you pass it a tag as input and it compares it against |
| 380 | 1328 the tag it computed while decrypting the message. If the tags match then it stores a $1$ in \textit{res}, otherwise it stores a $0$. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1329 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1330 \subsection{OCB Mode} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1331 LibTomCrypt provides support for a mode called OCB\footnote{See |
| 380 | 1332 P. Rogaway, M. Bellare, J. Black, T. Krovetz, \textit{OCB: A Block Cipher Mode of Operation for Efficient Authenticated Encryption}.} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1333 . OCB is an encryption protocol that simultaneously provides authentication. It is slightly faster to use than EAX mode |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1334 but is less flexible. Let's review how to initialize an OCB context. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1335 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1336 \index{ocb\_init()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1337 \begin{verbatim} |
| 380 | 1338 int ocb_init( ocb_state *ocb, |
| 1339 int cipher, | |
| 1340 const unsigned char *key, | |
| 1341 unsigned long keylen, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1342 const unsigned char *nonce); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1343 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1344 |
| 380 | 1345 This will initialize the \textit{ocb} context using cipher descriptor \textit{cipher}. It will use a \textit{key} of length \textit{keylen} |
| 1346 and the random \textit{nonce}. Note that \textit{nonce} must be a random (public) string the same length as the block ciphers | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1347 block size (e.g. 16 bytes for AES). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1348 |
| 380 | 1349 This mode has no \textit{Associated Data} like EAX mode does which means you cannot authenticate metadata along with the stream. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1350 To encrypt or decrypt data use the following. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1351 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1352 \index{ocb\_encrypt()} \index{ocb\_decrypt()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1353 \begin{verbatim} |
| 380 | 1354 int ocb_encrypt( ocb_state *ocb, |
| 1355 const unsigned char *pt, | |
| 1356 unsigned char *ct); | |
| 1357 | |
| 1358 int ocb_decrypt( ocb_state *ocb, | |
| 1359 const unsigned char *ct, | |
| 1360 unsigned char *pt); | |
| 1361 \end{verbatim} | |
| 1362 | |
| 1363 This will encrypt (or decrypt for the latter) a fixed length of data from \textit{pt} to \textit{ct} (vice versa for the latter). | |
| 1364 They assume that \textit{pt} and \textit{ct} are the same size as the block cipher's block size. Note that you cannot call | |
| 1365 both functions given a single \textit{ocb} state. For bi-directional communication you will have to initialize two \textit{ocb} | |
| 1366 states (with different nonces). Also \textit{pt} and \textit{ct} may point to the same location in memory. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1367 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1368 \subsubsection{State Termination} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1369 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1370 When you are finished encrypting the message you call the following function to compute the tag. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1371 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1372 \index{ocb\_done\_encrypt()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1373 \begin{verbatim} |
| 380 | 1374 int ocb_done_encrypt( ocb_state *ocb, |
| 1375 const unsigned char *pt, | |
| 1376 unsigned long ptlen, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1377 unsigned char *ct, |
| 380 | 1378 unsigned char *tag, |
| 1379 unsigned long *taglen); | |
| 1380 \end{verbatim} | |
| 1381 | |
| 1382 This will terminate an encrypt stream \textit{ocb}. If you have trailing bytes of plaintext that will not complete a block | |
| 1383 you can pass them here. This will also encrypt the \textit{ptlen} bytes in \textit{pt} and store them in \textit{ct}. It will also | |
| 1384 store up to \textit{taglen} bytes of the tag into \textit{tag}. | |
| 1385 | |
| 1386 Note that \textit{ptlen} must be less than or equal to the block size of block cipher chosen. Also note that if you have | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1387 an input message equal to the length of the block size then you pass the data here (not to ocb\_encrypt()) only. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1388 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1389 To terminate a decrypt stream and compared the tag you call the following. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1390 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1391 \index{ocb\_done\_decrypt()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1392 \begin{verbatim} |
| 380 | 1393 int ocb_done_decrypt( ocb_state *ocb, |
| 1394 const unsigned char *ct, | |
| 1395 unsigned long ctlen, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1396 unsigned char *pt, |
| 380 | 1397 const unsigned char *tag, |
| 1398 unsigned long taglen, | |
| 1399 int *res); | |
| 1400 \end{verbatim} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1401 Similarly to the previous function you can pass trailing message bytes into this function. This will compute the |
| 380 | 1402 tag of the message (internally) and then compare it against the \textit{taglen} bytes of \textit{tag} provided. By default |
| 1403 \textit{res} is set to zero. If all \textit{taglen} bytes of \textit{tag} can be verified then \textit{res} is set to one (authenticated | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1404 message). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1405 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1406 \subsubsection{Packet Functions} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1407 To make life simpler the following two functions are provided for memory bound OCB. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1408 |
| 380 | 1409 %\index{ocb\_encrypt\_authenticate\_memory()} |
| 1410 \begin{verbatim} | |
| 1411 int ocb_encrypt_authenticate_memory( | |
| 1412 int cipher, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1413 const unsigned char *key, unsigned long keylen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1414 const unsigned char *nonce, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1415 const unsigned char *pt, unsigned long ptlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1416 unsigned char *ct, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1417 unsigned char *tag, unsigned long *taglen); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1418 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1419 |
| 380 | 1420 This will OCB encrypt the message \textit{pt} of length \textit{ptlen}, and store the ciphertext in \textit{ct}. The length \textit{ptlen} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1421 can be any arbitrary length. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1422 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1423 \index{ocb\_decrypt\_verify\_memory()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1424 \begin{verbatim} |
| 380 | 1425 int ocb_decrypt_verify_memory( |
| 1426 int cipher, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1427 const unsigned char *key, unsigned long keylen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1428 const unsigned char *nonce, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1429 const unsigned char *ct, unsigned long ctlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1430 unsigned char *pt, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1431 const unsigned char *tag, unsigned long taglen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1432 int *res); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1433 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1434 |
| 380 | 1435 Similarly, this will OCB decrypt, and compare the internally computed tag against the tag provided. \textit{res} is set |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1436 appropriately. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1437 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1438 \subsection{CCM Mode} |
| 380 | 1439 CCM is a NIST proposal for encrypt + authenticate that is centered around using AES (or any 16--byte cipher) as a primitive. Unlike EAX and OCB mode, |
| 1440 it is only meant for \textit{packet} mode where the length of the input is known in advance. Since it is a packet mode function, CCM only has one | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1441 function that performs the protocol. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1442 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1443 \index{ccm\_memory()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1444 \begin{verbatim} |
| 380 | 1445 int ccm_memory( |
| 1446 int cipher, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1447 const unsigned char *key, unsigned long keylen, |
| 380 | 1448 symmetric_key *uskey, |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1449 const unsigned char *nonce, unsigned long noncelen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1450 const unsigned char *header, unsigned long headerlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1451 unsigned char *pt, unsigned long ptlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1452 unsigned char *ct, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1453 unsigned char *tag, unsigned long *taglen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1454 int direction); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1455 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1456 |
| 380 | 1457 This performs the \textit{CCM} operation on the data. The \textit{cipher} variable indicates which cipher in the descriptor table to use. It must have a |
| 1458 16--byte block size for CCM. | |
| 1459 | |
| 1460 The key can be specified in one of two fashions. First, it can be passed as an array of octets in \textit{key} of length \textit{keylen}. Alternatively, | |
| 1461 it can be passed in as a previously scheduled key in \textit{uskey}. The latter fashion saves time when the same key is used for multiple packets. If | |
| 1462 \textit{uskey} is not \textbf{NULL}, then \textit{key} may be \textbf{NULL} (and vice-versa). | |
| 1463 | |
| 1464 The nonce or salt is \textit{nonce} of length \textit{noncelen} octets. The header is meta--data you want to send with the message but not have | |
| 1465 encrypted, it is stored in \textit{header} of length \textit{headerlen} octets. The header can be zero octets long (if $headerlen = 0$ then | |
| 1466 you can pass \textit{header} as \textbf{NULL}). | |
| 1467 | |
| 1468 The plaintext is stored in \textit{pt}, and the ciphertext in \textit{ct}. The length of both are expected to be equal and is passed in as \textit{ptlen}. It is | |
| 1469 allowable that $pt = ct$. The \textit{direction} variable indicates whether encryption (direction $=$ \textbf{CCM\_ENCRYPT}) or | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1470 decryption (direction $=$ \textbf{CCM\_DECRYPT}) is to be performed. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1471 |
| 380 | 1472 As implemented, this version of CCM cannot handle header or plaintext data longer than $2^{32} - 1$ octets long. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1473 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1474 You can test the implementation of CCM with the following function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1475 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1476 \index{ccm\_test()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1477 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1478 int ccm_test(void); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1479 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1480 |
| 380 | 1481 This will return \textbf{CRYPT\_OK} if the CCM routine passes known test vectors. It requires AES or Rijndael to be registered previously, otherwise it will |
| 1482 return \textbf{CRYPT\_NOP}. | |
| 1483 | |
| 1484 \subsubsection{CCM Example} | |
| 1485 The following is a sample of how to call CCM. | |
| 1486 | |
| 1487 \begin{small} | |
| 1488 \begin{verbatim} | |
| 1489 #include <tomcrypt.h> | |
| 1490 int main(void) | |
| 1491 { | |
| 1492 unsigned char key[16], nonce[12], pt[32], ct[32], | |
| 1493 tag[16], tagcp[16]; | |
| 1494 unsigned long taglen; | |
| 1495 int err; | |
| 1496 | |
| 1497 /* register cipher */ | |
| 1498 register_cipher(&aes_desc); | |
| 1499 | |
| 1500 /* somehow fill key, nonce, pt */ | |
| 1501 | |
| 1502 /* encrypt it */ | |
| 1503 taglen = sizeof(tag); | |
| 1504 if ((err = | |
| 1505 ccm_memory(find_cipher("aes"), | |
| 1506 key, 16, /* 128-bit key */ | |
| 1507 NULL, /* not prescheduled */ | |
| 1508 nonce, 12, /* 96-bit nonce */ | |
| 1509 NULL, 0, /* no header */ | |
| 1510 pt, 32, /* 32-byte plaintext */ | |
| 1511 ct, /* ciphertext */ | |
| 1512 tag, &taglen, | |
| 1513 CCM_ENCRYPT)) != CRYPT_OK) { | |
| 1514 printf("ccm_memory error %s\n", error_to_string(err)); | |
| 1515 return -1; | |
| 1516 } | |
| 1517 /* ct[0..31] and tag[0..15] now hold the output */ | |
| 1518 | |
| 1519 /* decrypt it */ | |
| 1520 taglen = sizeof(tagcp); | |
| 1521 if ((err = | |
| 1522 ccm_memory(find_cipher("aes"), | |
| 1523 key, 16, /* 128-bit key */ | |
| 1524 NULL, /* not prescheduled */ | |
| 1525 nonce, 12, /* 96-bit nonce */ | |
| 1526 NULL, 0, /* no header */ | |
| 1527 ct, 32, /* 32-byte ciphertext */ | |
| 1528 pt, /* plaintext */ | |
| 1529 tagcp, &taglen, | |
| 1530 CCM_DECRYPT)) != CRYPT_OK) { | |
| 1531 printf("ccm_memory error %s\n", error_to_string(err)); | |
| 1532 return -1; | |
| 1533 } | |
| 1534 | |
| 1535 /* now pt[0..31] should hold the original plaintext, | |
| 1536 tagcp[0..15] and tag[0..15] should have the same contents */ | |
| 1537 } | |
| 1538 \end{verbatim} | |
| 1539 \end{small} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1540 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1541 \subsection{GCM Mode} |
| 380 | 1542 Galois counter mode is an IEEE proposal for authenticated encryption (also it is a planned NIST standard). Like EAX and OCB mode, it can be used in a streaming capacity |
| 1543 however, unlike EAX it cannot accept \textit{additional authentication data} (meta--data) after plaintext has been processed. This mode also only works with | |
| 1544 block ciphers with a 16--byte block. | |
| 1545 | |
| 1546 A GCM stream is meant to be processed in three modes, one after another. First, the initial vector (per session) data is processed. This should be | |
| 1547 unique to every session. Next, the the optional additional authentication data is processed, and finally the plaintext (or ciphertext depending on the direction). | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1548 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1549 \subsubsection{Initialization} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1550 To initialize the GCM context with a secret key call the following function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1551 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1552 \index{gcm\_init()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1553 \begin{verbatim} |
| 380 | 1554 int gcm_init( gcm_state *gcm, |
| 1555 int cipher, | |
| 1556 const unsigned char *key, | |
| 1557 int keylen); | |
| 1558 \end{verbatim} | |
| 1559 This initializes the GCM state \textit{gcm} for the given cipher indexed by \textit{cipher}, with a secret key \textit{key} of length \textit{keylen} octets. The cipher | |
| 1560 chosen must have a 16--byte block size (e.g., AES). | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1561 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1562 \subsubsection{Initial Vector} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1563 After the state has been initialized (or reset) the next step is to add the session (or packet) initial vector. It should be unique per packet encrypted. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1564 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1565 \index{gcm\_add\_iv()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1566 \begin{verbatim} |
| 380 | 1567 int gcm_add_iv( gcm_state *gcm, |
| 1568 const unsigned char *IV, | |
| 1569 unsigned long IVlen); | |
| 1570 \end{verbatim} | |
| 1571 This adds the initial vector octets from \textit{IV} of length \textit{IVlen} to the GCM state \textit{gcm}. You can call this function as many times as required | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1572 to process the entire IV. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1573 |
| 380 | 1574 Note: the GCM protocols provides a \textit{shortcut} for 12--byte IVs where no pre-processing is to be done. If you want to minimize per packet latency it is ideal |
| 1575 to only use 12--byte IVs. You can just increment it like a counter for each packet. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1576 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1577 \subsubsection{Additional Authentication Data} |
| 380 | 1578 After the entire IV has been processed, the additional authentication data can be processed. Unlike the IV, a packet/session does not require additional |
| 1579 authentication data (AAD) for security. The AAD is meant to be used as side--channel data you want to be authenticated with the packet. Note: once | |
| 1580 you begin adding AAD to the GCM state you cannot return to adding IV data until the state has been reset. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1581 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1582 \index{gcm\_add\_aad()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1583 \begin{verbatim} |
| 380 | 1584 int gcm_add_aad( gcm_state *gcm, |
| 1585 const unsigned char *adata, | |
| 1586 unsigned long adatalen); | |
| 1587 \end{verbatim} | |
| 1588 This adds the additional authentication data \textit{adata} of length \textit{adatalen} to the GCM state \textit{gcm}. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1589 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1590 \subsubsection{Plaintext Processing} |
| 380 | 1591 After the AAD has been processed, the plaintext (or ciphertext depending on the direction) can be processed. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1592 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1593 \index{gcm\_process()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1594 \begin{verbatim} |
| 380 | 1595 int gcm_process( gcm_state *gcm, |
| 1596 unsigned char *pt, | |
| 1597 unsigned long ptlen, | |
| 1598 unsigned char *ct, | |
| 1599 int direction); | |
| 1600 \end{verbatim} | |
| 1601 This processes message data where \textit{pt} is the plaintext and \textit{ct} is the ciphertext. The length of both are equal and stored in \textit{ptlen}. Depending on | |
| 1602 the mode \textit{pt} is the input and \textit{ct} is the output (or vice versa). When \textit{direction} equals \textbf{GCM\_ENCRYPT} the plaintext is read, | |
| 1603 encrypted and stored in the ciphertext buffer. When \textit{direction} equals \textbf{GCM\_DECRYPT} the opposite occurs. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1604 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1605 \subsubsection{State Termination} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1606 To terminate a GCM state and retrieve the message authentication tag call the following function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1607 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1608 \index{gcm\_done()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1609 \begin{verbatim} |
| 380 | 1610 int gcm_done( gcm_state *gcm, |
| 1611 unsigned char *tag, | |
| 1612 unsigned long *taglen); | |
| 1613 \end{verbatim} | |
| 1614 This terminates the GCM state \textit{gcm} and stores the tag in \textit{tag} of length \textit{taglen} octets. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1615 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1616 \subsubsection{State Reset} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1617 The call to gcm\_init() will perform considerable pre--computation (when \textbf{GCM\_TABLES} is defined) and if you're going to be dealing with a lot of packets |
| 380 | 1618 it is very costly to have to call it repeatedly. To aid in this endeavour, the reset function has been provided. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1619 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1620 \index{gcm\_reset()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1621 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1622 int gcm_reset(gcm_state *gcm); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1623 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1624 |
| 380 | 1625 This will reset the GCM state \textit{gcm} to the state that gcm\_init() left it. The user would then call gcm\_add\_iv(), gcm\_add\_aad(), etc. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1626 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1627 \subsubsection{One--Shot Packet} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1628 To process a single packet under any given key the following helper function can be used. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1629 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1630 \index{gcm\_memory()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1631 \begin{verbatim} |
| 380 | 1632 int gcm_memory( |
| 1633 int cipher, | |
| 1634 const unsigned char *key, | |
| 1635 unsigned long keylen, | |
| 1636 const unsigned char *IV, unsigned long IVlen, | |
| 1637 const unsigned char *adata, unsigned long adatalen, | |
| 1638 unsigned char *pt, unsigned long ptlen, | |
| 1639 unsigned char *ct, | |
| 1640 unsigned char *tag, unsigned long *taglen, | |
| 1641 int direction); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1642 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1643 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1644 This will initialize the GCM state with the given key, IV and AAD value then proceed to encrypt or decrypt the message text and store the final |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1645 message tag. The definition of the variables is the same as it is for all the manual functions. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1646 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1647 If you are processing many packets under the same key you shouldn't use this function as it invokes the pre--computation with each call. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1648 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1649 \subsubsection{Example Usage} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1650 The following is an example usage of how to use GCM over multiple packets with a shared secret key. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1651 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1652 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1653 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1654 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1655 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1656 int send_packet(const unsigned char *pt, unsigned long ptlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1657 const unsigned char *iv, unsigned long ivlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1658 const unsigned char *aad, unsigned long aadlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1659 gcm_state *gcm) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1660 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1661 int err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1662 unsigned long taglen; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1663 unsigned char tag[16]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1664 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1665 /* reset the state */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1666 if ((err = gcm_reset(gcm)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1667 return err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1668 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1669 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1670 /* Add the IV */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1671 if ((err = gcm_add_iv(gcm, iv, ivlen)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1672 return err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1673 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1674 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1675 /* Add the AAD (note: aad can be NULL if aadlen == 0) */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1676 if ((err = gcm_add_aad(gcm, aad, aadlen)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1677 return err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1678 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1679 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1680 /* process the plaintext */ |
| 380 | 1681 if ((err = |
| 1682 gcm_process(gcm, pt, ptlen, pt, GCM_ENCRYPT)) != CRYPT_OK) { | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1683 return err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1684 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1685 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1686 /* Finish up and get the MAC tag */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1687 taglen = sizeof(tag); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1688 if ((err = gcm_done(gcm, tag, &taglen)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1689 return err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1690 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1691 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1692 /* ... send a header describing the lengths ... */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1693 |
| 380 | 1694 /* depending on the protocol and how IV is |
| 1695 * generated you may have to send it too... */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1696 send(socket, iv, ivlen, 0); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1697 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1698 /* send the aad */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1699 send(socket, aad, aadlen, 0); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1700 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1701 /* send the ciphertext */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1702 send(socket, pt, ptlen, 0); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1703 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1704 /* send the tag */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1705 send(socket, tag, taglen, 0); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1706 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1707 return CRYPT_OK; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1708 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1709 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1710 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1711 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1712 gcm_state gcm; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1713 unsigned char key[16], IV[12], pt[PACKET_SIZE]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1714 int err, x; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1715 unsigned long ptlen; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1716 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1717 /* somehow fill key/IV with random values */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1718 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1719 /* register AES */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1720 register_cipher(&aes_desc); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1721 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1722 /* init the GCM state */ |
| 380 | 1723 if ((err = |
| 1724 gcm_init(&gcm, find_cipher("aes"), key, 16)) != CRYPT_OK) { | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1725 whine_and_pout(err); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1726 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1727 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1728 /* handle us some packets */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1729 for (;;) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1730 ptlen = make_packet_we_want_to_send(pt); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1731 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1732 /* use IV as counter (12 byte counter) */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1733 for (x = 11; x >= 0; x--) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1734 if (++IV[x]) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1735 break; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1736 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1737 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1738 |
| 380 | 1739 if ((err = send_packet(pt, ptlen, iv, 12, NULL, 0, &gcm)) |
| 1740 != CRYPT_OK) { | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1741 whine_and_pout(err); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1742 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1743 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1744 return EXIT_SUCCESS; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1745 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1746 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1747 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1748 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1749 \chapter{One-Way Cryptographic Hash Functions} |
| 380 | 1750 \mysection{Core Functions} |
| 1751 Like the ciphers, there are hash core functions and a universal data type to hold the hash state called \textit{hash\_state}. To initialize hash | |
| 1752 XXX (where XXX is the name) call: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1753 \index{Hash Functions} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1754 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1755 void XXX_init(hash_state *md); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1756 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1757 |
| 380 | 1758 This simply sets up the hash to the default state governed by the specifications of the hash. To add data to the message being hashed call: |
| 1759 \begin{verbatim} | |
| 1760 int XXX_process( hash_state *md, | |
| 1761 const unsigned char *in, | |
| 1762 unsigned long inlen); | |
| 1763 \end{verbatim} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1764 Essentially all hash messages are virtually infinitely\footnote{Most hashes are limited to $2^{64}$ bits or 2,305,843,009,213,693,952 bytes.} long message which |
| 380 | 1765 are buffered. The data can be passed in any sized chunks as long as the order of the bytes are the same the message digest (hash output) will be the same. For example, |
| 1766 this means that: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1767 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1768 md5_process(&md, "hello ", 6); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1769 md5_process(&md, "world", 5); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1770 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1771 Will produce the same message digest as the single call: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1772 \index{Message Digest} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1773 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1774 md5_process(&md, "hello world", 11); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1775 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1776 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1777 To finally get the message digest (the hash) call: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1778 \begin{verbatim} |
| 380 | 1779 int XXX_done( hash_state *md, |
| 1780 unsigned char *out); | |
| 1781 \end{verbatim} | |
| 1782 | |
| 1783 This function will finish up the hash and store the result in the \textit{out} array. You must ensure that \textit{out} is long | |
| 1784 enough for the hash in question. Often hashes are used to get keys for symmetric ciphers so the \textit{XXX\_done()} functions | |
| 1785 will wipe the \textit{md} variable before returning automatically. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1786 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1787 To test a hash function call: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1788 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1789 int XXX_test(void); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1790 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1791 |
| 380 | 1792 This will return {\bf CRYPT\_OK} if the hash matches the test vectors, otherwise it returns an error code. An |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1793 example snippet that hashes a message with md5 is given below. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1794 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1795 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1796 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1797 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1798 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1799 hash_state md; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1800 unsigned char *in = "hello world", out[16]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1801 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1802 /* setup the hash */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1803 md5_init(&md); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1804 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1805 /* add the message */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1806 md5_process(&md, in, strlen(in)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1807 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1808 /* get the hash in out[0..15] */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1809 md5_done(&md, out); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1810 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1811 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1812 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1813 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1814 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1815 |
| 380 | 1816 \mysection{Hash Descriptors} |
| 1817 Like the set of ciphers, the set of hashes have descriptors as well. They are stored in an array called \textit{hash\_descriptor} and | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1818 are defined by: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1819 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1820 struct _hash_descriptor { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1821 char *name; |
| 380 | 1822 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1823 unsigned long hashsize; /* digest output size in bytes */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1824 unsigned long blocksize; /* the block size the hash uses */ |
| 380 | 1825 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1826 void (*init) (hash_state *hash); |
| 380 | 1827 |
| 1828 int (*process)( hash_state *hash, | |
| 1829 const unsigned char *in, | |
| 1830 unsigned long inlen); | |
| 1831 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1832 int (*done) (hash_state *hash, unsigned char *out); |
| 380 | 1833 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1834 int (*test) (void); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1835 }; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1836 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1837 |
| 380 | 1838 \index{find\_hash()} |
| 1839 The \textit{name} member is the name of the hash function (all lowercase). The \textit{hashsize} member is the size of the digest output | |
| 1840 in bytes, while \textit{blocksize} is the size of blocks the hash expects to the compression function. Technically, this detail is not important | |
| 1841 for high level developers but is useful to know for performance reasons. | |
| 1842 | |
| 1843 The \textit{init} member initializes the hash, \textit{process} passes data through the hash, \textit{done} terminates the hash and retrieves the | |
| 1844 digest. The \textit{test} member tests the hash against the specified test vectors. | |
| 1845 | |
| 1846 There is a function to search the array as well called \textit{int find\_hash(char *name)}. It returns -1 if the hash is not found, otherwise, the | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1847 position in the descriptor table of the hash. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1848 |
| 380 | 1849 In addition, there is also find\_hash\_oid() which finds a hash by the ASN.1 OBJECT IDENTIFIER string. |
| 1850 \index{find\_hash\_oid()} | |
| 1851 \begin{verbatim} | |
| 1852 int find_hash_oid(const unsigned long *ID, unsigned long IDlen); | |
| 1853 \end{verbatim} | |
| 1854 | |
| 1855 You can use the table to indirectly call a hash function that is chosen at run-time. For example: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1856 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1857 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1858 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1859 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1860 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1861 unsigned char buffer[100], hash[MAXBLOCKSIZE]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1862 int idx, x; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1863 hash_state md; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1864 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1865 /* register hashes .... */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1866 if (register_hash(&md5_desc) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1867 printf("Error registering MD5.\n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1868 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1869 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1870 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1871 /* register other hashes ... */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1872 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1873 /* prompt for name and strip newline */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1874 printf("Enter hash name: \n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1875 fgets(buffer, sizeof(buffer), stdin); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1876 buffer[strlen(buffer) - 1] = 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1877 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1878 /* get hash index */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1879 idx = find_hash(buffer); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1880 if (idx == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1881 printf("Invalid hash name!\n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1882 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1883 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1884 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1885 /* hash input until blank line */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1886 hash_descriptor[idx].init(&md); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1887 while (fgets(buffer, sizeof(buffer), stdin) != NULL) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1888 hash_descriptor[idx].process(&md, buffer, strlen(buffer)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1889 hash_descriptor[idx].done(&md, hash); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1890 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1891 /* dump to screen */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1892 for (x = 0; x < hash_descriptor[idx].hashsize; x++) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1893 printf("%02x ", hash[x]); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1894 printf("\n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1895 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1896 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1897 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1898 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1899 |
| 380 | 1900 Note the usage of \textbf{MAXBLOCKSIZE}. In LibTomCrypt, no symmetric block, key or hash digest is larger than \textbf{MAXBLOCKSIZE} in |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1901 length. This provides a simple size you can set your automatic arrays to that will not get overrun. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1902 |
| 380 | 1903 There are three helper functions to make working with hashes easier. The first is a function to hash a buffer, and produce the digest in a single |
| 1904 function call. | |
| 1905 | |
| 1906 \index{hash\_memory()} | |
| 1907 \begin{verbatim} | |
| 1908 int hash_memory( int hash, | |
| 1909 const unsigned char *in, | |
| 1910 unsigned long inlen, | |
| 1911 unsigned char *out, | |
| 1912 unsigned long *outlen); | |
| 1913 \end{verbatim} | |
| 1914 | |
| 1915 This will hash the data pointed to by \textit{in} of length \textit{inlen}. The hash used is indexed by the \textit{hash} parameter. The message | |
| 1916 digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size. | |
| 1917 | |
| 1918 The next helper function allows for the hashing of a file based on a file name. | |
| 1919 \index{hash\_file()} | |
| 1920 \begin{verbatim} | |
| 1921 int hash_file( int hash, | |
| 1922 const char *fname, | |
| 1923 unsigned char *out, | |
| 1924 unsigned long *outlen); | |
| 1925 \end{verbatim} | |
| 1926 | |
| 1927 This will hash the file named by \textit{fname} using the hash indexed by \textit{hash}. The file named in this function call must be readable by the | |
| 1928 user owning the process performing the request. This function can be omitted by the \textbf{LTC\_NO\_FILE} define, which forces it to return \textbf{CRYPT\_NOP} | |
| 1929 when it is called. The message digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size. | |
| 1930 | |
| 1931 \index{hash\_filehandle()} | |
| 1932 \begin{verbatim} | |
| 1933 int hash_filehandle( int hash, | |
| 1934 FILE *in, | |
| 1935 unsigned char *out, | |
| 1936 unsigned long *outlen); | |
| 1937 \end{verbatim} | |
| 1938 | |
| 1939 This will hash the file identified by the handle \textit{in} using the hash indexed by \textit{hash}. This will begin hashing from the current file pointer position, and | |
| 1940 will not rewind the file pointer when finished. This function can be omitted by the \textbf{LTC\_NO\_FILE} define, which forces it to return \textbf{CRYPT\_NOP} | |
| 1941 when it is called. The message digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1942 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1943 To perform the above hash with md5 the following code could be used: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1944 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1945 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1946 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1947 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1948 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1949 int idx, err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1950 unsigned long len; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1951 unsigned char out[MAXBLOCKSIZE]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1952 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1953 /* register the hash */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1954 if (register_hash(&md5_desc) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1955 printf("Error registering MD5.\n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1956 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1957 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1958 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1959 /* get the index of the hash */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1960 idx = find_hash("md5"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1961 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1962 /* call the hash */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1963 len = sizeof(out); |
| 380 | 1964 if ((err = |
| 1965 hash_memory(idx, "hello world", 11, out, &len)) != CRYPT_OK) { | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1966 printf("Error hashing data: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1967 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1968 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1969 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1970 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1971 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1972 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1973 |
| 380 | 1974 \subsection{Hash Registration} |
| 1975 Similar to the cipher descriptor table you must register your hash algorithms before you can use them. These functions | |
| 1976 work exactly like those of the cipher registration code. The functions are: | |
| 1977 \index{register\_hash()} \index{unregister\_hash()} | |
| 1978 \begin{verbatim} | |
| 1979 int register_hash(const struct _hash_descriptor *hash); | |
| 1980 | |
| 1981 int unregister_hash(const struct _hash_descriptor *hash); | |
| 1982 \end{verbatim} | |
| 1983 | |
| 1984 The following hashes are provided as of this release within the LibTomCrypt library: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1985 \index{Hash descriptor table} |
| 380 | 1986 |
| 1987 \begin{figure}[here] | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1988 \begin{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1989 \begin{tabular}{|c|c|c|} |
| 380 | 1990 \hline \textbf{Name} & \textbf{Descriptor Name} & \textbf{Size of Message Digest (bytes)} \\ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1991 \hline WHIRLPOOL & whirlpool\_desc & 64 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1992 \hline SHA-512 & sha512\_desc & 64 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1993 \hline SHA-384 & sha384\_desc & 48 \\ |
| 380 | 1994 \hline RIPEMD-320 & rmd160\_desc & 40 \\ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1995 \hline SHA-256 & sha256\_desc & 32 \\ |
| 380 | 1996 \hline RIPEMD-256 & rmd160\_desc & 32 \\ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1997 \hline SHA-224 & sha224\_desc & 28 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1998 \hline TIGER-192 & tiger\_desc & 24 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
1999 \hline SHA-1 & sha1\_desc & 20 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2000 \hline RIPEMD-160 & rmd160\_desc & 20 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2001 \hline RIPEMD-128 & rmd128\_desc & 16 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2002 \hline MD5 & md5\_desc & 16 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2003 \hline MD4 & md4\_desc & 16 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2004 \hline MD2 & md2\_desc & 16 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2005 \hline |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2006 \end{tabular} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2007 \end{center} |
| 380 | 2008 \caption{Built--In Software Hashes} |
| 2009 \end{figure} | |
| 2010 \vfil | |
| 2011 | |
| 2012 \mysection{Cipher Hash Construction} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2013 \index{Cipher Hash Construction} |
| 380 | 2014 An addition to the suite of hash functions is the \textit{Cipher Hash Construction} or \textit{CHC} mode. In this mode |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2015 applicable block ciphers (such as AES) can be turned into hash functions that other LTC functions can use. In |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2016 particular this allows a cryptosystem to be designed using very few moving parts. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2017 |
| 380 | 2018 In order to use the CHC system the developer will have to take a few extra steps. First the \textit{chc\_desc} hash |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2019 descriptor must be registered with register\_hash(). At this point the CHC hash cannot be used to hash |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2020 data. While it is in the hash system you still have to tell the CHC code which cipher to use. This is accomplished |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2021 via the chc\_register() function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2022 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2023 \index{chc\_register()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2024 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2025 int chc_register(int cipher); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2026 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2027 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2028 A cipher has to be registered with CHC (and also in the cipher descriptor tables with |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2029 register\_cipher()). The chc\_register() function will bind a cipher to the CHC system. Only one cipher can |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2030 be bound to the CHC hash at a time. There are additional requirements for the system to work. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2031 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2032 \begin{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2033 \item The cipher must have a block size greater than 64--bits. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2034 \item The cipher must allow an input key the size of the block size. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2035 \end{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2036 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2037 Example of using CHC with the AES block cipher. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2038 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2039 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2040 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2041 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2042 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2043 int err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2044 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2045 /* register cipher and hash */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2046 if (register_cipher(&aes_enc_desc) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2047 printf("Could not register cipher\n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2048 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2049 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2050 if (register_hash(&chc_desc) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2051 printf("Could not register hash\n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2052 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2053 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2054 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2055 /* start chc with AES */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2056 if ((err = chc_register(find_cipher("aes"))) != CRYPT_OK) { |
| 380 | 2057 printf("Error binding AES to CHC: %s\n", |
| 2058 error_to_string(err)); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2059 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2060 |
| 380 | 2061 /* now you can use chc_hash in any LTC function |
| 2062 * [aside from pkcs...] */ | |
| 2063 } | |
| 2064 \end{verbatim} | |
| 2065 | |
| 2066 | |
| 2067 \mysection{Notice} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2068 It is highly recommended that you \textbf{not} use the MD4 or MD5 hashes for the purposes of digital signatures or authentication codes. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2069 These hashes are provided for completeness and they still can be used for the purposes of password hashing or one-way accumulators |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2070 (e.g. Yarrow). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2071 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2072 The other hashes such as the SHA-1, SHA-2 (that includes SHA-512, SHA-384 and SHA-256) and TIGER-192 are still considered secure |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2073 for all purposes you would normally use a hash for. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2074 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2075 \chapter{Message Authentication Codes} |
| 380 | 2076 \mysection{HMAC Protocol} |
| 2077 Thanks to Dobes Vandermeer, the library now includes support for hash based message authentication codes, or HMAC for short. An HMAC | |
| 2078 of a message is a keyed authentication code that only the owner of a private symmetric key will be able to verify. The purpose is | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2079 to allow an owner of a private symmetric key to produce an HMAC on a message then later verify if it is correct. Any impostor or |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2080 eavesdropper will not be able to verify the authenticity of a message. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2081 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2082 The HMAC support works much like the normal hash functions except that the initialization routine requires you to pass a key |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2083 and its length. The key is much like a key you would pass to a cipher. That is, it is simply an array of octets stored in |
| 380 | 2084 unsigned characters. The initialization routine is: |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2085 \index{hmac\_init()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2086 \begin{verbatim} |
| 380 | 2087 int hmac_init( hmac_state *hmac, |
| 2088 int hash, | |
| 2089 const unsigned char *key, | |
| 2090 unsigned long keylen); | |
| 2091 \end{verbatim} | |
| 2092 The \textit{hmac} parameter is the state for the HMAC code. The \textit{hash} parameter is the index into the descriptor table of the hash you want | |
| 2093 to use to authenticate the message. The \textit{key} parameter is the pointer to the array of chars that make up the key. The \textit{keylen} parameter is the | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2094 length (in octets) of the key you want to use to authenticate the message. To send octets of a message through the HMAC system you must use the following function: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2095 \index{hmac\_process()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2096 \begin{verbatim} |
| 380 | 2097 int hmac_process( hmac_state *hmac, |
| 2098 const unsigned char *in, | |
| 2099 unsigned long inlen); | |
| 2100 \end{verbatim} | |
| 2101 \textit{hmac} is the HMAC state you are working with. \textit{buf} is the array of octets to send into the HMAC process. \textit{len} is the | |
| 2102 number of octets to process. Like the hash process routines you can send the data in arbitrarily sized chunks. When you | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2103 are finished with the HMAC process you must call the following function to get the HMAC code: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2104 \index{hmac\_done()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2105 \begin{verbatim} |
| 380 | 2106 int hmac_done( hmac_state *hmac, |
| 2107 unsigned char *out, | |
| 2108 unsigned long *outlen); | |
| 2109 \end{verbatim} | |
| 2110 The \textit{hmac} parameter is the HMAC state you are working with. The \textit{out} parameter is the array of octets where the HMAC code should be stored. | |
| 2111 You must set \textit{outlen} to the size of the destination buffer before calling this function. It is updated with the length of the HMAC code | |
| 2112 produced (depending on which hash was picked). If \textit{outlen} is less than the size of the message digest (and ultimately | |
| 2113 the HMAC code) then the HMAC code is truncated as per FIPS-198 specifications (e.g. take the first \textit{outlen} bytes). | |
| 2114 | |
| 2115 There are two utility functions provided to make using HMACs easier to do. They accept the key and information about the | |
| 2116 message (file pointer, address in memory), and produce the HMAC result in one shot. These are useful if you want to avoid | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2117 calling the three step process yourself. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2118 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2119 \index{hmac\_memory()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2120 \begin{verbatim} |
| 380 | 2121 int hmac_memory( |
| 2122 int hash, | |
| 2123 const unsigned char *key, unsigned long keylen, | |
| 2124 const unsigned char *in, unsigned long inlen, | |
| 2125 unsigned char *out, unsigned long *outlen); | |
| 2126 \end{verbatim} | |
| 2127 This will produce an HMAC code for the array of octets in \textit{in} of length \textit{inlen}. The index into the hash descriptor | |
| 2128 table must be provided in \textit{hash}. It uses the key from \textit{key} with a key length of \textit{keylen}. | |
| 2129 The result is stored in the array of octets \textit{out} and the length in \textit{outlen}. The value of \textit{outlen} must be set | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2130 to the size of the destination buffer before calling this function. Similarly for files there is the following function: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2131 \index{hmac\_file()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2132 \begin{verbatim} |
| 380 | 2133 int hmac_file( |
| 2134 int hash, | |
| 2135 const char *fname, | |
| 2136 const unsigned char *key, unsigned long keylen, | |
| 2137 unsigned char *out, unsigned long *outlen); | |
| 2138 \end{verbatim} | |
| 2139 \textit{hash} is the index into the hash descriptor table of the hash you want to use. \textit{fname} is the filename to process. | |
| 2140 \textit{key} is the array of octets to use as the key of length \textit{keylen}. \textit{out} is the array of octets where the | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2141 result should be stored. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2142 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2143 To test if the HMAC code is working there is the following function: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2144 \index{hmac\_test()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2145 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2146 int hmac_test(void); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2147 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2148 Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. Some example code for using the |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2149 HMAC system is given below. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2150 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2151 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2152 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2153 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2154 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2155 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2156 int idx, err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2157 hmac_state hmac; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2158 unsigned char key[16], dst[MAXBLOCKSIZE]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2159 unsigned long dstlen; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2160 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2161 /* register SHA-1 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2162 if (register_hash(&sha1_desc) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2163 printf("Error registering SHA1\n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2164 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2165 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2166 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2167 /* get index of SHA1 in hash descriptor table */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2168 idx = find_hash("sha1"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2169 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2170 /* we would make up our symmetric key in "key[]" here */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2171 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2172 /* start the HMAC */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2173 if ((err = hmac_init(&hmac, idx, key, 16)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2174 printf("Error setting up hmac: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2175 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2176 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2177 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2178 /* process a few octets */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2179 if((err = hmac_process(&hmac, "hello", 5) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2180 printf("Error processing hmac: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2181 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2182 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2183 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2184 /* get result (presumably to use it somehow...) */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2185 dstlen = sizeof(dst); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2186 if ((err = hmac_done(&hmac, dst, &dstlen)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2187 printf("Error finishing hmac: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2188 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2189 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2190 printf("The hmac is %lu bytes long\n", dstlen); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2191 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2192 /* return */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2193 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2194 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2195 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2196 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2197 |
| 380 | 2198 \mysection{OMAC Support} |
| 2199 \index{OMAC} \index{CMAC} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2200 OMAC\footnote{\url{http://crypt.cis.ibaraki.ac.jp/omac/omac.html}}, which stands for \textit{One-Key CBC MAC} is an |
| 380 | 2201 algorithm which produces a Message Authentication Code (MAC) using only a block cipher such as AES. Note: OMAC has been standardized as |
| 2202 CMAC within NIST, for the purposes of this library OMAC and CMAC are synonymous. From an API standpoint, the OMAC routines work much like the | |
| 2203 HMAC routines. Instead, in this case a cipher is used instead of a hash. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2204 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2205 To start an OMAC state you call |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2206 \index{omac\_init()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2207 \begin{verbatim} |
| 380 | 2208 int omac_init( omac_state *omac, |
| 2209 int cipher, | |
| 2210 const unsigned char *key, | |
| 2211 unsigned long keylen); | |
| 2212 \end{verbatim} | |
| 2213 The \textit{omac} parameter is the state for the OMAC algorithm. The \textit{cipher} parameter is the index into the cipher\_descriptor table | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2214 of the cipher\footnote{The cipher must have a 64 or 128 bit block size. Such as CAST5, Blowfish, DES, AES, Twofish, etc.} you |
| 380 | 2215 wish to use. The \textit{key} and \textit{keylen} parameters are the keys used to authenticate the data. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2216 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2217 To send data through the algorithm call |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2218 \index{omac\_process()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2219 \begin{verbatim} |
| 380 | 2220 int omac_process( omac_state *state, |
| 2221 const unsigned char *in, | |
| 2222 unsigned long inlen); | |
| 2223 \end{verbatim} | |
| 2224 This will send \textit{inlen} bytes from \textit{in} through the active OMAC state \textit{state}. Returns \textbf{CRYPT\_OK} if the | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2225 function succeeds. The function is not sensitive to the granularity of the data. For example, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2226 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2227 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2228 omac_process(&mystate, "hello", 5); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2229 omac_process(&mystate, " world", 6); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2230 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2231 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2232 Would produce the same result as, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2233 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2234 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2235 omac_process(&mystate, "hello world", 11); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2236 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2237 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2238 When you are done processing the message you can call the following to compute the message tag. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2239 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2240 \index{omac\_done()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2241 \begin{verbatim} |
| 380 | 2242 int omac_done( omac_state *state, |
| 2243 unsigned char *out, | |
| 2244 unsigned long *outlen); | |
| 2245 \end{verbatim} | |
| 2246 Which will terminate the OMAC and output the \textit{tag} (MAC) to \textit{out}. Note that unlike the HMAC and other code | |
| 2247 \textit{outlen} can be smaller than the default MAC size (for instance AES would make a 16-byte tag). Part of the OMAC | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2248 specification states that the output may be truncated. So if you pass in $outlen = 5$ and use AES as your cipher than |
| 380 | 2249 the output MAC code will only be five bytes long. If \textit{outlen} is larger than the default size it is set to the default |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2250 size to show how many bytes were actually used. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2251 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2252 Similar to the HMAC code the file and memory functions are also provided. To OMAC a buffer of memory in one shot use the |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2253 following function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2254 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2255 \index{omac\_memory()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2256 \begin{verbatim} |
| 380 | 2257 int omac_memory( |
| 2258 int cipher, | |
| 2259 const unsigned char *key, unsigned long keylen, | |
| 2260 const unsigned char *in, unsigned long inlen, | |
| 2261 unsigned char *out, unsigned long *outlen); | |
| 2262 \end{verbatim} | |
| 2263 This will compute the OMAC of \textit{inlen} bytes of \textit{in} using the key \textit{key} of length \textit{keylen} bytes and the cipher | |
| 2264 specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2265 rules as omac\_done. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2266 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2267 To OMAC a file use |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2268 \index{omac\_file()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2269 \begin{verbatim} |
| 380 | 2270 int omac_file( |
| 2271 int cipher, | |
| 2272 const unsigned char *key, unsigned long keylen, | |
| 2273 const char *filename, | |
| 2274 unsigned char *out, unsigned long *outlen); | |
| 2275 \end{verbatim} | |
| 2276 | |
| 2277 Which will OMAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes | |
| 2278 and the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2279 the same rules as omac\_done. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2280 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2281 To test if the OMAC code is working there is the following function: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2282 \index{omac\_test()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2283 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2284 int omac_test(void); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2285 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2286 Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. Some example code for using the |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2287 OMAC system is given below. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2288 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2289 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2290 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2291 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2292 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2293 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2294 int idx, err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2295 omac_state omac; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2296 unsigned char key[16], dst[MAXBLOCKSIZE]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2297 unsigned long dstlen; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2298 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2299 /* register Rijndael */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2300 if (register_cipher(&rijndael_desc) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2301 printf("Error registering Rijndael\n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2302 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2303 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2304 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2305 /* get index of Rijndael in cipher descriptor table */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2306 idx = find_cipher("rijndael"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2307 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2308 /* we would make up our symmetric key in "key[]" here */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2309 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2310 /* start the OMAC */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2311 if ((err = omac_init(&omac, idx, key, 16)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2312 printf("Error setting up omac: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2313 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2314 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2315 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2316 /* process a few octets */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2317 if((err = omac_process(&omac, "hello", 5) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2318 printf("Error processing omac: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2319 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2320 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2321 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2322 /* get result (presumably to use it somehow...) */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2323 dstlen = sizeof(dst); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2324 if ((err = omac_done(&omac, dst, &dstlen)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2325 printf("Error finishing omac: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2326 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2327 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2328 printf("The omac is %lu bytes long\n", dstlen); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2329 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2330 /* return */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2331 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2332 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2333 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2334 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2335 |
| 380 | 2336 \mysection{PMAC Support} |
| 2337 The PMAC\footnote{J.Black, P.Rogaway, \textit{A Block--Cipher Mode of Operation for Parallelizable Message Authentication}} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2338 protocol is another MAC algorithm that relies solely on a symmetric-key block cipher. It uses essentially the same |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2339 API as the provided OMAC code. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2340 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2341 A PMAC state is initialized with the following. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2342 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2343 \index{pmac\_init()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2344 \begin{verbatim} |
| 380 | 2345 int pmac_init( pmac_state *pmac, |
| 2346 int cipher, | |
| 2347 const unsigned char *key, | |
| 2348 unsigned long keylen); | |
| 2349 \end{verbatim} | |
| 2350 Which initializes the \textit{pmac} state with the given \textit{cipher} and \textit{key} of length \textit{keylen} bytes. The chosen cipher | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2351 must have a 64 or 128 bit block size (e.x. AES). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2352 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2353 To MAC data simply send it through the process function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2354 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2355 \index{pmac\_process()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2356 \begin{verbatim} |
| 380 | 2357 int pmac_process( pmac_state *state, |
| 2358 const unsigned char *in, | |
| 2359 unsigned long inlen); | |
| 2360 \end{verbatim} | |
| 2361 This will process \textit{inlen} bytes of \textit{in} in the given \textit{state}. The function is not sensitive to the granularity of the | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2362 data. For example, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2363 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2364 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2365 pmac_process(&mystate, "hello", 5); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2366 pmac_process(&mystate, " world", 6); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2367 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2368 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2369 Would produce the same result as, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2370 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2371 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2372 pmac_process(&mystate, "hello world", 11); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2373 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2374 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2375 When a complete message has been processed the following function can be called to compute the message tag. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2376 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2377 \index{pmac\_done()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2378 \begin{verbatim} |
| 380 | 2379 int pmac_done( pmac_state *state, |
| 2380 unsigned char *out, | |
| 2381 unsigned long *outlen); | |
| 2382 \end{verbatim} | |
| 2383 This will store up to \textit{outlen} bytes of the tag for the given \textit{state} into \textit{out}. Note that if \textit{outlen} is larger | |
| 2384 than the size of the tag it is set to the amount of bytes stored in \textit{out}. | |
| 2385 | |
| 2386 Similar to the OMAC code the file and memory functions are also provided. To PMAC a buffer of memory in one shot use the | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2387 following function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2388 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2389 \index{pmac\_memory()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2390 \begin{verbatim} |
| 380 | 2391 int pmac_memory( |
| 2392 int cipher, | |
| 2393 const unsigned char *key, unsigned long keylen, | |
| 2394 const unsigned char *in, unsigned long inlen, | |
| 2395 unsigned char *out, unsigned long *outlen); | |
| 2396 \end{verbatim} | |
| 2397 This will compute the PMAC of \textit{msglen} bytes of \textit{msg} using the key \textit{key} of length \textit{keylen} bytes, and the cipher | |
| 2398 specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same | |
| 2399 rules as pmac\_done(). | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2400 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2401 To PMAC a file use |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2402 \index{pmac\_file()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2403 \begin{verbatim} |
| 380 | 2404 int pmac_file( |
| 2405 int cipher, | |
| 2406 const unsigned char *key, unsigned long keylen, | |
| 2407 const char *filename, | |
| 2408 unsigned char *out, unsigned long *outlen); | |
| 2409 \end{verbatim} | |
| 2410 | |
| 2411 Which will PMAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, | |
| 2412 and the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with | |
| 2413 the same rules as pmac\_done(). | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2414 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2415 To test if the PMAC code is working there is the following function: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2416 \index{pmac\_test()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2417 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2418 int pmac_test(void); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2419 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2420 Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2421 |
| 380 | 2422 \mysection{Pelican MAC} |
| 2423 Pelican MAC is a new (experimental) MAC by the AES team that uses four rounds of AES as a \textit{mixing function}. It achieves a very high | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2424 rate of processing and is potentially very secure. It requires AES to be enabled to function. You do not have to register\_cipher() AES first though |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2425 as it calls AES directly. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2426 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2427 \index{pelican\_init()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2428 \begin{verbatim} |
| 380 | 2429 int pelican_init( pelican_state *pelmac, |
| 2430 const unsigned char *key, | |
| 2431 unsigned long keylen); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2432 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2433 This will initialize the Pelican state with the given AES key. Once this has been done you can begin processing data. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2434 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2435 \index{pelican\_process()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2436 \begin{verbatim} |
| 380 | 2437 int pelican_process( pelican_state *pelmac, |
| 2438 const unsigned char *in, | |
| 2439 unsigned long inlen); | |
| 2440 \end{verbatim} | |
| 2441 This will process \textit{inlen} bytes of \textit{in} through the Pelican MAC. It's best that you pass in multiples of 16 bytes as it makes the | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2442 routine more efficient but you may pass in any length of text. You can call this function as many times as required to process |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2443 an entire message. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2444 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2445 \index{pelican\_done()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2446 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2447 int pelican_done(pelican_state *pelmac, unsigned char *out); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2448 \end{verbatim} |
| 380 | 2449 This terminates a Pelican MAC and writes the 16--octet tag to \textit{out}. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2450 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2451 \subsection{Example} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2452 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2453 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2454 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2455 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2456 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2457 pelican_state pelstate; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2458 unsigned char key[32], tag[16]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2459 int err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2460 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2461 /* somehow initialize a key */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2462 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2463 /* initialize pelican mac */ |
| 380 | 2464 if ((err = pelican_init(&pelstate, /* the state */ |
| 2465 key, /* user key */ | |
| 2466 32 /* key length in octets */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2467 )) != CRYPT_OK) { |
| 380 | 2468 printf("Error initializing Pelican: %s", |
| 2469 error_to_string(err)); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2470 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2471 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2472 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2473 /* MAC some data */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2474 if ((err = pelican_process(&pelstate, /* the state */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2475 "hello world", /* data to mac */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2476 11 /* length of data */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2477 )) != CRYPT_OK) { |
| 380 | 2478 printf("Error processing Pelican: %s", |
| 2479 error_to_string(err)); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2480 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2481 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2482 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2483 /* Terminate the MAC */ |
| 380 | 2484 if ((err = pelican_done(&pelstate,/* the state */ |
| 2485 tag /* where to store the tag */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2486 )) != CRYPT_OK) { |
| 380 | 2487 printf("Error terminating Pelican: %s", |
| 2488 error_to_string(err)); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2489 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2490 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2491 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2492 /* tag[0..15] has the MAC output now */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2493 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2494 return EXIT_SUCCESS; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2495 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2496 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2497 |
| 380 | 2498 \mysection{XCBC-MAC} |
| 2499 As of LibTomCrypt v1.15, XCBC-MAC (RFC 3566) has been provided to support TLS encryption suites. Like OMAC, it computes a message authentication code | |
| 2500 by using a cipher in CBC mode. It also uses a single key which it expands into the requisite three keys for the MAC function. A XCBC--MAC state is | |
| 2501 initialized with the following function: | |
| 2502 | |
| 2503 \index{xcbc\_init()} | |
| 2504 \begin{verbatim} | |
| 2505 int xcbc_init( xcbc_state *xcbc, | |
| 2506 int cipher, | |
| 2507 const unsigned char *key, | |
| 2508 unsigned long keylen); | |
| 2509 \end{verbatim} | |
| 2510 | |
| 2511 This will initialize the XCBC--MAC state \textit{xcbc}, with the key specified in \textit{key} of length \textit{keylen} octets. The cipher indicated | |
| 2512 by the \textit{cipher} index can be either a 64 or 128--bit block cipher. This will return \textbf{CRYPT\_OK} on success. | |
| 2513 | |
| 2514 To process data through XCBC--MAC use the following function: | |
| 2515 | |
| 2516 \index{xcbc\_process()} | |
| 2517 \begin{verbatim} | |
| 2518 int xcbc_process( xcbc_state *state, | |
| 2519 const unsigned char *in, | |
| 2520 unsigned long inlen); | |
| 2521 \end{verbatim} | |
| 2522 | |
| 2523 This will add the message octets pointed to by \textit{in} of length \textit{inlen} to the XCBC--MAC state pointed to by \textit{state}. Like the other MAC functions, | |
| 2524 the granularity of the input is not important but the order is. This will return \textbf{CRYPT\_OK} on success. | |
| 2525 | |
| 2526 To compute the MAC tag value use the following function: | |
| 2527 | |
| 2528 \index{xcbc\_done()} | |
| 2529 \begin{verbatim} | |
| 2530 int xcbc_done( xcbc_state *state, | |
| 2531 unsigned char *out, | |
| 2532 unsigned long *outlen); | |
| 2533 \end{verbatim} | |
| 2534 | |
| 2535 This will retrieve the XCBC--MAC tag from the state pointed to by \textit{state}, and store it in the array pointed to by \textit{out}. The \textit{outlen} parameter | |
| 2536 specifies the maximum size of the destination buffer, and is updated to hold the final size of the tag when the function returns. This will return \textbf{CRYPT\_OK} on success. | |
| 2537 | |
| 2538 Helper functions are provided to make parsing memory buffers and files easier. The following functions are provided: | |
| 2539 | |
| 2540 \index{xcbc\_memory()} | |
| 2541 \begin{verbatim} | |
| 2542 int xcbc_memory( | |
| 2543 int cipher, | |
| 2544 const unsigned char *key, unsigned long keylen, | |
| 2545 const unsigned char *in, unsigned long inlen, | |
| 2546 unsigned char *out, unsigned long *outlen); | |
| 2547 \end{verbatim} | |
| 2548 This will compute the XCBC--MAC of \textit{msglen} bytes of \textit{msg}, using the key \textit{key} of length \textit{keylen} bytes, and the cipher | |
| 2549 specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same rules as xcbc\_done(). | |
| 2550 | |
| 2551 To xcbc a file use | |
| 2552 \index{xcbc\_file()} | |
| 2553 \begin{verbatim} | |
| 2554 int xcbc_file( | |
| 2555 int cipher, | |
| 2556 const unsigned char *key, unsigned long keylen, | |
| 2557 const char *filename, | |
| 2558 unsigned char *out, unsigned long *outlen); | |
| 2559 \end{verbatim} | |
| 2560 | |
| 2561 Which will XCBC--MAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, and the cipher | |
| 2562 specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same rules as xcbc\_done(). | |
| 2563 | |
| 2564 | |
| 2565 To test XCBC--MAC for RFC 3566 compliance use the following function: | |
| 2566 | |
| 2567 \index{xcbc\_test()} | |
| 2568 \begin{verbatim} | |
| 2569 int xcbc_test(void); | |
| 2570 \end{verbatim} | |
| 2571 | |
| 2572 This will return \textbf{CRYPT\_OK} on success. This requires the AES or Rijndael descriptor be previously registered, otherwise, it will return | |
| 2573 \textbf{CRYPT\_NOP}. | |
| 2574 | |
| 2575 \mysection{F9--MAC} | |
| 2576 The F9--MAC is yet another CBC--MAC variant proposed for the 3GPP standard. Originally specified to be used with the KASUMI block cipher, it can also be used | |
| 2577 with other ciphers. For LibTomCrypt, the F9--MAC code can use any cipher. | |
| 2578 | |
| 2579 \subsection{Usage Notice} | |
| 2580 F9--MAC differs slightly from the other MAC functions in that it requires the caller to perform the final message padding. The padding quite simply is a direction | |
| 2581 bit followed by a 1 bit and enough zeros to make the message a multiple of the cipher block size. If the message is byte aligned, the padding takes on the form of | |
| 2582 a single 0x40 or 0xC0 byte followed by enough 0x00 bytes to make the message proper multiple. | |
| 2583 | |
| 2584 If the user simply wants a MAC function (hint: use OMAC) padding with a single 0x40 byte should be sufficient for security purposes and still be reasonably compatible | |
| 2585 with F9--MAC. | |
| 2586 | |
| 2587 \subsection{F9--MAC Functions} | |
| 2588 A F9--MAC state is initialized with the following function: | |
| 2589 \index{f9\_init()} | |
| 2590 \begin{verbatim} | |
| 2591 int f9_init( f9_state *f9, | |
| 2592 int cipher, | |
| 2593 const unsigned char *key, | |
| 2594 unsigned long keylen); | |
| 2595 \end{verbatim} | |
| 2596 | |
| 2597 This will initialize the F9--MAC state \textit{f9}, with the key specified in \textit{key} of length \textit{keylen} octets. The cipher indicated | |
| 2598 by the \textit{cipher} index can be either a 64 or 128--bit block cipher. This will return \textbf{CRYPT\_OK} on success. | |
| 2599 | |
| 2600 To process data through F9--MAC use the following function: | |
| 2601 \index{f9\_process()} | |
| 2602 \begin{verbatim} | |
| 2603 int f9_process( f9_state *state, | |
| 2604 const unsigned char *in, | |
| 2605 unsigned long inlen); | |
| 2606 \end{verbatim} | |
| 2607 | |
| 2608 This will add the message octets pointed to by \textit{in} of length \textit{inlen} to the F9--MAC state pointed to by \textit{state}. Like the other MAC functions, | |
| 2609 the granularity of the input is not important but the order is. This will return \textbf{CRYPT\_OK} on success. | |
| 2610 | |
| 2611 To compute the MAC tag value use the following function: | |
| 2612 | |
| 2613 \index{f9\_done()} | |
| 2614 \begin{verbatim} | |
| 2615 int f9_done( f9_state *state, | |
| 2616 unsigned char *out, | |
| 2617 unsigned long *outlen); | |
| 2618 \end{verbatim} | |
| 2619 | |
| 2620 This will retrieve the F9--MAC tag from the state pointed to by \textit{state}, and store it in the array pointed to by \textit{out}. The \textit{outlen} parameter | |
| 2621 specifies the maximum size of the destination buffer, and is updated to hold the final size of the tag when the function returns. This will return | |
| 2622 \textbf{CRYPT\_OK} on success. | |
| 2623 | |
| 2624 Helper functions are provided to make parsing memory buffers and files easier. The following functions are provided: | |
| 2625 | |
| 2626 \index{f9\_memory()} | |
| 2627 \begin{verbatim} | |
| 2628 int f9_memory( | |
| 2629 int cipher, | |
| 2630 const unsigned char *key, unsigned long keylen, | |
| 2631 const unsigned char *in, unsigned long inlen, | |
| 2632 unsigned char *out, unsigned long *outlen); | |
| 2633 \end{verbatim} | |
| 2634 This will compute the F9--MAC of \textit{msglen} bytes of \textit{msg}, using the key \textit{key} of length \textit{keylen} bytes, and the cipher | |
| 2635 specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same rules as f9\_done(). | |
| 2636 | |
| 2637 To F9--MAC a file use | |
| 2638 \index{f9\_file()} | |
| 2639 \begin{verbatim} | |
| 2640 int f9_file( | |
| 2641 int cipher, | |
| 2642 const unsigned char *key, unsigned long keylen, | |
| 2643 const char *filename, | |
| 2644 unsigned char *out, unsigned long *outlen); | |
| 2645 \end{verbatim} | |
| 2646 | |
| 2647 Which will F9--MAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, and the cipher | |
| 2648 specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same rules as f9\_done(). | |
| 2649 | |
| 2650 | |
| 2651 To test f9--MAC for RFC 3566 compliance use the following function: | |
| 2652 | |
| 2653 \index{f9\_test()} | |
| 2654 \begin{verbatim} | |
| 2655 int f9_test(void); | |
| 2656 \end{verbatim} | |
| 2657 | |
| 2658 This will return \textbf{CRYPT\_OK} on success. This requires the AES or Rijndael descriptor be previously registered, otherwise, it will return | |
| 2659 \textbf{CRYPT\_NOP}. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2660 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2661 \chapter{Pseudo-Random Number Generators} |
| 380 | 2662 \mysection{Core Functions} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2663 The library provides an array of core functions for Pseudo-Random Number Generators (PRNGs) as well. A cryptographic PRNG is |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2664 used to expand a shorter bit string into a longer bit string. PRNGs are used wherever random data is required such as Public Key (PK) |
| 380 | 2665 key generation. There is a universal structure called \textit{prng\_state}. To initialize a PRNG call: |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2666 \index{PRNG start} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2667 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2668 int XXX_start(prng_state *prng); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2669 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2670 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2671 This will setup the PRNG for future use and not seed it. In order for the PRNG to be cryptographically useful you must give it |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2672 entropy. Ideally you'd have some OS level source to tap like in UNIX. To add entropy to the PRNG call: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2673 \index{PRNG add\_entropy} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2674 \begin{verbatim} |
| 380 | 2675 int XXX_add_entropy(const unsigned char *in, |
| 2676 unsigned long inlen, | |
| 2677 prng_state *prng); | |
| 2678 \end{verbatim} | |
| 2679 Which returns {\bf CRYPT\_OK} if the entropy was accepted. Once you think you have enough entropy you call another | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2680 function to put the entropy into action. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2681 \index{PRNG ready} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2682 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2683 int XXX_ready(prng_state *prng); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2684 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2685 |
| 380 | 2686 Which returns {\bf CRYPT\_OK} if it is ready. Finally to actually read bytes call: |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2687 \index{PRNG read} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2688 \begin{verbatim} |
| 380 | 2689 unsigned long XXX_read(unsigned char *out, |
| 2690 unsigned long outlen, | |
| 2691 prng_state *prng); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2692 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2693 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2694 Which returns the number of bytes read from the PRNG. When you are finished with a PRNG state you call |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2695 the following. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2696 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2697 \index{PRNG done} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2698 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2699 void XXX_done(prng_state *prng); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2700 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2701 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2702 This will terminate a PRNG state and free any memory (if any) allocated. To export a PRNG state |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2703 so that you can later resume the PRNG call the following. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2704 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2705 \index{PRNG export} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2706 \begin{verbatim} |
| 380 | 2707 int XXX_export(unsigned char *out, |
| 2708 unsigned long *outlen, | |
| 2709 prng_state *prng); | |
| 2710 \end{verbatim} | |
| 2711 | |
| 2712 This will write a \textit{PRNG state} to the buffer \textit{out} of length \textit{outlen} bytes. The idea of | |
| 2713 the export is meant to be used as a \textit{seed file}. That is, when the program starts up there will not likely | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2714 be that much entropy available. To import a state to seed a PRNG call the following function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2715 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2716 \index{PRNG import} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2717 \begin{verbatim} |
| 380 | 2718 int XXX_import(const unsigned char *in, |
| 2719 unsigned long inlen, | |
| 2720 prng_state *prng); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2721 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2722 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2723 This will call the start and add\_entropy functions of the given PRNG. It will use the state in |
| 380 | 2724 \textit{in} of length \textit{inlen} as the initial seed. You must pass the same seed length as was exported |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2725 by the corresponding export function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2726 |
| 380 | 2727 Note that importing a state will not \textit{resume} the PRNG from where it left off. That is, if you export |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2728 a state, emit (say) 8 bytes and then import the previously exported state the next 8 bytes will not |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2729 specifically equal the 8 bytes you generated previously. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2730 |
| 380 | 2731 When a program is first executed the normal course of operation is: |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2732 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2733 \begin{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2734 \item Gather entropy from your sources for a given period of time or number of events. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2735 \item Start, use your entropy via add\_entropy and ready the PRNG yourself. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2736 \end{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2737 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2738 When your program is finished you simply call the export function and save the state to a medium (disk, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2739 flash memory, etc). The next time your application starts up you can detect the state, feed it to the |
| 380 | 2740 import function and go on your way. It is ideal that (as soon as possible) after start up you export a |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2741 fresh state. This helps in the case that the program aborts or the machine is powered down without |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2742 being given a chance to exit properly. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2743 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2744 Note that even if you have a state to import it is important to add new entropy to the state. However, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2745 there is less pressure to do so. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2746 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2747 To test a PRNG for operational conformity call the following functions. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2748 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2749 \index{PRNG test} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2750 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2751 int XXX_test(void); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2752 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2753 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2754 This will return \textbf{CRYPT\_OK} if PRNG is operating properly. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2755 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2756 \subsection{Remarks} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2757 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2758 It is possible to be adding entropy and reading from a PRNG at the same time. For example, if you first seed the PRNG |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2759 and call ready() you can now read from it. You can also keep adding new entropy to it. The new entropy will not be used |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2760 in the PRNG until ready() is called again. This allows the PRNG to be used and re-seeded at the same time. No real error |
| 380 | 2761 checking is guaranteed to see if the entropy is sufficient, or if the PRNG is even in a ready state before reading. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2762 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2763 \subsection{Example} |
| 380 | 2764 Below is a simple snippet to read 10 bytes from Yarrow. It is important to note that this snippet is {\bf NOT} secure since |
| 2765 the entropy added is not random. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2766 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2767 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2768 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2769 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2770 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2771 prng_state prng; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2772 unsigned char buf[10]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2773 int err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2774 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2775 /* start it */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2776 if ((err = yarrow_start(&prng)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2777 printf("Start error: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2778 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2779 /* add entropy */ |
| 380 | 2780 if ((err = yarrow_add_entropy("hello world", 11, &prng)) |
| 2781 != CRYPT_OK) { | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2782 printf("Add_entropy error: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2783 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2784 /* ready and read */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2785 if ((err = yarrow_ready(&prng)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2786 printf("Ready error: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2787 } |
| 380 | 2788 printf("Read %lu bytes from yarrow\n", |
| 2789 yarrow_read(buf, sizeof(buf), &prng)); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2790 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2791 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2792 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2793 |
| 380 | 2794 \mysection{PRNG Descriptors} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2795 \index{PRNG Descriptor} |
| 380 | 2796 PRNGs have descriptors that allow plugin driven functions to be created using PRNGs. The plugin descriptors are stored in the structure \textit{prng\_descriptor}. The |
| 2797 format of an element is: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2798 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2799 struct _prng_descriptor { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2800 char *name; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2801 int export_size; /* size in bytes of exported state */ |
| 380 | 2802 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2803 int (*start) (prng_state *); |
| 380 | 2804 |
| 2805 int (*add_entropy)(const unsigned char *, unsigned long, | |
| 2806 prng_state *); | |
| 2807 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2808 int (*ready) (prng_state *); |
| 380 | 2809 |
| 2810 unsigned long (*read)(unsigned char *, unsigned long len, | |
| 2811 prng_state *); | |
| 2812 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2813 void (*done)(prng_state *); |
| 380 | 2814 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2815 int (*export)(unsigned char *, unsigned long *, prng_state *); |
| 380 | 2816 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2817 int (*import)(const unsigned char *, unsigned long, prng_state *); |
| 380 | 2818 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2819 int (*test)(void); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2820 }; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2821 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2822 |
| 380 | 2823 To find a PRNG in the descriptor table the following function can be used: |
| 2824 \index{find\_prng()} | |
| 2825 \begin{verbatim} | |
| 2826 int find_prng(const char *name); | |
| 2827 \end{verbatim} | |
| 2828 This will search the PRNG descriptor table for the PRNG named \textit{name}. It will return -1 if the PRNG is not found, otherwise, it returns | |
| 2829 the index into the descriptor table. | |
| 2830 | |
| 2831 Just like the ciphers and hashes, you must register your prng before you can use it. The two functions provided work exactly as those for the cipher registry functions. | |
| 2832 They are the following: | |
| 2833 \index{register\_prng()} \index{unregister\_prng()} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2834 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2835 int register_prng(const struct _prng_descriptor *prng); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2836 int unregister_prng(const struct _prng_descriptor *prng); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2837 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2838 |
| 380 | 2839 The register function will register the PRNG, and return the index into the table where it was placed (or -1 for error). It will avoid registering the same |
| 2840 descriptor twice, and will return the index of the current placement in the table if the caller attempts to register it more than once. The unregister function | |
| 2841 will return \textbf{CRYPT\_OK} if the PRNG was found and removed. Otherwise, it returns \textbf{CRYPT\_ERROR}. | |
| 2842 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2843 \subsection{PRNGs Provided} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2844 \begin{figure}[here] |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2845 \begin{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2846 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2847 \begin{tabular}{|c|c|l|} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2848 \hline \textbf{Name} & \textbf{Descriptor} & \textbf{Usage} \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2849 \hline Yarrow & yarrow\_desc & Fast short-term PRNG \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2850 \hline Fortuna & fortuna\_desc & Fast long-term PRNG (recommended) \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2851 \hline RC4 & rc4\_desc & Stream Cipher \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2852 \hline SOBER-128 & sober128\_desc & Stream Cipher (also very fast PRNG) \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2853 \hline |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2854 \end{tabular} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2855 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2856 \end{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2857 \caption{List of Provided PRNGs} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2858 \end{figure} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2859 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2860 \subsubsection{Yarrow} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2861 Yarrow is fast PRNG meant to collect an unspecified amount of entropy from sources |
| 380 | 2862 (keyboard, mouse, interrupts, etc), and produce an unbounded string of random bytes. |
| 2863 | |
| 2864 \textit{Note:} This PRNG is still secure for most tasks but is no longer recommended. Users | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2865 should use Fortuna instead. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2866 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2867 \subsubsection{Fortuna} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2868 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2869 Fortuna is a fast attack tolerant and more thoroughly designed PRNG suitable for long term |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2870 usage. It is faster than the default implementation of Yarrow\footnote{Yarrow has been implemented |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2871 to work with most cipher and hash combos based on which you have chosen to build into the library.} while |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2872 providing more security. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2873 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2874 Fortuna is slightly less flexible than Yarrow in the sense that it only works with the AES block cipher |
| 380 | 2875 and SHA--256 hash function. Technically, Fortuna will work with any block cipher that accepts a 256--bit |
| 2876 key, and any hash that produces at least a 256--bit output. However, to make the implementation simpler | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2877 it has been fixed to those choices. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2878 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2879 Fortuna is more secure than Yarrow in the sense that attackers who learn parts of the entropy being |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2880 added to the PRNG learn far less about the state than that of Yarrow. Without getting into to many |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2881 details Fortuna has the ability to recover from state determination attacks where the attacker starts |
| 380 | 2882 to learn information from the PRNGs output about the internal state. Yarrow on the other hand, cannot |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2883 recover from that problem until new entropy is added to the pool and put to use through the ready() function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2884 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2885 \subsubsection{RC4} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2886 |
| 380 | 2887 RC4 is an old stream cipher that can also double duty as a PRNG in a pinch. You key RC4 by |
| 2888 calling add\_entropy(), and setup the key by calling ready(). You can only add up to 256 bytes via | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2889 add\_entropy(). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2890 |
| 380 | 2891 When you read from RC4, the output is XOR'ed against your buffer you provide. In this manner, you can use rc4\_read() |
| 2892 as an encrypt (and decrypt) function. | |
| 2893 | |
| 2894 You really should not use RC4. This is not because RC4 is weak, (though biases are known to exist) but simply due to | |
| 2895 the fact that faster alternatives exist. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2896 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2897 \subsubsection{SOBER-128} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2898 |
| 380 | 2899 SOBER--128 is a stream cipher designed by the QUALCOMM Australia team. Like RC4, you key it by |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2900 calling add\_entropy(). There is no need to call ready() for this PRNG as it does not do anything. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2901 |
| 380 | 2902 Note: this cipher has several oddities about how it operates. The first call to add\_entropy() sets the cipher's key. |
| 2903 Every other time call to the add\_entropy() function sets the cipher's IV variable. The IV mechanism allows you to | |
| 2904 encrypt several messages with the same key, and not re--use the same key material. | |
| 2905 | |
| 2906 Unlike Yarrow and Fortuna, all of the entropy (and hence security) of this algorithm rests in the data | |
| 2907 you pass it on the \textbf{first} call to add\_entropy(). All buffers sent to add\_entropy() must have a length | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2908 that is a multiple of four bytes. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2909 |
| 380 | 2910 Like RC4, the output of SOBER--128 is XOR'ed against the buffer you provide it. In this manner, you can use |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2911 sober128\_read() as an encrypt (and decrypt) function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2912 |
| 380 | 2913 Since SOBER-128 has a fixed keying scheme, and is very fast (faster than RC4) the ideal usage of SOBER-128 is to |
| 2914 key it from the output of Fortuna (or Yarrow), and use it to encrypt messages. It is also ideal for | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2915 simulations which need a high quality (and fast) stream of bytes. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2916 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2917 \subsubsection{Example Usage} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2918 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2919 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2920 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2921 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2922 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2923 prng_state prng; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2924 unsigned char buf[32]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2925 int err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2926 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2927 if ((err = rc4_start(&prng)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2928 printf("RC4 init error: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2929 exit(-1); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2930 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2931 |
| 380 | 2932 /* use "key" as the key */ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2933 if ((err = rc4_add_entropy("key", 3, &prng)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2934 printf("RC4 add entropy error: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2935 exit(-1); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2936 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2937 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2938 /* setup RC4 for use */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2939 if ((err = rc4_ready(&prng)) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2940 printf("RC4 ready error: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2941 exit(-1); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2942 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2943 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2944 /* encrypt buffer */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2945 strcpy(buf,"hello world"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2946 if (rc4_read(buf, 11, &prng) != 11) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2947 printf("RC4 read error\n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2948 exit(-1); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2949 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2950 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2951 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2952 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2953 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2954 To decrypt you have to do the exact same steps. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2955 |
| 380 | 2956 \mysection{The Secure RNG} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2957 \index{Secure RNG} |
| 380 | 2958 An RNG is related to a PRNG in many ways, except that it does not expand a smaller seed to get the data. They generate their random bits |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2959 by performing some computation on fresh input bits. Possibly the hardest thing to get correctly in a cryptosystem is the |
| 380 | 2960 PRNG. Computers are deterministic that try hard not to stray from pre--determined paths. This makes gathering entropy needed to seed a PRNG |
| 2961 a hard task. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2962 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2963 There is one small function that may help on certain platforms: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2964 \index{rng\_get\_bytes()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2965 \begin{verbatim} |
| 380 | 2966 unsigned long rng_get_bytes( |
| 2967 unsigned char *buf, | |
| 2968 unsigned long len, | |
| 2969 void (*callback)(void)); | |
| 2970 \end{verbatim} | |
| 2971 | |
| 2972 Which will try one of three methods of getting random data. The first is to open the popular \textit{/dev/random} device which | |
| 2973 on most *NIX platforms provides cryptographic random bits\footnote{This device is available in Windows through the Cygwin compiler suite. It emulates \textit{/dev/random} via the Microsoft CSP.}. | |
| 2974 The second method is to try the Microsoft Cryptographic Service Provider, and read the RNG. The third method is an ANSI C | |
| 2975 clock drift method that is also somewhat popular but gives bits of lower entropy. The \textit{callback} parameter is a pointer to a function that returns void. It is | |
| 2976 used when the slower ANSI C RNG must be used so the calling application can still work. This is useful since the ANSI C RNG has a throughput of roughly three | |
| 2977 bytes a second. The callback pointer may be set to {\bf NULL} to avoid using it if you do not want to. The function returns the number of bytes actually read from | |
| 2978 any RNG source. There is a function to help setup a PRNG as well: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2979 \index{rng\_make\_prng()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2980 \begin{verbatim} |
| 380 | 2981 int rng_make_prng( int bits, |
| 2982 int wprng, | |
| 2983 prng_state *prng, | |
| 2984 void (*callback)(void)); | |
| 2985 \end{verbatim} | |
| 2986 This will try to initialize the prng with a state of at least \textit{bits} of entropy. The \textit{callback} parameter works much like | |
| 2987 the callback in \textit{rng\_get\_bytes()}. It is highly recommended that you use this function to setup your PRNGs unless you have a | |
| 2988 platform where the RNG does not work well. Example usage of this function is given below: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2989 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2990 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2991 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2992 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2993 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2994 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2995 ecc_key mykey; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2996 prng_state prng; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2997 int err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2998 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
2999 /* register yarrow */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3000 if (register_prng(&yarrow_desc) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3001 printf("Error registering Yarrow\n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3002 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3003 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3004 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3005 /* setup the PRNG */ |
| 380 | 3006 if ((err = rng_make_prng(128, find_prng("yarrow"), &prng, NULL)) |
| 3007 != CRYPT_OK) { | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3008 printf("Error setting up PRNG, %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3009 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3010 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3011 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3012 /* make a 192-bit ECC key */ |
| 380 | 3013 if ((err = ecc_make_key(&prng, find_prng("yarrow"), 24, &mykey)) |
| 3014 != CRYPT_OK) { | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3015 printf("Error making key: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3016 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3017 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3018 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3019 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3020 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3021 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3022 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3023 \subsection{The Secure PRNG Interface} |
| 380 | 3024 It is possible to access the secure RNG through the PRNG interface, and in turn use it within dependent functions such |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3025 as the PK API. This simplifies the cryptosystem on platforms where the secure RNG is fast. The secure PRNG never |
| 380 | 3026 requires to be started, that is you need not call the start, add\_entropy, or ready functions. For example, consider |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3027 the previous example using this PRNG. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3028 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3029 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3030 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3031 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3032 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3033 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3034 ecc_key mykey; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3035 int err; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3036 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3037 /* register SPRNG */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3038 if (register_prng(&sprng_desc) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3039 printf("Error registering SPRNG\n"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3040 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3041 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3042 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3043 /* make a 192-bit ECC key */ |
| 380 | 3044 if ((err = ecc_make_key(NULL, find_prng("sprng"), 24, &mykey)) |
| 3045 != CRYPT_OK) { | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3046 printf("Error making key: %s\n", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3047 return -1; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3048 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3049 return 0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3050 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3051 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3052 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3053 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3054 \chapter{RSA Public Key Cryptography} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3055 |
| 380 | 3056 \mysection{Introduction} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3057 RSA wrote the PKCS \#1 specifications which detail RSA Public Key Cryptography. In the specifications are |
| 380 | 3058 padding algorithms for encryption and signatures. The standard includes the \textit{v1.5} and \textit{v2.1} algorithms. |
| 3059 To simplify matters a little the v2.1 encryption and signature padding algorithms are called OAEP and PSS respectively. | |
| 3060 | |
| 3061 \mysection{PKCS \#1 Padding} | |
| 3062 PKCS \#1 v1.5 padding is so simple that both signature and encryption padding are performed by the same function. Note: the | |
| 3063 signature padding does \textbf{not} include the ASN.1 padding required. That is performed by the rsa\_sign\_hash\_ex() function | |
| 3064 documented later on in this chapter. | |
| 3065 | |
| 3066 \subsection{PKCS \#1 v1.5 Encoding} | |
| 3067 The following function performs PKCS \#1 v1.5 padding: | |
| 3068 \index{pkcs\_1\_v1\_5\_encode()} | |
| 3069 \begin{verbatim} | |
| 3070 int pkcs_1_v1_5_encode( | |
| 3071 const unsigned char *msg, | |
| 3072 unsigned long msglen, | |
| 3073 int block_type, | |
| 3074 unsigned long modulus_bitlen, | |
| 3075 prng_state *prng, | |
| 3076 int prng_idx, | |
| 3077 unsigned char *out, | |
| 3078 unsigned long *outlen); | |
| 3079 \end{verbatim} | |
| 3080 | |
| 3081 This will encode the message pointed to by \textit{msg} of length \textit{msglen} octets. The \textit{block\_type} parameter must be set to | |
| 3082 \textbf{LTC\_PKCS\_1\_EME} to perform encryption padding. It must be set to \textbf{LTC\_PKCS\_1\_EMSA} to perform signature padding. The \textit{modulus\_bitlen} | |
| 3083 parameter indicates the length of the modulus in bits. The padded data is stored in \textit{out} with a length of \textit{outlen} octets. The output will not be | |
| 3084 longer than the modulus which helps allocate the correct output buffer size. | |
| 3085 | |
| 3086 Only encryption padding requires a PRNG. When performing signature padding the \textit{prng\_idx} parameter may be left to zero as it is not checked for validity. | |
| 3087 | |
| 3088 \subsection{PKCS \#1 v1.5 Decoding} | |
| 3089 The following function performs PKCS \#1 v1.5 de--padding: | |
| 3090 \index{pkcs\_1\_v1\_5\_decode()} | |
| 3091 \begin{verbatim} | |
| 3092 int pkcs_1_v1_5_decode( | |
| 3093 const unsigned char *msg, | |
| 3094 unsigned long msglen, | |
| 3095 int block_type, | |
| 3096 unsigned long modulus_bitlen, | |
| 3097 unsigned char *out, | |
| 3098 unsigned long *outlen, | |
| 3099 int *is_valid); | |
| 3100 \end{verbatim} | |
| 3101 \index{LTC\_PKCS\_1\_EME} \index{LTC\_PKCS\_1\_EMSA} | |
| 3102 This will remove the PKCS padding data pointed to by \textit{msg} of length \textit{msglen}. The decoded data is stored in \textit{out} of length | |
| 3103 \textit{outlen}. If the padding is valid, a 1 is stored in \textit{is\_valid}, otherwise, a 0 is stored. The \textit{block\_type} parameter must be set to either | |
| 3104 \textbf{LTC\_PKCS\_1\_EME} or \textbf{LTC\_PKCS\_1\_EMSA} depending on whether encryption or signature padding is being removed. | |
| 3105 | |
| 3106 \mysection{PKCS \#1 v2.1 Encryption} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3107 PKCS \#1 RSA Encryption amounts to OAEP padding of the input message followed by the modular exponentiation. As far as this portion of |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3108 the library is concerned we are only dealing with th OAEP padding of the message. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3109 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3110 \subsection{OAEP Encoding} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3111 |
| 380 | 3112 The following function performs PKCS \#1 v2.1 encryption padding: |
| 3113 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3114 \index{pkcs\_1\_oaep\_encode()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3115 \begin{alltt} |
| 380 | 3116 int pkcs_1_oaep_encode( |
| 3117 const unsigned char *msg, | |
| 3118 unsigned long msglen, | |
| 3119 const unsigned char *lparam, | |
| 3120 unsigned long lparamlen, | |
| 3121 unsigned long modulus_bitlen, | |
| 3122 prng_state *prng, | |
| 3123 int prng_idx, | |
| 3124 int hash_idx, | |
| 3125 unsigned char *out, | |
| 3126 unsigned long *outlen); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3127 \end{alltt} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3128 |
| 380 | 3129 This accepts \textit{msg} as input of length \textit{msglen} which will be OAEP padded. The \textit{lparam} variable is an additional system specific |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3130 tag that can be applied to the encoding. This is useful to identify which system encoded the message. If no variance is desired then |
| 380 | 3131 \textit{lparam} can be set to \textbf{NULL}. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3132 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3133 OAEP encoding requires the length of the modulus in bits in order to calculate the size of the output. This is passed as the parameter |
| 380 | 3134 \textit{modulus\_bitlen}. \textit{hash\_idx} is the index into the hash descriptor table of the hash desired. PKCS \#1 allows any hash to be |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3135 used but both the encoder and decoder must use the same hash in order for this to succeed. The size of hash output affects the maximum |
| 380 | 3136 sized input message. \textit{prng\_idx} and \textit{prng} are the random number generator arguments required to randomize the padding process. |
| 3137 The padded message is stored in \textit{out} along with the length in \textit{outlen}. | |
| 3138 | |
| 3139 If $h$ is the length of the hash and $m$ the length of the modulus (both in octets) then the maximum payload for \textit{msg} is | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3140 $m - 2h - 2$. For example, with a $1024$--bit RSA key and SHA--1 as the hash the maximum payload is $86$ bytes. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3141 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3142 Note that when the message is padded it still has not been RSA encrypted. You must pass the output of this function to |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3143 rsa\_exptmod() to encrypt it. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3144 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3145 \subsection{OAEP Decoding} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3146 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3147 \index{pkcs\_1\_oaep\_decode()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3148 \begin{alltt} |
| 380 | 3149 int pkcs_1_oaep_decode( |
| 3150 const unsigned char *msg, | |
| 3151 unsigned long msglen, | |
| 3152 const unsigned char *lparam, | |
| 3153 unsigned long lparamlen, | |
| 3154 unsigned long modulus_bitlen, | |
| 3155 int hash_idx, | |
| 3156 unsigned char *out, | |
| 3157 unsigned long *outlen, | |
| 3158 int *res); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3159 \end{alltt} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3160 |
| 380 | 3161 This function decodes an OAEP encoded message and outputs the original message that was passed to the OAEP encoder. \textit{msg} is the |
| 3162 output of pkcs\_1\_oaep\_encode() of length \textit{msglen}. \textit{lparam} is the same system variable passed to the OAEP encoder. If it does not | |
| 3163 match what was used during encoding this function will not decode the packet. \textit{modulus\_bitlen} is the size of the RSA modulus in bits | |
| 3164 and must match what was used during encoding. Similarly the \textit{hash\_idx} index into the hash descriptor table must match what was used | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3165 during encoding. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3166 |
| 380 | 3167 If the function succeeds it decodes the OAEP encoded message into \textit{out} of length \textit{outlen} and stores a |
| 3168 $1$ in \textit{res}. If the packet is invalid it stores $0$ in \textit{res} and if the function fails for another reason | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3169 it returns an error code. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3170 |
| 380 | 3171 \mysection{PKCS \#1 Digital Signatures} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3172 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3173 \subsection{PSS Encoding} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3174 PSS encoding is the second half of the PKCS \#1 standard which is padding to be applied to messages that are signed. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3175 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3176 \index{pkcs\_1\_pss\_encode()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3177 \begin{alltt} |
| 380 | 3178 int pkcs_1_pss_encode( |
| 3179 const unsigned char *msghash, | |
| 3180 unsigned long msghashlen, | |
| 3181 unsigned long saltlen, | |
| 3182 prng_state *prng, | |
| 3183 int prng_idx, | |
| 3184 int hash_idx, | |
| 3185 unsigned long modulus_bitlen, | |
| 3186 unsigned char *out, | |
| 3187 unsigned long *outlen); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3188 \end{alltt} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3189 |
| 380 | 3190 This function assumes the message to be PSS encoded has previously been hashed. The input hash \textit{msghash} is of length |
| 3191 \textit{msghashlen}. PSS allows a variable length random salt (it can be zero length) to be introduced in the signature process. | |
| 3192 \textit{hash\_idx} is the index into the hash descriptor table of the hash to use. \textit{prng\_idx} and \textit{prng} are the random | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3193 number generator information required for the salt. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3194 |
| 380 | 3195 Similar to OAEP encoding \textit{modulus\_bitlen} is the size of the RSA modulus (in bits). It limits the size of the salt. If $m$ is the length |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3196 of the modulus $h$ the length of the hash output (in octets) then there can be $m - h - 2$ bytes of salt. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3197 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3198 This function does not actually sign the data it merely pads the hash of a message so that it can be processed by rsa\_exptmod(). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3199 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3200 \subsection{PSS Decoding} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3201 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3202 To decode a PSS encoded signature block you have to use the following. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3203 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3204 \index{pkcs\_1\_pss\_decode()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3205 \begin{alltt} |
| 380 | 3206 int pkcs_1_pss_decode( |
| 3207 const unsigned char *msghash, | |
| 3208 unsigned long msghashlen, | |
| 3209 const unsigned char *sig, | |
| 3210 unsigned long siglen, | |
| 3211 unsigned long saltlen, | |
| 3212 int hash_idx, | |
| 3213 unsigned long modulus_bitlen, | |
| 3214 int *res); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3215 \end{alltt} |
| 380 | 3216 This will decode the PSS encoded message in \textit{sig} of length \textit{siglen} and compare it to values in \textit{msghash} of length |
| 3217 \textit{msghashlen}. If the block is a valid PSS block and the decoded hash equals the hash supplied \textit{res} is set to non--zero. Otherwise, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3218 it is set to zero. The rest of the parameters are as in the PSS encode call. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3219 |
| 380 | 3220 It's important to use the same \textit{saltlen} and hash for both encoding and decoding as otherwise the procedure will not work. |
| 3221 | |
| 3222 \mysection{RSA Key Operations} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3223 \subsection{Background} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3224 |
| 380 | 3225 RSA is a public key algorithm that is based on the inability to find the \textit{e-th} root modulo a composite of unknown |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3226 factorization. Normally the difficulty of breaking RSA is associated with the integer factoring problem but they are |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3227 not strictly equivalent. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3228 |
| 380 | 3229 The system begins with with two primes $p$ and $q$ and their product $N = pq$. The order or \textit{Euler totient} of the |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3230 multiplicative sub-group formed modulo $N$ is given as $\phi(N) = (p - 1)(q - 1)$ which can be reduced to |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3231 $\mbox{lcm}(p - 1, q - 1)$. The public key consists of the composite $N$ and some integer $e$ such that |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3232 $\mbox{gcd}(e, \phi(N)) = 1$. The private key consists of the composite $N$ and the inverse of $e$ modulo $\phi(N)$ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3233 often simply denoted as $de \equiv 1\mbox{ }(\mbox{mod }\phi(N))$. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3234 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3235 A person who wants to encrypt with your public key simply forms an integer (the plaintext) $M$ such that |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3236 $1 < M < N-2$ and computes the ciphertext $C = M^e\mbox{ }(\mbox{mod }N)$. Since finding the inverse exponent $d$ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3237 given only $N$ and $e$ appears to be intractable only the owner of the private key can decrypt the ciphertext and compute |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3238 $C^d \equiv \left (M^e \right)^d \equiv M^1 \equiv M\mbox{ }(\mbox{mod }N)$. Similarly the owner of the private key |
| 380 | 3239 can sign a message by \textit{decrypting} it. Others can verify it by \textit{encrypting} it. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3240 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3241 Currently RSA is a difficult system to cryptanalyze provided that both primes are large and not close to each other. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3242 Ideally $e$ should be larger than $100$ to prevent direct analysis. For example, if $e$ is three and you do not pad |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3243 the plaintext to be encrypted than it is possible that $M^3 < N$ in which case finding the cube-root would be trivial. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3244 The most often suggested value for $e$ is $65537$ since it is large enough to make such attacks impossible and also well |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3245 designed for fast exponentiation (requires 16 squarings and one multiplication). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3246 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3247 It is important to pad the input to RSA since it has particular mathematical structure. For instance |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3248 $M_1^dM_2^d = (M_1M_2)^d$ which can be used to forge a signature. Suppose $M_3 = M_1M_2$ is a message you want |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3249 to have a forged signature for. Simply get the signatures for $M_1$ and $M_2$ on their own and multiply the result |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3250 together. Similar tricks can be used to deduce plaintexts from ciphertexts. It is important not only to sign |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3251 the hash of documents only but also to pad the inputs with data to remove such structure. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3252 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3253 \subsection{RSA Key Generation} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3254 |
| 380 | 3255 For RSA routines a single \textit{rsa\_key} structure is used. To make a new RSA key call: |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3256 \index{rsa\_make\_key()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3257 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3258 int rsa_make_key(prng_state *prng, |
| 380 | 3259 int wprng, |
| 3260 int size, | |
| 3261 long e, | |
| 3262 rsa_key *key); | |
| 3263 \end{verbatim} | |
| 3264 | |
| 3265 Where \textit{wprng} is the index into the PRNG descriptor array. The \textit{size} parameter is the size in bytes of the RSA modulus desired. | |
| 3266 The \textit{e} parameter is the encryption exponent desired, typical values are 3, 17, 257 and 65537. Stick with 65537 since it is big enough to prevent | |
| 3267 trivial math attacks, and not super slow. The \textit{key} parameter is where the constructed key is placed. All keys must be at | |
| 3268 least 128 bytes, and no more than 512 bytes in size (\textit{that is from 1024 to 4096 bits}). | |
| 3269 | |
| 3270 \index{rsa\_free()} | |
| 3271 Note: the \textit{rsa\_make\_key()} function allocates memory at run--time when you make the key. Make sure to call | |
| 3272 \textit{rsa\_free()} (see below) when you are finished with the key. If \textit{rsa\_make\_key()} fails it will automatically | |
| 3273 free the memory allocated. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3274 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3275 \index{PK\_PRIVATE} \index{PK\_PUBLIC} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3276 There are two types of RSA keys. The types are {\bf PK\_PRIVATE} and {\bf PK\_PUBLIC}. The first type is a private |
| 380 | 3277 RSA key which includes the CRT parameters\footnote{As of v0.99 the PK\_PRIVATE\_OPTIMIZED type has been deprecated, and has been replaced by the |
| 3278 PK\_PRIVATE type.} in the form of a RSAPrivateKey (PKCS \#1 compliant). The second type, is a public RSA key which only includes the modulus and public exponent. | |
| 3279 It takes the form of a RSAPublicKey (PKCS \#1 compliant). | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3280 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3281 \subsection{RSA Exponentiation} |
| 380 | 3282 To do raw work with the RSA function, that is without padding, use the following function: |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3283 \index{rsa\_exptmod()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3284 \begin{verbatim} |
| 380 | 3285 int rsa_exptmod(const unsigned char *in, |
| 3286 unsigned long inlen, | |
| 3287 unsigned char *out, | |
| 3288 unsigned long *outlen, | |
| 3289 int which, | |
| 3290 rsa_key *key); | |
| 3291 \end{verbatim} | |
| 3292 This will load the bignum from \textit{in} as a big endian integer in the format PKCS \#1 specifies, raises it to either \textit{e} or \textit{d} and stores the result | |
| 3293 in \textit{out} and the size of the result in \textit{outlen}. \textit{which} is set to {\bf PK\_PUBLIC} to use \textit{e} | |
| 3294 (i.e. for encryption/verifying) and set to {\bf PK\_PRIVATE} to use \textit{d} as the exponent (i.e. for decrypting/signing). | |
| 3295 | |
| 3296 Note: the output of this function is zero--padded as per PKCS \#1 specification. This allows this routine to work with PKCS \#1 padding functions properly. | |
| 3297 | |
| 3298 \mysection{RSA Key Encryption} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3299 Normally RSA is used to encrypt short symmetric keys which are then used in block ciphers to encrypt a message. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3300 To facilitate encrypting short keys the following functions have been provided. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3301 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3302 \index{rsa\_encrypt\_key()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3303 \begin{verbatim} |
| 380 | 3304 int rsa_encrypt_key( |
| 3305 const unsigned char *in, | |
| 3306 unsigned long inlen, | |
| 3307 unsigned char *out, | |
| 3308 unsigned long *outlen, | |
| 3309 const unsigned char *lparam, | |
| 3310 unsigned long lparamlen, | |
| 3311 prng_state *prng, | |
| 3312 int prng_idx, | |
| 3313 int hash_idx, | |
| 3314 rsa_key *key); | |
| 3315 \end{verbatim} | |
| 3316 This function will OAEP pad \textit{in} of length \textit{inlen} bytes, RSA encrypt it, and store the ciphertext | |
| 3317 in \textit{out} of length \textit{outlen} octets. The \textit{lparam} and \textit{lparamlen} are the same parameters you would pass | |
| 3318 to \index{pkcs\_1\_oaep\_encode()} pkcs\_1\_oaep\_encode(). | |
| 3319 | |
| 3320 \subsection{Extended Encryption} | |
| 3321 As of v1.15, the library supports both v1.5 and v2.1 PKCS \#1 style paddings in these higher level functions. The following is the extended | |
| 3322 encryption function: | |
| 3323 | |
| 3324 \index{rsa\_encrypt\_key\_ex()} | |
| 3325 \begin{verbatim} | |
| 3326 int rsa_encrypt_key_ex( | |
| 3327 const unsigned char *in, | |
| 3328 unsigned long inlen, | |
| 3329 unsigned char *out, | |
| 3330 unsigned long *outlen, | |
| 3331 const unsigned char *lparam, | |
| 3332 unsigned long lparamlen, | |
| 3333 prng_state *prng, | |
| 3334 int prng_idx, | |
| 3335 int hash_idx, | |
| 3336 int padding, | |
| 3337 rsa_key *key); | |
| 3338 \end{verbatim} | |
| 3339 | |
| 3340 \index{LTC\_PKCS\_1\_OAEP} \index{LTC\_PKCS\_1\_V1\_5} | |
| 3341 The parameters are all the same as for rsa\_encrypt\_key() except for the addition of the \textit{padding} parameter. It must be set to | |
| 3342 \textbf{LTC\_PKCS\_1\_V1\_5} to perform v1.5 encryption, or set to \textbf{LTC\_PKCS\_1\_OAEP} to perform v2.1 encryption. | |
| 3343 | |
| 3344 When performing v1.5 encryption, the hash and lparam parameters are totally ignored and can be set to \textbf{NULL} or zero (respectively). | |
| 3345 | |
| 3346 \mysection{RSA Key Decryption} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3347 \index{rsa\_decrypt\_key()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3348 \begin{verbatim} |
| 380 | 3349 int rsa_decrypt_key( |
| 3350 const unsigned char *in, | |
| 3351 unsigned long inlen, | |
| 3352 unsigned char *out, | |
| 3353 unsigned long *outlen, | |
| 3354 const unsigned char *lparam, | |
| 3355 unsigned long lparamlen, | |
| 3356 int hash_idx, | |
| 3357 int *stat, | |
| 3358 rsa_key *key); | |
| 3359 \end{verbatim} | |
| 3360 This function will RSA decrypt \textit{in} of length \textit{inlen} then OAEP de-pad the resulting data and store it in | |
| 3361 \textit{out} of length \textit{outlen}. The \textit{lparam} and \textit{lparamlen} are the same parameters you would pass | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3362 to pkcs\_1\_oaep\_decode(). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3363 |
| 380 | 3364 If the RSA decrypted data is not a valid OAEP packet then \textit{stat} is set to $0$. Otherwise, it is set to $1$. |
| 3365 | |
| 3366 \subsection{Extended Decryption} | |
| 3367 As of v1.15, the library supports both v1.5 and v2.1 PKCS \#1 style paddings in these higher level functions. The following is the extended | |
| 3368 decryption function: | |
| 3369 | |
| 3370 \index{rsa\_decrypt\_key\_ex()} | |
| 3371 \begin{verbatim} | |
| 3372 int rsa_decrypt_key_ex( | |
| 3373 const unsigned char *in, | |
| 3374 unsigned long inlen, | |
| 3375 unsigned char *out, | |
| 3376 unsigned long *outlen, | |
| 3377 const unsigned char *lparam, | |
| 3378 unsigned long lparamlen, | |
| 3379 int hash_idx, | |
| 3380 int padding, | |
| 3381 int *stat, | |
| 3382 rsa_key *key); | |
| 3383 \end{verbatim} | |
| 3384 | |
| 3385 Similar to the extended encryption, the new parameter \textit{padding} indicates which version of the PKCS \#1 standard to use. | |
| 3386 It must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to perform v1.5 decryption, or set to \textbf{LTC\_PKCS\_1\_OAEP} to perform v2.1 decryption. | |
| 3387 | |
| 3388 When performing v1.5 decryption, the hash and lparam parameters are totally ignored and can be set to \textbf{NULL} or zero (respectively). | |
| 3389 | |
| 3390 | |
| 3391 \mysection{RSA Signature Generation} | |
| 3392 Similar to RSA key encryption RSA is also used to \textit{digitally sign} message digests (hashes). To facilitate this | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3393 process the following functions have been provided. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3394 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3395 \index{rsa\_sign\_hash()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3396 \begin{verbatim} |
| 380 | 3397 int rsa_sign_hash(const unsigned char *in, |
| 3398 unsigned long inlen, | |
| 3399 unsigned char *out, | |
| 3400 unsigned long *outlen, | |
| 3401 prng_state *prng, | |
| 3402 int prng_idx, | |
| 3403 int hash_idx, | |
| 3404 unsigned long saltlen, | |
| 3405 rsa_key *key); | |
| 3406 \end{verbatim} | |
| 3407 | |
| 3408 This will PSS encode the message digest pointed to by \textit{in} of length \textit{inlen} octets. Next, the PSS encoded hash will be RSA | |
| 3409 \textit{signed} and the output stored in the buffer pointed to by \textit{out} of length \textit{outlen} octets. | |
| 3410 | |
| 3411 The \textit{hash\_idx} parameter indicates which hash will be used to create the PSS encoding. It should be the same as the hash used to | |
| 3412 hash the message being signed. The \textit{saltlen} parameter indicates the length of the desired salt, and should typically be small. A good | |
| 3413 default value is between 8 and 16 octets. Strictly, it must be small than $modulus\_len - hLen - 2$ where \textit{modulus\_len} is the size of | |
| 3414 the RSA modulus (in octets), and \textit{hLen} is the length of the message digest produced by the chosen hash. | |
| 3415 | |
| 3416 \subsection{Extended Signatures} | |
| 3417 | |
| 3418 As of v1.15, the library supports both v1.5 and v2.1 signatures. The extended signature generation function has the following prototype: | |
| 3419 | |
| 3420 \index{rsa\_sign\_hash\_ex()} | |
| 3421 \begin{verbatim} | |
| 3422 int rsa_sign_hash_ex( | |
| 3423 const unsigned char *in, | |
| 3424 unsigned long inlen, | |
| 3425 unsigned char *out, | |
| 3426 unsigned long *outlen, | |
| 3427 int padding, | |
| 3428 prng_state *prng, | |
| 3429 int prng_idx, | |
| 3430 int hash_idx, | |
| 3431 unsigned long saltlen, | |
| 3432 rsa_key *key); | |
| 3433 \end{verbatim} | |
| 3434 | |
| 3435 This will PKCS encode the message digest pointed to by \textit{in} of length \textit{inlen} octets. Next, the PKCS encoded hash will be RSA | |
| 3436 \textit{signed} and the output stored in the buffer pointed to by \textit{out} of length \textit{outlen} octets. The \textit{padding} parameter | |
| 3437 must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to produce a v1.5 signature, otherwise, it must be set to \textbf{LTC\_PKCS\_1\_PSS} to produce a | |
| 3438 v2.1 signature. | |
| 3439 | |
| 3440 When performing a v1.5 signature the \textit{prng}, \textit{prng\_idx}, and \textit{hash\_idx} parameters are not checked and can be left to any | |
| 3441 values such as $\lbrace$\textbf{NULL}, 0, 0$\rbrace$. | |
| 3442 | |
| 3443 \mysection{RSA Signature Verification} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3444 \index{rsa\_verify\_hash()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3445 \begin{verbatim} |
| 380 | 3446 int rsa_verify_hash(const unsigned char *sig, |
| 3447 unsigned long siglen, | |
| 3448 const unsigned char *msghash, | |
| 3449 unsigned long msghashlen, | |
| 3450 int hash_idx, | |
| 3451 unsigned long saltlen, | |
| 3452 int *stat, | |
| 3453 rsa_key *key); | |
| 3454 \end{verbatim} | |
| 3455 | |
| 3456 This will RSA \textit{verify} the signature pointed to by \textit{sig} of length \textit{siglen} octets. Next, the RSA decoded data is PSS decoded | |
| 3457 and the extracted hash is compared against the message digest pointed to by \textit{msghash} of length \textit{msghashlen} octets. | |
| 3458 | |
| 3459 If the RSA decoded data is not a valid PSS message, or if the PSS decoded hash does not match the \textit{msghash} | |
| 3460 value, \textit{res} is set to $0$. Otherwise, if the function succeeds, and signature is valid \textit{res} is set to $1$. | |
| 3461 | |
| 3462 \subsection{Extended Verification} | |
| 3463 | |
| 3464 As of v1.15, the library supports both v1.5 and v2.1 signature verification. The extended signature verification function has the following prototype: | |
| 3465 | |
| 3466 \index{rsa\_verify\_hash\_ex()} | |
| 3467 \begin{verbatim} | |
| 3468 int rsa_verify_hash_ex( | |
| 3469 const unsigned char *sig, | |
| 3470 unsigned long siglen, | |
| 3471 const unsigned char *hash, | |
| 3472 unsigned long hashlen, | |
| 3473 int padding, | |
| 3474 int hash_idx, | |
| 3475 unsigned long saltlen, | |
| 3476 int *stat, | |
| 3477 rsa_key *key); | |
| 3478 \end{verbatim} | |
| 3479 | |
| 3480 This will RSA \textit{verify} the signature pointed to by \textit{sig} of length \textit{siglen} octets. Next, the RSA decoded data is PKCS decoded | |
| 3481 and the extracted hash is compared against the message digest pointed to by \textit{msghash} of length \textit{msghashlen} octets. | |
| 3482 | |
| 3483 If the RSA decoded data is not a valid PSS message, or if the PKCS decoded hash does not match the \textit{msghash} | |
| 3484 value, \textit{res} is set to $0$. Otherwise, if the function succeeds, and signature is valid \textit{res} is set to $1$. | |
| 3485 | |
| 3486 The \textit{padding} parameter must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to perform a v1.5 verification. Otherwise, it must be set to | |
| 3487 \textbf{LTC\_PKCS\_1\_PSS} to perform a v2.1 verification. When performing a v1.5 verification the \textit{hash\_idx} parameter is ignored. | |
| 3488 | |
| 3489 \mysection{RSA Encryption Example} | |
| 3490 \begin{small} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3491 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3492 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3493 int main(void) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3494 { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3495 int err, hash_idx, prng_idx, res; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3496 unsigned long l1, l2; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3497 unsigned char pt[16], pt2[16], out[1024]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3498 rsa_key key; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3499 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3500 /* register prng/hash */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3501 if (register_prng(&sprng_desc) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3502 printf("Error registering sprng"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3503 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3504 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3505 |
| 380 | 3506 /* register a math library (in this case TomsFastMath) |
| 3507 ltc_mp = tfm_desc; | |
| 3508 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3509 if (register_hash(&sha1_desc) == -1) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3510 printf("Error registering sha1"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3511 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3512 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3513 hash_idx = find_hash("sha1"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3514 prng_idx = find_prng("sprng"); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3515 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3516 /* make an RSA-1024 key */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3517 if ((err = rsa_make_key(NULL, /* PRNG state */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3518 prng_idx, /* PRNG idx */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3519 1024/8, /* 1024-bit key */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3520 65537, /* we like e=65537 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3521 &key) /* where to store the key */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3522 ) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3523 printf("rsa_make_key %s", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3524 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3525 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3526 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3527 /* fill in pt[] with a key we want to send ... */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3528 l1 = sizeof(out); |
| 380 | 3529 if ((err = rsa_encrypt_key(pt, /* data we wish to encrypt */ |
| 3530 16, /* data is 16 bytes long */ | |
| 3531 out, /* where to store ciphertext */ | |
| 3532 &l1, /* length of ciphertext */ | |
| 3533 "TestApp", /* our lparam for this program */ | |
| 3534 7, /* lparam is 7 bytes long */ | |
| 3535 NULL, /* PRNG state */ | |
| 3536 prng_idx, /* prng idx */ | |
| 3537 hash_idx, /* hash idx */ | |
| 3538 &key) /* our RSA key */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3539 ) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3540 printf("rsa_encrypt_key %s", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3541 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3542 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3543 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3544 /* now let's decrypt the encrypted key */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3545 l2 = sizeof(pt2); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3546 if ((err = rsa_decrypt_key(out, /* encrypted data */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3547 l1, /* length of ciphertext */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3548 pt2, /* where to put plaintext */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3549 &l2, /* plaintext length */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3550 "TestApp", /* lparam for this program */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3551 7, /* lparam is 7 bytes long */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3552 hash_idx, /* hash idx */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3553 &res, /* validity of data */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3554 &key) /* our RSA key */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3555 ) != CRYPT_OK) { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3556 printf("rsa_decrypt_key %s", error_to_string(err)); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3557 return EXIT_FAILURE; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3558 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3559 /* if all went well pt == pt2, l2 == 16, res == 1 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3560 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3561 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3562 \end{small} |
| 380 | 3563 |
| 3564 \mysection{RSA Key Format} | |
| 3565 | |
| 3566 The RSA key format adopted for exporting and importing keys is the PKCS \#1 format defined by the ASN.1 constructs known as | |
| 3567 RSAPublicKey and RSAPrivateKey. Additionally, the OpenSSL key format is supported by the import function only. | |
| 3568 | |
| 3569 \subsection{RSA Key Export} | |
| 3570 To export a RSA key use the following function. | |
| 3571 | |
| 3572 \index{rsa\_export()} | |
| 3573 \begin{verbatim} | |
| 3574 int rsa_export(unsigned char *out, | |
| 3575 unsigned long *outlen, | |
| 3576 int type, | |
| 3577 rsa_key *key); | |
| 3578 \end{verbatim} | |
| 3579 This will export the RSA key in either a RSAPublicKey or RSAPrivateKey (PKCS \#1 types) depending on the value of \textit{type}. When it is | |
| 3580 set to \textbf{PK\_PRIVATE} the export format will be RSAPrivateKey and otherwise it will be RSAPublicKey. | |
| 3581 | |
| 3582 \subsection{RSA Key Import} | |
| 3583 To import a RSA key use the following function. | |
| 3584 | |
| 3585 \index{rsa\_import()} | |
| 3586 \begin{verbatim} | |
| 3587 int rsa_import(const unsigned char *in, | |
| 3588 unsigned long inlen, | |
| 3589 rsa_key *key); | |
| 3590 \end{verbatim} | |
| 3591 | |
| 3592 This will import the key stored in \textit{inlen} and import it to \textit{key}. If the function fails it will automatically free any allocated memory. This | |
| 3593 function can import both RSAPublicKey and RSAPrivateKey formats. | |
| 3594 | |
| 3595 As of v1.06 this function can also import OpenSSL DER formatted public RSA keys. They are essentially encapsulated RSAPublicKeys. LibTomCrypt will | |
| 3596 import the key, strip off the additional data (it's the preferred hash) and fill in the rsa\_key structure as if it were a native RSAPublicKey. Note that | |
| 3597 there is no function provided to export in this format. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3598 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3599 \chapter{Elliptic Curve Cryptography} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3600 |
| 380 | 3601 \mysection{Background} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3602 The library provides a set of core ECC functions as well that are designed to be the Elliptic Curve analogy of all of the |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3603 Diffie-Hellman routines in the previous chapter. Elliptic curves (of certain forms) have the benefit that they are harder |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3604 to attack (no sub-exponential attacks exist unlike normal DH crypto) in fact the fastest attack requires the square root |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3605 of the order of the base point in time. That means if you use a base point of order $2^{192}$ (which would represent a |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3606 192-bit key) then the work factor is $2^{96}$ in order to find the secret key. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3607 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3608 The curves in this library are taken from the following website: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3609 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3610 http://csrc.nist.gov/cryptval/dss.htm |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3611 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3612 |
| 380 | 3613 As of v1.15 three new curves from the SECG standards are also included they are the secp112r1, secp128r1, and secp160r1 curves. These curves were added to |
| 3614 support smaller devices which do not need as large keys for security. | |
| 3615 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3616 They are all curves over the integers modulo a prime. The curves have the basic equation that is: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3617 \begin{equation} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3618 y^2 = x^3 - 3x + b\mbox{ }(\mbox{mod }p) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3619 \end{equation} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3620 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3621 The variable $b$ is chosen such that the number of points is nearly maximal. In fact the order of the base points $\beta$ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3622 provided are very close to $p$ that is $\vert \vert \phi(\beta) \vert \vert \approx \vert \vert p \vert \vert$. The curves |
| 380 | 3623 range in order from $\approx 2^{112}$ points to $\approx 2^{521}$. According to the source document any key size greater |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3624 than or equal to 256-bits is sufficient for long term security. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3625 |
| 380 | 3626 \mysection{Fixed Point Optimizations} |
| 3627 \index{Fixed Point ECC} | |
| 3628 \index{MECC\_FP} | |
| 3629 As of v1.12 of LibTomCrypt, support for Fixed Point ECC point multiplication has been added. It is a generic optimization that is | |
| 3630 supported by any conforming math plugin. It is enabled by defining \textbf{MECC\_FP} during the build, such as | |
| 3631 | |
| 3632 \begin{verbatim} | |
| 3633 CFLAGS="-DTFM_DESC -DMECC_FP" make | |
| 3634 \end{verbatim} | |
| 3635 | |
| 3636 which will build LTC using the TFM math library and enabling this new feature. The feature is not enabled by default as it is \textbf{NOT} thread | |
| 3637 safe (by default). It supports the LTC locking macros (such as by enabling LTC\_PTHREAD), but by default is not locked. | |
| 3638 | |
| 3639 \index{FP\_ENTRIES} | |
| 3640 The optimization works by using a Fixed Point multiplier on any base point you use twice or more in a short period of time. It has a limited size | |
| 3641 cache (of FP\_ENTRIES entries) which it uses to hold recent bases passed to ltc\_ecc\_mulmod(). Any base detected to be used twice is sent through the | |
| 3642 pre--computation phase, and then the fixed point algorithm can be used. For example, if you use a NIST base point twice in a row, the 2$^{nd}$ and | |
| 3643 all subsequent point multiplications with that point will use the faster algorithm. | |
| 3644 | |
| 3645 \index{FP\_LUT} | |
| 3646 The optimization uses a window on the multiplicand of FP\_LUT bits (default: 8, min: 2, max: 12), and this controls the memory/time trade-off. The larger the | |
| 3647 value the faster the algorithm will be but the more memory it will take. The memory usage is $3 \cdot 2^{FP\_LUT}$ integers which by default | |
| 3648 with TFM amounts to about 400kB of memory. Tuning TFM (by changing FP\_SIZE) can decrease the usage by a fair amount. Memory is only used by a cache entry | |
| 3649 if it is active. Both FP\_ENTRIES and FP\_LUT are definable on the command line if you wish to override them. For instance, | |
| 3650 | |
| 3651 \begin{verbatim} | |
| 3652 CFLAGS="-DTFM_DESC -DMECC_FP -DFP_ENTRIES=8 -DFP_LUT=6" make | |
| 3653 \end{verbatim} | |
| 3654 | |
| 3655 \begin{flushleft} | |
| 3656 \index{FP\_SIZE} \index{TFM} \index{tfm.h} | |
| 3657 would define a window of 6 bits and limit the cache to 8 entries. Generally, it is better to first tune TFM by adjusting FP\_SIZE (from tfm.h). It defaults | |
| 3658 to 4096 bits (512 bytes) which is way more than what is required by ECC. At most, you need 1152 bits to accommodate ECC--521. If you're only using (say) | |
| 3659 ECC--256 you will only need 576 bits, which would reduce the memory usage by 700\%. | |
| 3660 \end{flushleft} | |
| 3661 | |
| 3662 \mysection{Key Format} | |
| 3663 LibTomCrypt uses a unique format for ECC public and private keys. While ANSI X9.63 partially specifies key formats, it does it in a less than ideally simple manner. \ | |
| 3664 In the case of LibTomCrypt, it is meant \textbf{solely} for NIST and SECG $GF(p)$ curves. The format of the keys is as follows: | |
| 3665 | |
| 3666 \index{ECC Key Format} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3667 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3668 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3669 ECCPublicKey ::= SEQUENCE { |
| 380 | 3670 flags BIT STRING(0), -- public/private flag (always zero), |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3671 keySize INTEGER, -- Curve size (in bits) divided by eight |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3672 -- and rounded down, e.g. 521 => 65 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3673 pubkey.x INTEGER, -- The X co-ordinate of the public key point |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3674 pubkey.y INTEGER, -- The Y co-ordinate of the public key point |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3675 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3676 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3677 ECCPrivateKey ::= SEQUENCE { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3678 flags BIT STRING(1), -- public/private flag (always one), |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3679 keySize INTEGER, -- Curve size (in bits) divided by eight |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3680 -- and rounded down, e.g. 521 => 65 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3681 pubkey.x INTEGER, -- The X co-ordinate of the public key point |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3682 pubkey.y INTEGER, -- The Y co-ordinate of the public key point |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3683 secret.k INTEGER, -- The secret key scalar |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3684 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3685 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3686 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3687 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3688 The first flags bit denotes whether the key is public (zero) or private (one). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3689 |
| 380 | 3690 \vfil |
| 3691 | |
| 3692 \mysection{ECC Curve Parameters} | |
| 3693 The library uses the following structure to describe an elliptic curve. This is used internally, as well as by the new | |
| 3694 extended ECC functions which allow the user to specify their own curves. | |
| 3695 | |
| 3696 \index{ltc\_ecc\_set\_type} | |
| 3697 \begin{verbatim} | |
| 3698 /** Structure defines a NIST GF(p) curve */ | |
| 3699 typedef struct { | |
| 3700 /** The size of the curve in octets */ | |
| 3701 int size; | |
| 3702 | |
| 3703 /** name of curve */ | |
| 3704 char *name; | |
| 3705 | |
| 3706 /** The prime that defines the field (encoded in hex) */ | |
| 3707 char *prime; | |
| 3708 | |
| 3709 /** The fields B param (hex) */ | |
| 3710 char *B; | |
| 3711 | |
| 3712 /** The order of the curve (hex) */ | |
| 3713 char *order; | |
| 3714 | |
| 3715 /** The x co-ordinate of the base point on the curve (hex) */ | |
| 3716 char *Gx; | |
| 3717 | |
| 3718 /** The y co-ordinate of the base point on the curve (hex) */ | |
| 3719 char *Gy; | |
| 3720 } ltc_ecc_set_type; | |
| 3721 \end{verbatim} | |
| 3722 | |
| 3723 The curve must be of the form $y^2 = x^3 - 3x + b$, and all of the integer parameters are encoded in hexadecimal format. | |
| 3724 | |
| 3725 \mysection{Core Functions} | |
| 3726 \subsection{ECC Key Generation} | |
| 3727 There is a key structure called \textit{ecc\_key} used by the ECC functions. There is a function to make a key: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3728 \index{ecc\_make\_key()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3729 \begin{verbatim} |
| 380 | 3730 int ecc_make_key(prng_state *prng, |
| 3731 int wprng, | |
| 3732 int keysize, | |
| 3733 ecc_key *key); | |
| 3734 \end{verbatim} | |
| 3735 | |
| 3736 The \textit{keysize} is the size of the modulus in bytes desired. Currently directly supported values are 12, 16, 20, 24, 28, 32, 48, and 65 bytes which | |
| 3737 correspond to key sizes of 112, 128, 160, 192, 224, 256, 384, and 521 bits respectively. If you pass a key size that is between any key size it will round | |
| 3738 the keysize up to the next available one. | |
| 3739 | |
| 3740 The function will free any internally allocated resources if there is an error. | |
| 3741 | |
| 3742 \subsection{Extended Key Generation} | |
| 3743 As of v1.16, the library supports an extended key generation routine which allows the user to specify their own curve. It is specified as follows: | |
| 3744 | |
| 3745 \index{ecc\_make\_key\_ex()} | |
| 3746 \begin{verbatim} | |
| 3747 int ecc_make_key_ex( | |
| 3748 prng_state *prng, | |
| 3749 int wprng, | |
| 3750 ecc_key *key, | |
| 3751 const ltc_ecc_set_type *dp); | |
| 3752 \end{verbatim} | |
| 3753 | |
| 3754 This function generates a random ECC key over the curve specified by the parameters by \textit{dp}. The rest of the parameters are equivalent to | |
| 3755 those from the original key generation function. | |
| 3756 | |
| 3757 \subsection{ECC Key Free} | |
| 3758 To free the memory allocated by a ecc\_make\_key(), ecc\_make\_key\_ex(), ecc\_import(), or ecc\_import\_ex() call use the following function: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3759 \index{ecc\_free()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3760 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3761 void ecc_free(ecc_key *key); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3762 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3763 |
| 380 | 3764 \subsection{ECC Key Export} |
| 3765 To export an ECC key using the LibTomCrypt format call the following function: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3766 \index{ecc\_export()} |
| 380 | 3767 \begin{verbatim} |
| 3768 int ecc_export(unsigned char *out, | |
| 3769 unsigned long *outlen, | |
| 3770 int type, | |
| 3771 ecc_key *key); | |
| 3772 \end{verbatim} | |
| 3773 This will export the key with the given \textit{type} (\textbf{PK\_PUBLIC} or \textbf{PK\_PRIVATE}), and store it to \textit{out}. | |
| 3774 | |
| 3775 \subsection{ECC Key Import} | |
| 3776 The following function imports a LibTomCrypt format ECC key: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3777 \index{ecc\_import()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3778 \begin{verbatim} |
| 380 | 3779 int ecc_import(const unsigned char *in, |
| 3780 unsigned long inlen, | |
| 3781 ecc_key *key); | |
| 3782 \end{verbatim} | |
| 3783 This will import the ECC key from \textit{in}, and store it in the ecc\_key structure pointed to by \textit{key}. If the operation fails it will free | |
| 3784 any allocated memory automatically. | |
| 3785 | |
| 3786 \subsection{Extended Key Import} | |
| 3787 | |
| 3788 The following function imports a LibTomCrypt format ECC key using a specified set of curve parameters: | |
| 3789 \index{ecc\_import\_ex()} | |
| 3790 \begin{verbatim} | |
| 3791 int ecc_import_ex(const unsigned char *in, | |
| 3792 unsigned long inlen, | |
| 3793 ecc_key *key, | |
| 3794 const ltc_ecc_set_type *dp); | |
| 3795 \end{verbatim} | |
| 3796 This will import the key from the array pointed to by \textit{in} of length \textit{inlen} octets. The key is stored in | |
| 3797 the ECC structure pointed to by \textit{key}. The curve is specified by the parameters pointed to by \textit{dp}. The function will free | |
| 3798 all internally allocated memory upon error. | |
| 3799 | |
| 3800 \subsection{ANSI X9.63 Export} | |
| 3801 The following function exports an ECC public key in the ANSI X9.63 format: | |
| 3802 | |
| 3803 \index{ecc\_ansi\_x963\_export()} | |
| 3804 \begin{verbatim} | |
| 3805 int ecc_ansi_x963_export( ecc_key *key, | |
| 3806 unsigned char *out, | |
| 3807 unsigned long *outlen); | |
| 3808 \end{verbatim} | |
| 3809 The ECC key pointed to by \textit{key} is exported in public fashion to the array pointed to by \textit{out}. The ANSI X9.63 format used is from | |
| 3810 section 4.3.6 of the standard. It does not allow for the export of private keys. | |
| 3811 | |
| 3812 \subsection{ANSI X9.63 Import} | |
| 3813 The following function imports an ANSI X9.63 section 4.3.6 format public ECC key: | |
| 3814 | |
| 3815 \index{ecc\_ansi\_x963\_import()} | |
| 3816 \begin{verbatim} | |
| 3817 int ecc_ansi_x963_import(const unsigned char *in, | |
| 3818 unsigned long inlen, | |
| 3819 ecc_key *key); | |
| 3820 \end{verbatim} | |
| 3821 This will import the key stored in the array pointed to by \textit{in} of length \textit{inlen} octets. The imported key is stored in the ECC key pointed to by | |
| 3822 \textit{key}. The function will free any allocated memory upon error. | |
| 3823 | |
| 3824 \subsection{Extended ANSI X9.63 Import} | |
| 3825 The following function allows the importing of an ANSI x9.63 section 4.3.6 format public ECC key using user specified domain parameters: | |
| 3826 | |
| 3827 \index{ecc\_ansi\_x963\_import\_ex()} | |
| 3828 \begin{verbatim} | |
| 3829 int ecc_ansi_x963_import_ex(const unsigned char *in, | |
| 3830 unsigned long inlen, | |
| 3831 ecc_key *key, | |
| 3832 ltc_ecc_set_type *dp); | |
| 3833 \end{verbatim} | |
| 3834 This will import the key stored in the array pointed to by \textit{in} of length \textit{inlen} octets using the domain parameters pointed to by \textit{dp}. | |
| 3835 The imported key is stored in the ECC key pointed to by \textit{key}. The function will free any allocated memory upon error. | |
| 3836 | |
| 3837 \subsection{ECC Shared Secret} | |
| 3838 To construct a Diffie-Hellman shared secret with a private and public ECC key, use the following function: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3839 \index{ecc\_shared\_secret()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3840 \begin{verbatim} |
| 380 | 3841 int ecc_shared_secret( ecc_key *private_key, |
| 3842 ecc_key *public_key, | |
| 3843 unsigned char *out, | |
| 3844 unsigned long *outlen); | |
| 3845 \end{verbatim} | |
| 3846 The \textit{private\_key} is typically the local private key, and \textit{public\_key} is the key the remote party has shared. | |
| 3847 Note: this function stores only the $x$ co-ordinate of the shared elliptic point as described in ANSI X9.63 ECC--DH. | |
| 3848 | |
| 3849 \mysection{ECC Diffie-Hellman Encryption} | |
| 3850 ECC--DH Encryption is performed by producing a random key, hashing it, and XOR'ing the digest against the plaintext. It is not strictly ANSI X9.63 compliant | |
| 3851 but it is very similar. It has been extended by using an ASN.1 sequence and hash object identifiers to allow portable usage. The following function | |
| 3852 encrypts a short string (no longer than the message digest) using this technique: | |
| 3853 | |
| 3854 \subsection{ECC-DH Encryption} | |
| 3855 \index{ecc\_encrypt\_key()} | |
| 3856 \begin{verbatim} | |
| 3857 int ecc_encrypt_key(const unsigned char *in, | |
| 3858 unsigned long inlen, | |
| 3859 unsigned char *out, | |
| 3860 unsigned long *outlen, | |
| 3861 prng_state *prng, | |
| 3862 int wprng, | |
| 3863 int hash, | |
| 3864 ecc_key *key); | |
| 3865 \end{verbatim} | |
| 3866 | |
| 3867 As the name implies this function encrypts a (symmetric) key, and is not intended for encrypting long messages directly. It will encrypt the | |
| 3868 plaintext in the array pointed to by \textit{in} of length \textit{inlen} octets. It uses the public ECC key pointed to by \textit{key}, and | |
| 3869 hash algorithm indexed by \textit{hash} to construct a shared secret which may be XOR'ed against the plaintext. The ciphertext is stored in | |
| 3870 the output buffer pointed to by \textit{out} of length \textit{outlen} octets. | |
| 3871 | |
| 3872 The data is encrypted to the public ECC \textit{key} such that only the holder of the private key can decrypt the payload. To have multiple | |
| 3873 recipients multiple call to this function for each public ECC key is required. | |
| 3874 | |
| 3875 \subsection{ECC-DH Decryption} | |
| 3876 \index{ecc\_decrypt\_key()} | |
| 3877 \begin{verbatim} | |
| 3878 int ecc_decrypt_key(const unsigned char *in, | |
| 3879 unsigned long inlen, | |
| 3880 unsigned char *out, | |
| 3881 unsigned long *outlen, | |
| 3882 ecc_key *key); | |
| 3883 \end{verbatim} | |
| 3884 | |
| 3885 This function will decrypt an encrypted payload. The \textit{key} provided must be the private key corresponding to the public key | |
| 3886 used during encryption. If the wrong key is provided the function will not specifically return an error code. It is important | |
| 3887 to use some form of challenge response in that case (e.g. compute a MAC of a known string). | |
| 3888 | |
| 3889 \subsection{ECC Encryption Format} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3890 The packet format for the encrypted keys is the following ASN.1 SEQUENCE: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3891 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3892 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3893 ECCEncrypt ::= SEQUENCE { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3894 hashID OBJECT IDENTIFIER, -- OID of hash used |
| 380 | 3895 pubkey OCTET STRING , -- Encapsulated ECCPublicKey |
| 3896 skey OCTET STRING -- xor of plaintext and | |
| 3897 --"hash of shared secret" | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3898 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3899 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3900 |
| 380 | 3901 \mysection{EC DSA Signatures} |
| 3902 | |
| 3903 There are also functions to sign and verify messages. They use the ANSI X9.62 EC-DSA algorithm to generate and verify signatures in the | |
| 3904 ANSI X9.62 format. | |
| 3905 | |
| 3906 \subsection{EC-DSA Signature Generation} | |
| 3907 To sign a message digest (hash) use the following function: | |
| 3908 | |
| 3909 \index{ecc\_sign\_hash()} | |
| 3910 \begin{verbatim} | |
| 3911 int ecc_sign_hash(const unsigned char *in, | |
| 3912 unsigned long inlen, | |
| 3913 unsigned char *out, | |
| 3914 unsigned long *outlen, | |
| 3915 prng_state *prng, | |
| 3916 int wprng, | |
| 3917 ecc_key *key); | |
| 3918 \end{verbatim} | |
| 3919 | |
| 3920 This function will EC--DSA sign the message digest stored in the array pointed to by \textit{in} of length \textit{inlen} octets. The signature | |
| 3921 will be stored in the array pointed to by \textit{out} of length \textit{outlen} octets. The function requires a properly seeded PRNG, and | |
| 3922 the ECC \textit{key} provided must be a private key. | |
| 3923 | |
| 3924 \subsection{EC-DSA Signature Verification} | |
| 3925 \index{ecc\_verify\_hash()} | |
| 3926 \begin{verbatim} | |
| 3927 int ecc_verify_hash(const unsigned char *sig, | |
| 3928 unsigned long siglen, | |
| 3929 const unsigned char *hash, | |
| 3930 unsigned long hashlen, | |
| 3931 int *stat, | |
| 3932 ecc_key *key); | |
| 3933 \end{verbatim} | |
| 3934 | |
| 3935 This function will verify the EC-DSA signature in the array pointed to by \textit{sig} of length \textit{siglen} octets, against the message digest | |
| 3936 pointed to by the array \textit{hash} of length \textit{hashlen}. It will store a non--zero value in \textit{stat} if the signature is valid. Note: | |
| 3937 the function will not return an error if the signature is invalid. It will return an error, if the actual signature payload is an invalid format. | |
| 3938 The ECC \textit{key} must be the public (or private) ECC key corresponding to the key that performed the signature. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3939 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3940 \subsection{Signature Format} |
| 380 | 3941 The signature code is an implementation of X9.62 EC--DSA, and the output is compliant for GF(p) curves. |
| 3942 | |
| 3943 \mysection{ECC Keysizes} | |
| 3944 With ECC if you try to sign a hash that is bigger than your ECC key you can run into problems. The math will still work, and in effect the signature will still | |
| 3945 work. With ECC keys the strength of the signature is limited by the size of the hash, or the size of they key, whichever is smaller. For example, if you sign with | |
| 3946 SHA256 and an ECC-192 key, you in effect have 96--bits of security. | |
| 3947 | |
| 3948 The library will not warn you if you make this mistake, so it is important to check yourself before using the signatures. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3949 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3950 \chapter{Digital Signature Algorithm} |
| 380 | 3951 \mysection{Introduction} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3952 The Digital Signature Algorithm (or DSA) is a variant of the ElGamal Signature scheme which has been modified to |
| 380 | 3953 reduce the bandwidth of the signatures. For example, to have \textit{80-bits of security} with ElGamal, you need a group with an order of at least 1024--bits. |
| 3954 With DSA, you need a group of order at least 160--bits. By comparison, the ElGamal signature would require at least 256 bytes of storage, whereas the DSA signature | |
| 3955 would require only at least 40 bytes. | |
| 3956 | |
| 3957 \mysection{Key Format} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3958 Since no useful public standard for DSA key storage was presented to me during the course of this development I made my own ASN.1 SEQUENCE which I document |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3959 now so that others can interoperate with this library. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3960 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3961 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3962 DSAPublicKey ::= SEQUENCE { |
| 380 | 3963 publicFlags BIT STRING(0), -- must be 0 |
| 3964 g INTEGER , -- base generator | |
| 3965 -- check that g^q mod p == 1 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3966 -- and that 1 < g < p - 1 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3967 p INTEGER , -- prime modulus |
| 380 | 3968 q INTEGER , -- order of sub-group |
| 3969 -- (must be prime) | |
| 3970 y INTEGER , -- public key, specifically, | |
| 3971 -- g^x mod p, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3972 -- check that y^q mod p == 1 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3973 -- and that 1 < y < p - 1 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3974 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3975 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3976 DSAPrivateKey ::= SEQUENCE { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3977 publicFlags BIT STRING(1), -- must be 1 |
| 380 | 3978 g INTEGER , -- base generator |
| 3979 -- check that g^q mod p == 1 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3980 -- and that 1 < g < p - 1 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3981 p INTEGER , -- prime modulus |
| 380 | 3982 q INTEGER , -- order of sub-group |
| 3983 -- (must be prime) | |
| 3984 y INTEGER , -- public key, specifically, | |
| 3985 -- g^x mod p, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3986 -- check that y^q mod p == 1 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3987 -- and that 1 < y < p - 1 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3988 x INTEGER -- private key |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3989 } |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3990 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3991 |
| 380 | 3992 The leading BIT STRING has a single bit in it which is zero for public keys and one for private keys. This makes the structure uniquely decodable, |
| 3993 and easy to work with. | |
| 3994 | |
| 3995 \mysection{Key Generation} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3996 To make a DSA key you must call the following function |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
3997 \begin{verbatim} |
| 380 | 3998 int dsa_make_key(prng_state *prng, |
| 3999 int wprng, | |
| 4000 int group_size, | |
| 4001 int modulus_size, | |
| 4002 dsa_key *key); | |
| 4003 \end{verbatim} | |
| 4004 The variable \textit{prng} is an active PRNG state and \textit{wprng} the index to the descriptor. \textit{group\_size} and | |
| 4005 \textit{modulus\_size} control the difficulty of forging a signature. Both parameters are in bytes. The larger the | |
| 4006 \textit{group\_size} the more difficult a forgery becomes upto a limit. The value of $group\_size$ is limited by | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4007 $15 < group\_size < 1024$ and $modulus\_size - group\_size < 512$. Suggested values for the pairs are as follows. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4008 |
| 380 | 4009 \begin{figure}[here] |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4010 \begin{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4011 \begin{tabular}{|c|c|c|} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4012 \hline \textbf{Bits of Security} & \textbf{group\_size} & \textbf{modulus\_size} \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4013 \hline 80 & 20 & 128 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4014 \hline 120 & 30 & 256 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4015 \hline 140 & 35 & 384 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4016 \hline 160 & 40 & 512 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4017 \hline |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4018 \end{tabular} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4019 \end{center} |
| 380 | 4020 \caption{DSA Key Sizes} |
| 4021 \end{figure} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4022 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4023 When you are finished with a DSA key you can call the following function to free the memory used. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4024 \index{dsa\_free()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4025 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4026 void dsa_free(dsa_key *key); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4027 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4028 |
| 380 | 4029 \mysection{Key Verification} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4030 Each DSA key is composed of the following variables. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4031 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4032 \begin{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4033 \item $q$ a small prime of magnitude $256^{group\_size}$. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4034 \item $p = qr + 1$ a large prime of magnitude $256^{modulus\_size}$ where $r$ is a random even integer. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4035 \item $g = h^r \mbox{ (mod }p\mbox{)}$ a generator of order $q$ modulo $p$. $h$ can be any non-trivial random |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4036 value. For this library they start at $h = 2$ and step until $g$ is not $1$. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4037 \item $x$ a random secret (the secret key) in the range $1 < x < q$ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4038 \item $y = g^x \mbox{ (mod }p\mbox{)}$ the public key. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4039 \end{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4040 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4041 A DSA key is considered valid if it passes all of the following tests. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4042 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4043 \begin{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4044 \item $q$ must be prime. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4045 \item $p$ must be prime. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4046 \item $g$ cannot be one of $\lbrace -1, 0, 1 \rbrace$ (modulo $p$). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4047 \item $g$ must be less than $p$. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4048 \item $(p-1) \equiv 0 \mbox{ (mod }q\mbox{)}$. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4049 \item $g^q \equiv 1 \mbox{ (mod }p\mbox{)}$. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4050 \item $1 < y < p - 1$ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4051 \item $y^q \equiv 1 \mbox{ (mod }p\mbox{)}$. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4052 \end{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4053 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4054 Tests one and two ensure that the values will at least form a field which is required for the signatures to |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4055 function. Tests three and four ensure that the generator $g$ is not set to a trivial value which would make signature |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4056 forgery easier. Test five ensures that $q$ divides the order of multiplicative sub-group of $\Z/p\Z$. Test six |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4057 ensures that the generator actually generates a prime order group. Tests seven and eight ensure that the public key |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4058 is within range and belongs to a group of prime order. Note that test eight does not prove that $g$ generated $y$ only |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4059 that $y$ belongs to a multiplicative sub-group of order $q$. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4060 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4061 The following function will perform these tests. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4062 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4063 \index{dsa\_verify\_key()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4064 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4065 int dsa_verify_key(dsa_key *key, int *stat); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4066 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4067 |
| 380 | 4068 This will test \textit{key} and store the result in \textit{stat}. If the result is $stat = 0$ the DSA key failed one of the tests |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4069 and should not be used at all. If the result is $stat = 1$ the DSA key is valid (as far as valid mathematics are concerned). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4070 |
| 380 | 4071 \mysection{Signatures} |
| 4072 \subsection{Signature Generation} | |
| 4073 To generate a DSA signature call the following function: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4074 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4075 \index{dsa\_sign\_hash()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4076 \begin{verbatim} |
| 380 | 4077 int dsa_sign_hash(const unsigned char *in, |
| 4078 unsigned long inlen, | |
| 4079 unsigned char *out, | |
| 4080 unsigned long *outlen, | |
| 4081 prng_state *prng, | |
| 4082 int wprng, | |
| 4083 dsa_key *key); | |
| 4084 \end{verbatim} | |
| 4085 | |
| 4086 Which will sign the data in \textit{in} of length \textit{inlen} bytes. The signature is stored in \textit{out} and the size | |
| 4087 of the signature in \textit{outlen}. If the signature is longer than the size you initially specify in \textit{outlen} nothing | |
| 4088 is stored and the function returns an error code. The DSA \textit{key} must be of the \textbf{PK\_PRIVATE} persuasion. | |
| 4089 | |
| 4090 \subsection{Signature Verification} | |
| 4091 To verify a hash created with that function use the following function: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4092 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4093 \index{dsa\_verify\_hash()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4094 \begin{verbatim} |
| 380 | 4095 int dsa_verify_hash(const unsigned char *sig, |
| 4096 unsigned long siglen, | |
| 4097 const unsigned char *hash, | |
| 4098 unsigned long inlen, | |
| 4099 int *stat, | |
| 4100 dsa_key *key); | |
| 4101 \end{verbatim} | |
| 4102 Which will verify the data in \textit{hash} of length \textit{inlen} against the signature stored in \textit{sig} of length \textit{siglen}. | |
| 4103 It will set \textit{stat} to $1$ if the signature is valid, otherwise it sets \textit{stat} to $0$. | |
| 4104 | |
| 4105 \mysection{DSA Encrypt and Decrypt} | |
| 4106 As of version 1.07, the DSA keys can be used to encrypt and decrypt small payloads. It works similar to the ECC encryption where | |
| 4107 a shared key is computed, and the hash of the shared key XOR'ed against the plaintext forms the ciphertext. The format used is functional port of | |
| 4108 the ECC encryption format to the DSA algorithm. | |
| 4109 | |
| 4110 \subsection{DSA Encryption} | |
| 4111 This function will encrypt a small payload with a recipients public DSA key. | |
| 4112 | |
| 4113 \index{dsa\_encrypt\_key()} | |
| 4114 \begin{verbatim} | |
| 4115 int dsa_encrypt_key(const unsigned char *in, | |
| 4116 unsigned long inlen, | |
| 4117 unsigned char *out, | |
| 4118 unsigned long *outlen, | |
| 4119 prng_state *prng, | |
| 4120 int wprng, | |
| 4121 int hash, | |
| 4122 dsa_key *key); | |
| 4123 \end{verbatim} | |
| 4124 | |
| 4125 This will encrypt the payload in \textit{in} of length \textit{inlen} and store the ciphertext in the output buffer \textit{out}. The | |
| 4126 length of the ciphertext \textit{outlen} must be originally set to the length of the output buffer. The DSA \textit{key} can be | |
| 4127 a public key. | |
| 4128 | |
| 4129 \subsection{DSA Decryption} | |
| 4130 | |
| 4131 \index{dsa\_decrypt\_key()} | |
| 4132 \begin{verbatim} | |
| 4133 int dsa_decrypt_key(const unsigned char *in, | |
| 4134 unsigned long inlen, | |
| 4135 unsigned char *out, | |
| 4136 unsigned long *outlen, | |
| 4137 dsa_key *key); | |
| 4138 \end{verbatim} | |
| 4139 This will decrypt the ciphertext \textit{in} of length \textit{inlen}, and store the original payload in \textit{out} of length \textit{outlen}. | |
| 4140 The DSA \textit{key} must be a private key. | |
| 4141 | |
| 4142 \mysection{DSA Key Import and Export} | |
| 4143 | |
| 4144 \subsection{DSA Key Export} | |
| 4145 To export a DSA key so that it can be transported use the following function: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4146 \index{dsa\_export()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4147 \begin{verbatim} |
| 380 | 4148 int dsa_export(unsigned char *out, |
| 4149 unsigned long *outlen, | |
| 4150 int type, | |
| 4151 dsa_key *key); | |
| 4152 \end{verbatim} | |
| 4153 This will export the DSA \textit{key} to the buffer \textit{out} and set the length in \textit{outlen} (which must have been previously | |
| 4154 initialized to the maximum buffer size). The \textit{type} variable may be either \textbf{PK\_PRIVATE} or \textbf{PK\_PUBLIC} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4155 depending on whether you want to export a private or public copy of the DSA key. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4156 |
| 380 | 4157 \subsection{DSA Key Import} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4158 To import an exported DSA key use the following function |
| 380 | 4159 : |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4160 \index{dsa\_import()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4161 \begin{verbatim} |
| 380 | 4162 int dsa_import(const unsigned char *in, |
| 4163 unsigned long inlen, | |
| 4164 dsa_key *key); | |
| 4165 \end{verbatim} | |
| 4166 | |
| 4167 This will import the DSA key from the buffer \textit{in} of length \textit{inlen} to the \textit{key}. If the process fails the function | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4168 will automatically free all of the heap allocated in the process (you don't have to call dsa\_free()). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4169 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4170 \chapter{Standards Support} |
| 380 | 4171 \mysection{ASN.1 Formats} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4172 LibTomCrypt supports a variety of ASN.1 data types encoded with the Distinguished Encoding Rules (DER) suitable for various cryptographic protocols. The data types |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4173 are all provided with three basic functions with \textit{similar} prototypes. One function has been dedicated to calculate the length in octets of a given |
| 380 | 4174 format, and two functions have been dedicated to encoding and decoding the format. |
| 4175 | |
| 4176 On top of the basic data types are the SEQUENCE and SET data types which are collections of other ASN.1 types. They are provided | |
| 4177 in the same manner as the other data types except they use list of objects known as the \textbf{ltc\_asn1\_list} structure. It is defined as the following: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4178 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4179 \index{ltc\_asn1\_list structure} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4180 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4181 typedef struct { |
| 380 | 4182 int type; |
| 4183 void *data; | |
| 4184 unsigned long size; | |
| 4185 int used; | |
| 4186 struct ltc_asn1_list_ *prev, *next, | |
| 4187 *child, *parent; | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4188 } ltc_asn1_list; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4189 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4190 |
| 380 | 4191 \index{LTC\_SET\_ASN1 macro} |
| 4192 The \textit{type} field is one of the following ASN.1 field definitions. The \textit{data} pointer is a void pointer to the data to be encoded (or the destination) and the | |
| 4193 \textit{size} field is specific to what you are encoding (e.g. number of bits in the BIT STRING data type). The \textit{used} field is primarily for the CHOICE decoder | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4194 and reflects if the particular member of a list was the decoded data type. To help build the lists in an orderly fashion the macro |
| 380 | 4195 \textit{LTC\_SET\_ASN1(list, index, Type, Data, Size)} has been provided. |
| 4196 | |
| 4197 It will assign to the \textit{index}th position in the \textit{list} the triplet (Type, Data, Size). An example usage would be: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4198 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4199 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4200 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4201 ... |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4202 ltc_asn1_list sequence[3]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4203 unsigned long three=3; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4204 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4205 LTC_SET_ASN1(sequence, 0, LTC_ASN1_IA5_STRING, "hello", 5); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4206 LTC_SET_ASN1(sequence, 1, LTC_ASN1_SHORT_INTEGER, &three, 1); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4207 LTC_SET_ASN1(sequence, 2, LTC_ASN1_NULL, NULL, 0); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4208 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4209 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4210 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4211 The macro is relatively safe with respect to modifying variables, for instance the following code is equivalent. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4212 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4213 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4214 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4215 ... |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4216 ltc_asn1_list sequence[3]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4217 unsigned long three=3; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4218 int x=0; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4219 LTC_SET_ASN1(sequence, x++, LTC_ASN1_IA5_STRING, "hello", 5); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4220 LTC_SET_ASN1(sequence, x++, LTC_ASN1_SHORT_INTEGER, &three, 1); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4221 LTC_SET_ASN1(sequence, x++, LTC_ASN1_NULL, NULL, 0); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4222 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4223 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4224 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4225 \begin{figure}[here] |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4226 \begin{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4227 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4228 \begin{tabular}{|l|l|} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4229 \hline \textbf{Definition} & \textbf{ASN.1 Type} \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4230 \hline LTC\_ASN1\_EOL & End of a ASN.1 list structure. \\ |
| 380 | 4231 \hline LTC\_ASN1\_BOOLEAN & BOOLEAN type \\ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4232 \hline LTC\_ASN1\_INTEGER & INTEGER (uses mp\_int) \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4233 \hline LTC\_ASN1\_SHORT\_INTEGER & INTEGER (32--bit using unsigned long) \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4234 \hline LTC\_ASN1\_BIT\_STRING & BIT STRING (one bit per char) \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4235 \hline LTC\_ASN1\_OCTET\_STRING & OCTET STRING (one octet per char) \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4236 \hline LTC\_ASN1\_NULL & NULL \\ |
| 380 | 4237 \hline LTC\_ASN1\_OBJECT\_IDENTIFIER & OBJECT IDENTIFIER \\ |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4238 \hline LTC\_ASN1\_IA5\_STRING & IA5 STRING (one octet per char) \\ |
| 380 | 4239 \hline LTC\_ASN1\_UTF8\_STRING & UTF8 STRING (one wchar\_t per char) \\ |
| 4240 \hline LTC\_ASN1\_PRINTABLE\_STRING & PRINTABLE STRING (one octet per char) \\ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4241 \hline LTC\_ASN1\_UTCTIME & UTCTIME (see ltc\_utctime structure) \\ |
| 380 | 4242 \hline LTC\_ASN1\_SEQUENCE & SEQUENCE (and SEQUENCE OF) \\ |
| 4243 \hline LTC\_ASN1\_SET & SET \\ | |
| 4244 \hline LTC\_ASN1\_SETOF & SET OF \\ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4245 \hline LTC\_ASN1\_CHOICE & CHOICE \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4246 \hline |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4247 \end{tabular} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4248 \caption{List of ASN.1 Supported Types} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4249 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4250 \end{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4251 \end{figure} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4252 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4253 \subsection{SEQUENCE Type} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4254 The SEQUENCE data type is a collection of other ASN.1 data types encapsulated with a small header which is a useful way of sending multiple data types in one packet. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4255 |
| 380 | 4256 \subsubsection{SEQUENCE Encoding} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4257 To encode a sequence a \textbf{ltc\_asn1\_list} array must be initialized with the members of the sequence and their respective pointers. The encoding is performed |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4258 with the following function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4259 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4260 \index{der\_encode\_sequence()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4261 \begin{verbatim} |
| 380 | 4262 int der_encode_sequence(ltc_asn1_list *list, |
| 4263 unsigned long inlen, | |
| 4264 unsigned char *out, | |
| 4265 unsigned long *outlen); | |
| 4266 \end{verbatim} | |
| 4267 This encodes a sequence of items pointed to by \textit{list} where the list has \textit{inlen} items in it. The SEQUENCE will be encoded to \textit{out} and of length \textit{outlen}. The | |
| 4268 function will terminate when it reads all the items out of the list (upto \textit{inlen}) or it encounters an item in the list with a type of \textbf{LTC\_ASN1\_EOL}. | |
| 4269 | |
| 4270 The \textit{data} pointer in the list would be the same pointer you would pass to the respective ASN.1 encoder (e.g. der\_encode\_bit\_string()) and it is simply passed on | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4271 verbatim to the dependent encoder. The list can contain other SEQUENCE or SET types which enables you to have nested SEQUENCE and SET definitions. In these cases |
| 380 | 4272 the \textit{data} pointer is simply a pointer to another \textbf{ltc\_asn1\_list}. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4273 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4274 \subsubsection{SEQUENCE Decoding} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4275 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4276 \index{der\_decode\_sequence()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4277 |
| 380 | 4278 Decoding a SEQUENCE is similar to encoding. You set up an array of \textbf{ltc\_asn1\_list} where in this case the \textit{size} member is the maximum size |
| 4279 (in certain cases). For types such as IA5 STRING, BIT STRING, OCTET STRING (etc) the \textit{size} field is updated after successful decoding to reflect how many | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4280 units of the respective type has been loaded. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4281 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4282 \begin{verbatim} |
| 380 | 4283 int der_decode_sequence(const unsigned char *in, |
| 4284 unsigned long inlen, | |
| 4285 ltc_asn1_list *list, | |
| 4286 unsigned long outlen); | |
| 4287 \end{verbatim} | |
| 4288 | |
| 4289 This will decode upto \textit{outlen} items from the input buffer \textit{in} of length \textit{inlen} octets. The function will stop (gracefully) when it runs out of items to decode. | |
| 4290 It will fail (for among other reasons) when it runs out of input bytes to read, a data type is invalid or a heap failure occurred. | |
| 4291 | |
| 4292 For the following types the \textit{size} field will be updated to reflect the number of units read of the given type. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4293 \begin{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4294 \item BIT STRING |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4295 \item OCTET STRING |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4296 \item OBJECT IDENTIFIER |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4297 \item IA5 STRING |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4298 \item PRINTABLE STRING |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4299 \end{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4300 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4301 \subsubsection{SEQUENCE Length} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4302 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4303 The length of a SEQUENCE can be determined with the following function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4304 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4305 \index{der\_length\_sequence()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4306 \begin{verbatim} |
| 380 | 4307 int der_length_sequence(ltc_asn1_list *list, |
| 4308 unsigned long inlen, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4309 unsigned long *outlen); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4310 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4311 |
| 380 | 4312 This will get the encoding size for the given \textit{list} of length \textit{inlen} and store it in \textit{outlen}. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4313 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4314 \subsubsection{SEQUENCE Multiple Argument Lists} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4315 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4316 For small or simple sequences an encoding or decoding can be performed with one of the following two functions. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4317 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4318 \index{der\_encode\_sequence\_multi()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4319 \index{der\_decode\_sequence\_multi()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4320 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4321 \begin{verbatim} |
| 380 | 4322 int der_encode_sequence_multi(unsigned char *out, |
| 4323 unsigned long *outlen, ...); | |
| 4324 | |
| 4325 int der_decode_sequence_multi(const unsigned char *in, | |
| 4326 unsigned long inlen, ...); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4327 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4328 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4329 These either encode or decode (respectively) a SEQUENCE data type where the items in the sequence are specified after the length parameter. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4330 |
| 380 | 4331 The list of items are specified as a triple of the form \textit{(type, size, data)} where \textit{type} is an \textbf{int}, \textit{size} is a \textbf{unsigned long} |
| 4332 and \textit{data} is \textbf{void} pointer. The list of items must be terminated with an item with the type \textbf{LTC\_ASN1\_EOL}. | |
| 4333 | |
| 4334 It is ideal that you cast the \textit{size} values to unsigned long to ensure that the proper data type is passed to the function. Constants such as \textit{1} without | |
| 4335 a cast or prototype are of type \textbf{int} by default. Appending \textit{UL} or pre-pending \textit{(unsigned long)} is enough to cast it to the correct type. | |
| 4336 | |
| 4337 \begin{small} | |
| 4338 \begin{verbatim} | |
| 4339 unsigned char buf[MAXBUFSIZE]; | |
| 4340 unsigned long buflen; | |
| 4341 int err; | |
| 4342 | |
| 4343 buflen = sizeof(buf); | |
| 4344 if ((err = | |
| 4345 der_encode_sequence_multi(buf, &buflen, | |
| 4346 LTC_ASN1_IA5_STRING, 5UL, "Hello", | |
| 4347 LTC_ASN1_IA5_STRING, 7UL, " World!", | |
| 4348 LTC_ASN1_EOL, 0UL, NULL)) != CRYPT_OK) { | |
| 4349 // error handling | |
| 4350 } | |
| 4351 \end{verbatim} | |
| 4352 \end{small} | |
| 4353 | |
| 4354 This example encodes a SEQUENCE with two IA5 STRING types containing ``Hello'' and `` World!'' respectively. Note the usage of the \textbf{UL} modifier | |
| 4355 on the size parameters. This forces the compiler to pass the numbers as the required \textbf{unsigned long} type that the function expects. | |
| 4356 | |
| 4357 \subsection{SET and SET OF} | |
| 4358 | |
| 4359 \index{SET} \index{SET OF} | |
| 4360 SET and SET OF are related to the SEQUENCE type in that they can be pretty much be decoded with the same code. However, they are different, and they should | |
| 4361 be carefully noted. The SET type is an unordered array of ASN.1 types sorted by the TAG (type identifier), whereas the SET OF type is an ordered array of | |
| 4362 a \textbf{single} ASN.1 object sorted in ascending order by the DER their respective encodings. | |
| 4363 | |
| 4364 \subsubsection{SET Encoding} | |
| 4365 | |
| 4366 SETs use the same array structure of ltc\_asn1\_list that the SEQUENCE functions use. They are encoded with the following function: | |
| 4367 | |
| 4368 \index{der\_encode\_set()} | |
| 4369 \begin{verbatim} | |
| 4370 int der_encode_set(ltc_asn1_list *list, | |
| 4371 unsigned long inlen, | |
| 4372 unsigned char *out, | |
| 4373 unsigned long *outlen); | |
| 4374 \end{verbatim} | |
| 4375 | |
| 4376 This will encode the list of ASN.1 objects in \textit{list} of length \textit{inlen} objects, and store the output in \textit{out} of length \textit{outlen} bytes. | |
| 4377 The function will make a copy of the list provided, and sort it by the TAG. Objects with identical TAGs are additionally sorted on their original placement in the | |
| 4378 array (to make the process deterministic). | |
| 4379 | |
| 4380 This function will \textbf{NOT} recognize \textit{DEFAULT} objects, and it is the responsibility of the caller to remove them as required. | |
| 4381 | |
| 4382 \subsubsection{SET Decoding} | |
| 4383 | |
| 4384 The SET type can be decoded with the following function. | |
| 4385 | |
| 4386 \index{der\_decode\_set()} | |
| 4387 \begin{verbatim} | |
| 4388 int der_decode_set(const unsigned char *in, | |
| 4389 unsigned long inlen, | |
| 4390 ltc_asn1_list *list, | |
| 4391 unsigned long outlen); | |
| 4392 \end{verbatim} | |
| 4393 | |
| 4394 This will decode the SET specified by \textit{list} of length \textit{outlen} objects from the input buffer \textit{in} of length \textit{inlen} octets. | |
| 4395 | |
| 4396 It handles the fact that SETs are not strictly ordered and will make multiple passes (as required) through the list to decode all the objects. | |
| 4397 | |
| 4398 \subsubsection{SET Length} | |
| 4399 The length of a SET can be determined by calling der\_length\_sequence() since they have the same encoding length. | |
| 4400 | |
| 4401 \subsubsection{SET OF Encoding} | |
| 4402 A \textit{SET OF} object is an array of identical objects (e.g. OCTET STRING) sorted in ascending order by the DER encoding of the object. They are | |
| 4403 used to store objects deterministically based solely on their encoding. It uses the same array structure of ltc\_asn1\_list that the SEQUENCE functions | |
| 4404 use. They are encoded with the following function. | |
| 4405 | |
| 4406 \index{der\_encode\_setof()} | |
| 4407 \begin{verbatim} | |
| 4408 int der_encode_setof(ltc_asn1_list *list, | |
| 4409 unsigned long inlen, | |
| 4410 unsigned char *out, | |
| 4411 unsigned long *outlen); | |
| 4412 \end{verbatim} | |
| 4413 | |
| 4414 This will encode a \textit{SET OF} containing the \textit{list} of \textit{inlen} ASN.1 objects and store the encoding in the output buffer \textit{out} of length \textit{outlen}. | |
| 4415 | |
| 4416 The routine will first encode the SET OF in an unordered fashion (in a temporary buffer) then sort using the XQSORT macro and copy back to the output buffer. This | |
| 4417 means you need at least enough memory to keep an additional copy of the output on the heap. | |
| 4418 | |
| 4419 \subsubsection{SET OF Decoding} | |
| 4420 Since the decoding of a \textit{SET OF} object is unambiguous it can be decoded with der\_decode\_sequence(). | |
| 4421 | |
| 4422 \subsubsection{SET OF Length} | |
| 4423 Like the SET type the der\_length\_sequence() function can be used to determine the length of a \textit{SET OF} object. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4424 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4425 \subsection{ASN.1 INTEGER} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4426 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4427 To encode or decode INTEGER data types use the following functions. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4428 |
| 380 | 4429 \index{der\_encode\_integer()}\index{der\_decode\_integer()}\index{der\_length\_integer()} |
| 4430 \begin{verbatim} | |
| 4431 int der_encode_integer( void *num, | |
| 4432 unsigned char *out, | |
| 4433 unsigned long *outlen); | |
| 4434 | |
| 4435 int der_decode_integer(const unsigned char *in, | |
| 4436 unsigned long inlen, | |
| 4437 void *num); | |
| 4438 | |
| 4439 int der_length_integer( void *num, | |
| 4440 unsigned long *len); | |
| 4441 \end{verbatim} | |
| 4442 | |
| 4443 These will encode or decode a signed INTEGER data type using the bignum data type to store the large INTEGER. To encode smaller values without allocating | |
| 4444 a bignum to store the value, the \textit{short} INTEGER functions were made available. | |
| 4445 | |
| 4446 \index{der\_encode\_short\_integer()}\index{der\_decode\_short\_integer()}\index{der\_length\_short\_integer()} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4447 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4448 int der_encode_short_integer(unsigned long num, |
| 380 | 4449 unsigned char *out, |
| 4450 unsigned long *outlen); | |
| 4451 | |
| 4452 int der_decode_short_integer(const unsigned char *in, | |
| 4453 unsigned long inlen, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4454 unsigned long *num); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4455 |
| 380 | 4456 int der_length_short_integer(unsigned long num, |
| 4457 unsigned long *outlen); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4458 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4459 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4460 These will encode or decode an unsigned \textbf{unsigned long} type (only reads upto 32--bits). For values in the range $0 \dots 2^{32} - 1$ the integer |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4461 and short integer functions can encode and decode each others outputs. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4462 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4463 \subsection{ASN.1 BIT STRING} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4464 |
| 380 | 4465 \index{der\_encode\_bit\_string()}\index{der\_decode\_bit\_string()}\index{der\_length\_bit\_string()} |
| 4466 \begin{verbatim} | |
| 4467 int der_encode_bit_string(const unsigned char *in, | |
| 4468 unsigned long inlen, | |
| 4469 unsigned char *out, | |
| 4470 unsigned long *outlen); | |
| 4471 | |
| 4472 int der_decode_bit_string(const unsigned char *in, | |
| 4473 unsigned long inlen, | |
| 4474 unsigned char *out, | |
| 4475 unsigned long *outlen); | |
| 4476 | |
| 4477 int der_length_bit_string(unsigned long nbits, | |
| 4478 unsigned long *outlen); | |
| 4479 \end{verbatim} | |
| 4480 | |
| 4481 These will encode or decode a BIT STRING data type. The bits are passed in (or read out) using one \textbf{char} per bit. A non--zero value will be interpreted | |
| 4482 as a one bit, and a zero value a zero bit. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4483 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4484 \subsection{ASN.1 OCTET STRING} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4485 |
| 380 | 4486 \index{der\_encode\_octet\_string()}\index{der\_decode\_octet\_string()}\index{der\_length\_octet\_string()} |
| 4487 \begin{verbatim} | |
| 4488 int der_encode_octet_string(const unsigned char *in, | |
| 4489 unsigned long inlen, | |
| 4490 unsigned char *out, | |
| 4491 unsigned long *outlen); | |
| 4492 | |
| 4493 int der_decode_octet_string(const unsigned char *in, | |
| 4494 unsigned long inlen, | |
| 4495 unsigned char *out, | |
| 4496 unsigned long *outlen); | |
| 4497 | |
| 4498 int der_length_octet_string(unsigned long noctets, | |
| 4499 unsigned long *outlen); | |
| 4500 \end{verbatim} | |
| 4501 | |
| 4502 These will encode or decode an OCTET STRING data type. The octets are stored using one \textbf{unsigned char} each. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4503 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4504 \subsection{ASN.1 OBJECT IDENTIFIER} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4505 |
| 380 | 4506 \index{der\_encode\_object\_identifier()}\index{der\_decode\_object\_identifier()}\index{der\_length\_object\_identifier()} |
| 4507 \begin{verbatim} | |
| 4508 int der_encode_object_identifier(unsigned long *words, | |
| 4509 unsigned long nwords, | |
| 4510 unsigned char *out, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4511 unsigned long *outlen); |
| 380 | 4512 |
| 4513 int der_decode_object_identifier(const unsigned char *in, | |
| 4514 unsigned long inlen, | |
| 4515 unsigned long *words, | |
| 4516 unsigned long *outlen); | |
| 4517 | |
| 4518 int der_length_object_identifier(unsigned long *words, | |
| 4519 unsigned long nwords, | |
| 4520 unsigned long *outlen); | |
| 4521 \end{verbatim} | |
| 4522 | |
| 4523 These will encode or decode an OBJECT IDENTIFIER object. The words of the OID are stored in individual \textbf{unsigned long} elements, and must be in the range | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4524 $0 \ldots 2^{32} - 1$. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4525 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4526 \subsection{ASN.1 IA5 STRING} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4527 |
| 380 | 4528 \index{der\_encode\_ia5\_string()}\index{der\_decode\_ia5\_string()}\index{der\_length\_ia5\_string()} |
| 4529 \begin{verbatim} | |
| 4530 int der_encode_ia5_string(const unsigned char *in, | |
| 4531 unsigned long inlen, | |
| 4532 unsigned char *out, | |
| 4533 unsigned long *outlen); | |
| 4534 | |
| 4535 int der_decode_ia5_string(const unsigned char *in, | |
| 4536 unsigned long inlen, | |
| 4537 unsigned char *out, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4538 unsigned long *outlen); |
| 380 | 4539 |
| 4540 int der_length_ia5_string(const unsigned char *octets, | |
| 4541 unsigned long noctets, | |
| 4542 unsigned long *outlen); | |
| 4543 \end{verbatim} | |
| 4544 | |
| 4545 These will encode or decode an IA5 STRING. The characters are read or stored in individual \textbf{char} elements. These functions performs internal character | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4546 to numerical conversions based on the conventions of the compiler being used. For instance, on an x86\_32 machine 'A' == 65 but the same may not be true on |
| 380 | 4547 say a SPARC machine. Internally, these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided |
| 4548 that the build platform honours the run--time platforms character conventions. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4549 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4550 \subsection{ASN.1 PRINTABLE STRING} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4551 |
| 380 | 4552 \index{der\_encode\_printable\_string()}\index{der\_decode\_printable\_string()}\index{der\_length\_printable\_string()} |
| 4553 \begin{verbatim} | |
| 4554 int der_encode_printable_string(const unsigned char *in, | |
| 4555 unsigned long inlen, | |
| 4556 unsigned char *out, | |
| 4557 unsigned long *outlen); | |
| 4558 | |
| 4559 int der_decode_printable_string(const unsigned char *in, | |
| 4560 unsigned long inlen, | |
| 4561 unsigned char *out, | |
| 4562 unsigned long *outlen); | |
| 4563 | |
| 4564 int der_length_printable_string(const unsigned char *octets, | |
| 4565 unsigned long noctets, | |
| 4566 unsigned long *outlen); | |
| 4567 \end{verbatim} | |
| 4568 | |
| 4569 These will encode or decode an PRINTABLE STRING. The characters are read or stored in individual \textbf{char} elements. These functions performs internal character | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4570 to numerical conversions based on the conventions of the compiler being used. For instance, on an x86\_32 machine 'A' == 65 but the same may not be true on |
| 380 | 4571 say a SPARC machine. Internally, these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided |
| 4572 that the build platform honours the run-time platforms character conventions. | |
| 4573 | |
| 4574 \subsection{ASN.1 UTF8 STRING} | |
| 4575 | |
| 4576 \index{der\_encode\_utf8\_string()}\index{der\_decode\_utf8\_string()}\index{der\_length\_utf8\_string()} | |
| 4577 \begin{verbatim} | |
| 4578 int der_encode_utf8_string(const wchar_t *in, | |
| 4579 unsigned long inlen, | |
| 4580 unsigned char *out, | |
| 4581 unsigned long *outlen); | |
| 4582 | |
| 4583 int der_decode_utf8_string(const unsigned char *in, | |
| 4584 unsigned long inlen, | |
| 4585 wchar_t *out, | |
| 4586 unsigned long *outlen); | |
| 4587 | |
| 4588 int der_length_utf8_string(const wchar_t *octets, | |
| 4589 unsigned long noctets, | |
| 4590 unsigned long *outlen); | |
| 4591 \end{verbatim} | |
| 4592 | |
| 4593 These will encode or decode an UTF8 STRING. The characters are read or stored in individual \textbf{wchar\_t} elements. These function performs no internal | |
| 4594 mapping and treat the characters as literals. | |
| 4595 | |
| 4596 These functions use the \textbf{wchar\_t} type which is not universally available. In those cases, the library will typedef it to \textbf{unsigned long}. If you | |
| 4597 intend to use the ISO C functions for working with wide--char arrays, you should make sure that wchar\_t has been defined previously. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4598 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4599 \subsection{ASN.1 UTCTIME} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4600 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4601 The UTCTIME type is to store a date and time in ASN.1 format. It uses the following structure to organize the time. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4602 |
| 380 | 4603 \index{ltc\_utctime structure} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4604 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4605 typedef struct { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4606 unsigned YY, /* year 00--99 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4607 MM, /* month 01--12 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4608 DD, /* day 01--31 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4609 hh, /* hour 00--23 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4610 mm, /* minute 00--59 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4611 ss, /* second 00--59 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4612 off_dir, /* timezone offset direction 0 == +, 1 == - */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4613 off_hh, /* timezone offset hours */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4614 off_mm; /* timezone offset minutes */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4615 } ltc_utctime; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4616 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4617 |
| 380 | 4618 The time can be offset plus or minus a set amount of hours (off\_hh) and minutes (off\_mm). When \textit{off\_dir} is zero, the time will be added otherwise it |
| 4619 will be subtracted. For instance, the array $\lbrace 5, 6, 20, 22, 4, 00, 0, 5, 0 \rbrace$ represents the current time of | |
| 4620 \textit{2005, June 20th, 22:04:00} with a time offset of +05h00. | |
| 4621 | |
| 4622 \index{der\_encode\_utctime()}\index{der\_decode\_utctime()}\index{der\_length\_utctime()} | |
| 4623 \begin{verbatim} | |
| 4624 int der_encode_utctime( ltc_utctime *utctime, | |
| 4625 unsigned char *out, | |
| 4626 unsigned long *outlen); | |
| 4627 | |
| 4628 int der_decode_utctime(const unsigned char *in, | |
| 4629 unsigned long *inlen, | |
| 4630 ltc_utctime *out); | |
| 4631 | |
| 4632 int der_length_utctime( ltc_utctime *utctime, | |
| 4633 unsigned long *outlen); | |
| 4634 \end{verbatim} | |
| 4635 | |
| 4636 The encoder will store time in one of the two ASN.1 formats, either \textit{YYMMDDhhmmssZ} or \textit{YYMMDDhhmmss$\pm$hhmm}, and perform minimal error checking on the | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4637 input. The decoder will read all valid ASN.1 formats and perform range checking on the values (not complete but rational) useful for catching packet errors. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4638 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4639 It is suggested that decoded data be further scrutinized (e.g. days of month in particular). |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4640 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4641 \subsection{ASN.1 CHOICE} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4642 |
| 380 | 4643 The CHOICE ASN.1 type represents a union of ASN.1 types all of which are stored in a \textit{ltc\_asn1\_list}. There is no encoder for the CHOICE type, only a |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4644 decoder. The decoder will scan through the provided list attempting to use the appropriate decoder on the input packet. The list can contain any ASN.1 data |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4645 type\footnote{Except it cannot have LTC\_ASN1\_INTEGER and LTC\_ASN1\_SHORT\_INTEGER simultaneously.} except for other CHOICE types. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4646 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4647 There is no encoder for the CHOICE type as the actual DER encoding is the encoding of the chosen type. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4648 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4649 \index{der\_decode\_choice()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4650 \begin{verbatim} |
| 380 | 4651 int der_decode_choice(const unsigned char *in, |
| 4652 unsigned long *inlen, | |
| 4653 ltc_asn1_list *list, | |
| 4654 unsigned long outlen); | |
| 4655 \end{verbatim} | |
| 4656 | |
| 4657 This will decode the input in the \textit{in} field of length \textit{inlen}. It uses the provided ASN.1 list specified in the \textit{list} field which has | |
| 4658 \textit{outlen} elements. The \textit{inlen} field will be updated with the length of the decoded data type, as well as the respective entry in the \textit{list} field | |
| 4659 will have the \textit{used} flag set to non--zero to reflect it was the data type decoded. | |
| 4660 | |
| 4661 \subsection{ASN.1 Flexi Decoder} | |
| 4662 The ASN.1 \textit{flexi} decoder allows the developer to decode arbitrary ASN.1 DER packets (provided they use data types LibTomCrypt supports) without first knowing | |
| 4663 the structure of the data. Where der\_decode \_sequence() requires the developer to specify the data types to decode in advance the flexi decoder is entirely | |
| 4664 free form. | |
| 4665 | |
| 4666 The flexi decoder uses the same \textit{ltc\_asn1\_list} but instead of being stored in an array it uses the linked list pointers \textit{prev}, \textit{next}, \textit{parent} | |
| 4667 and \textit{child}. The list works as a \textit{doubly-linked list} structure where decoded items at the same level are siblings (using next and prev) and items | |
| 4668 encoded in a SEQUENCE are stored as a child element. | |
| 4669 | |
| 4670 When a SEQUENCE or SET has been encountered a SEQUENCE (or SET resp.) item will be added as a sibling (e.g. list.type == LTC\_ASN1\_SEQUENCE) and the child | |
| 4671 pointer points to a new list of items contained within the object. | |
| 4672 | |
| 4673 \index{der\_decode\_sequence\_flexi()} | |
| 4674 \begin{verbatim} | |
| 4675 int der_decode_sequence_flexi(const unsigned char *in, | |
| 4676 unsigned long *inlen, | |
| 4677 ltc_asn1_list **out); | |
| 4678 \end{verbatim} | |
| 4679 | |
| 4680 This will decode items in the \textit{in} buffer of max input length \textit{inlen} and store the newly created pointer to the list in \textit{out}. This function allocates | |
| 4681 all required memory for the decoding. It stores the number of octets read back into \textit{inlen}. | |
| 4682 | |
| 4683 The function will terminate when either it hits an invalid ASN.1 tag, or it reads \textit{inlen} octets. An early termination is a soft error, and returns | |
| 4684 normally. The decoded list \textit{out} will point to the very first element of the list (e.g. both parent and prev pointers will be \textbf{NULL}). | |
| 4685 | |
| 4686 An invalid decoding will terminate the process, and free the allocated memory automatically. | |
| 4687 | |
| 4688 \textbf{Note:} the list decoded by this function is \textbf{NOT} in the correct form for der\_encode\_sequence() to use directly. You will have to first | |
| 4689 have to convert the list by first storing all of the siblings in an array then storing all the children as sub-lists of a sequence using the \textit{.data} | |
| 4690 pointer. Currently no function in LibTomCrypt provides this ability. | |
| 4691 | |
| 4692 \subsubsection{Sample Decoding} | |
| 4693 Suppose we decode the following structure: | |
| 4694 \begin{small} | |
| 4695 \begin{verbatim} | |
| 4696 User ::= SEQUENCE { | |
| 4697 Name IA5 STRING | |
| 4698 LoginToken SEQUENCE { | |
| 4699 passwdHash OCTET STRING | |
| 4700 pubkey ECCPublicKey | |
| 4701 } | |
| 4702 LastOn UTCTIME | |
| 4703 } | |
| 4704 \end{verbatim} | |
| 4705 \end{small} | |
| 4706 \begin{flushleft}and we decoded it with the following code:\end{flushleft} | |
| 4707 | |
| 4708 \begin{small} | |
| 4709 \begin{verbatim} | |
| 4710 unsigned char inbuf[MAXSIZE]; | |
| 4711 unsigned long inbuflen; | |
| 4712 ltc_asn1_list *list; | |
| 4713 int err; | |
| 4714 | |
| 4715 /* somehow fill inbuf/inbuflen */ | |
| 4716 if ((err = der_decode_sequence_flexi(inbuf, inbuflen, &list)) != CRYPT_OK) { | |
| 4717 printf("Error decoding: %s\n", error_to_string(err)); | |
| 4718 exit(EXIT_FAILURE); | |
| 4719 } | |
| 4720 \end{verbatim} | |
| 4721 \end{small} | |
| 4722 | |
| 4723 At this point \textit{list} would point to the SEQUENCE identified by \textit{User}. It would have no sibblings (prev or next), and only a child node. Walking to the child | |
| 4724 node with the following code will bring us to the \textit{Name} portion of the SEQUENCE: | |
| 4725 \begin{small} | |
| 4726 \begin{verbatim} | |
| 4727 list = list->child; | |
| 4728 \end{verbatim} | |
| 4729 \end{small} | |
| 4730 Now \textit{list} points to the \textit{Name} member (with the tag IA5 STRING). The \textit{data}, \textit{size}, and \textit{type} members of \textit{list} should reflect | |
| 4731 that of an IA5 STRING. The sibbling will now be the \textit{LoginToken} SEQUENCE. The sibbling has a child node which points to the \textit{passwdHash} OCTET STRING. | |
| 4732 We can walk to this node with the following code: | |
| 4733 \begin{small} | |
| 4734 \begin{verbatim} | |
| 4735 /* list already pointing to 'Name' */ | |
| 4736 list = list->next->child; | |
| 4737 \end{verbatim} | |
| 4738 \end{small} | |
| 4739 At this point, \textit{list} will point to the \textit{passwdHash} member of the innermost SEQUENCE. This node has a sibbling, the \textit{pubkey} member of the SEQUENCE. | |
| 4740 The \textit{LastOn} member of the SEQUENCE is a sibbling of the LoginToken node, if we wanted to walk there we would have to go up and over via: | |
| 4741 \begin{small} | |
| 4742 \begin{verbatim} | |
| 4743 list = list->parent->next; | |
| 4744 \end{verbatim} | |
| 4745 \end{small} | |
| 4746 At this point, we are pointing to the last node of the list. Lists are terminated in all directions by a \textbf{NULL} pointer. All nodes are doubly linked so that you | |
| 4747 can walk up and down the nodes without keeping pointers lying around. | |
| 4748 | |
| 4749 | |
| 4750 | |
| 4751 | |
| 4752 | |
| 4753 \subsubsection{Free'ing a Flexi List} | |
| 4754 To free the list use the following function. | |
| 4755 | |
| 4756 \index{der\_sequence\_free()} | |
| 4757 \begin{verbatim} | |
| 4758 void der_sequence_free(ltc_asn1_list *in); | |
| 4759 \end{verbatim} | |
| 4760 | |
| 4761 This will free all of the memory allocated by der\_decode\_sequence\_flexi(). | |
| 4762 | |
| 4763 \mysection{Password Based Cryptography} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4764 \subsection{PKCS \#5} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4765 \index{PKCS \#5} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4766 In order to securely handle user passwords for the purposes of creating session keys and chaining IVs the PKCS \#5 was drafted. PKCS \#5 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4767 is made up of two algorithms, Algorithm One and Algorithm Two. Algorithm One is the older fairly limited algorithm which has been implemented |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4768 for completeness. Algorithm Two is a bit more modern and more flexible to work with. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4769 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4770 \subsection{Algorithm One} |
| 380 | 4771 Algorithm One accepts as input a password, an 8--byte salt, and an iteration counter. The iteration counter is meant to act as delay for |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4772 people trying to brute force guess the password. The higher the iteration counter the longer the delay. This algorithm also requires a hash |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4773 algorithm and produces an output no longer than the output of the hash. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4774 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4775 \index{pkcs\_5\_alg1()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4776 \begin{alltt} |
| 380 | 4777 int pkcs_5_alg1(const unsigned char *password, |
| 4778 unsigned long password_len, | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4779 const unsigned char *salt, |
| 380 | 4780 int iteration_count, |
| 4781 int hash_idx, | |
| 4782 unsigned char *out, | |
| 4783 unsigned long *outlen) | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4784 \end{alltt} |
| 380 | 4785 Where \textit{password} is the user's password. Since the algorithm allows binary passwords you must also specify the length in \textit{password\_len}. |
| 4786 The \textit{salt} is a fixed size 8--byte array which should be random for each user and session. The \textit{iteration\_count} is the delay desired | |
| 4787 on the password. The \textit{hash\_idx} is the index of the hash you wish to use in the descriptor table. | |
| 4788 | |
| 4789 The output of length up to \textit{outlen} is stored in \textit{out}. If \textit{outlen} is initially larger than the size of the hash functions output | |
| 4790 it is set to the number of bytes stored. If it is smaller than not all of the hash output is stored in \textit{out}. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4791 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4792 \subsection{Algorithm Two} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4793 |
| 380 | 4794 Algorithm Two is the recommended algorithm for this task. It allows variable length salts, and can produce outputs larger than the |
| 4795 hash functions output. As such, it can easily be used to derive session keys for ciphers and MACs as well initial vectors as required | |
| 4796 from a single password and invocation of this algorithm. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4797 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4798 \index{pkcs\_5\_alg2()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4799 \begin{alltt} |
| 380 | 4800 int pkcs_5_alg2(const unsigned char *password, |
| 4801 unsigned long password_len, | |
| 4802 const unsigned char *salt, | |
| 4803 unsigned long salt_len, | |
| 4804 int iteration_count, | |
| 4805 int hash_idx, | |
| 4806 unsigned char *out, | |
| 4807 unsigned long *outlen) | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4808 \end{alltt} |
| 380 | 4809 Where \textit{password} is the users password. Since the algorithm allows binary passwords you must also specify the length in \textit{password\_len}. |
| 4810 The \textit{salt} is an array of size \textit{salt\_len}. It should be random for each user and session. The \textit{iteration\_count} is the delay desired | |
| 4811 on the password. The \textit{hash\_idx} is the index of the hash you wish to use in the descriptor table. The output of length up to | |
| 4812 \textit{outlen} is stored in \textit{out}. | |
| 4813 | |
| 4814 \begin{verbatim} | |
| 4815 /* demo to show how to make session state material | |
| 4816 * from a password */ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4817 #include <tomcrypt.h> |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4818 int main(void) |
| 380 | 4819 { |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4820 unsigned char password[100], salt[100], |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4821 cipher_key[16], cipher_iv[16], |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4822 mac_key[16], outbuf[48]; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4823 int err, hash_idx; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4824 unsigned long outlen, password_len, salt_len; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4825 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4826 /* register hash and get it's idx .... */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4827 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4828 /* get users password and make up a salt ... */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4829 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4830 /* create the material (100 iterations in algorithm) */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4831 outlen = sizeof(outbuf); |
| 380 | 4832 if ((err = pkcs_5_alg2(password, password_len, salt, |
| 4833 salt_len, 100, hash_idx, outbuf, | |
| 4834 &outlen)) | |
| 4835 != CRYPT_OK) { | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4836 /* error handle */ |
| 380 | 4837 } |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4838 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4839 /* now extract it */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4840 memcpy(cipher_key, outbuf, 16); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4841 memcpy(cipher_iv, outbuf+16, 16); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4842 memcpy(mac_key, outbuf+32, 16); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4843 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4844 /* use material (recall to store the salt in the output) */ |
| 380 | 4845 } |
| 4846 \end{verbatim} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4847 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4848 \chapter{Miscellaneous} |
| 380 | 4849 \mysection{Base64 Encoding and Decoding} |
| 4850 The library provides functions to encode and decode a RFC 1521 base--64 coding scheme. The characters used in the mappings are: | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4851 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4852 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4853 \end{verbatim} |
| 380 | 4854 Those characters are supported in the 7-bit ASCII map, which means they can be used for transport over |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4855 common e-mail, usenet and HTTP mediums. The format of an encoded stream is just a literal sequence of ASCII characters |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4856 where a group of four represent 24-bits of input. The first four chars of the encoders output is the length of the |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4857 original input. After the first four characters is the rest of the message. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4858 |
| 380 | 4859 Often, it is desirable to line wrap the output to fit nicely in an e-mail or usenet posting. The decoder allows you to |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4860 put any character (that is not in the above sequence) in between any character of the encoders output. You may not however, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4861 break up the first four characters. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4862 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4863 To encode a binary string in base64 call: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4864 \index{base64\_encode()} \index{base64\_decode()} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4865 \begin{verbatim} |
| 380 | 4866 int base64_encode(const unsigned char *in, |
| 4867 unsigned long len, | |
| 4868 unsigned char *out, | |
| 4869 unsigned long *outlen); | |
| 4870 \end{verbatim} | |
| 4871 Where \textit{in} is the binary string and \textit{out} is where the ASCII output is placed. You must set the value of \textit{outlen} prior | |
| 4872 to calling this function and it sets the length of the base64 output in \textit{outlen} when it is done. To decode a base64 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4873 string call: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4874 \begin{verbatim} |
| 380 | 4875 int base64_decode(const unsigned char *in, |
| 4876 unsigned long len, | |
| 4877 unsigned char *out, | |
| 4878 unsigned long *outlen); | |
| 4879 \end{verbatim} | |
| 4880 | |
| 4881 \mysection{Primality Testing} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4882 \index{Primality Testing} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4883 The library includes primality testing and random prime functions as well. The primality tester will perform the test in |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4884 two phases. First it will perform trial division by the first few primes. Second it will perform eight rounds of the |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4885 Rabin-Miller primality testing algorithm. If the candidate passes both phases it is declared prime otherwise it is declared |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4886 composite. No prime number will fail the two phases but composites can. Each round of the Rabin-Miller algorithm reduces |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4887 the probability of a pseudo-prime by $1 \over 4$ therefore after sixteen rounds the probability is no more than |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4888 $\left ( { 1 \over 4 } \right )^{8} = 2^{-16}$. In practice the probability of error is in fact much lower than that. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4889 |
| 380 | 4890 When making random primes the trial division step is in fact an optimized implementation of \textit{Implementation of Fast RSA Key Generation on Smart Cards}\footnote{Chenghuai Lu, Andre L. M. dos Santos and Francisco R. Pimentel}. |
| 4891 In essence a table of machine-word sized residues are kept of a candidate modulo a set of primes. When the candidate | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4892 is rejected and ultimately incremented to test the next number the residues are updated without using multi-word precision |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4893 math operations. As a result the routine can scan ahead to the next number required for testing with very little work |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4894 involved. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4895 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4896 In the event that a composite did make it through it would most likely cause the the algorithm trying to use it to fail. For |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4897 instance, in RSA two primes $p$ and $q$ are required. The order of the multiplicative sub-group (modulo $pq$) is given |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4898 as $\phi(pq)$ or $(p - 1)(q - 1)$. The decryption exponent $d$ is found as $de \equiv 1\mbox{ }(\mbox{mod } \phi(pq))$. If either $p$ or $q$ is composite the value of $d$ will be incorrect and the user |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4899 will not be able to sign or decrypt messages at all. Suppose $p$ was prime and $q$ was composite this is just a variation of |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4900 the multi-prime RSA. Suppose $q = rs$ for two primes $r$ and $s$ then $\phi(pq) = (p - 1)(r - 1)(s - 1)$ which clearly is |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4901 not equal to $(p - 1)(rs - 1)$. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4902 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4903 These are not technically part of the LibTomMath library but this is the best place to document them. |
| 380 | 4904 To test if a \textit{mp\_int} is prime call: |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4905 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4906 int is_prime(mp_int *N, int *result); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4907 \end{verbatim} |
| 380 | 4908 This puts a one in \textit{result} if the number is probably prime, otherwise it places a zero in it. It is assumed that if |
| 4909 it returns an error that the value in \textit{result} is undefined. To make | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4910 a random prime call: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4911 \begin{verbatim} |
| 380 | 4912 int rand_prime( mp_int *N, |
| 4913 unsigned long len, | |
| 4914 prng_state *prng, | |
| 4915 int wprng); | |
| 4916 \end{verbatim} | |
| 4917 Where \textit{len} is the size of the prime in bytes ($2 \le len \le 256$). You can set \textit{len} to the negative size you want | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4918 to get a prime of the form $p \equiv 3\mbox{ }(\mbox{mod } 4)$. So if you want a 1024-bit prime of this sort pass |
| 380 | 4919 \textit{len = -128} to the function. Upon success it will return {\bf CRYPT\_OK} and \textit{N} will contain an integer which |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4920 is very likely prime. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4921 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4922 \chapter{Programming Guidelines} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4923 |
| 380 | 4924 \mysection{Secure Pseudo Random Number Generators} |
| 4925 Probably the single most vulnerable point of any cryptosystem is the PRNG. Without one, generating and protecting secrets | |
| 4926 would be impossible. The requirement that one be setup correctly is vitally important, and to address this point the library | |
| 4927 does provide two RNG sources that will address the largest amount of end users as possible. The \textit{sprng} PRNG provides an easy to | |
| 4928 access source of entropy for any application on a UNIX (and the like) or Windows computer. | |
| 4929 | |
| 4930 However, when the end user is not on one of these platforms, the application developer must address the issue of finding | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4931 entropy. This manual is not designed to be a text on cryptography. I would just like to highlight that when you design |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4932 a cryptosystem make sure the first problem you solve is getting a fresh source of entropy. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4933 |
| 380 | 4934 \mysection{Preventing Trivial Errors} |
| 4935 Two simple ways to prevent trivial errors is to prevent overflows, and to check the return values. All of the functions | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4936 which output variable length strings will require you to pass the length of the destination. If the size of your output |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4937 buffer is smaller than the output it will report an error. Therefore, make sure the size you pass is correct! |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4938 |
| 380 | 4939 Also, virtually all of the functions return an error code or {\bf CRYPT\_OK}. You should detect all errors, as simple |
| 4940 typos can cause algorithms to fail to work as desired. | |
| 4941 | |
| 4942 \mysection{Registering Your Algorithms} | |
| 4943 To avoid linking and other run--time errors it is important to register the ciphers, hashes and PRNGs you intend to use | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4944 before you try to use them. This includes any function which would use an algorithm indirectly through a descriptor table. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4945 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4946 A neat bonus to the registry system is that you can add external algorithms that are not part of the library without |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4947 having to hack the library. For example, suppose you have a hardware specific PRNG on your system. You could easily |
| 380 | 4948 write the few functions required plus a descriptor. After registering your PRNG, all of the library functions that |
| 4949 need a PRNG can instantly take advantage of it. The same applies for ciphers, hashes, and bignum math routines. | |
| 4950 | |
| 4951 \mysection{Key Sizes} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4952 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4953 \subsection{Symmetric Ciphers} |
| 380 | 4954 For symmetric ciphers, use as large as of a key as possible. For the most part \textit{bits are cheap} so using a 256--bit key |
| 4955 is not a hard thing to do. As a good rule of thumb do not use a key smaller than 128 bits. | |
| 4956 | |
| 4957 \subsection{Asymmetric Ciphers} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4958 The following chart gives the work factor for solving a DH/RSA public key using the NFS. The work factor for a key of order |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4959 $n$ is estimated to be |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4960 \begin{equation} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4961 e^{1.923 \cdot ln(n)^{1 \over 3} \cdot ln(ln(n))^{2 \over 3}} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4962 \end{equation} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4963 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4964 Note that $n$ is not the bit-length but the magnitude. For example, for a 1024-bit key $n = 2^{1024}$. The work required |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4965 is: |
| 380 | 4966 \begin{figure}[here] |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4967 \begin{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4968 \begin{tabular}{|c|c|} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4969 \hline RSA/DH Key Size (bits) & Work Factor ($log_2$) \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4970 \hline 512 & 63.92 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4971 \hline 768 & 76.50 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4972 \hline 1024 & 86.76 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4973 \hline 1536 & 103.37 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4974 \hline 2048 & 116.88 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4975 \hline 2560 & 128.47 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4976 \hline 3072 & 138.73 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4977 \hline 4096 & 156.49 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4978 \hline |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4979 \end{tabular} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4980 \end{center} |
| 380 | 4981 \caption{RSA/DH Key Strength} |
| 4982 \end{figure} | |
| 4983 | |
| 4984 The work factor for ECC keys is much higher since the best attack is still fully exponential. Given a key of magnitude | |
| 4985 $n$ it requires $\sqrt n$ work. The following table summarizes the work required: | |
| 4986 \begin{figure}[here] | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4987 \begin{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4988 \begin{tabular}{|c|c|} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4989 \hline ECC Key Size (bits) & Work Factor ($log_2$) \\ |
| 380 | 4990 \hline 112 & 56 \\ |
| 4991 \hline 128 & 64 \\ | |
| 4992 \hline 160 & 80 \\ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4993 \hline 192 & 96 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4994 \hline 224 & 112 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4995 \hline 256 & 128 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4996 \hline 384 & 192 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4997 \hline 521 & 260.5 \\ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4998 \hline |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
4999 \end{tabular} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5000 \end{center} |
| 380 | 5001 \caption{ECC Key Strength} |
| 5002 \end{figure} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5003 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5004 Using the above tables the following suggestions for key sizes seems appropriate: |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5005 \begin{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5006 \begin{tabular}{|c|c|c|} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5007 \hline Security Goal & RSA/DH Key Size (bits) & ECC Key Size (bits) \\ |
| 380 | 5008 \hline Near term & 1024 & 160 \\ |
| 5009 \hline Short term & 1536 & 192 \\ | |
| 5010 \hline Long Term & 2560 & 384 \\ | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5011 \hline |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5012 \end{tabular} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5013 \end{center} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5014 |
| 380 | 5015 \mysection{Thread Safety} |
| 5016 The library is not fully thread safe but several simple precautions can be taken to avoid any problems. The registry functions | |
| 5017 such as register\_cipher() are not thread safe no matter what you do. It is best to call them from your programs initialization | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5018 code before threads are initiated. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5019 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5020 The rest of the code uses state variables you must pass it such as hash\_state, hmac\_state, etc. This means that if each |
| 380 | 5021 thread has its own state variables then they will not affect each other, and are fully thread safe. This is fairly simple with symmetric ciphers |
| 5022 and hashes. | |
| 5023 | |
| 5024 \index{LTC\_PTHREAD} | |
| 5025 The only sticky issue is a shared PRNG which can be alleviated with the careful use of mutex devices. Defining LTC\_PTHREAD for instance, enables | |
| 5026 pthreads based mutex locking in various routines such as the Yarrow and Fortuna PRNGs, the fixed point ECC multiplier, and other routines. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5027 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5028 \chapter{Configuring and Building the Library} |
| 380 | 5029 \mysection{Introduction} |
| 5030 The library is fairly flexible about how it can be built, used, and generally distributed. Additions are being made with | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5031 each new release that will make the library even more flexible. Each of the classes of functions can be disabled during |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5032 the build process to make a smaller library. This is particularly useful for shared libraries. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5033 |
| 380 | 5034 As of v1.06 of the library, the build process has been moved to two steps for the typical LibTomCrypt application. This is because |
| 5035 LibTomCrypt no longer provides a math API on its own and relies on third party libraries (such as LibTomMath, GnuMP, or TomsFastMath). | |
| 5036 | |
| 5037 The build process now consists of installing a math library first, and then building and installing LibTomCrypt with a math library | |
| 5038 configured. Note that LibTomCrypt can be built with no internal math descriptors. This means that one must be provided at either | |
| 5039 build, or run time for the application. LibTomCrypt comes with three math descriptors that provide a standard interface to math | |
| 5040 libraries. | |
| 5041 | |
| 5042 \mysection{Makefile variables} | |
| 5043 | |
| 5044 All GNU driven makefiles (including the makefile for ICC) use a set of common variables to control the build and install process. Most of the | |
| 5045 settings can be overwritten from the command line which makes custom installation a breeze. | |
| 5046 | |
| 5047 \index{MAKE}\index{CC}\index{AR} | |
| 5048 \subsection{MAKE, CC and AR} | |
| 5049 The MAKE, CC and AR flags can all be overwritten. They default to \textit{make}, \textit{\$CC} and \textit{\$AR} respectively. | |
| 5050 Changing MAKE allows you to change what program will be invoked to handle sub--directories. For example, this | |
| 5051 | |
| 5052 \begin{verbatim} | |
| 5053 MAKE=gmake gmake install | |
| 5054 \end{verbatim} | |
| 5055 | |
| 5056 \begin{flushleft} will build and install the libraries with the \textit{gmake} tool. Similarly, \end{flushleft} | |
| 5057 | |
| 5058 \begin{verbatim} | |
| 5059 CC=arm-gcc AR=arm-ar make | |
| 5060 \end{verbatim} | |
| 5061 | |
| 5062 \begin{flushleft} will build the library using \textit{arm--gcc} as the compiler and \textit{arm--ar} as the archiver. \end{flushleft} | |
| 5063 | |
| 5064 \subsection{IGNORE\_SPEED} | |
| 5065 \index{IGNORE\_SPEED} | |
| 5066 When \textbf{IGNORE\_SPEED} has been defined the default optimization flags for CFLAGS will be disabled which allows the developer to specify new | |
| 5067 CFLAGS on the command line. E.g. to add debugging | |
| 5068 | |
| 5069 \begin{verbatim} | |
| 5070 CFLAGS="-g3" make IGNORE_SPEED=1 | |
| 5071 \end{verbatim} | |
| 5072 | |
| 5073 This will turn off optimizations and add \textit{-g3} to the CFLAGS which enables debugging. | |
| 5074 | |
| 5075 \subsection{LIBNAME and LIBNAME\_S} | |
| 5076 \index{LIBNAME} \index{LIBNAME\_S} | |
| 5077 \textbf{LIBNAME} is the name of the output library (archive) to create. It defaults to \textit{libtomcrypt.a} for static builds and \textit{libtomcrypt.la} for | |
| 5078 shared. The \textbf{LIBNAME\_S} variable is the static name while doing shared builds. Ideally they should have the same prefix but don't have to. | |
| 5079 | |
| 5080 \index{LIBTEST} \index{LIBTEST\_S} | |
| 5081 Similarly \textbf{LIBTEST} and \textbf{LIBTEST\_S} are the names for the profiling and testing library. The default is \textit{libtomcrypt\_prof.a} for | |
| 5082 static and \textit{libtomcrypt\_prof.la} for shared. | |
| 5083 | |
| 5084 \subsection{Installation Directories} | |
| 5085 \index{DESTDIR} \index{LIBPATH} \index{INCPATH} \index{DATADIR} | |
| 5086 \textbf{DESTDIR} is the prefix for the installation directories. It defaults to an empty string. \textbf{LIBPATH} is the prefix for the library | |
| 5087 directory which defaults to \textit{/usr/lib}. \textbf{INCPATH} is the prefix for the header file directory which defaults to \textit{/usr/include}. | |
| 5088 \textbf{DATADIR} is the prefix for the data (documentation) directory which defaults to \textit{/usr/share/doc/libtomcrypt/pdf}. | |
| 5089 | |
| 5090 All four can be used to create custom install locations depending on the nature of the OS and file system in use. | |
| 5091 | |
| 5092 \begin{verbatim} | |
| 5093 make LIBPATH=/home/tom/project/lib INCPATH=/home/tom/project/include \ | |
| 5094 DATAPATH=/home/tom/project/docs install | |
| 5095 \end{verbatim} | |
| 5096 | |
| 5097 This will build the library and install it to the directories under \textit{/home/tom/project/}. e.g. | |
| 5098 | |
| 5099 \begin{small} | |
| 5100 \begin{verbatim} | |
| 5101 /home/tom/project/: | |
| 5102 total 1 | |
| 5103 drwxr-xr-x 2 tom users 80 Jul 30 16:02 docs | |
| 5104 drwxr-xr-x 2 tom users 528 Jul 30 16:02 include | |
| 5105 drwxr-xr-x 2 tom users 80 Jul 30 16:02 lib | |
| 5106 | |
| 5107 /home/tom/project/docs: | |
| 5108 total 452 | |
| 5109 -rwxr-xr-x 1 tom users 459009 Jul 30 16:02 crypt.pdf | |
| 5110 | |
| 5111 /home/tom/project/include: | |
| 5112 total 132 | |
| 5113 -rwxr-xr-x 1 tom users 2482 Jul 30 16:02 tomcrypt.h | |
| 5114 -rwxr-xr-x 1 tom users 702 Jul 30 16:02 tomcrypt_argchk.h | |
| 5115 -rwxr-xr-x 1 tom users 2945 Jul 30 16:02 tomcrypt_cfg.h | |
| 5116 -rwxr-xr-x 1 tom users 22763 Jul 30 16:02 tomcrypt_cipher.h | |
| 5117 -rwxr-xr-x 1 tom users 5174 Jul 30 16:02 tomcrypt_custom.h | |
| 5118 -rwxr-xr-x 1 tom users 11314 Jul 30 16:02 tomcrypt_hash.h | |
| 5119 -rwxr-xr-x 1 tom users 11571 Jul 30 16:02 tomcrypt_mac.h | |
| 5120 -rwxr-xr-x 1 tom users 13614 Jul 30 16:02 tomcrypt_macros.h | |
| 5121 -rwxr-xr-x 1 tom users 14714 Jul 30 16:02 tomcrypt_math.h | |
| 5122 -rwxr-xr-x 1 tom users 632 Jul 30 16:02 tomcrypt_misc.h | |
| 5123 -rwxr-xr-x 1 tom users 10934 Jul 30 16:02 tomcrypt_pk.h | |
| 5124 -rwxr-xr-x 1 tom users 2634 Jul 30 16:02 tomcrypt_pkcs.h | |
| 5125 -rwxr-xr-x 1 tom users 7067 Jul 30 16:02 tomcrypt_prng.h | |
| 5126 -rwxr-xr-x 1 tom users 1467 Jul 30 16:02 tomcrypt_test.h | |
| 5127 | |
| 5128 /home/tom/project/lib: | |
| 5129 total 1073 | |
| 5130 -rwxr-xr-x 1 tom users 1096284 Jul 30 16:02 libtomcrypt.a | |
| 5131 \end{verbatim} | |
| 5132 \end{small} | |
| 5133 | |
| 5134 \mysection{Extra libraries} | |
| 5135 \index{EXTRALIBS} | |
| 5136 \textbf{EXTRALIBS} specifies any extra libraries required to link the test programs and shared libraries. They are specified in the notation | |
| 5137 that GCC expects for global archives. | |
| 5138 | |
| 5139 \begin{verbatim} | |
| 5140 CFLAGS="-DTFM_DESC -DUSE_TFM" EXTRALIBS=-ltfm make install \ | |
| 5141 test timing | |
| 5142 \end{verbatim} | |
| 5143 | |
| 5144 This will install the library using the TomsFastMath library and link the \textit{libtfm.a} library out of the default library search path. The two | |
| 5145 defines are explained below. You can specify multiple archives (say if you want to support two math libraries, or add on additional code) to | |
| 5146 the \textbf{EXTRALIBS} variable by separating them by a space. | |
| 5147 | |
| 5148 Note that \textbf{EXTRALIBS} is not required if you are only making and installing the static library but none of the test programs. | |
| 5149 | |
| 5150 \mysection{Building a Static Library} | |
| 5151 | |
| 5152 Building a static library is fairly trivial as it only requires one invocation of the GNU make command. | |
| 5153 | |
| 5154 \begin{verbatim} | |
| 5155 CFLAGS="-DTFM_DESC" make install | |
| 5156 \end{verbatim} | |
| 5157 | |
| 5158 That will build LibTomCrypt (including the TomsFastMath descriptor), and install it in the default locations indicated previously. You can enable | |
| 5159 the built--in LibTomMath descriptor as well (or in place of the TomsFastMath descriptor). Similarly, you can build the library with no built--in | |
| 5160 math descriptors. | |
| 5161 | |
| 5162 \begin{verbatim} | |
| 5163 make install | |
| 5164 \end{verbatim} | |
| 5165 | |
| 5166 In this case, no math descriptors are present in the library and they will have to be made available at build or run time before you can use any of the | |
| 5167 public key functions. | |
| 5168 | |
| 5169 Note that even if you include the built--in descriptors you must link against the source library as well. | |
| 5170 | |
| 5171 \begin{verbatim} | |
| 5172 gcc -DTFM_DESC myprogram.c -ltomcrypt -ltfm -o myprogram | |
| 5173 \end{verbatim} | |
| 5174 | |
| 5175 This will compile \textit{myprogram} and link it against the LibTomCrypt library as well as TomsFastMath (which must have been previously installed). Note that | |
| 5176 we define \textbf{TFM\_DESC} for compilation. This is so that the TFM descriptor symbol will be defined for the client application to make use of without | |
| 5177 giving warnings. | |
| 5178 | |
| 5179 \mysection{Building a Shared Library} | |
| 5180 | |
| 5181 LibTomCrypt can also be built as a shared library through the \textit{makefile.shared} make script. It is similar to use as the static script except | |
| 5182 that you \textbf{must} specify the \textbf{EXTRALIBS} variable at install time. | |
| 5183 | |
| 5184 \begin{verbatim} | |
| 5185 CFLAGS="-DTFM_DESC" EXTRALIBS=-ltfm make -f makefile.shared install | |
| 5186 \end{verbatim} | |
| 5187 | |
| 5188 This will build and install the library and link the shared object against the TomsFastMath library (which must be installed as a shared object as well). The | |
| 5189 shared build process requires libtool to be installed. | |
| 5190 | |
| 5191 \mysection{Header Configuration} | |
| 5192 The file \textit{tomcrypt\_cfg.h} is what lets you control various high level macros which control the behaviour of the library. Build options are also | |
| 5193 stored in \textit{tomcrypt\_custom.h} which allow the enabling and disabling of various algorithms. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5194 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5195 \subsubsection{ARGTYPE} |
| 380 | 5196 This lets you control how the LTC\_ARGCHK macro will behave. The macro is used to check pointers inside the functions against |
| 5197 NULL. There are four settings for ARGTYPE. When set to 0, it will have the default behaviour of printing a message to | |
| 5198 stderr and raising a SIGABRT signal. This is provided so all platforms that use LibTomCrypt can have an error that functions | |
| 5199 similarly. When set to 1, it will simply pass on to the assert() macro. When set to 2, the macro will display the error to | |
| 5200 stderr then return execution to the caller. This could lead to a segmentation fault (e.g. when a pointer is \textbf{NULL}) but is useful | |
| 5201 if you handle signals on your own. When set to 3, it will resolve to a empty macro and no error checking will be performed. Finally, when set | |
| 5202 to 4, it will return CRYPT\_INVALID\_ARG to the caller. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5203 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5204 \subsubsection{Endianess} |
| 380 | 5205 There are five macros related to endianess issues. For little endian platforms define, \textbf{ENDIAN\_LITTLE}. For big endian |
| 5206 platforms define \textbf{ENDIAN\_BIG}. Similarly when the default word size of an \textit{unsigned long} is 32-bits define \textbf{ENDIAN\_32BITWORD} | |
| 5207 or define \textbf{ENDIAN\_64BITWORD} when its 64-bits. If you do not define any of them the library will automatically use \textbf{ENDIAN\_NEUTRAL} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5208 which will work on all platforms. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5209 |
| 380 | 5210 Currently LibTomCrypt will detect x86-32, x86-64, MIPS R5900, SPARC and SPARC64 running GCC as well as x86-32 running MSVC. |
| 5211 | |
| 5212 \mysection{The Configure Script} | |
| 5213 There are also options you can specify from the \textit{tomcrypt\_custom.h} header file. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5214 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5215 \subsection{X memory routines} |
| 380 | 5216 \index{XMALLOC}\index{XCALLOC}\index{XREALLOC}\index{XFREE} |
| 5217 At the top of tomcrypt\_custom.h are a series of macros denoted as XMALLOC, XCALLOC, XREALLOC, XFREE, and so on. They resolve to | |
| 5218 the name of the respective functions from the standard C library by default. This lets you substitute in your own memory routines. | |
| 5219 If you substitute in your own functions they must behave like the standard C library functions in terms of what they expect as input and | |
| 5220 output. | |
| 5221 | |
| 5222 These macros are handy for working with platforms which do not have a standard C library. For instance, the OLPC\footnote{See http://dev.laptop.org/git?p=bios-crypto;a=summary} | |
| 5223 bios code uses these macros to redirect to very compact heap and string operations. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5224 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5225 \subsection{X clock routines} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5226 The rng\_get\_bytes() function can call a function that requires the clock() function. These macros let you override |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5227 the default clock() used with a replacement. By default the standard C library clock() function is used. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5228 |
| 380 | 5229 \subsection{LTC\_NO\_FILE} |
| 5230 During the build if LTC\_NO\_FILE is defined then any function in the library that uses file I/O will not call the file I/O | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5231 functions and instead simply return CRYPT\_NOP. This should help resolve any linker errors stemming from a lack of |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5232 file I/O on embedded platforms. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5233 |
| 380 | 5234 \subsection{LTC\_CLEAN\_STACK} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5235 When this functions is defined the functions that store key material on the stack will clean up afterwards. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5236 Assumes that you have no memory paging with the stack. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5237 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5238 \subsection{LTC\_TEST} |
| 380 | 5239 When this has been defined the various self--test functions (for ciphers, hashes, prngs, etc) are included in the build. This is the default configuration. |
| 5240 If LTC\_NO\_TEST has been defined, the testing routines will be compacted and only return CRYPT\_NOP. | |
| 5241 | |
| 5242 \subsection{LTC\_NO\_FAST} | |
| 5243 When this has been defined the library will not use faster word oriented operations. By default, they are only enabled for platforms | |
| 5244 which can be auto-detected. This macro ensures that they are never enabled. | |
| 5245 | |
| 5246 \subsection{LTC\_FAST} | |
| 5247 This mode (auto-detected with x86\_32,x86\_64 platforms with GCC or MSVC) configures various routines such as ctr\_encrypt() or | |
| 5248 cbc\_encrypt() that it can safely XOR multiple octets in one step by using a larger data type. This has the benefit of | |
| 5249 cutting down the overhead of the respective functions. | |
| 5250 | |
| 5251 This mode does have one downside. It can cause unaligned reads from memory if you are not careful with the functions. This is why | |
| 5252 it has been enabled by default only for the x86 class of processors where unaligned accesses are allowed. Technically LTC\_FAST | |
| 5253 is not \textit{portable} since unaligned accesses are not covered by the ISO C specifications. | |
| 5254 | |
| 5255 In practice however, you can use it on pretty much any platform (even MIPS) with care. | |
| 5256 | |
| 5257 By design the \textit{fast} mode functions won't get unaligned on their own. For instance, if you call ctr\_encrypt() right after calling | |
| 5258 ctr\_start() and all the inputs you gave are aligned than ctr\_encrypt() will perform aligned memory operations only. However, if you | |
| 5259 call ctr\_encrypt() with an odd amount of plaintext then call it again the CTR pad (the IV) will be partially used. This will | |
| 5260 cause the ctr routine to first use up the remaining pad bytes. Then if there are enough plaintext bytes left it will use | |
| 5261 whole word XOR operations. These operations will be unaligned. | |
| 5262 | |
| 5263 The simplest precaution is to make sure you process all data in power of two blocks and handle \textit{remainder} at the end. e.g. If you are | |
| 5264 CTR'ing a long stream process it in blocks of (say) four kilobytes and handle any remaining incomplete blocks at the end of the stream. | |
| 5265 | |
| 5266 \index{LTC\_FAST\_TYPE} | |
| 5267 If you do plan on using the \textit{LTC\_FAST} mode you have to also define a \textit{LTC\_FAST\_TYPE} macro which resolves to an optimal sized | |
| 5268 data type you can perform integer operations with. Ideally it should be four or eight bytes since it must properly divide the size | |
| 5269 of your block cipher (e.g. 16 bytes for AES). This means sadly if you're on a platform with 57--bit words (or something) you can't | |
| 5270 use this mode. So sad. | |
| 5271 | |
| 5272 \subsection{LTC\_NO\_ASM} | |
| 5273 When this has been defined the library will not use any inline assembler. Only a few platforms support assembler inlines but various versions of ICC and GCC | |
| 5274 cannot handle all of the assembler functions. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5275 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5276 \subsection{Symmetric Ciphers, One-way Hashes, PRNGS and Public Key Functions} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5277 There are a plethora of macros for the ciphers, hashes, PRNGs and public key functions which are fairly |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5278 self-explanatory. When they are defined the functionality is included otherwise it is not. There are some |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5279 dependency issues which are noted in the file. For instance, Yarrow requires CTR chaining mode, a block |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5280 cipher and a hash function. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5281 |
| 380 | 5282 Also see technical note number five for more details. |
| 5283 | |
| 5284 \subsection{LTC\_EASY} | |
| 5285 When defined the library is configured to build fewer algorithms and modes. Mostly it sticks to NIST and ANSI approved algorithms. See | |
| 5286 the header file \textit{tomcrypt\_custom.h} for more details. It is meant to provide literally an easy method of trimming the library | |
| 5287 build to the most minimum of useful functionality. | |
| 5288 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5289 \subsection{TWOFISH\_SMALL and TWOFISH\_TABLES} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5290 Twofish is a 128-bit symmetric block cipher that is provided within the library. The cipher itself is flexible enough |
| 380 | 5291 to allow some trade-offs in the implementation. When TWOFISH\_SMALL is defined the scheduled symmetric key for Twofish |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5292 requires only 200 bytes of memory. This is achieved by not pre-computing the substitution boxes. Having this |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5293 defined will also greatly slow down the cipher. When this macro is not defined Twofish will pre-compute the |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5294 tables at a cost of 4KB of memory. The cipher will be much faster as a result. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5295 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5296 When TWOFISH\_TABLES is defined the cipher will use pre-computed (and fixed in code) tables required to work. This is |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5297 useful when TWOFISH\_SMALL is defined as the table values are computed on the fly. When this is defined the code size |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5298 will increase by approximately 500 bytes. If this is defined but TWOFISH\_SMALL is not the cipher will still work but |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5299 it will not speed up the encryption or decryption functions. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5300 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5301 \subsection{GCM\_TABLES} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5302 When defined GCM will use a 64KB table (per GCM state) which will greatly speed up the per--packet latency. |
| 380 | 5303 It also increases the initialization time and is not suitable when you are going to use a key a few times only. |
| 5304 | |
| 5305 \subsection{GCM\_TABLES\_SSE2} | |
| 5306 \index{SSE2} | |
| 5307 When defined GCM will use the SSE2 instructions to perform the $GF(2^x)$ multiply using 16 128--bit XOR operations. It shaves a few cycles per byte | |
| 5308 of GCM output on both the AMD64 and Intel Pentium 4 platforms. Requires GCC and an SSE2 equipped platform. | |
| 5309 | |
| 5310 \subsection{LTC\_SMALL\_CODE} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5311 When this is defined some of the code such as the Rijndael and SAFER+ ciphers are replaced with smaller code variants. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5312 These variants are slower but can save quite a bit of code space. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5313 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5314 \subsection{LTC\_PTHREAD} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5315 When this is activated all of the descriptor table functions will use pthread locking to ensure thread safe updates to the tables. Note that |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5316 it doesn't prevent a thread that is passively using a table from being messed up by another thread that updates the table. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5317 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5318 Generally the rule of thumb is to setup the tables once at startup and then leave them be. This added build flag simply makes updating |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5319 the tables safer. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5320 |
| 380 | 5321 \subsection{LTC\_ECC\_TIMING\_RESISTANT} |
| 5322 When this has been defined the ECC point multiplier (built--in to the library) will use a timing resistant point multiplication | |
| 5323 algorithm which prevents leaking key bits of the private key (scalar). It is a slower algorithm but useful for situations | |
| 5324 where timing side channels pose a significant threat. | |
| 5325 | |
| 5326 \subsection{Math Descriptors} | |
| 5327 The library comes with three math descriptors that allow you to interface the public key cryptography API to freely available math | |
| 5328 libraries. When \textbf{GMP\_DESC}, \textbf{LTM\_DESC}, or \textbf{TFM\_DESC} are defined | |
| 5329 descriptors for the respective library are built and included in the library as \textit{gmp\_desc}, \textit{ltm\_desc}, or \textit{tfm\_desc} respectively. | |
| 5330 | |
| 5331 In the test demos that use the libraries the additional flags \textbf{USE\_GMP}, \textbf{USE\_LTM}, and \textbf{USE\_TFM} can be defined | |
| 5332 to tell the program which library to use. Only one of the USE flags can be defined at once. | |
| 5333 | |
| 5334 \index{GMP\_DESC} \index{USE\_GMP} \index{LTM\_DESC} \index{TFM\_DESC} \index{USE\_LTM} \index{USE\_TFM} | |
| 5335 \begin{small} | |
| 5336 \begin{verbatim} | |
| 5337 CFLAGS="-DGMP_DESC -DLTM_DESC -DTFM_DESC -DUSE_TFM" \ | |
| 5338 EXTRALIBS="-lgmp -ltommath -ltfm" make -f makefile.shared install timing | |
| 5339 \end{verbatim} | |
| 5340 \end{small} | |
| 5341 | |
| 5342 That will build and install the library with all descriptors (and link against all), but only use TomsFastMath in the timing demo. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5343 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5344 \chapter{Optimizations} |
| 380 | 5345 \mysection{Introduction} |
| 5346 The entire API was designed with plug and play in mind at the low level. That is you can swap out any cipher, hash, PRNG or bignum library and the dependent API will not | |
| 5347 require updating. This has the nice benefit that one can add ciphers (etc.) not have to re--write portions of the API. For the most part, LibTomCrypt has also been written | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5348 to be highly portable and easy to build out of the box on pretty much any platform. As such there are no assembler inlines throughout the code, I make no assumptions |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5349 about the platform, etc... |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5350 |
| 380 | 5351 That works well for most cases but there are times where performance is of the essence. This API allows optimized routines to be dropped in--place of the existing |
| 5352 portable routines. For instance, hand optimized assembler versions of AES could be provided. Any existing function that uses the cipher could automatically use | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5353 the optimized code without re--writing. This also paves the way for hardware drivers that can access hardware accelerated cryptographic devices. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5354 |
| 380 | 5355 At the heart of this flexibility is the \textit{descriptor} system. A descriptor is essentially just a C \textit{struct} which describes the algorithm and provides pointers |
| 5356 to functions that do the required work. For a given class of operation (e.g. cipher, hash, prng, bignum) the functions of a descriptor have identical prototypes which makes | |
| 5357 development simple. In most dependent routines all an end developer has to do is register\_XXX() the descriptor and they are set. | |
| 5358 | |
| 5359 \mysection{Ciphers} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5360 The ciphers in LibTomCrypt are accessed through the ltc\_cipher\_descriptor structure. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5361 |
| 380 | 5362 \label{sec:cipherdesc} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5363 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5364 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5365 struct ltc_cipher_descriptor { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5366 /** name of cipher */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5367 char *name; |
| 380 | 5368 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5369 /** internal ID */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5370 unsigned char ID; |
| 380 | 5371 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5372 /** min keysize (octets) */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5373 int min_key_length, |
| 380 | 5374 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5375 /** max keysize (octets) */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5376 max_key_length, |
| 380 | 5377 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5378 /** block size (octets) */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5379 block_length, |
| 380 | 5380 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5381 /** default number of rounds */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5382 default_rounds; |
| 380 | 5383 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5384 /** Setup the cipher |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5385 @param key The input symmetric key |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5386 @param keylen The length of the input key (octets) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5387 @param num_rounds The requested number of rounds (0==default) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5388 @param skey [out] The destination of the scheduled key |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5389 @return CRYPT_OK if successful |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5390 */ |
| 380 | 5391 int (*setup)(const unsigned char *key, |
| 5392 int keylen, | |
| 5393 int num_rounds, | |
| 5394 symmetric_key *skey); | |
| 5395 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5396 /** Encrypt a block |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5397 @param pt The plaintext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5398 @param ct [out] The ciphertext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5399 @param skey The scheduled key |
| 380 | 5400 @return CRYPT_OK if successful |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5401 */ |
| 380 | 5402 int (*ecb_encrypt)(const unsigned char *pt, |
| 5403 unsigned char *ct, | |
| 5404 symmetric_key *skey); | |
| 5405 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5406 /** Decrypt a block |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5407 @param ct The ciphertext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5408 @param pt [out] The plaintext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5409 @param skey The scheduled key |
| 380 | 5410 @return CRYPT_OK if successful |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5411 */ |
| 380 | 5412 int (*ecb_decrypt)(const unsigned char *ct, |
| 5413 unsigned char *pt, | |
| 5414 symmetric_key *skey); | |
| 5415 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5416 /** Test the block cipher |
| 380 | 5417 @return CRYPT_OK if successful, |
| 5418 CRYPT_NOP if self-testing has been disabled | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5419 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5420 int (*test)(void); |
| 380 | 5421 |
| 5422 /** Terminate the context | |
| 5423 @param skey The scheduled key | |
| 5424 */ | |
| 5425 void (*done)(symmetric_key *skey); | |
| 5426 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5427 /** Determine a key size |
| 380 | 5428 @param keysize [in/out] The size of the key desired |
| 5429 The suggested size | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5430 @return CRYPT_OK if successful |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5431 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5432 int (*keysize)(int *keysize); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5433 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5434 /** Accelerators **/ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5435 /** Accelerated ECB encryption |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5436 @param pt Plaintext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5437 @param ct Ciphertext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5438 @param blocks The number of complete blocks to process |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5439 @param skey The scheduled key context |
| 380 | 5440 @return CRYPT_OK if successful |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5441 */ |
| 380 | 5442 int (*accel_ecb_encrypt)(const unsigned char *pt, |
| 5443 unsigned char *ct, | |
| 5444 unsigned long blocks, | |
| 5445 symmetric_key *skey); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5446 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5447 /** Accelerated ECB decryption |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5448 @param pt Plaintext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5449 @param ct Ciphertext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5450 @param blocks The number of complete blocks to process |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5451 @param skey The scheduled key context |
| 380 | 5452 @return CRYPT_OK if successful |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5453 */ |
| 380 | 5454 int (*accel_ecb_decrypt)(const unsigned char *ct, |
| 5455 unsigned char *pt, | |
| 5456 unsigned long blocks, | |
| 5457 symmetric_key *skey); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5458 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5459 /** Accelerated CBC encryption |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5460 @param pt Plaintext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5461 @param ct Ciphertext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5462 @param blocks The number of complete blocks to process |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5463 @param IV The initial value (input/output) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5464 @param skey The scheduled key context |
| 380 | 5465 @return CRYPT_OK if successful |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5466 */ |
| 380 | 5467 int (*accel_cbc_encrypt)(const unsigned char *pt, |
| 5468 unsigned char *ct, | |
| 5469 unsigned long blocks, | |
| 5470 unsigned char *IV, | |
| 5471 symmetric_key *skey); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5472 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5473 /** Accelerated CBC decryption |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5474 @param pt Plaintext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5475 @param ct Ciphertext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5476 @param blocks The number of complete blocks to process |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5477 @param IV The initial value (input/output) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5478 @param skey The scheduled key context |
| 380 | 5479 @return CRYPT_OK if successful |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5480 */ |
| 380 | 5481 int (*accel_cbc_decrypt)(const unsigned char *ct, |
| 5482 unsigned char *pt, | |
| 5483 unsigned long blocks, | |
| 5484 unsigned char *IV, | |
| 5485 symmetric_key *skey); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5486 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5487 /** Accelerated CTR encryption |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5488 @param pt Plaintext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5489 @param ct Ciphertext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5490 @param blocks The number of complete blocks to process |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5491 @param IV The initial value (input/output) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5492 @param mode little or big endian counter (mode=0 or mode=1) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5493 @param skey The scheduled key context |
| 380 | 5494 @return CRYPT_OK if successful |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5495 */ |
| 380 | 5496 int (*accel_ctr_encrypt)(const unsigned char *pt, |
| 5497 unsigned char *ct, | |
| 5498 unsigned long blocks, | |
| 5499 unsigned char *IV, | |
| 5500 int mode, | |
| 5501 symmetric_key *skey); | |
| 5502 | |
| 5503 /** Accelerated LRW | |
| 5504 @param pt Plaintext | |
| 5505 @param ct Ciphertext | |
| 5506 @param blocks The number of complete blocks to process | |
| 5507 @param IV The initial value (input/output) | |
| 5508 @param tweak The LRW tweak | |
| 5509 @param skey The scheduled key context | |
| 5510 @return CRYPT_OK if successful | |
| 5511 */ | |
| 5512 int (*accel_lrw_encrypt)(const unsigned char *pt, | |
| 5513 unsigned char *ct, | |
| 5514 unsigned long blocks, | |
| 5515 unsigned char *IV, | |
| 5516 const unsigned char *tweak, | |
| 5517 symmetric_key *skey); | |
| 5518 | |
| 5519 /** Accelerated LRW | |
| 5520 @param ct Ciphertext | |
| 5521 @param pt Plaintext | |
| 5522 @param blocks The number of complete blocks to process | |
| 5523 @param IV The initial value (input/output) | |
| 5524 @param tweak The LRW tweak | |
| 5525 @param skey The scheduled key context | |
| 5526 @return CRYPT_OK if successful | |
| 5527 */ | |
| 5528 int (*accel_lrw_decrypt)(const unsigned char *ct, | |
| 5529 unsigned char *pt, | |
| 5530 unsigned long blocks, | |
| 5531 unsigned char *IV, | |
| 5532 const unsigned char *tweak, | |
| 5533 symmetric_key *skey); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5534 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5535 /** Accelerated CCM packet (one-shot) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5536 @param key The secret key to use |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5537 @param keylen The length of the secret key (octets) |
| 380 | 5538 @param uskey A previously scheduled key [can be NULL] |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5539 @param nonce The session nonce [use once] |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5540 @param noncelen The length of the nonce |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5541 @param header The header for the session |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5542 @param headerlen The length of the header (octets) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5543 @param pt [out] The plaintext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5544 @param ptlen The length of the plaintext (octets) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5545 @param ct [out] The ciphertext |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5546 @param tag [out] The destination tag |
| 380 | 5547 @param taglen [in/out] The max size and resulting size |
| 5548 of the authentication tag | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5549 @param direction Encrypt or Decrypt direction (0 or 1) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5550 @return CRYPT_OK if successful |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5551 */ |
| 380 | 5552 int (*accel_ccm_memory)( |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5553 const unsigned char *key, unsigned long keylen, |
| 380 | 5554 symmetric_key *uskey, |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5555 const unsigned char *nonce, unsigned long noncelen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5556 const unsigned char *header, unsigned long headerlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5557 unsigned char *pt, unsigned long ptlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5558 unsigned char *ct, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5559 unsigned char *tag, unsigned long *taglen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5560 int direction); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5561 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5562 /** Accelerated GCM packet (one shot) |
| 380 | 5563 @param key The secret key |
| 5564 @param keylen The length of the secret key | |
| 5565 @param IV The initial vector | |
| 5566 @param IVlen The length of the initial vector | |
| 5567 @param adata The additional authentication data (header) | |
| 5568 @param adatalen The length of the adata | |
| 5569 @param pt The plaintext | |
| 5570 @param ptlen The length of the plaintext/ciphertext | |
| 5571 @param ct The ciphertext | |
| 5572 @param tag [out] The MAC tag | |
| 5573 @param taglen [in/out] The MAC tag length | |
| 5574 @param direction Encrypt or Decrypt mode (GCM_ENCRYPT or GCM_DECRYPT) | |
| 5575 @return CRYPT_OK on success | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5576 */ |
| 380 | 5577 int (*accel_gcm_memory)( |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5578 const unsigned char *key, unsigned long keylen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5579 const unsigned char *IV, unsigned long IVlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5580 const unsigned char *adata, unsigned long adatalen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5581 unsigned char *pt, unsigned long ptlen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5582 unsigned char *ct, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5583 unsigned char *tag, unsigned long *taglen, |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5584 int direction); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5585 |
| 380 | 5586 /** Accelerated one shot OMAC |
| 5587 @param key The secret key | |
| 5588 @param keylen The key length (octets) | |
| 5589 @param in The message | |
| 5590 @param inlen Length of message (octets) | |
| 5591 @param out [out] Destination for tag | |
| 5592 @param outlen [in/out] Initial and final size of out | |
| 5593 @return CRYPT_OK on success | |
| 5594 */ | |
| 5595 int (*omac_memory)( | |
| 5596 const unsigned char *key, unsigned long keylen, | |
| 5597 const unsigned char *in, unsigned long inlen, | |
| 5598 unsigned char *out, unsigned long *outlen); | |
| 5599 | |
| 5600 /** Accelerated one shot XCBC | |
| 5601 @param key The secret key | |
| 5602 @param keylen The key length (octets) | |
| 5603 @param in The message | |
| 5604 @param inlen Length of message (octets) | |
| 5605 @param out [out] Destination for tag | |
| 5606 @param outlen [in/out] Initial and final size of out | |
| 5607 @return CRYPT_OK on success | |
| 5608 */ | |
| 5609 int (*xcbc_memory)( | |
| 5610 const unsigned char *key, unsigned long keylen, | |
| 5611 const unsigned char *in, unsigned long inlen, | |
| 5612 unsigned char *out, unsigned long *outlen); | |
| 5613 | |
| 5614 /** Accelerated one shot F9 | |
| 5615 @param key The secret key | |
| 5616 @param keylen The key length (octets) | |
| 5617 @param in The message | |
| 5618 @param inlen Length of message (octets) | |
| 5619 @param out [out] Destination for tag | |
| 5620 @param outlen [in/out] Initial and final size of out | |
| 5621 @return CRYPT_OK on success | |
| 5622 @remark Requires manual padding | |
| 5623 */ | |
| 5624 int (*f9_memory)( | |
| 5625 const unsigned char *key, unsigned long keylen, | |
| 5626 const unsigned char *in, unsigned long inlen, | |
| 5627 unsigned char *out, unsigned long *outlen); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5628 }; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5629 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5630 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5631 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5632 \subsection{Name} |
| 380 | 5633 \index{find\_cipher()} |
| 5634 The \textit{name} parameter specifies the name of the cipher. This is what a developer would pass to find\_cipher() to find the cipher in the descriptor | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5635 tables. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5636 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5637 \subsection{Internal ID} |
| 380 | 5638 This is a single byte Internal ID you can use to distinguish ciphers from each other. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5639 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5640 \subsection{Key Lengths} |
| 380 | 5641 The minimum key length is \textit{min\_key\_length} and is measured in octets. Similarly the maximum key length is \textit{max\_key\_length}. They can be equal |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5642 and both must valid key sizes for the cipher. Values in between are not assumed to be valid though they may be. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5643 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5644 \subsection{Block Length} |
| 380 | 5645 The size of the ciphers plaintext or ciphertext is \textit{block\_length} and is measured in octets. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5646 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5647 \subsection{Rounds} |
| 380 | 5648 Some ciphers allow different number of rounds to be used. Usually you just use the default. The default round count is \textit{default\_rounds}. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5649 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5650 \subsection{Setup} |
| 380 | 5651 To initialize a cipher (for ECB mode) the function setup() was provided. It accepts an array of key octets \textit{key} of length \textit{keylen} octets. The user |
| 5652 can specify the number of rounds they want through \textit{num\_rounds} where $num\_rounds = 0$ means use the default. The destination of a scheduled key is stored | |
| 5653 in \textit{skey}. | |
| 5654 | |
| 5655 Inside the \textit{symmetric\_key} union there is a \textit{void *data} which you can use to allocate data if you need a data structure that does not fit with the existing | |
| 5656 ones provided. Just make sure in your \textit{done()} function that you free the allocated memory. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5657 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5658 \subsection{Single block ECB} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5659 To process a single block in ECB mode the ecb\_encrypt() and ecb\_decrypt() functions were provided. The plaintext and ciphertext buffers are allowed to overlap so you |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5660 must make sure you do not overwrite the output before you are finished with the input. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5661 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5662 \subsection{Testing} |
| 380 | 5663 The test() function is used to self--test the \textit{device}. It takes no arguments and returns \textbf{CRYPT\_OK} if all is working properly. You may return |
| 5664 \textbf{CRYPT\_NOP} to indicate that no testing was performed. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5665 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5666 \subsection{Key Sizing} |
| 380 | 5667 Occasionally, a function will want to find a suitable key size to use since the input is oddly sized. The keysize() function is for this case. It accepts a |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5668 pointer to an integer which represents the desired size. The function then has to match it to the exact or a lower key size that is valid for the cipher. For |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5669 example, if the input is $25$ and $24$ is valid then it stores $24$ back in the pointed to integer. It must not round up and must return an error if the keysize |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5670 cannot be mapped to a valid key size for the cipher. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5671 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5672 \subsection{Acceleration} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5673 The next set of functions cover the accelerated functionality of the cipher descriptor. Any combination of these functions may be set to \textbf{NULL} to indicate |
| 380 | 5674 it is not supported. In those cases the software defaults are used (using the single ECB block routines). |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5675 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5676 \subsubsection{Accelerated ECB} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5677 These two functions are meant for cases where a user wants to encrypt (in ECB mode no less) an array of blocks. These functions are accessed |
| 380 | 5678 through the accel\_ecb\_encrypt and accel\_ecb\_decrypt pointers. The \textit{blocks} count is the number of complete blocks to process. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5679 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5680 \subsubsection{Accelerated CBC} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5681 These two functions are meant for accelerated CBC encryption. These functions are accessed through the accel\_cbc\_encrypt and accel\_cbc\_decrypt pointers. |
| 380 | 5682 The \textit{blocks} value is the number of complete blocks to process. The \textit{IV} is the CBC initial vector. It is an input upon calling this function and must be |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5683 updated by the function before returning. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5684 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5685 \subsubsection{Accelerated CTR} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5686 This function is meant for accelerated CTR encryption. It is accessible through the accel\_ctr\_encrypt pointer. |
| 380 | 5687 The \textit{blocks} value is the number of complete blocks to process. The \textit{IV} is the CTR counter vector. It is an input upon calling this function and must be |
| 5688 updated by the function before returning. The \textit{mode} value indicates whether the counter is big (mode = CTR\_COUNTER\_BIG\_ENDIAN) or | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5689 little (mode = CTR\_COUNTER\_LITTLE\_ENDIAN) endian. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5690 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5691 This function (and the way it's called) differs from the other two since ctr\_encrypt() allows any size input plaintext. The accelerator will only be |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5692 called if the following conditions are met. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5693 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5694 \begin{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5695 \item The accelerator is present |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5696 \item The CTR pad is empty |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5697 \item The remaining length of the input to process is greater than or equal to the block size. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5698 \end{enumerate} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5699 |
| 380 | 5700 The \textit{CTR pad} is empty when a multiple (including zero) blocks of text have been processed. That is, if you pass in seven bytes to AES--CTR mode you would have to |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5701 pass in a minimum of nine extra bytes before the accelerator could be called. The CTR accelerator must increment the counter (and store it back into the |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5702 buffer provided) before encrypting it to create the pad. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5703 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5704 The accelerator will only be used to encrypt whole blocks. Partial blocks are always handled in software. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5705 |
| 380 | 5706 \subsubsection{Accelerated LRW} |
| 5707 These functions are meant for accelerated LRW. They process blocks of input in lengths of multiples of 16 octets. They must accept the \textit{IV} and \textit{tweak} | |
| 5708 state variables and updated them prior to returning. Note that you may want to disable \textbf{LRW\_TABLES} in \textit{tomcrypt\_custom.h} if you intend | |
| 5709 to use accelerators for LRW. | |
| 5710 | |
| 5711 While both encrypt and decrypt accelerators are not required it is suggested as it makes lrw\_setiv() more efficient. | |
| 5712 | |
| 5713 Note that calling lrw\_done() will only invoke the cipher\_descriptor[].done() function on the \textit{symmetric\_key} parameter of the LRW state. That means | |
| 5714 if your device requires any (LRW specific) resources you should free them in your ciphers() done function. The simplest way to think of it is to write | |
| 5715 the plugin solely to do LRW with the cipher. That way cipher\_descriptor[].setup() means to init LRW resources and cipher\_descriptor[].done() means to | |
| 5716 free them. | |
| 5717 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5718 \subsubsection{Accelerated CCM} |
| 380 | 5719 This function is meant for accelerated CCM encryption or decryption. It processes the entire packet in one call. You can optimize the work flow somewhat |
| 5720 by allowing the caller to call the setup() function first to schedule the key if your accelerator cannot do the key schedule on the fly (for instance). This | |
| 5721 function MUST support both key passing methods. | |
| 5722 | |
| 5723 \begin{center} | |
| 5724 \begin{small} | |
| 5725 \begin{tabular}{|r|r|l|} | |
| 5726 \hline \textbf{key} & \textbf{uskey} & \textbf{Source of key} \\ | |
| 5727 \hline NULL & NULL & Error, not supported \\ | |
| 5728 \hline non-NULL & NULL & Use key, do a key schedule \\ | |
| 5729 \hline NULL & non-NULL & Use uskey, key schedule not required \\ | |
| 5730 \hline non-NULL & non-NULL & Use uskey, key schedule not required \\ | |
| 5731 \hline | |
| 5732 \end{tabular} | |
| 5733 \end{small} | |
| 5734 \end{center} | |
| 5735 | |
| 5736 \index{ccm\_memory()} This function is called when the user calls ccm\_memory(). | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5737 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5738 \subsubsection{Accelerated GCM} |
| 380 | 5739 \index{gcm\_memory()} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5740 This function is meant for accelerated GCM encryption or decryption. It processes the entire packet in one call. Note that the setup() function will not |
| 380 | 5741 be called prior to this. This function must handle scheduling the key provided on its own. It is called when the user calls gcm\_memory(). |
| 5742 | |
| 5743 \subsubsection{Accelerated OMAC} | |
| 5744 \index{omac\_memory()} | |
| 5745 This function is meant to perform an optimized OMAC1 (CMAC) message authentication code computation when the user calls omac\_memory(). | |
| 5746 | |
| 5747 \subsubsection{Accelerated XCBC-MAC} | |
| 5748 \index{xcbc\_memory()} | |
| 5749 This function is meant to perform an optimized XCBC-MAC message authentication code computation when the user calls xcbc\_memory(). | |
| 5750 | |
| 5751 \subsubsection{Accelerated F9} | |
| 5752 \index{f9\_memory()} | |
| 5753 This function is meant to perform an optimized F9 message authentication code computation when the user calls f9\_memory(). Like f9\_memory(), it requires | |
| 5754 the caller to perform any 3GPP related padding before calling in order to ensure proper compliance with F9. | |
| 5755 | |
| 5756 | |
| 5757 \mysection{One--Way Hashes} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5758 The hash functions are accessed through the ltc\_hash\_descriptor structure. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5759 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5760 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5761 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5762 struct ltc_hash_descriptor { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5763 /** name of hash */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5764 char *name; |
| 380 | 5765 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5766 /** internal ID */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5767 unsigned char ID; |
| 380 | 5768 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5769 /** Size of digest in octets */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5770 unsigned long hashsize; |
| 380 | 5771 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5772 /** Input block size in octets */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5773 unsigned long blocksize; |
| 380 | 5774 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5775 /** ASN.1 OID */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5776 unsigned long OID[16]; |
| 380 | 5777 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5778 /** Length of DER encoding */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5779 unsigned long OIDlen; |
| 380 | 5780 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5781 /** Init a hash state |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5782 @param hash The hash to initialize |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5783 @return CRYPT_OK if successful |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5784 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5785 int (*init)(hash_state *hash); |
| 380 | 5786 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5787 /** Process a block of data |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5788 @param hash The hash state |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5789 @param in The data to hash |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5790 @param inlen The length of the data (octets) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5791 @return CRYPT_OK if successful |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5792 */ |
| 380 | 5793 int (*process)( hash_state *hash, |
| 5794 const unsigned char *in, | |
| 5795 unsigned long inlen); | |
| 5796 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5797 /** Produce the digest and store it |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5798 @param hash The hash state |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5799 @param out [out] The destination of the digest |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5800 @return CRYPT_OK if successful |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5801 */ |
| 380 | 5802 int (*done)( hash_state *hash, |
| 5803 unsigned char *out); | |
| 5804 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5805 /** Self-test |
| 380 | 5806 @return CRYPT_OK if successful, |
| 5807 CRYPT_NOP if self-tests have been disabled | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5808 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5809 int (*test)(void); |
| 380 | 5810 |
| 5811 /* accelerated hmac callback: if you need to-do | |
| 5812 multiple packets just use the generic hmac_memory | |
| 5813 and provide a hash callback | |
| 5814 */ | |
| 5815 int (*hmac_block)(const unsigned char *key, | |
| 5816 unsigned long keylen, | |
| 5817 const unsigned char *in, | |
| 5818 unsigned long inlen, | |
| 5819 unsigned char *out, | |
| 5820 unsigned long *outlen); | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5821 }; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5822 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5823 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5824 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5825 \subsection{Name} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5826 This is the name the hash is known by and what find\_hash() will look for. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5827 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5828 \subsection{Internal ID} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5829 This is the internal ID byte used to distinguish the hash from other hashes. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5830 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5831 \subsection{Digest Size} |
| 380 | 5832 The \textit{hashsize} variable indicates the length of the output in octets. |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5833 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5834 \subsection{Block Size} |
| 380 | 5835 The \textit{blocksize} variable indicates the length of input (in octets) that the hash processes in a given |
| 5836 invocation. | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5837 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5838 \subsection{OID Identifier} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5839 This is the universal ASN.1 Object Identifier for the hash. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5840 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5841 \subsection{Initialization} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5842 The init function initializes the hash and prepares it to process message bytes. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5843 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5844 \subsection{Process} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5845 This processes message bytes. The algorithm must accept any length of input that the hash would allow. The input is not |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5846 guaranteed to be a multiple of the block size in length. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5847 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5848 \subsection{Done} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5849 The done function terminates the hash and returns the message digest. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5850 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5851 \subsection{Acceleration} |
| 380 | 5852 A compatible accelerator must allow processing data in any granularity which may require internal padding on the driver side. |
| 5853 | |
| 5854 \subsection{HMAC Acceleration} | |
| 5855 The hmac\_block() callback is meant for single--shot optimized HMAC implementations. It is called directly by hmac\_memory() if present. If you need | |
| 5856 to be able to process multiple blocks per MAC then you will have to simply provide a process() callback and use hmac\_memory() as provided in LibTomCrypt. | |
| 5857 | |
| 5858 \mysection{Pseudo--Random Number Generators} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5859 The pseudo--random number generators are accessible through the ltc\_prng\_descriptor structure. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5860 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5861 \begin{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5862 \begin{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5863 struct ltc_prng_descriptor { |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5864 /** Name of the PRNG */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5865 char *name; |
| 380 | 5866 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5867 /** size in bytes of exported state */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5868 int export_size; |
| 380 | 5869 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5870 /** Start a PRNG state |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5871 @param prng [out] The state to initialize |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5872 @return CRYPT_OK if successful |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5873 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5874 int (*start)(prng_state *prng); |
| 380 | 5875 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5876 /** Add entropy to the PRNG |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5877 @param in The entropy |
| 380 | 5878 @param inlen Length of the entropy (octets) |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5879 @param prng The PRNG state |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5880 @return CRYPT_OK if successful |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5881 */ |
| 380 | 5882 int (*add_entropy)(const unsigned char *in, |
| 5883 unsigned long inlen, | |
| 5884 prng_state *prng); | |
| 5885 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5886 /** Ready a PRNG state to read from |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5887 @param prng The PRNG state to ready |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5888 @return CRYPT_OK if successful |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5889 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5890 int (*ready)(prng_state *prng); |
| 380 | 5891 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5892 /** Read from the PRNG |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5893 @param out [out] Where to store the data |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5894 @param outlen Length of data desired (octets) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5895 @param prng The PRNG state to read from |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5896 @return Number of octets read |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5897 */ |
| 380 | 5898 unsigned long (*read)(unsigned char *out, |
| 5899 unsigned long outlen, | |
| 5900 prng_state *prng); | |
| 5901 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5902 /** Terminate a PRNG state |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5903 @param prng The PRNG state to terminate |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5904 @return CRYPT_OK if successful |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5905 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5906 int (*done)(prng_state *prng); |
| 380 | 5907 |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5908 /** Export a PRNG state |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5909 @param out [out] The destination for the state |
| 380 | 5910 @param outlen [in/out] The max size and resulting size |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5911 @param prng The PRNG to export |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5912 @return CRYPT_OK if successful |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5913 */ |
| 380 | 5914 int (*pexport)(unsigned char *out, |
| 5915 unsigned long *outlen, | |
| 5916 prng_state *prng); | |
| 5917 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5918 /** Import a PRNG state |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5919 @param in The data to import |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5920 @param inlen The length of the data to import (octets) |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5921 @param prng The PRNG to initialize/import |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5922 @return CRYPT_OK if successful |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5923 */ |
| 380 | 5924 int (*pimport)(const unsigned char *in, |
| 5925 unsigned long inlen, | |
| 5926 prng_state *prng); | |
| 5927 | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5928 /** Self-test the PRNG |
| 380 | 5929 @return CRYPT_OK if successful, |
| 5930 CRYPT_NOP if self-testing has been disabled | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5931 */ |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5932 int (*test)(void); |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5933 }; |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5934 \end{verbatim} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5935 \end{small} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5936 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5937 \subsection{Name} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5938 The name by which find\_prng() will find the PRNG. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5939 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5940 \subsection{Export Size} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5941 When an PRNG state is to be exported for future use you specify the space required in this variable. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5942 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5943 \subsection{Start} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5944 Initialize the PRNG and make it ready to accept entropy. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5945 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5946 \subsection{Entropy Addition} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5947 Add entropy to the PRNG state. The exact behaviour of this function depends on the particulars of the PRNG. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5948 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5949 \subsection{Ready} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5950 This function makes the PRNG ready to read from by processing the entropy added. The behaviour of this function depends |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5951 on the specific PRNG used. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5952 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5953 \subsection{Read} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5954 Read from the PRNG and return the number of bytes read. This function does not have to fill the buffer but it is best |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5955 if it does as many protocols do not retry reads and will fail on the first try. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5956 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5957 \subsection{Done} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5958 Terminate a PRNG state. The behaviour of this function depends on the particular PRNG used. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5959 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5960 \subsection{Exporting and Importing} |
| 380 | 5961 An exported PRNG state is data that the PRNG can later import to resume activity. They're not meant to resume \textit{the same session} |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5962 but should at least maintain the same level of state entropy. |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
5963 |
| 380 | 5964 \mysection{BigNum Math Descriptors} |
| 5965 The library also makes use of the math descriptors to access math functions. While bignum math libraries usually differ in implementation | |
| 5966 it hasn't proven hard to write \textit{glue} to use math libraries so far. The basic descriptor looks like. | |
| 5967 | |
| 5968 \begin{small} | |
| 5969 \begin{verbatim} | |
| 5970 /** math descriptor */ | |
| 5971 typedef struct { | |
| 5972 /** Name of the math provider */ | |
| 5973 char *name; | |
| 5974 | |
| 5975 /** Bits per digit, amount of bits must fit in an unsigned long */ | |
| 5976 int bits_per_digit; | |
| 5977 | |
| 5978 /* ---- init/deinit functions ---- */ | |
| 5979 | |
| 5980 /** initialize a bignum | |
| 5981 @param a The number to initialize | |
| 5982 @return CRYPT_OK on success | |
| 5983 */ | |
| 5984 int (*init)(void **a); | |
| 5985 | |
| 5986 /** init copy | |
| 5987 @param dst The number to initialize and write to | |
| 5988 @param src The number to copy from | |
| 5989 @return CRYPT_OK on success | |
| 5990 */ | |
| 5991 int (*init_copy)(void **dst, void *src); | |
| 5992 | |
| 5993 /** deinit | |
| 5994 @param a The number to free | |
| 5995 @return CRYPT_OK on success | |
| 5996 */ | |
| 5997 void (*deinit)(void *a); | |
| 5998 | |
| 5999 /* ---- data movement ---- */ | |
| 6000 | |
| 6001 /** copy | |
| 6002 @param src The number to copy from | |
| 6003 @param dst The number to write to | |
| 6004 @return CRYPT_OK on success | |
| 6005 */ | |
| 6006 int (*copy)(void *src, void *dst); | |
| 6007 | |
| 6008 /* ---- trivial low level functions ---- */ | |
| 6009 | |
| 6010 /** set small constant | |
| 6011 @param a Number to write to | |
| 6012 @param n Source upto bits_per_digit (meant for small constants) | |
| 6013 @return CRYPT_OK on success | |
| 6014 */ | |
| 6015 int (*set_int)(void *a, unsigned long n); | |
| 6016 | |
| 6017 /** get small constant | |
| 6018 @param a Small number to read | |
| 6019 @return The lower bits_per_digit of the integer (unsigned) | |
| 6020 */ | |
| 6021 unsigned long (*get_int)(void *a); | |
| 6022 | |
| 6023 /** get digit n | |
| 6024 @param a The number to read from | |
| 6025 @param n The number of the digit to fetch | |
| 6026 @return The bits_per_digit sized n'th digit of a | |
| 6027 */ | |
| 6028 unsigned long (*get_digit)(void *a, int n); | |
| 6029 | |
| 6030 /** Get the number of digits that represent the number | |
| 6031 @param a The number to count | |
| 6032 @return The number of digits used to represent the number | |
| 6033 */ | |
| 6034 int (*get_digit_count)(void *a); | |
| 6035 | |
| 6036 /** compare two integers | |
| 6037 @param a The left side integer | |
| 6038 @param b The right side integer | |
| 6039 @return LTC_MP_LT if a < b, | |
| 6040 LTC_MP_GT if a > b and | |
| 6041 LTC_MP_EQ otherwise. (signed comparison) | |
| 6042 */ | |
| 6043 int (*compare)(void *a, void *b); | |
| 6044 | |
| 6045 /** compare against int | |
| 6046 @param a The left side integer | |
| 6047 @param b The right side integer (upto bits_per_digit) | |
| 6048 @return LTC_MP_LT if a < b, | |
| 6049 LTC_MP_GT if a > b and | |
| 6050 LTC_MP_EQ otherwise. (signed comparison) | |
| 6051 */ | |
| 6052 int (*compare_d)(void *a, unsigned long n); | |
| 6053 | |
| 6054 /** Count the number of bits used to represent the integer | |
| 6055 @param a The integer to count | |
| 6056 @return The number of bits required to represent the integer | |
| 6057 */ | |
| 6058 int (*count_bits)(void * a); | |
| 6059 | |
| 6060 /** Count the number of LSB bits which are zero | |
| 6061 @param a The integer to count | |
| 6062 @return The number of contiguous zero LSB bits | |
| 6063 */ | |
| 6064 int (*count_lsb_bits)(void *a); | |
| 6065 | |
| 6066 /** Compute a power of two | |
| 6067 @param a The integer to store the power in | |
| 6068 @param n The power of two you want to store (a = 2^n) | |
| 6069 @return CRYPT_OK on success | |
| 6070 */ | |
| 6071 int (*twoexpt)(void *a , int n); | |
| 6072 | |
| 6073 /* ---- radix conversions ---- */ | |
| 6074 | |
| 6075 /** read ascii string | |
| 6076 @param a The integer to store into | |
| 6077 @param str The string to read | |
| 6078 @param radix The radix the integer has been represented in (2-64) | |
| 6079 @return CRYPT_OK on success | |
| 6080 */ | |
| 6081 int (*read_radix)(void *a, const char *str, int radix); | |
| 6082 | |
| 6083 /** write number to string | |
| 6084 @param a The integer to store | |
| 6085 @param str The destination for the string | |
| 6086 @param radix The radix the integer is to be represented in (2-64) | |
| 6087 @return CRYPT_OK on success | |
| 6088 */ | |
| 6089 int (*write_radix)(void *a, char *str, int radix); | |
| 6090 | |
| 6091 /** get size as unsigned char string | |
| 6092 @param a The integer to get the size | |
| 6093 @return The length of the integer in octets | |
| 6094 */ | |
| 6095 unsigned long (*unsigned_size)(void *a); | |
| 6096 | |
| 6097 /** store an integer as an array of octets | |
| 6098 @param src The integer to store | |
| 6099 @param dst The buffer to store the integer in | |
| 6100 @return CRYPT_OK on success | |
| 6101 */ | |
| 6102 int (*unsigned_write)(void *src, unsigned char *dst); | |
| 6103 | |
| 6104 /** read an array of octets and store as integer | |
| 6105 @param dst The integer to load | |
| 6106 @param src The array of octets | |
| 6107 @param len The number of octets | |
| 6108 @return CRYPT_OK on success | |
| 6109 */ | |
| 6110 int (*unsigned_read)( void *dst, | |
| 6111 unsigned char *src, | |
| 6112 unsigned long len); | |
| 6113 | |
| 6114 /* ---- basic math ---- */ | |
| 6115 | |
| 6116 /** add two integers | |
| 6117 @param a The first source integer | |
| 6118 @param b The second source integer | |
| 6119 @param c The destination of "a + b" | |
| 6120 @return CRYPT_OK on success | |
| 6121 */ | |
| 6122 int (*add)(void *a, void *b, void *c); | |
| 6123 | |
| 6124 /** add two integers | |
| 6125 @param a The first source integer | |
| 6126 @param b The second source integer | |
| 6127 (single digit of upto bits_per_digit in length) | |
| 6128 @param c The destination of "a + b" | |
| 6129 @return CRYPT_OK on success | |
| 6130 */ | |
| 6131 int (*addi)(void *a, unsigned long b, void *c); | |
| 6132 | |
| 6133 /** subtract two integers | |
| 6134 @param a The first source integer | |
| 6135 @param b The second source integer | |
| 6136 @param c The destination of "a - b" | |
| 6137 @return CRYPT_OK on success | |
| 6138 */ | |
| 6139 int (*sub)(void *a, void *b, void *c); | |
| 6140 | |
| 6141 /** subtract two integers | |
| 6142 @param a The first source integer | |
| 6143 @param b The second source integer | |
| 6144 (single digit of upto bits_per_digit in length) | |
| 6145 @param c The destination of "a - b" | |
| 6146 @return CRYPT_OK on success | |
| 6147 */ | |
| 6148 int (*subi)(void *a, unsigned long b, void *c); | |
| 6149 | |
| 6150 /** multiply two integers | |
| 6151 @param a The first source integer | |
| 6152 @param b The second source integer | |
| 6153 (single digit of upto bits_per_digit in length) | |
| 6154 @param c The destination of "a * b" | |
| 6155 @return CRYPT_OK on success | |
| 6156 */ | |
| 6157 int (*mul)(void *a, void *b, void *c); | |
| 6158 | |
| 6159 /** multiply two integers | |
| 6160 @param a The first source integer | |
| 6161 @param b The second source integer | |
| 6162 (single digit of upto bits_per_digit in length) | |
| 6163 @param c The destination of "a * b" | |
| 6164 @return CRYPT_OK on success | |
| 6165 */ | |
| 6166 int (*muli)(void *a, unsigned long b, void *c); | |
| 6167 | |
| 6168 /** Square an integer | |
| 6169 @param a The integer to square | |
| 6170 @param b The destination | |
| 6171 @return CRYPT_OK on success | |
| 6172 */ | |
| 6173 int (*sqr)(void *a, void *b); | |
| 6174 | |
| 6175 /** Divide an integer | |
| 6176 @param a The dividend | |
| 6177 @param b The divisor | |
| 6178 @param c The quotient (can be NULL to signify don't care) | |
| 6179 @param d The remainder (can be NULL to signify don't care) | |
| 6180 @return CRYPT_OK on success | |
| 6181 */ | |
| 6182 int (*div)(void *a, void *b, void *c, void *d); | |
| 6183 | |
| 6184 /** divide by two | |
| 6185 @param a The integer to divide (shift right) | |
| 6186 @param b The destination | |
| 6187 @return CRYPT_OK on success | |
| 6188 */ | |
| 6189 int (*div_2)(void *a, void *b); | |
| 6190 | |
| 6191 /** Get remainder (small value) | |
| 6192 @param a The integer to reduce | |
| 6193 @param b The modulus (upto bits_per_digit in length) | |
| 6194 @param c The destination for the residue | |
| 6195 @return CRYPT_OK on success | |
| 6196 */ | |
| 6197 int (*modi)(void *a, unsigned long b, unsigned long *c); | |
| 6198 | |
| 6199 /** gcd | |
| 6200 @param a The first integer | |
| 6201 @param b The second integer | |
| 6202 @param c The destination for (a, b) | |
| 6203 @return CRYPT_OK on success | |
| 6204 */ | |
| 6205 int (*gcd)(void *a, void *b, void *c); | |
| 6206 | |
| 6207 /** lcm | |
| 6208 @param a The first integer | |
| 6209 @param b The second integer | |
| 6210 @param c The destination for [a, b] | |
| 6211 @return CRYPT_OK on success | |
| 6212 */ | |
| 6213 int (*lcm)(void *a, void *b, void *c); | |
| 6214 | |
| 6215 /** Modular multiplication | |
| 6216 @param a The first source | |
| 6217 @param b The second source | |
| 6218 @param c The modulus | |
| 6219 @param d The destination (a*b mod c) | |
| 6220 @return CRYPT_OK on success | |
| 6221 */ | |
| 6222 int (*mulmod)(void *a, void *b, void *c, void *d); | |
| 6223 | |
| 6224 /** Modular squaring | |
| 6225 @param a The first source | |
| 6226 @param b The modulus | |
| 6227 @param c The destination (a*a mod b) | |
| 6228 @return CRYPT_OK on success | |
| 6229 */ | |
| 6230 int (*sqrmod)(void *a, void *b, void *c); | |
| 6231 | |
| 6232 /** Modular inversion | |
| 6233 @param a The value to invert | |
| 6234 @param b The modulus | |
| 6235 @param c The destination (1/a mod b) | |
| 6236 @return CRYPT_OK on success | |
| 6237 */ | |
| 6238 int (*invmod)(void *, void *, void *); | |
| 6239 | |
| 6240 /* ---- reduction ---- */ | |
| 6241 | |
| 6242 /** setup Montgomery | |
| 6243 @param a The modulus | |
| 6244 @param b The destination for the reduction digit | |
| 6245 @return CRYPT_OK on success | |
| 6246 */ | |
| 6247 int (*montgomery_setup)(void *a, void **b); | |
| 6248 | |
| 6249 /** get normalization value | |
| 6250 @param a The destination for the normalization value | |
| 6251 @param b The modulus | |
| 6252 @return CRYPT_OK on success | |
| 6253 */ | |
| 6254 int (*montgomery_normalization)(void *a, void *b); | |
| 6255 | |
| 6256 /** reduce a number | |
| 6257 @param a The number [and dest] to reduce | |
| 6258 @param b The modulus | |
| 6259 @param c The value "b" from montgomery_setup() | |
| 6260 @return CRYPT_OK on success | |
| 6261 */ | |
| 6262 int (*montgomery_reduce)(void *a, void *b, void *c); | |
| 6263 | |
| 6264 /** clean up (frees memory) | |
| 6265 @param a The value "b" from montgomery_setup() | |
| 6266 @return CRYPT_OK on success | |
| 6267 */ | |
| 6268 void (*montgomery_deinit)(void *a); | |
| 6269 | |
| 6270 /* ---- exponentiation ---- */ | |
| 6271 | |
| 6272 /** Modular exponentiation | |
| 6273 @param a The base integer | |
| 6274 @param b The power (can be negative) integer | |
| 6275 @param c The modulus integer | |
| 6276 @param d The destination | |
| 6277 @return CRYPT_OK on success | |
| 6278 */ | |
| 6279 int (*exptmod)(void *a, void *b, void *c, void *d); | |
| 6280 | |
| 6281 /** Primality testing | |
| 6282 @param a The integer to test | |
| 6283 @param b The destination of the result (FP_YES if prime) | |
| 6284 @return CRYPT_OK on success | |
| 6285 */ | |
| 6286 int (*isprime)(void *a, int *b); | |
| 6287 | |
| 6288 /* ---- (optional) ecc point math ---- */ | |
| 6289 | |
| 6290 /** ECC GF(p) point multiplication (from the NIST curves) | |
| 6291 @param k The integer to multiply the point by | |
| 6292 @param G The point to multiply | |
| 6293 @param R The destination for kG | |
| 6294 @param modulus The modulus for the field | |
| 6295 @param map Boolean indicated whether to map back to affine or not | |
| 6296 (can be ignored if you work in affine only) | |
| 6297 @return CRYPT_OK on success | |
| 6298 */ | |
| 6299 int (*ecc_ptmul)( void *k, | |
| 6300 ecc_point *G, | |
| 6301 ecc_point *R, | |
| 6302 void *modulus, | |
| 6303 int map); | |
| 6304 | |
| 6305 /** ECC GF(p) point addition | |
| 6306 @param P The first point | |
| 6307 @param Q The second point | |
| 6308 @param R The destination of P + Q | |
| 6309 @param modulus The modulus | |
| 6310 @param mp The "b" value from montgomery_setup() | |
| 6311 @return CRYPT_OK on success | |
| 6312 */ | |
| 6313 int (*ecc_ptadd)(ecc_point *P, | |
| 6314 ecc_point *Q, | |
| 6315 ecc_point *R, | |
| 6316 void *modulus, | |
| 6317 void *mp); | |
| 6318 | |
| 6319 /** ECC GF(p) point double | |
| 6320 @param P The first point | |
| 6321 @param R The destination of 2P | |
| 6322 @param modulus The modulus | |
| 6323 @param mp The "b" value from montgomery_setup() | |
| 6324 @return CRYPT_OK on success | |
| 6325 */ | |
| 6326 int (*ecc_ptdbl)(ecc_point *P, | |
| 6327 ecc_point *R, | |
| 6328 void *modulus, | |
| 6329 void *mp); | |
| 6330 | |
| 6331 /** ECC mapping from projective to affine, | |
| 6332 currently uses (x,y,z) => (x/z^2, y/z^3, 1) | |
| 6333 @param P The point to map | |
| 6334 @param modulus The modulus | |
| 6335 @param mp The "b" value from montgomery_setup() | |
| 6336 @return CRYPT_OK on success | |
| 6337 @remark The mapping can be different but keep in mind a | |
| 6338 ecc_point only has three integers (x,y,z) so if | |
| 6339 you use a different mapping you have to make it fit. | |
| 6340 */ | |
| 6341 int (*ecc_map)(ecc_point *P, void *modulus, void *mp); | |
| 6342 | |
| 6343 /** Computes kA*A + kB*B = C using Shamir's Trick | |
| 6344 @param A First point to multiply | |
| 6345 @param kA What to multiple A by | |
| 6346 @param B Second point to multiply | |
| 6347 @param kB What to multiple B by | |
| 6348 @param C [out] Destination point (can overlap with A or B) | |
| 6349 @param modulus Modulus for curve | |
| 6350 @return CRYPT_OK on success | |
| 6351 */ | |
| 6352 int (*ecc_mul2add)(ecc_point *A, void *kA, | |
| 6353 ecc_point *B, void *kB, | |
| 6354 ecc_point *C, | |
| 6355 void *modulus); | |
| 6356 | |
| 6357 | |
| 6358 /* ---- (optional) rsa optimized math (for internal CRT) ---- */ | |
| 6359 | |
| 6360 /** RSA Key Generation | |
| 6361 @param prng An active PRNG state | |
| 6362 @param wprng The index of the PRNG desired | |
| 6363 @param size The size of the key in octets | |
| 6364 @param e The "e" value (public key). | |
| 6365 e==65537 is a good choice | |
| 6366 @param key [out] Destination of a newly created private key pair | |
| 6367 @return CRYPT_OK if successful, upon error all allocated ram is freed | |
| 6368 */ | |
| 6369 int (*rsa_keygen)(prng_state *prng, | |
| 6370 int wprng, | |
| 6371 int size, | |
| 6372 long e, | |
| 6373 rsa_key *key); | |
| 6374 | |
| 6375 /** RSA exponentiation | |
| 6376 @param in The octet array representing the base | |
| 6377 @param inlen The length of the input | |
| 6378 @param out The destination (to be stored in an octet array format) | |
| 6379 @param outlen The length of the output buffer and the resulting size | |
| 6380 (zero padded to the size of the modulus) | |
| 6381 @param which PK_PUBLIC for public RSA and PK_PRIVATE for private RSA | |
| 6382 @param key The RSA key to use | |
| 6383 @return CRYPT_OK on success | |
| 6384 */ | |
| 6385 int (*rsa_me)(const unsigned char *in, unsigned long inlen, | |
| 6386 unsigned char *out, unsigned long *outlen, int which, | |
| 6387 rsa_key *key); | |
| 6388 } ltc_math_descriptor; | |
| 6389 \end{verbatim} | |
| 6390 \end{small} | |
| 6391 | |
| 6392 Most of the functions are fairly straightforward and do not need documentation. We'll cover the basic conventions of the API and then explain the accelerated functions. | |
| 6393 | |
| 6394 \subsection{Conventions} | |
| 6395 | |
| 6396 All \textit{bignums} are accessed through an opaque \textit{void *} data type. You must internally cast the pointer if you need to access members of your bignum structure. During | |
| 6397 the init calls a \textit{void **} will be passed where you allocate your structure and set the pointer then initialize the number to zero. During the deinit calls you must | |
| 6398 free the bignum as well as the structure you allocated to place it in. | |
| 6399 | |
| 6400 All functions except the Montgomery reductions work from left to right with the arguments. For example, mul(a, b, c) computes $c \leftarrow ab$. | |
| 6401 | |
| 6402 All functions (except where noted otherwise) return \textbf{CRYPT\_OK} to signify a successful operation. All error codes must be valid LibTomCrypt error codes. | |
| 6403 | |
| 6404 The digit routines (including functions with the \textit{i} suffix) use a \textit{unsigned long} to represent the digit. If your internal digit is larger than this you must | |
| 6405 then partition your digits. Normally this does not matter as \textit{unsigned long} will be the same size as your register size. Note that if your digit is smaller | |
| 6406 than an \textit{unsigned long} that is also acceptable as the \textit{bits\_per\_digit} parameter will specify this. | |
| 6407 | |
| 6408 \subsection{ECC Functions} | |
| 6409 The ECC system in LibTomCrypt is based off of the NIST recommended curves over $GF(p)$ and is used to implement EC-DSA and EC-DH. The ECC functions work with | |
| 6410 the \textbf{ecc\_point} structure and assume the points are stored in Jacobian projective format. | |
| 6411 | |
| 6412 \begin{verbatim} | |
| 6413 /** A point on a ECC curve, stored in Jacobian format such | |
| 6414 that (x,y,z) => (x/z^2, y/z^3, 1) when interpreted as affine */ | |
| 6415 typedef struct { | |
| 6416 /** The x co-ordinate */ | |
| 6417 void *x; | |
| 6418 /** The y co-ordinate */ | |
| 6419 void *y; | |
| 6420 /** The z co-ordinate */ | |
| 6421 void *z; | |
| 6422 } ecc_point; | |
| 6423 \end{verbatim} | |
| 6424 | |
| 6425 All ECC functions must use this mapping system. The only exception is when you remap all ECC callbacks which will allow you to have more control | |
| 6426 over how the ECC math will be implemented. Out of the box you only have three parameters per point to use $(x, y, z)$ however, these are just void pointers. They | |
| 6427 could point to anything you want. The only further exception is the export functions which expects the values to be in affine format. | |
| 6428 | |
| 6429 \subsubsection{Point Multiply} | |
| 6430 This will multiply the point $G$ by the scalar $k$ and store the result in the point $R$. The value should be mapped to affine only if $map$ is set to one. | |
| 6431 | |
| 6432 \subsubsection{Point Addition} | |
| 6433 This will add the point $P$ to the point $Q$ and store it in the point $R$. The $mp$ parameter is the \textit{b} value from the montgomery\_setup() call. The input points | |
| 6434 may be in either affine (with $z = 1$) or projective format and the output point is always projective. | |
| 6435 | |
| 6436 \subsubsection{Point Mapping} | |
| 6437 This will map the point $P$ back from projective to affine. The output point $P$ must be of the form $(x, y, 1)$. | |
| 6438 | |
| 6439 \subsubsection{Shamir's Trick} | |
| 6440 \index{Shamir's Trick} | |
| 6441 \index{ltc\_ecc\_mul2add()} | |
| 6442 To accelerate EC--DSA verification the library provides a built--in function called ltc\_ecc\_mul2add(). This performs two point multiplications and an addition in | |
| 6443 roughly the time of one point multiplication. It is called from ecc\_verify\_hash() if an accelerator is not present. The acclerator function must allow the points to | |
| 6444 overlap (e.g., $A \leftarrow k_1A + k_2B$) and must return the final point in affine format. | |
| 6445 | |
| 6446 | |
| 6447 \subsection{RSA Functions} | |
| 6448 The RSA Modular Exponentiation (ME) function is used by the RSA API to perform exponentiations for private and public key operations. In particular for | |
| 6449 private key operations it uses the CRT approach to lower the time required. It is passed an RSA key with the following format. | |
| 6450 | |
| 6451 \begin{verbatim} | |
| 6452 /** RSA PKCS style key */ | |
| 6453 typedef struct Rsa_key { | |
| 6454 /** Type of key, PK_PRIVATE or PK_PUBLIC */ | |
| 6455 int type; | |
| 6456 /** The public exponent */ | |
| 6457 void *e; | |
| 6458 /** The private exponent */ | |
| 6459 void *d; | |
| 6460 /** The modulus */ | |
| 6461 void *N; | |
| 6462 /** The p factor of N */ | |
| 6463 void *p; | |
| 6464 /** The q factor of N */ | |
| 6465 void *q; | |
| 6466 /** The 1/q mod p CRT param */ | |
| 6467 void *qP; | |
| 6468 /** The d mod (p - 1) CRT param */ | |
| 6469 void *dP; | |
| 6470 /** The d mod (q - 1) CRT param */ | |
| 6471 void *dQ; | |
| 6472 } rsa_key; | |
| 6473 \end{verbatim} | |
| 6474 | |
| 6475 The call reads the \textit{in} buffer as an unsigned char array in big endian format. Then it performs the exponentiation and stores the output in big endian format | |
| 6476 to the \textit{out} buffer. The output must be zero padded (leading bytes) so that the length of the output matches the length of the modulus (in bytes). For example, | |
| 6477 for RSA--1024 the output is always 128 bytes regardless of how small the numerical value of the exponentiation is. | |
| 6478 | |
| 6479 Since the function is given the entire RSA key (for private keys only) CRT is possible as prescribed in the PKCS \#1 v2.1 specification. | |
| 6480 | |
| 6481 \newpage | |
| 6482 \markboth{Index}{Index} | |
|
280
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
6483 \input{crypt.ind} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
6484 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
6485 \end{document} |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
6486 |
|
59400faa4b44
Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff
changeset
|
6487 % $Source: /cvs/libtom/libtomcrypt/crypt.tex,v $ |
| 380 | 6488 % $Revision: 1.123 $ |
| 6489 % $Date: 2006/12/16 19:08:17 $ |