dropbear: crypt.tex annotate

annotate crypt.tex @ 281:997e6f7dc01e libtomcrypt-dropbear

Just import the Dropbear 0.47 libtomcrypt changes

author	Matt Johnston <matt@ucc.asn.au>
date	Wed, 08 Mar 2006 13:02:58 +0000
parents	59400faa4b44
children	d5faf4814ddb

rev	line source
280 59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1 \documentclass[a4paper]{book}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2 \usepackage{hyperref}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3 \usepackage{makeidx}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4 \usepackage{amssymb}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	5 \usepackage{color}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	6 \usepackage{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	7 \usepackage{graphicx}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	8 \usepackage{layout}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	9 \def\union{\cup}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	10 \def\intersect{\cap}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	11 \def\getsrandom{\stackrel{\rm R}{\gets}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	12 \def\cross{\times}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	13 \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	14 \def\catn{$\\|$}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	15 \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	16 \def\nequiv{\not\equiv}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	17 \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	18 \def\lcm{{\rm lcm}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	19 \def\gcd{{\rm gcd}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	20 \def\log{{\rm log}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	21 \def\ord{{\rm ord}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	22 \def\abs{{\mathit abs}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	23 \def\rep{{\mathit rep}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	24 \def\mod{{\mathit\ mod\ }}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	25 \renewcommand{\pmod}[1]{\ ({\rm mod\ }{#1})}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	26 \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	27 \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	28 \def\Or{{\rm\ or\ }}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	29 \def\And{{\rm\ and\ }}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	30 \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	31 \def\implies{\Rightarrow}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	32 \def\undefined{{\rm ``undefined"}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	33 \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	34 \let\oldphi\phi
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	35 \def\phi{\varphi}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	36 \def\Pr{{\rm Pr}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	37 \newcommand{\str}[1]{{\mathbf{#1}}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	38 \def\F{{\mathbb F}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	39 \def\N{{\mathbb N}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	40 \def\Z{{\mathbb Z}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	41 \def\R{{\mathbb R}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	42 \def\C{{\mathbb C}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	43 \def\Q{{\mathbb Q}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	44
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	45 \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	46
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	47 \def\gap{\vspace{0.5ex}}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	48 \makeindex
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	49 \begin{document}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	50 \title{LibTomCrypt \\ Version 1.05}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	51 \author{Tom St Denis \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	52 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	53 [email protected] \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	54 http://libtomcrypt.org
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	55 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	56 \maketitle
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	57 This text and source code library are both hereby placed in the public domain. This book has been
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	58 formatted for A4 paper using the \LaTeX{} {\em book} macro package.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	59
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	60 \vspace{15cm}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	61
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	62 \begin{flushright}Open Source. Open Academia. Open Minds.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	63
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	64 \mbox{ }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	65
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	66 Tom St Denis,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	67
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	68 Phone: 1-613-836-3160
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	69
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	70 111 Banning Rd
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	71
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	72 Kanata, Ontario
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	73
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	74 K2L 1C3
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	75
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	76 Canada
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	77 \end{flushright}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	78 \newpage
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	79 \tableofcontents
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	80 \chapter{Introduction}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	81 \section{What is the LibTomCrypt?}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	82 LibTomCrypt is a portable ISO C cryptographic library that is meant to be a toolset for cryptographers who are
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	83 designing a cryptosystem. It supports symmetric ciphers, one-way hashes, pseudo-random number generators,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	84 public key cryptography (via PKCS \#1 RSA, DH or ECCDH) and a plethora of support
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	85 routines.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	86
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	87 The library was designed such that new ciphers/hashes/PRNGs can be added at runtime and the existing API
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	88 (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	89 block cipher and hash function to ensure that they compile and execute to the published design specifications. The library
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	90 also performs extensive parameter error checking to prevent any number of runtime exploits or errors.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	91
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	92 \subsection{What the library IS for?}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	93
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	94 The library serves as a toolkit for developers who have to solve cryptographic problems. Out of the box LibTomCrypt
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	95 does not process SSL or OpenPGP messages, it doesn't read x.591 certificates or write PEM encoded data. It does, however,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	96 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	97 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	98
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	99 \section{Why did I write it?}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	100 You may be wondering, ``Tom, why did you write a crypto library. I already have one.''. Well the reason falls into
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	101 two categories:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	102 \begin{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	103 \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	104 \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	105 \end{enumerate}
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 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	108 {\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	109
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	110 With this library all core functions (ciphers, hashes, prngs) have the {\bf exact} same prototype definition. They all load
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	111 and store data in a format independent of the platform. This means if you encrypt with Blowfish on a PPC it should decrypt
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	112 on an x86 with zero problems. The consistent API also means that if you learn how to use Blowfish with my library you
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	113 know how to use Safer+ or RC6 or Serpent or ... as well. With all of the core functions there are central descriptor tables
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	114 that can be used to make a program automatically pick between ciphers, hashes and PRNGs at runtime. That means your
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	115 application can support all ciphers/hashes/prngs without changing the source code.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	116
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	117 Not only did I strive to make a consistent and simple API to work with but I also strived to make the library
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	118 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	119 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	120 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	121
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	122 On top of making the build simple and the API approachable I've also strived for a reasonably high level of
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	123 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	124 arguments to buffer overflows/overruns. It is mostly thread safe and has been clocked on various platforms
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	125 with ``cycles per byte'' timings that are comparable (and often favourable) to other libraries such as OpenSSL and
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	126 Crypto++.
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{Modular}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	129 The LibTomCrypt package has also been written to be very modular. The block ciphers, one--way hashes and
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	130 pseudo--random number generators (PRNG) are all used within the API through ``descriptor'' tables which
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	131 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	132 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	133 usage of the library.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	134
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	135 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	136 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	137 is write a descriptor and the few support routines required for the device. After that the rest of the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	138 API can make use of it without change. Similiarly imagine a few years down the road when AES2
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	139 (\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	140 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	141
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	142 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	143 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	144 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	145 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	146 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	147 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	148 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	149
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	150 \section{License}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	151
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	152 All of the source code except for the following files have been written by the author or donated to the project
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	153 under a public domain license:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	154
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	155 \begin{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	156 \item rc2.c
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	157 \end{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	158
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	159 `mpi.c'' was originally written by Michael Fromberger ([email protected]) but has since been replaced with
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	160 my LibTomMath library which is public domain.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	161
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	162 ``rc2.c'' is based on publicly available code that is not attributed to a person from the given source.
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 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	165
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	166 \section{Patent Disclosure}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	167
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	168 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	169 of the authors knowledge the only patent related issues within the library are the RC5 and RC6 symmetric block ciphers.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	170 They can be removed from a build by simply commenting out the two appropriate lines in ``tomcrypt\_custom.h''. The rest
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	171 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	172
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	173 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	174 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	175
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	176 \section{Thanks}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	177 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	178 early on:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	179 \begin{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	180 \item Richard van de Laarschot
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	181 \item Richard Heathfield
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	182 \item Ajay K. Agrawal
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	183 \item Brian Gladman
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	184 \item Svante Seleborg
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	185 \item Clay Culver
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	186 \item Jason Klapste
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	187 \item Dobes Vandermeer
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	188 \item Daniel Richards
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	189 \item Wayne Scott
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	190 \item Andrew Tyler
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	191 \item Sky Schulz
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	192 \item Christopher Imes
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	193 \end{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	194
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	195 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	196 time to time.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	197
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	198 \chapter{The Application Programming Interface (API)}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	199 \section{Introduction}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	200 \index{CRYPT\_ERROR} \index{CRYPT\_OK}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	201
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	202 In general the API is very simple to memorize and use. Most of the functions return either {\bf void} or {\bf int}. Functions
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	203 that return {\bf int} will return {\bf CRYPT\_OK} if the function was successful or one of the many error codes
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	204 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	205 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	206
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	207 \index{error\_to\_string()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	208 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	209 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	210 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	211
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	212 An example of handling an error is:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	213 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	214 void somefunc(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	215 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	216 int err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	217
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	218 /* call a cryptographic function */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	219 if ((err = some_crypto_function(...)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	220 printf("A crypto error occured, %s\n", error_to_string(err));
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	221 /* perform error handling */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	222 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	223 /* continue on if no error occured */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	224 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	225 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	226
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	227 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	228 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	229 that is not an issue.
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 To include the prototypes for ``LibTomCrypt.a'' into your own program simply include ``tomcrypt.h'' like so:
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 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	234 int main(void) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	235 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	236 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	237 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	238
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	239 The header file ``tomcrypt.h'' also includes ``stdio.h'', ``string.h'', ``stdlib.h'', ``time.h'', ``ctype.h'' and
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	240 ``ltc\_tommath.h'' (the bignum library routines).
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	241
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	242 \section{Macros}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	243
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	244 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	245 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	246
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	247 \index{STORE32L} \index{STORE64L} \index{LOAD32L} \index{LOAD64L} \index{STORE32H} \index{STORE64H} \index{LOAD32H} \index{LOAD64H} \index{BSWAP}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	248 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	249 \begin{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	250 \begin{tabular}{\|c\|c\|c\|}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	251 \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	252 \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	253 \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	254 \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	255 \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	256 \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	257 \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	258 \hline LOAD64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[7 \ldots 0] \to x$ \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	259 \hline BSWAP(x) & {\bf unsigned long} x & Swaps byte order (32--bits only) \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	260 \hline
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	261 \end{tabular}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	262 \end{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	263 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	264
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	265 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	266 \index{ROL} \index{ROR} \index{ROL64} \index{ROR64} \index{ROLc} \index{RORc} \index{ROL64c} \index{ROR64c}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	267 \begin{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	268 \begin{tabular}{\|c\|c\|c\|}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	269 \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	270 \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	271 \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	272 \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	273 \hline && \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	274 \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	275 \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	276 \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	277 \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	278 \hline
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	279 \end{tabular}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	280 \end{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	281
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	282 \section{Functions with Variable Length Output}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	283 Certain functions such as (for example) ``rsa\_export()'' give an output that is variable length. To prevent buffer overflows you
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	284 must pass it the length of the buffer\footnote{Extensive error checking is not in place but it will be in future releases so it is a good idea to follow through with these guidelines.} where
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	285 the output will be stored. For example:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	286 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	287 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	288 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	289 int main(void) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	290 rsa_key key;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	291 unsigned char buffer[1024];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	292 unsigned long x;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	293 int err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	294
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	295 /* ... Make up the RSA key somehow ... */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	296
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	297 /* lets export the key, set x to the size of the output buffer */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	298 x = sizeof(buffer);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	299 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	300 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	301 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	302 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	303
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	304 /* if rsa_export() was successful then x will have the size of the output */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	305 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	306
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	307 /* ... do something with the buffer */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	308
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	309 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	310 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	311 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	312 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	313 In the above example if the size of the RSA public key was more than 1024 bytes this function would return an error code
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	314 indicating a buffer overflow would have occurred. If the function succeeds it stores the length of the output
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	315 back into ``x'' so that the calling application will know how many bytes were used.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	316
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	317 \section{Functions that need a PRNG}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	318 \index{Pseudo Random Number Generator} \index{PRNG}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	319 Certain functions such as ``rsa\_make\_key()'' require a Pseudo Random Number Generator (PRNG). These functions do not setup
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	320 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	321
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	322 Certain PRNG algorithms do not require a ``prng\_state'' argument (sprng for example). The ``prng\_state'' argument
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	323 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	324
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	325 \section{Functions that use Arrays of Octets}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	326 Most functions require inputs that are arrays of the data type ``unsigned char''. Whether it is a symmetric key, IV
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	327 for a chaining mode or public key packet it is assumed that regardless of the actual size of ``unsigned char'' only the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	328 lower eight bits contain data. For example, if you want to pass a 256 bit key to a symmetric ciphers setup routine
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	329 you must pass it in (a pointer to) an array of 32 ``unsigned char'' variables. Certain routines
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	330 (such as SAFER+) take special care to work properly on platforms where an ``unsigned char'' is not eight bits.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	331
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	332 For the purposes of this library the term ``byte'' will refer to an octet or eight bit word. Typically an array of
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	333 type ``byte'' will be synonymous with an array of type ``unsigned char''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	334
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	335 \chapter{Symmetric Block Ciphers}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	336 \section{Core Functions}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	337
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	338 LibTomCrypt provides several block ciphers with an ECB block mode interface. It's important to first note that you
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	339 should never use the ECB modes directly to encrypt data. Instead you should use the ECB functions to make a chaining mode
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	340 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	341 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	342
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	343 \subsection{Key Scheduling}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	344 All ciphers store their scheduled keys in a single data type called ``symmetric\_key''. This allows all ciphers to
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	345 have the same prototype and store their keys as naturally as possible. This also removes the need for dynamic memory
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	346 allocation and allows you to allocate a fixed sized buffer for storing scheduled keys. All ciphers provide five visible
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	347 functions which are (given that XXX is the name of the cipher):
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	348 \index{Cipher Setup}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	349 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	350 int XXX_setup(const unsigned char *key, int keylen, int rounds,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	351 symmetric_key *skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	352 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	353
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	354 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	355 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	356
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	357 If the function returns successfully the variable ``skey'' will have a scheduled key stored in it. It's important to note
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	358 that you should only used this scheduled key with the intended cipher. For example, if you call ``blowfish\_setup()'' do not
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	359 pass the scheduled key onto ``rc5\_ecb\_encrypt()''. All setup functions do not allocate memory off the heap so when you are
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	360 done with a key you can simply discard it (e.g. they can be on the stack).
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	361
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	362 \subsection{ECB Encryption and Decryption}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	363 To encrypt or decrypt a block in ECB mode there are these two function classes
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	364 \index{Cipher Encrypt} \index{Cipher Decrypt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	365 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	366 void XXX_ecb_encrypt(const unsigned char pt, unsigned char ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	367 symmetric_key *skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	368
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	369 void XXX_ecb_decrypt(const unsigned char ct, unsigned char pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	370 symmetric_key *skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	371 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	372 These two functions will encrypt or decrypt (respectively) a single block of text\footnote{The size of which depends on
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	373 which cipher you are using.} and store the result where you want it. It is possible that the input and output buffer are
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	374 the same buffer. For the encrypt function ``pt''\footnote{pt stands for plaintext.} is the input and
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	375 ``ct''\footnote{ct stands for ciphertext.} is the output. For the decryption function it's the opposite. To test a particular
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	376 cipher against test vectors\footnote{As published in their design papers.} call the self-test function
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	377
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	378 \subsection{Self--Testing}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	379 \index{Cipher Testing}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	380 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	381 int XXX_test(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	382 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	383 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	384 based upon.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	385
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	386 \subsection{Key Sizing}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	387 For each cipher there is a function which will help find a desired key size:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	388 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	389 int XXX_keysize(int *keysize);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	390 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	391 Essentially it will round the input keysize in ``keysize'' down to the next appropriate key size. This function
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	392 return {\bf CRYPT\_OK} if the key size specified is acceptable. For example:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	393 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	394 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	395 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	396 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	397 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	398 int keysize, err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	399
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	400 /* 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	401 keysize = 20;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	402 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	403 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	404 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	405 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	406 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	407 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	408 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	409 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	410 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	411 This should indicate a keysize of sixteen bytes is suggested.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	412
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	413 \subsection{Cipher Termination}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	414 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	415 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	416 void XXX_done(symmetric_key *skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	417 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	418 For the software based ciphers within LibTomCrypt this function will not do anything. However, user supplied
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	419 cipher descriptors may require calls to it for resource management. To be compliant all functions which call a cipher
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	420 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	421
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	422 \subsection{Simple Encryption Demonstration}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	423 An example snippet that encodes a block with Blowfish in ECB mode is below.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	424
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	425 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	426 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	427 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	428 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	429 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	430 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	431 symmetric_key skey;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	432 int err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	433
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	434 /* ... key is loaded appropriately in ``key'' ... */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	435 /* ... load a block of plaintext in ``pt'' ... */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	436
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	437 /* schedule the key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	438 if ((err = blowfish_setup(key, /* the key we will use */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	439 8, /* key is 8 bytes (64-bits) long */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	440 0, /* 0 == use default # of rounds */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	441 &skey) /* where to put the scheduled key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	442 ) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	443 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	444 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	445 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	446
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	447 /* encrypt the block */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	448 blowfish_ecb_encrypt(pt, /* encrypt this 8-byte array */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	449 ct, /* store encrypted data here */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	450 &skey); /* our previously scheduled key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	451
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	452 /* 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	453
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	454 /* decrypt the block */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	455 blowfish_ecb_decrypt(ct, /* decrypt this 8-byte array */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	456 pt, /* store decrypted data here */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	457 &skey); /* our previously scheduled key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	458
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	459 /* 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	460
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	461 /* Terminate the cipher context */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	462 blowfish_done(&skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	463
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	464 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	465 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	466 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	467 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	468
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	469 \section{Key Sizes and Number of Rounds}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	470 \index{Symmetric Keys}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	471 As a general rule of thumb do not use symmetric keys under 80 bits if you can. Only a few of the ciphers support smaller
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	472 keys (mainly for test vectors anyways). Ideally your application should be making at least 256 bit keys. This is not
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	473 because you're supposed to be paranoid. It's because if your PRNG has a bias of any sort the more bits the better. For
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	474 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	475 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	476 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	477 only 53 bits of entropy.
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 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	480 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	481 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	482 size.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	483
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	484 \section{The Cipher Descriptors}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	485 \index{Cipher Descriptor}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	486 To facilitate automatic routines an array of cipher descriptors is provided in the array ``cipher\_descriptor''. An element
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	487 of this array has the following format:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	488
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	489 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	490 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	491 struct _cipher_descriptor {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	492 char *name;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	493 unsigned char ID;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	494 int min_key_length,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	495 max_key_length,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	496 block_length,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	497 default_rounds;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	498 int (setup)(const unsigned char key, int keylen, int num_rounds, symmetric_key *skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	499 void (ecb_encrypt)(const unsigned char pt, unsigned char ct, symmetric_key skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	500 void (ecb_decrypt)(const unsigned char ct, unsigned char pt, symmetric_key skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	501 int (*test)(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	502 void (done)(symmetric_key skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	503 int (keysize)(int keysize);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	504
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	505 void (accel_ecb_encrypt)(const unsigned char pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	506 unsigned char *ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	507 unsigned long blocks, symmetric_key *skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	508 void (accel_ecb_decrypt)(const unsigned char ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	509 unsigned char *pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	510 unsigned long blocks, symmetric_key *skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	511 void (accel_cbc_encrypt)(const unsigned char pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	512 unsigned char *ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	513 unsigned long blocks, unsigned char *IV,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	514 symmetric_key *skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	515 void (accel_cbc_decrypt)(const unsigned char ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	516 unsigned char *pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	517 unsigned long blocks, unsigned char *IV,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	518 symmetric_key *skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	519 void (accel_ctr_encrypt)(const unsigned char pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	520 unsigned char *ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	521 unsigned long blocks, unsigned char *IV,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	522 int mode, symmetric_key *skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	523 void (*accel_ccm_memory)(
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	524 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	525 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	526 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	527 unsigned char *pt, unsigned long ptlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	528 unsigned char *ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	529 unsigned char tag, unsigned long taglen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	530 int direction);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	531
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 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	534 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	535
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	536 Where ``name'' is the lower case ASCII version of the name. The fields ``min\_key\_length'' and ``max\_key\_length''
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	537 are the minimum and maximum key sizes in bytes. The ``block\_length'' member is the block size of the cipher
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	538 in bytes. As a good rule of thumb it is assumed that the cipher supports
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	539 the min and max key lengths but not always everything in between. The ``default\_rounds'' field is the default number
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	540 of rounds that will be used.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	541
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	542 The remaining fields are all pointers to the core functions for each cipher. The end of the cipher\_descriptor array is
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	543 marked when ``name'' equals {\bf NULL}.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	544
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	545 As of this release the current cipher\_descriptors elements are
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	546
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	547 \index{Cipher descriptor table}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	548 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	549 \begin{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	550 \begin{tabular}{\|c\|c\|c\|c\|c\|c\|}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	551 \hline Name & Descriptor Name & Block Size & Key Range & Rounds \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	552 \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	553 \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	554 \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	555 \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	556 \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	557 \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	558 \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	559 & 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	560 \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	561 \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	562 \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	563 \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	564 \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	565 \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	566 \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	567 \hline Khazad & khazad\_desc & 8 & 16 & 8 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	568 \hline
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	569 \end{tabular}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	570 \end{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	571 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	572
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	573 \subsection{Notes}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	574 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	575 \begin{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	576 \item
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	577 For AES (also known as Rijndael) there are four descriptors which complicate issues a little. The descriptors
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	578 rijndael\_desc and rijndael\_enc\_desc provide the cipher named ``rijndael''. The descriptors aes\_desc and
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	579 aes\_enc\_desc provide the cipher name ``aes''. Functionally both ``rijndael'' and ``aes'' are the same cipher. The
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	580 only difference is when you call find\_cipher() you have to pass the correct name. The cipher descriptors with ``enc''
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	581 in the middle (e.g. rijndael\_enc\_desc) are related to an implementation of Rijndael with only the encryption routine
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	582 and tables. The decryption and self--test function pointers of both ``encrypt only'' descriptors are set to \textbf{NULL} and
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	583 should not be called.
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 The ``encrypt only'' descriptors are useful for applications that only use the encryption function of the cipher. Algorithms such
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	586 as EAX, PMAC and OMAC only require the encryption function. So far this ``encrypt only'' functionality has only been implemented for
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	587 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	588
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	589 \item
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	590 Note that for ``DES'' and ``3DES'' they use 8 and 24 byte keys but only 7 and 21 [respectively] bytes of the keys are in
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	591 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	592 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	593
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	594 \item
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	595 Note that ``Twofish'' has additional configuration options that take place at build time. These options are found in
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	596 the file ``tomcrypt\_cfg.h''. The first option is ``TWOFISH\_SMALL'' which when defined will force the Twofish code
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	597 to not pre-compute the Twofish ``$g(X)$'' function as a set of four $8 \times 32$ s-boxes. This means that a scheduled
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	598 key will require less ram but the resulting cipher will be slower. The second option is ``TWOFISH\_TABLES'' which when
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	599 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	600 by the polynomials 5B and EF used in the MDS multiplication. As a result the code is faster and slightly larger. The
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	601 speed increase is useful when ``TWOFISH\_SMALL'' is defined since the s-boxes and MDS multiply form the heart of the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	602 Twofish round function.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	603
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	604 \index{Twofish build options}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	605 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	606 \begin{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	607 \begin{tabular}{\|l\|l\|l\|}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	608 \hline TWOFISH\_SMALL & TWOFISH\_TABLES & Speed and Memory (per key) \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	609 \hline undefined & undefined & Very fast, 4.2KB of ram. \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	610 \hline undefined & defined & Faster keysetup, larger code. \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	611 \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	612 \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	613 \hline
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	614 \end{tabular}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	615 \end{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	616 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	617
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	618 \end{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	619 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	620
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	621 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	622 \index{find\_cipher()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	623 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	624 int find_cipher(char *name)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	625 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	626 Which will search for a given name in the array. It returns negative one if the cipher is not found, otherwise it returns
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	627 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	628 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	629 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	630 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	631 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	632 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	633 unsigned char key[8];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	634 symmetric_key skey;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	635 int err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	636
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	637 /* 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	638 if (register_cipher(&blowfish_desc)) == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	639 printf("Unable to register Blowfish cipher.");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	640 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	641 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	642
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	643 /* generic call to function (assuming the key in key[] was already setup) */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	644 if ((err = cipher_descriptor[find_cipher("blowfish")].setup(key, 8, 0, &skey)) !=
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	645 CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	646 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	647 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	648 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	649
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	650 /* ... use cipher ... */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	651 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	652 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	653 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	654
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	655 A good safety would be to check the return value of ``find\_cipher()'' before accessing the desired function. In order
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	656 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	657 \index{register\_cipher()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	658 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	659 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	660 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	661 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	662 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	663 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	664 \index{unregister\_cipher()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	665 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	666 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	667 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	668 Which returns {\bf CRYPT\_OK} if it removes it otherwise it returns {\bf CRYPT\_ERROR}. Consider:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	669 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	670 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	671 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	672 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	673 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	674 int err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	675
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	676 /* register the cipher */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	677 if (register_cipher(&rijndael_desc) == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	678 printf("Error registering Rijndael\n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	679 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	680 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	681
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	682 /* use Rijndael */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	683
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	684 /* remove it */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	685 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	686 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	687 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	688 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	689
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	690 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	691 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	692 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	693 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	694 This snippet is a small program that registers only Rijndael only.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	695
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	696 \section{Symmetric Modes of Operations}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	697 \subsection{Background}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	698 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	699 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	700 $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	701
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	702 \subsubsection{ECB Mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	703 \index{ECB mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	704 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	705 \begin{equation}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	706 C_i = E_k(P_i)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	707 \end{equation}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	708 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	709 than once.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	710
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	711 \subsubsection{CBC Mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	712 \index{CBC mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	713 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	714 It is given as:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	715 \begin{equation}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	716 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	717 \end{equation}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	718 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	719
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	720 \subsubsection{CTR Mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	721 \index{CTR mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	722 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	723 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	724 \begin{eqnarray}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	725 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	726 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	727 \end{eqnarray}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	728 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	729 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	730 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	731
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	732 \subsubsection{CFB Mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	733 \index{CFB mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	734 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	735 \begin{eqnarray}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	736 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	737 C_{-1} = E_k(C_i)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	738 \end{eqnarray}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	739 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	740 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	741 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	742
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	743 \subsubsection{OFB Mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	744 \index{OFB mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	745 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	746 \begin{eqnarray}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	747 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	748 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	749 \end{eqnarray}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	750 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	751 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	752
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	753 \subsection{Choice of Mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	754 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	755 \begin{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	756 \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	757 \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	758 \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	759 \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	760 \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	761 \end{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	762 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	763 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	764 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	765
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	766 The ECB and CBC modes process blocks of the same size as the cipher at a time. Therefore they are less flexible than the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	767 other modes.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	768
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	769 \subsection{Initialization}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	770 \index{CBC Mode} \index{CTR Mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	771 \index{OFB Mode} \index{CFB Mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	772 The library provides simple support routines for handling CBC, CTR, CFB, OFB and ECB encoded messages. Assuming the mode
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	773 you want is XXX there is a structure called ``symmetric\_XXX'' that will contain the information required to
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	774 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	775 \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	776 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	777 int XXX_start(int cipher, const unsigned char *IV,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	778 const unsigned char *key, int keylen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	779 int num_rounds, symmetric_XXX *XXX);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	780
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	781 int ctr_start( int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	782 const unsigned char *IV,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	783 const unsigned char *key, int keylen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	784 int num_rounds, int ctr_mode,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	785 symmetric_CTR *ctr);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	786
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	787 int ecb_start(int cipher, const unsigned char *key, int keylen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	788 int num_rounds, symmetric_ECB *ecb);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	789 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	790
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	791 In each case ``cipher'' is the index into the cipher\_descriptor array of the cipher you want to use. The ``IV'' value is
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	792 the initialization vector to be used with the cipher. You must fill the IV yourself and it is assumed they are the same
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	793 length as the block size\footnote{In otherwords the size of a block of plaintext for the cipher, e.g. 8 for DES, 16 for AES, etc.}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	794 of the cipher you choose. It is important that the IV be random for each unique message you want to encrypt. The
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	795 parameters ``key'', ``keylen'' and ``num\_rounds'' are the same as in the XXX\_setup() function call. The final parameter
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	796 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	797
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	798
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	799 In the case of CTR mode there is an additional parameter ``ctr\_mode'' which specifies the mode that the counter is to be used in.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	800 If \textbf{CTR\_COUNTER\_LITTLE\_ENDIAN} was specified then the counter will be treated as a little endian value. Otherwise, if
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	801 \textbf{CTR\_COUNTER\_BIG\_ENDIAN} was specified the counter will be treated as a big endian value.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	802
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	803 The routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise they return an error code.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	804
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	805 \subsection{Encryption and Decryption}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	806 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	807 \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	808 \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	809 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	810 int XXX_encrypt(const unsigned char pt, unsigned char ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	811 unsigned long len, symmetric_YYY *YYY);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	812 int XXX_decrypt(const unsigned char ct, unsigned char pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	813 unsigned long len, symmetric_YYY *YYY);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	814 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	815 Where ``XXX'' is one of $\lbrace ecb, cbc, ctr, cfb, ofb \rbrace$.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	816
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	817 In all cases ``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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	818 chunk sensitive. That is you can encrypt ``ABCDEF'' in three calls like ``AB'', ``CD'', ``EF'' or two like ``ABCDE'' and ``F''
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	819 and end up with the same ciphertext. However, encrypting ``ABC'' and ``DABC'' will result in different ciphertexts. All
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	820 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	821
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	822 In the ECB and CBC cases ``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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	823 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	824
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	825 To decrypt in either mode you simply perform the setup like before (recall you have to fetch the IV value you used)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	826 and use the decrypt routine on all of the blocks.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	827
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	828 \subsection{IV Manipulation}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	829 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	830
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	831 \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	832 \index{ctr\_setiv()} \index{ctr\_getiv()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	833 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	834 int XXX_getiv(unsigned char IV, unsigned long len, symmetric_XXX *XXX);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	835 int XXX_setiv(const unsigned char IV, unsigned long len, symmetric_XXX XXX);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	836 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	837
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	838 The XXX\_getiv() functions will read the IV out of the chaining mode and store it into ``IV'' along with the length of the IV
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	839 stored in ``len''. The XXX\_setiv will initialize the chaining mode state as if the original IV were the new IV specified. The length
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	840 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	841
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	842 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	843
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	844 \subsection{Stream Termination}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	845 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	846
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	847 \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	848 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	849 int XXX_done(symmetric_XXX *XXX);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	850 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	851
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	852 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	853
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	854 \subsection{Examples}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	855
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	856 \newpage
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	857 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	858 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	859 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	860 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	861 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	862 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	863 symmetric_CTR ctr;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	864 int x, err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	865
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	866 /* register twofish first */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	867 if (register_cipher(&twofish_desc) == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	868 printf("Error registering cipher.\n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	869 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	870 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	871
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	872 /* somehow fill out key and IV */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	873
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	874 /* start up CTR mode */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	875 if ((err = ctr_start(
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	876 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	877 IV, /* the initial vector */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	878 key, /* the secret key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	879 16, /* length of secret key (16 bytes, 128 bits) */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	880 0, /* 0 == default # of rounds */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	881 CTR_COUNTER_LITTLE_ENDIAN, /* Little endian counter */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	882 &ctr) /* where to store initialized CTR state */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	883 ) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	884 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	885 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	886 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	887
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	888 /* somehow fill buffer than encrypt it */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	889 if ((err = ctr_encrypt( buffer, /* plaintext */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	890 buffer, /* ciphertext */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	891 sizeof(buffer), /* length of data to encrypt */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	892 &ctr) /* previously initialized CTR state */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	893 ) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	894 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	895 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	896 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	897
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	898 /* make use of ciphertext... */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	899
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	900 /* 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	901 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	902 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	903 &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	904 ) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	905 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	906 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	907 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	908
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	909 if ((err = ctr_decrypt( buffer, /* ciphertext */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	910 buffer, /* plaintext */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	911 sizeof(buffer), /* length of data to encrypt */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	912 &ctr) /* previously initialized CTR state */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	913 ) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	914 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	915 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	916 }
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 /* terminate the stream */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	919 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	920 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	921 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	922 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	923
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	924 /* clear up and return */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	925 zeromem(key, sizeof(key));
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	926 zeromem(&ctr, sizeof(ctr));
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	927
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	928 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	929 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	930 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	931 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	932
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	933 \section{Encrypt and Authenticate Modes}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	934
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	935 \subsection{EAX Mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	936 LibTomCrypt provides support for a mode called EAX\footnote{See
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	937 M. Bellare, P. Rogaway, D. Wagner, A Conventional Authenticated-Encryption Mode.} in a manner similar to the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	938 way it was intended to be used by the designers. First a short description of what EAX mode is before I explain how to use it.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	939 EAX is a mode that requires a cipher, CTR and OMAC support and provides encryption and authentication\footnote{Note that since EAX only requires OMAC and CTR you may use ``encrypt only'' cipher descriptors with this mode.}.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	940 It is initialized with a random ``nonce'' that can be shared publicly as well as a ``header'' which can be fixed and public as well as a random
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	941 secret symmetric key.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	942
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	943 The ``header'' data is meant to be meta-data associated with a stream that isn't private (e.g. protocol messages). It can
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	944 be added at anytime during an EAX stream and is part of the authentication tag. That is, changes in the meta-data can
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	945 be detected by changes in the output tag.
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 The mode can then process plaintext producing ciphertext as well as compute a partial checksum. The actual checksum
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	948 called a ``tag'' is only emitted when the message is finished. In the interim though the user can process any arbitrary
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	949 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	950 of operation.
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 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	953 \index{eax\_init()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	954 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	955 int eax_init(eax_state *eax, int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	956 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	957 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	958 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	959 \end{verbatim}
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 Where ``eax'' is the EAX state. ``cipher'' is the index of the desired cipher in the descriptor table.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	962 ``key'' is the shared secret symmetric key of length ``keylen''. ``nonce'' is the random public string of
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	963 length ``noncelen''. ``header'' is the random (or fixed or \textbf{NULL}) header for the message of length
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	964 ``headerlen''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	965
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	966 When this function completes ``eax'' will be initialized such that you can now either have data decrypted or
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	967 encrypted in EAX mode. Note that if ``headerlen'' is zero you may pass ``header'' as \textbf{NULL} to indicate
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	968 there is no initial header data.
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 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	971 \index{eax\_encrypt()} \index{eax\_decrypt()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	972 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	973 int eax_encrypt(eax_state eax, const unsigned char pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	974 unsigned char *ct, unsigned long length);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	975
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	976 int eax_decrypt(eax_state eax, const unsigned char ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	977 unsigned char *pt, unsigned long length);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	978 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	979 The function ``eax\_encrypt'' will encrypt the bytes in ``pt'' of ``length'' bytes and store the ciphertext in
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	980 ``ct''. Note that ``ct'' and ``pt'' may be the same region in memory. This function will also send the ciphertext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	981 through the OMAC function. The function ``eax\_decrypt'' decrypts ``ct'' and stores it in ``pt''. This also allows
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	982 ``pt'' and ``ct'' to be the same region in memory.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	983
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	984 You cannot both encrypt or decrypt with the same ``eax'' context. For bi-directional communication you
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	985 will need to initialize two EAX contexts (preferably with different headers and nonces).
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 Note that both of these functions allow you to send the data in any granularity but the order is important. While
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	988 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	989 EAX stream with the following.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	990
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	991 \index{eax\_addheader()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	992 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	993 int eax_addheader(eax_state *eax,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	994 const unsigned char *header, unsigned long length);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	995 \end{verbatim}
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 This will add the ``length'' bytes from ``header'' to the given ``eax'' stream. Once the message is finished the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	998 ``tag'' (checksum) may be computed with the following function.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	999
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1000 \index{eax\_done()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1001 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1002 int eax_done(eax_state *eax,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1003 unsigned char tag, unsigned long taglen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1004 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1005 This will terminate the EAX state ``eax'' and store upto ``taglen'' bytes of the message tag in ``tag''. The function
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1006 then stores how many bytes of the tag were written out back into ``taglen''.
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 The EAX mode code can be tested to ensure it matches the test vectors by calling the following function.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1009 \index{eax\_test()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1010 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1011 int eax_test(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1012 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1013 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	1014
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1015 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1016 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1017 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1018 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1019 int err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1020 eax_state eax;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1021 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	1022 unsigned long taglen;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1023
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1024 if (register_cipher(&rijndael_desc) == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1025 printf("Error registering Rijndael");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1026 return EXIT_FAILURE;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1027 }
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 /* ... make up random nonce and key ... */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1030
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1031 /* initialize context */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1032 if ((err = eax_init( &eax, /* the context */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1033 find_cipher("rijndael"), /* cipher we want to use */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1034 nonce, /* our state nonce */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1035 16, /* none is 16 bytes */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1036 "TestApp", /* example header, identifies this program */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1037 7) /* length of the header */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1038 ) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1039 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	1040 return EXIT_FAILURE;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1041 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1042
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1043 /* now encrypt data, say in a loop or whatever */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1044 if ((err = eax_encrypt( &eax, /* eax context */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1045 pt, /* plaintext (source) */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1046 ct, /* ciphertext (destination) */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1047 sizeof(pt) /* size of plaintext */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1048 ) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1049 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	1050 return EXIT_FAILURE;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1051 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1052
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1053 /* finish message and get authentication tag */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1054 taglen = sizeof(tag);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1055 if ((err = eax_done( &eax, /* eax context */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1056 tag, /* where to put tag */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1057 &taglen /* length of tag space */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1058 ) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1059 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	1060 return EXIT_FAILURE;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1061 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1062
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1063 /* now we have the authentication tag in "tag" and it's taglen bytes long */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1064
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1065 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1066 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1067
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1068 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	1069 following functions.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1070
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1071
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1072 \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	1073 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1074 int eax_encrypt_authenticate_memory(int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1075 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	1076 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	1077 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	1078 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	1079 unsigned char *ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1080 unsigned char tag, unsigned long taglen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1081
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1082 int eax_decrypt_verify_memory(int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1083 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	1084 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	1085 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	1086 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	1087 unsigned char *pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1088 unsigned char *tag, unsigned long taglen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1089 int *res);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1090 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1091
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1092 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	1093 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	1094
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1095 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1096 the tag it computed while decrypting the message. If the tags match then it stores a $1$ in ``res'', otherwise it stores a $0$.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1097
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1098 \subsection{OCB Mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1099 LibTomCrypt provides support for a mode called OCB\footnote{See
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1100 P. Rogaway, M. Bellare, J. Black, T. Krovetz, ``OCB: A Block Cipher Mode of Operation for Efficient Authenticated Encryption''.}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1101 . 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	1102 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	1103
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1104 \index{ocb\_init()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1105 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1106 int ocb_init(ocb_state *ocb, int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1107 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	1108 const unsigned char *nonce);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1109 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1110
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1111 This will initialize the ``ocb'' context using cipher descriptor ``cipher''. It will use a ``key'' of length ``keylen''
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1112 and the random ``nonce''. Note that ``nonce'' must be a random (public) string the same length as the block ciphers
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1113 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	1114
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1115 This mode has no ``Associated Data'' like EAX mode does which means you cannot authenticate metadata along with the stream.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1116 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	1117
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1118 \index{ocb\_encrypt()} \index{ocb\_decrypt()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1119 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1120 int ocb_encrypt(ocb_state ocb, const unsigned char pt, unsigned char *ct);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1121 int ocb_decrypt(ocb_state ocb, const unsigned char ct, unsigned char *pt);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1122 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1123
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1124 This will encrypt (or decrypt for the latter) a fixed length of data from ``pt'' to ``ct'' (vice versa for the latter).
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1125 They assume that ``pt'' and ``ct'' are the same size as the block cipher's block size. Note that you cannot call
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1126 both functions given a single ``ocb'' state. For bi-directional communication you will have to initialize two ``ocb''
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1127 states (with different nonces). Also ``pt'' and ``ct'' may point to the same location in memory.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1128
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1129 \subsubsection{State Termination}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1130
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1131 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	1132
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1133 \index{ocb\_done\_encrypt()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1134 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1135 int ocb_done_encrypt(ocb_state *ocb,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1136 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	1137 unsigned char *ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1138 unsigned char tag, unsigned long taglen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1139 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1140
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1141 This will terminate an encrypt stream ``ocb''. If you have trailing bytes of plaintext that will not complete a block
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1142 you can pass them here. This will also encrypt the ``ptlen'' bytes in ``pt'' and store them in ``ct''. It will also
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1143 store upto ``taglen'' bytes of the tag into ``tag''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1144
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1145 Note that ``ptlen'' must be less than or equal to the block size of block cipher chosen. Also note that if you have
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1146 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	1147
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1148 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	1149
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1150 \index{ocb\_done\_decrypt()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1151 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1152 int ocb_done_decrypt(ocb_state *ocb,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1153 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	1154 unsigned char *pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1155 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	1156 int *res);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1157 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1158
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1159 Similarly to the previous function you can pass trailing message bytes into this function. This will compute the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1160 tag of the message (internally) and then compare it against the ``taglen'' bytes of ``tag'' provided. By default
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1161 ``res'' is set to zero. If all ``taglen'' bytes of ``tag'' can be verified then ``res'' is set to one (authenticated
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1162 message).
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1163
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1164 \subsubsection{Packet Functions}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1165 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	1166
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1167 \index{ocb\_encrypt\_authenticate\_memory()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1168 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1169 int ocb_encrypt_authenticate_memory(int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1170 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	1171 const unsigned char *nonce,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1172 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	1173 unsigned char *ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1174 unsigned char tag, unsigned long taglen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1175 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1176
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1177 This will OCB encrypt the message ``pt'' of length ``ptlen'' and store the ciphertext in ``ct''. The length ``ptlen''
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1178 can be any arbitrary length.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1179
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1180 \index{ocb\_decrypt\_verify\_memory()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1181 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1182 int ocb_decrypt_verify_memory(int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1183 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	1184 const unsigned char *nonce,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1185 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	1186 unsigned char *pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1187 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	1188 int *res);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1189 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1190
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1191 Similarly this will OCB decrypt and compare the internally computed tag against the tag provided. ``res'' is set
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1192 appropriately.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1193
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1194 \subsection{CCM Mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1195 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1196 it is only meant for ``packet'' mode where the length of the input is known in advance. Since it is a packet mode function CCM only has one
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1197 function that performs the protocol.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1198
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1199 \index{ccm\_memory()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1200 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1201 int ccm_memory(int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1202 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	1203 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	1204 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	1205 unsigned char *pt, unsigned long ptlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1206 unsigned char *ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1207 unsigned char tag, unsigned long taglen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1208 int direction);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1209 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1210
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1211 This performs the ``CCM'' operation on the data. The ``cipher'' variable indicates which cipher in the descriptor table to use. It must have a
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1212 16--byte block size for CCM. The key is ``key'' with a length of ``keylen'' octets. The nonce or salt is ``nonce'' of
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1213 length ``noncelen'' octets. The header is meta--data you want to send with the message but not have encrypted, it is stored in ``header''
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1214 of length ``headerlen'' octets. The header can be zero octets long (if $headerlen = 0$ then you can pass ``header'' as \textbf{NULL}).
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1215
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1216 The plaintext is stored in ``pt'' and the ciphertext in ``ct''. The length of both are expected to be equal and is passed in as ``ptlen''. It is
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1217 allowable that $pt = ct$. The ``direction'' variable indicates whether encryption (direction $=$ \textbf{CCM\_ENCRYPT}) or
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1218 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	1219
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1220 As implemented this copy of CCM cannot handle a header or plaintext longer than $2^{32} - 1$ octets long.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1221
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1222 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	1223
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1224 \index{ccm\_test()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1225 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1226 int ccm_test(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1227 \end{verbatim}
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 This will return \textbf{CRYPT\_OK} if the CCM routine passes known test vectors.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1230
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1231 \subsection{GCM Mode}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1232 Galois counter mode is an IEEE proposal for authenticated encryption. Like EAX and OCB it can be used in a streaming capacity however, unlike EAX it cannot
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1233 accept ``additional authentication data'' (meta--data) after plaintext has been processed. This mode also only works with block ciphers with a sixteen
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1234 byte block.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1235
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1236 A GCM stream is meant to be processed in three modes each one sequential serial. First the initial vector (per session) data is processed. This should be
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1237 unique to every session. Next the the optional additional authentication data is processed and finally the plaintext.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1238
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1239 \subsubsection{Initialization}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1240 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	1241
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1242 \index{gcm\_init()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1243 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1244 int gcm_init(gcm_state *gcm, int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1245 const unsigned char *key, int keylen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1246 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1247 This initializes the GCM state ``gcm'' for the given cipher indexed by ``cipher'' with a secret key ``key'' of length ``keylen'' octets. The cipher chosen
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1248 must have a 16--byte block size (e.g. AES).
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1249
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1250 \subsubsection{Initial Vector}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1251 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	1252
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1253 \index{gcm\_add\_iv()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1254 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1255 int gcm_add_iv(gcm_state *gcm,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1256 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	1257 \end{verbatim}
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 This adds the initial vector octets from ``IV'' of length ``IVlen'' to the GCM state ``gcm''. You can call this function as many times as required
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1260 to process the entire IV.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1261
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1262 Note that the GCM protocols provides a ``shortcut'' for 12--byte IVs where no preprocessing is to be done. If you want to minimize per packet latency it's ideal
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1263 to only use 12--byte IVs. You can just increment it like a counter for each packet and the CTR [privacy] will be ensured.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1264
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1265 \subsubsection{Additional Authentication Data}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1266 After the entire IV has been processed the additional authentication data can be processed. Unlike the IV a packet/session does not require additional
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1267 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 that once
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1268 you begin adding AAD to the GCM state you cannot return to adding IV data until the state is reset.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1269
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1270 \index{gcm\_add\_aad()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1271 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1272 int gcm_add_aad(gcm_state *gcm,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1273 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	1274 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1275 This adds the additional authentication data ``adata'' of length ``adatalen'' to the GCM state ``gcm''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1276
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1277 \subsubsection{Plaintext Processing}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1278 After the AAD has been processed the plaintext (or ciphertext depending on the direction) can be processed.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1279
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1280 \index{gcm\_process()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1281 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1282 int gcm_process(gcm_state *gcm,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1283 unsigned char *pt, unsigned long ptlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1284 unsigned char *ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1285 int direction);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1286 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1287 This processes message data where ``pt'' is the plaintext and ``ct'' is the ciphertext. The length of both are equal and stored in ``ptlen''. Depending on the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1288 mode ``pt'' is the input and ``ct'' is the output (or vice versa). When ``direction'' equals \textbf{GCM\_ENCRYPT} the plaintext is read, encrypted and stored
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1289 in the ciphertext buffer. When ``direction'' equals \textbf{GCM\_DECRYPT} the opposite occurs.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1290
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1291 \subsubsection{State Termination}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1292 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	1293
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1294 \index{gcm\_done()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1295 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1296 int gcm_done(gcm_state *gcm,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1297 unsigned char tag, unsigned long taglen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1298 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1299 This terminates the GCM state ``gcm'' and stores the tag in ``tag'' of length ``taglen'' octets.
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 \subsubsection{State Reset}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1302 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1303 it is very costly to have to call it repeatedly. To aid in this endeavour the reset function has been provided.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1304
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1305 \index{gcm\_reset()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1306 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1307 int gcm_reset(gcm_state *gcm);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1308 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1309
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1310 This will reset the GCM state ``gcm'' to the state that gcm\_init() left it. The user would then call gcm\_add\_iv(), gcm\_add\_aad(), etc.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1311
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1312 \subsubsection{One--Shot Packet}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1313 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	1314
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1315 \index{gcm\_memory()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1316 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1317 int gcm_memory( int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1318 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	1319 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	1320 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	1321 unsigned char *pt, unsigned long ptlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1322 unsigned char *ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1323 unsigned char tag, unsigned long taglen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1324 int direction);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1325 \end{verbatim}
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 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	1328 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	1329
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1330 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	1331
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1332 \subsubsection{Example Usage}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1333 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	1334
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1335 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1336 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1337 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1338
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1339 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	1340 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	1341 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	1342 gcm_state *gcm)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1343 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1344 int err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1345 unsigned long taglen;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1346 unsigned char tag[16];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1347
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1348 /* reset the state */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1349 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	1350 return err;
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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1353 /* Add the IV */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1354 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	1355 return err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1356 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1357
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1358 /* 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	1359 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	1360 return err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1361 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1362
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1363 /* process the plaintext */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1364 if ((err = gcm_process(gcm, pt, ptlen, pt, GCM_ENCRYPT)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1365 return err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1366 }
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 /* 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	1369 taglen = sizeof(tag);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1370 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	1371 return err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1372 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1373
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1374 /* ... send a header describing the lengths ... */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1375
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1376 /* depending on the protocol and how IV is generated you may have to send it too... */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1377 send(socket, iv, ivlen, 0);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1378
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1379 /* send the aad */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1380 send(socket, aad, aadlen, 0);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1381
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1382 /* send the ciphertext */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1383 send(socket, pt, ptlen, 0);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1384
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1385 /* send the tag */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1386 send(socket, tag, taglen, 0);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1387
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1388 return CRYPT_OK;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1389 }
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 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1392 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1393 gcm_state gcm;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1394 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	1395 int err, x;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1396 unsigned long ptlen;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1397
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1398 /* 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	1399
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1400 /* register AES */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1401 register_cipher(&aes_desc);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1402
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1403 /* init the GCM state */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1404 if ((err = gcm_init(&gcm, find_cipher("aes"), key, 16)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1405 whine_and_pout(err);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1406 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1407
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1408 /* handle us some packets */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1409 for (;;) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1410 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	1411
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1412 /* 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	1413 for (x = 11; x >= 0; x--) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1414 if (++IV[x]) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1415 break;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1416 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1417 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1418
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1419 if ((err = send_packet(pt, ptlen, iv, 12, NULL, 0, &gcm)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1420 whine_and_pout(err);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1421 }
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 return EXIT_SUCCESS;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1424 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1425 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1426 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1427
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1428 \chapter{One-Way Cryptographic Hash Functions}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1429 \section{Core Functions}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1430
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1431 Like the ciphers there are hash core functions and a universal data type to hold the hash state called ``hash\_state''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1432 To initialize hash XXX (where XXX is the name) call:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1433 \index{Hash Functions}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1434 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1435 void XXX_init(hash_state *md);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1436 \end{verbatim}
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 This simply sets up the hash to the default state governed by the specifications of the hash. To add data to the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1439 message being hashed call:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1440 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1441 int XXX_process(hash_state md, const unsigned char in, unsigned long inlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1442 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1443
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1444 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1445 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1446 (hash output) will be the same. For example, this means that:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1447 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1448 md5_process(&md, "hello ", 6);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1449 md5_process(&md, "world", 5);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1450 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1451 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	1452 \index{Message Digest}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1453 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1454 md5_process(&md, "hello world", 11);
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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1457 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	1458 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1459 int XXX_done(hash_state *md,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1460 unsigned char *out);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1461 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1462
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1463 This function will finish up the hash and store the result in the ``out'' array. You must ensure that ``out'' is long
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1464 enough for the hash in question. Often hashes are used to get keys for symmetric ciphers so the ``XXX\_done()'' functions
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1465 will wipe the ``md'' variable before returning automatically.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1466
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1467 To test a hash function call:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1468 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1469 int XXX_test(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1470 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1471
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1472 This will return {\bf CRYPTO\_OK} if the hash matches the test vectors, otherwise it returns an error code. An
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1473 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	1474 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1475 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1476 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1477 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1478 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1479 hash_state md;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1480 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	1481
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1482 /* setup the hash */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1483 md5_init(&md);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1484
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1485 /* add the message */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1486 md5_process(&md, in, strlen(in));
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1487
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1488 /* 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	1489 md5_done(&md, out);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1490
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1491 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1492 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1493 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1494 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1495
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1496 \section{Hash Descriptors}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1497 Like the set of ciphers the set of hashes have descriptors too. They are stored in an array called ``hash\_descriptor'' and
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1498 are defined by:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1499 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1500 struct _hash_descriptor {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1501 char *name;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1502 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	1503 unsigned long blocksize; /* the block size the hash uses */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1504 void (init) (hash_state hash);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1505 int (process)(hash_state hash,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1506 const unsigned char *in, unsigned long inlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1507 int (done) (hash_state hash, unsigned char *out);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1508 int (*test) (void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1509 };
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1510 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1511
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1512 Similarly ``name'' is the name of the hash function in ASCII (all lowercase). ``hashsize'' is the size of the digest output
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1513 in bytes. The remaining fields are pointers to the functions that do the respective tasks. There is a function to
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1514 search the array as well called ``int find\_hash(char *name)''. It returns -1 if the hash is not found, otherwise the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1515 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	1516
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1517 You can use the table to indirectly call a hash function that is chosen at runtime. For example:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1518 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1519 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1520 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1521 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1522 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1523 unsigned char buffer[100], hash[MAXBLOCKSIZE];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1524 int idx, x;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1525 hash_state md;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1526
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1527 /* register hashes .... */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1528 if (register_hash(&md5_desc) == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1529 printf("Error registering MD5.\n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1530 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1531 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1532
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1533 /* register other hashes ... */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1534
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1535 /* prompt for name and strip newline */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1536 printf("Enter hash name: \n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1537 fgets(buffer, sizeof(buffer), stdin);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1538 buffer[strlen(buffer) - 1] = 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1539
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1540 /* get hash index */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1541 idx = find_hash(buffer);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1542 if (idx == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1543 printf("Invalid hash name!\n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1544 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1545 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1546
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1547 /* hash input until blank line */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1548 hash_descriptor[idx].init(&md);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1549 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	1550 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	1551 hash_descriptor[idx].done(&md, hash);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1552
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1553 /* dump to screen */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1554 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	1555 printf("%02x ", hash[x]);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1556 printf("\n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1557 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1558 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1559 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1560 \end{small}
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 Note the usage of ``MAXBLOCKSIZE''. In Libtomcrypt no symmetric block, key or hash digest is larger than MAXBLOCKSIZE in
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1563 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	1564
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1565 There are three helper functions as well:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1566 \index{hash\_memory()} \index{hash\_file()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1567 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1568 int hash_memory(int hash,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1569 const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1570 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1571
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1572 int hash_file(int hash, const char *fname,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1573 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1574
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1575 int hash_filehandle(int hash, FILE *in,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1576 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1577 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1578
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1579 The ``hash'' parameter is the location in the descriptor table of the hash (\textit{e.g. the return of find\_hash()}).
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1580 The ``*outlen'' variable is used to keep track of the output size. You must set it to the size of your output buffer before
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1581 calling the functions. When they complete succesfully they store the length of the message digest back in it. The functions
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1582 are otherwise straightforward. The ``hash\_filehandle'' function assumes that ``in'' is an file handle opened in binary mode.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1583 It will hash to the end of file and not reset the file position when finished.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1584
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1585 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	1586 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1587 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1588 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1589 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1590 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1591 int idx, err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1592 unsigned long len;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1593 unsigned char out[MAXBLOCKSIZE];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1594
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1595 /* register the hash */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1596 if (register_hash(&md5_desc) == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1597 printf("Error registering MD5.\n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1598 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1599 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1600
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1601 /* get the index of the hash */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1602 idx = find_hash("md5");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1603
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1604 /* call the hash */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1605 len = sizeof(out);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1606 if ((err = hash_memory(idx, "hello world", 11, out, &len)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1607 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	1608 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1609 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1610 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1611 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1612 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1613 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1614
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1615 The following hashes are provided as of this release:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1616 \index{Hash descriptor table}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1617 \begin{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1618 \begin{tabular}{\|c\|c\|c\|}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1619 \hline Name & Descriptor Name & Size of Message Digest (bytes) \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1620 \hline WHIRLPOOL & whirlpool\_desc & 64 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1621 \hline SHA-512 & sha512\_desc & 64 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1622 \hline SHA-384 & sha384\_desc & 48 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1623 \hline SHA-256 & sha256\_desc & 32 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1624 \hline SHA-224 & sha224\_desc & 28 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1625 \hline TIGER-192 & tiger\_desc & 24 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1626 \hline SHA-1 & sha1\_desc & 20 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1627 \hline RIPEMD-160 & rmd160\_desc & 20 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1628 \hline RIPEMD-128 & rmd128\_desc & 16 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1629 \hline MD5 & md5\_desc & 16 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1630 \hline MD4 & md4\_desc & 16 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1631 \hline MD2 & md2\_desc & 16 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1632 \hline
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1633 \end{tabular}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1634 \end{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1635
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1636 Similar to the cipher descriptor table you must register your hash algorithms before you can use them. These functions
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1637 work exactly like those of the cipher registration code. The functions are:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1638 \index{register\_hash()} \index{unregister\_hash()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1639 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1640 int register_hash(const struct _hash_descriptor *hash);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1641 int unregister_hash(const struct _hash_descriptor *hash);
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 \section{Cipher Hash Construction}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1645 \index{Cipher Hash Construction}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1646 An addition to the suite of hash functions is the ``Cipher Hash Construction'' or ``CHC'' mode. In this mode
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1647 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	1648 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	1649
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1650 In order to use the CHC system the developer will have to take a few extra steps. First the ``chc\_desc'' hash
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1651 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	1652 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	1653 via the chc\_register() function.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1654
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1655 \index{chc\_register()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1656 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1657 int chc_register(int cipher);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1658 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1659
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1660 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	1661 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	1662 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	1663
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1664 \begin{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1665 \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	1666 \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	1667 \end{enumerate}
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 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	1670
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1671 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1672 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1673 int main(void)
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 int err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1676
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1677 /* register cipher and hash */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1678 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	1679 printf("Could not register cipher\n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1680 return EXIT_FAILURE;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1681 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1682 if (register_hash(&chc_desc) == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1683 printf("Could not register hash\n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1684 return EXIT_FAILURE;
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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1687 /* start chc with AES */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1688 if ((err = chc_register(find_cipher("aes"))) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1689 printf("Error binding AES to CHC: %s\n", error_to_string(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 /* now you can use chc_hash in any LTC function [aside from pkcs...] */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1693 /* ... */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1694 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1695
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1696
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1697 \section{Notice}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1698 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	1699 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	1700 (e.g. Yarrow).
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1701
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1702 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	1703 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	1704
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1705 \chapter{Message Authentication Codes}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1706 \section{HMAC Protocol}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1707 Thanks to Dobes Vandermeer the library now includes support for hash based message authenication codes or HMAC for short. An HMAC
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1708 of a message is a keyed authenication code that only the owner of a private symmetric key will be able to verify. The purpose is
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1709 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	1710 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	1711
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1712 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	1713 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1714 chars. The initialization routine is:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1715 \index{hmac\_init()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1716 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1717 int hmac_init(hmac_state *hmac, int hash,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1718 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	1719 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1720 The ``hmac'' parameter is the state for the HMAC code. ``hash'' is the index into the descriptor table of the hash you want
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1721 to use to authenticate the message. ``key'' is the pointer to the array of chars that make up the key. ``keylen'' is the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1722 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	1723 \index{hmac\_process()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1724 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1725 int hmac_process(hmac_state *hmac,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1726 const unsigned char *in, unsigned long inlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1727 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1728 ``hmac'' is the HMAC state you are working with. ``buf'' is the array of octets to send into the HMAC process. ``len'' is the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1729 number of octets to process. Like the hash process routines you can send the data in arbitrarly sized chunks. When you
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1730 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	1731 \index{hmac\_done()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1732 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1733 int hmac_done(hmac_state *hmac,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1734 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1735 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1736 ``hmac'' is the HMAC state you are working with. ``out'' is the array of octets where the HMAC code should be stored. You must
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1737 set ``outlen'' to the size of the destination buffer before calling this function. It is updated with the length of the HMAC code
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1738 produced (depending on which hash was picked). If ``outlen'' is less than the size of the message digest (and ultimately
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1739 the HMAC code) then the HMAC code is truncated as per FIPS-198 specifications (e.g. take the first ``outlen'' bytes).
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1740
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1741 There are two utility functions provided to make using HMACs easier todo. They accept the key and information about the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1742 message (file pointer, address in memory) and produce the HMAC result in one shot. These are useful if you want to avoid
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1743 calling the three step process yourself.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1744
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1745 \index{hmac\_memory()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1746 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1747 int hmac_memory(int hash,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1748 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	1749 const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1750 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1751 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1752 This will produce an HMAC code for the array of octets in ``in'' of length ``inlen''. The index into the hash descriptor
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1753 table must be provided in ``hash''. It uses the key from ``key'' with a key length of ``keylen''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1754 The result is stored in the array of octets ``out'' and the length in ``outlen''. The value of ``outlen'' must be set
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1755 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	1756 \index{hmac\_file()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1757 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1758 int hmac_file(int hash, const char *fname,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1759 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	1760 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1761 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1762 ``hash'' is the index into the hash descriptor table of the hash you want to use. ``fname'' is the filename to process.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1763 ``key'' is the array of octets to use as the key of length ``keylen''. ``out'' is the array of octets where the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1764 result should be stored.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1765
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1766 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	1767 \index{hmac\_test()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1768 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1769 int hmac_test(void);
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 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	1772 HMAC system is given below.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1773
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1774 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1775 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1776 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1777 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1778 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1779 int idx, err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1780 hmac_state hmac;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1781 unsigned char key[16], dst[MAXBLOCKSIZE];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1782 unsigned long dstlen;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1783
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1784 /* register SHA-1 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1785 if (register_hash(&sha1_desc) == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1786 printf("Error registering SHA1\n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1787 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1788 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1789
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1790 /* 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	1791 idx = find_hash("sha1");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1792
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1793 /* 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	1794
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1795 /* start the HMAC */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1796 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	1797 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	1798 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1799 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1800
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1801 /* process a few octets */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1802 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	1803 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	1804 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1805 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1806
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1807 /* 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	1808 dstlen = sizeof(dst);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1809 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	1810 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	1811 return -1;
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 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	1814
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1815 /* return */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1816 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1817 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1818 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1819 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1820
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1821 \section{OMAC Support}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1822 OMAC\footnote{\url{http://crypt.cis.ibaraki.ac.jp/omac/omac.html}}, which stands for \textit{One-Key CBC MAC} is an
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1823 algorithm which produces a Message Authentication Code (MAC) using only a block cipher such as AES. From an API
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1824 standpoint the OMAC routines work much like the HMAC routines do. Instead in this case a cipher is used instead of a hash.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1825
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1826 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	1827 \index{omac\_init()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1828 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1829 int omac_init(omac_state *omac, int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1830 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	1831 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1832 The ``omac'' variable is the state for the OMAC algorithm. ``cipher'' is the index into the cipher\_descriptor table
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1833 of the cipher\footnote{The cipher must have a 64 or 128 bit block size. Such as CAST5, Blowfish, DES, AES, Twofish, etc.} you
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1834 wish to use. ``key'' and ``keylen'' are the keys used to authenticate the data.
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 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	1837 \index{omac\_process()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1838 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1839 int omac_process(omac_state *state,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1840 const unsigned char *in, unsigned long inlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1841 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1842 This will send ``inlen'' bytes from ``in'' through the active OMAC state ``state''. Returns \textbf{CRYPT\_OK} if the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1843 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	1844
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1845 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1846 omac_process(&mystate, "hello", 5);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1847 omac_process(&mystate, " world", 6);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1848 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1849
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1850 Would produce the same result as,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1851
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1852 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1853 omac_process(&mystate, "hello world", 11);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1854 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1855
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1856 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	1857
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1858 \index{omac\_done()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1859 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1860 int omac_done(omac_state *state,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1861 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1862 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1863 Which will terminate the OMAC and output the \textit{tag} (MAC) to ``out''. Note that unlike the HMAC and other code
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1864 ``outlen'' can be smaller than the default MAC size (for instance AES would make a 16-byte tag). Part of the OMAC
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1865 specification states that the output may be truncated. So if you pass in $outlen = 5$ and use AES as your cipher than
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1866 the output MAC code will only be five bytes long. If ``outlen'' is larger than the default size it is set to the default
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1867 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	1868
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1869 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	1870 following function.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1871
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1872 \index{omac\_memory()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1873 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1874 int omac_memory(int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1875 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	1876 const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1877 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1878 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1879 This will compute the OMAC of ``inlen'' bytes of ``in'' using the key ``key'' of length ``keylen'' bytes and the cipher
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1880 specified by the ``cipher'''th entry in the cipher\_descriptor table. It will store the MAC in ``out'' with the same
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1881 rules as omac\_done.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1882
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1883 To OMAC a file use
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1884 \index{omac\_file()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1885 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1886 int omac_file(int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1887 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	1888 const char *filename,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1889 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1890 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1891
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1892 Which will OMAC the entire contents of the file specified by ``filename'' using the key ``key'' of length ``keylen'' bytes
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1893 and the cipher specified by the ``cipher'''th entry in the cipher\_descriptor table. It will store the MAC in ``out'' with
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1894 the same rules as omac\_done.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1895
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1896 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	1897 \index{omac\_test()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1898 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1899 int omac_test(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1900 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1901 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	1902 OMAC system is given below.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1903
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1904 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1905 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1906 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1907 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1908 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1909 int idx, err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1910 omac_state omac;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1911 unsigned char key[16], dst[MAXBLOCKSIZE];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1912 unsigned long dstlen;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1913
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1914 /* register Rijndael */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1915 if (register_cipher(&rijndael_desc) == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1916 printf("Error registering Rijndael\n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1917 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1918 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1919
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1920 /* 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	1921 idx = find_cipher("rijndael");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1922
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1923 /* 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	1924
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1925 /* start the OMAC */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1926 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	1927 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	1928 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1929 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1930
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1931 /* process a few octets */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1932 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	1933 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	1934 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1935 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1936
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1937 /* 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	1938 dstlen = sizeof(dst);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1939 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	1940 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	1941 return -1;
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 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	1944
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1945 /* return */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1946 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1947 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1948 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1949 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1950
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1951 \section{PMAC Support}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1952 The PMAC\footnote{J.Black, P.Rogaway, ``A Block--Cipher Mode of Operation for Parallelizable Message Authentication''}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1953 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	1954 API as the provided OMAC code.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1955
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1956 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	1957
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1958 \index{pmac\_init()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1959 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1960 int pmac_init(pmac_state *pmac, int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1961 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	1962 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1963 Which initializes the ``pmac'' state with the given ``cipher'' and ``key'' of length ``keylen'' bytes. The chosen cipher
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1964 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	1965
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1966 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	1967
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1968 \index{pmac\_process()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1969 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1970 int pmac_process(pmac_state *state,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1971 const unsigned char *in, unsigned long inlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1972 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1973 This will process ``inlen'' bytes of ``in'' in the given ``state''. The function is not sensitive to the granularity of the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1974 data. For example,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1975
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1976 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1977 pmac_process(&mystate, "hello", 5);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1978 pmac_process(&mystate, " world", 6);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1979 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1980
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1981 Would produce the same result as,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1982
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1983 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1984 pmac_process(&mystate, "hello world", 11);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1985 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1986
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1987 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	1988
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1989 \index{pmac\_done()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1990 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1991 int pmac_done(pmac_state *state,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1992 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1993 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1994 This will store upto ``outlen'' bytes of the tag for the given ``state'' into ``out''. Note that if ``outlen'' is larger
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1995 than the size of the tag it is set to the amount of bytes stored in ``out''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1996
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1997 Similar to the PMAC code the file and memory functions are also provided. To PMAC 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	1998 following function.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	1999
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2000 \index{pmac\_memory()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2001 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2002 int pmac_memory(int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2003 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	2004 const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2005 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2006 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2007 This will compute the PMAC of ``msglen'' bytes of ``msg'' using the key ``key'' of length ``keylen'' bytes and the cipher
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2008 specified by the ``cipher'''th entry in the cipher\_descriptor table. It will store the MAC in ``out'' with the same
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2009 rules as omac\_done.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2010
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2011 To PMAC a file use
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2012 \index{pmac\_file()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2013 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2014 int pmac_file(int cipher,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2015 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	2016 const char *filename,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2017 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2018 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2019
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2020 Which will PMAC the entire contents of the file specified by ``filename'' using the key ``key'' of length ``keylen'' bytes
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2021 and the cipher specified by the ``cipher'''th entry in the cipher\_descriptor table. It will store the MAC in ``out'' with
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2022 the same rules as omac\_done.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2023
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2024 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	2025 \index{pmac\_test()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2026 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2027 int pmac_test(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2028 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2029 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	2030
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2031 \section{Pelican MAC}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2032 Pelican MAC is a new (experimental) MAC by the AES team that uses four rounds of AES as a ``mixing function''. It achieves a very high
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2033 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	2034 as it calls AES directly.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2035
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2036 \index{pelican\_init()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2037 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2038 int pelican_init(pelican_state pelmac, 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	2039 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2040 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	2041
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2042 \index{pelican\_process()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2043 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2044 int pelican_process(pelican_state pelmac, const unsigned char in, unsigned long inlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2045 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2046 This will process ``inlen'' bytes of ``in'' through the Pelican MAC. It's best that you pass in multiples of 16 bytes as it makes the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2047 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	2048 an entire message.
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 \index{pelican\_done()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2051 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2052 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	2053 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2054 This terminates a Pelican MAC and writes the 16--octet tag to ``out''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2055
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2056 \subsection{Example}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2057
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2058 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2059 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2060 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2061 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2062 pelican_state pelstate;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2063 unsigned char key[32], tag[16];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2064 int err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2065
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2066 /* somehow initialize a key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2067
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2068 /* initialize pelican mac */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2069 if ((err = pelican_init(&pelstate, /* the state */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2070 key, /* user key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2071 32 /* key length in octets */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2072 )) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2073 printf("Error initializing Pelican: %s", error_to_string(err));
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2074 return EXIT_FAILURE;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2075 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2076
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2077 /* MAC some data */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2078 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	2079 "hello world", /* data to mac */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2080 11 /* length of data */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2081 )) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2082 printf("Error processing Pelican: %s", error_to_string(err));
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2083 return EXIT_FAILURE;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2084 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2085
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2086 /* Terminate the MAC */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2087 if ((err = pelican_done(&pelstate, /* the state */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2088 tag /* where to store the tag */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2089 )) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2090 printf("Error terminating Pelican: %s", error_to_string(err));
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2091 return EXIT_FAILURE;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2092 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2093
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2094 /* 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	2095
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2096 return EXIT_SUCCESS;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2097 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2098 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2099
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2100
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2101 \chapter{Pseudo-Random Number Generators}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2102 \section{Core Functions}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2103 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	2104 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)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2105 key generation. There is a universal structure called ``prng\_state''. To initialize a PRNG call:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2106 \index{PRNG start}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2107 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2108 int XXX_start(prng_state *prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2109 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2110
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2111 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	2112 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	2113 \index{PRNG add\_entropy}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2114 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2115 int XXX_add_entropy(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2116 prng_state *prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2117 \end{verbatim}
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 Which returns {\bf CRYPTO\_OK} if the entropy was accepted. Once you think you have enough entropy you call another
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2120 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	2121 \index{PRNG ready}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2122 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2123 int XXX_ready(prng_state *prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2124 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2125
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2126 Which returns {\bf CRYPTO\_OK} if it is ready. Finally to actually read bytes call:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2127 \index{PRNG read}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2128 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2129 unsigned long XXX_read(unsigned char *out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2130 prng_state *prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2131 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2132
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2133 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	2134 the following.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2135
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2136 \index{PRNG done}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2137 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2138 void XXX_done(prng_state *prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2139 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2140
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2141 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	2142 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	2143
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2144 \index{PRNG export}
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 XXX_export(unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2147 prng_state *prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2148 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2149
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2150 This will write a ``PRNG state'' to the buffer ``out'' of length ``outlen'' bytes. The idea of
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2151 the export is meant to be used as a ``seed file''. That is, when the program starts up there will not likely
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2152 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	2153
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2154 \index{PRNG import}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2155 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2156 int XXX_import(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2157 prng_state *prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2158 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2159
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2160 This will call the start and add\_entropy functions of the given PRNG. It will use the state in
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2161 ``in'' of length ``inlen'' as the initial seed. You must pass the same seed length as was exported
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2162 by the corresponding export function.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2163
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2164 Note that importing a state will not ``resume'' the PRNG from where it left off. That is, if you export
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2165 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	2166 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	2167
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2168 When a program is first executed the normal course of operation is
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 \begin{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2171 \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	2172 \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	2173 \end{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2174
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2175 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	2176 flash memory, etc). The next time your application starts up you can detect the state, feed it to the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2177 import function and go on your way. It is ideal that (as soon as possible) after startup you export a
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2178 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	2179 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	2180
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2181 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	2182 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	2183
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2184 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	2185
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2186 \index{PRNG test}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2187 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2188 int XXX_test(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2189 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2190
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2191 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	2192
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2193 \subsection{Remarks}
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 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	2196 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	2197 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2198 checking is guaranteed to see if the entropy is sufficient or if the PRNG is even in a ready state before reading.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2199
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2200 \subsection{Example}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2201
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2202 Below is a simple snippet to read 10 bytes from yarrow. Its important to note that this snippet is
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2203 {\bf NOT} secure since the entropy added is not random.
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 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2206 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2207 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2208 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2209 prng_state prng;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2210 unsigned char buf[10];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2211 int err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2212
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2213 /* start it */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2214 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	2215 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	2216 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2217 /* add entropy */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2218 if ((err = yarrow_add_entropy("hello world", 11, &prng)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2219 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	2220 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2221 /* ready and read */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2222 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	2223 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	2224 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2225 printf("Read %lu bytes from yarrow\n", yarrow_read(buf, 10, &prng));
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2226 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2227 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2228 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2229
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2230 \section{PRNG Descriptors}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2231 \index{PRNG Descriptor}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2232 PRNGs have descriptors too (surprised?). Stored in the structure ``prng\_descriptor''. The format of an element is:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2233 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2234 struct _prng_descriptor {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2235 char *name;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2236 int export_size; /* size in bytes of exported state */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2237 int (start) (prng_state );
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2238 int (add_entropy)(const unsigned char , unsigned long, prng_state *);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2239 int (ready) (prng_state );
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2240 unsigned long (read)(unsigned char , unsigned long len, prng_state *);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2241 void (done)(prng_state );
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2242 int (export)(unsigned char , unsigned long , prng_state );
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2243 int (import)(const unsigned char , unsigned long, prng_state *);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2244 int (*test)(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2245 };
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2246 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2247
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2248 There is a ``int find\_prng(char *name)'' function as well. Returns -1 if the PRNG is not found, otherwise it returns
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2249 the position in the prng\_descriptor array.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2250
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2251 Just like the ciphers and hashes you must register your prng before you can use it. The two functions provided work
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2252 exactly as those for the cipher registry functions. They are:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2253 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2254 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	2255 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	2256 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2257
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2258 \subsection{PRNGs Provided}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2259 \begin{figure}[here]
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2260 \begin{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2261 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2262 \begin{tabular}{\|c\|c\|l\|}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2263 \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	2264 \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	2265 \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	2266 \hline RC4 & rc4\_desc & Stream Cipher \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2267 \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	2268 \hline
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2269 \end{tabular}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2270 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2271 \end{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2272 \caption{List of Provided PRNGs}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2273 \end{figure}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2274
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2275 \subsubsection{Yarrow}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2276 Yarrow is fast PRNG meant to collect an unspecified amount of entropy from sources
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2277 (keyboard, mouse, interrupts, etc) and produce an unbounded string of random bytes.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2278
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2279 \textit{Note:} This PRNG is still secure for most taskings but is no longer recommended. Users
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2280 should use Fortuna instead.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2281
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2282 \subsubsection{Fortuna}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2283
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2284 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	2285 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	2286 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	2287 providing more security.
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 Fortuna is slightly less flexible than Yarrow in the sense that it only works with the AES block cipher
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2290 and SHA--256 hash function. Technically Fortuna will work with any block cipher that accepts a 256--bit
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2291 key and any hash that produces at least a 256--bit output. However, to make the implementation simpler
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2292 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	2293
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2294 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	2295 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	2296 details Fortuna has the ability to recover from state determination attacks where the attacker starts
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2297 to learn information from the PRNGs output about the internal state. Yarrow on the other hand cannot
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2298 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	2299
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2300 \subsubsection{RC4}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2301
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2302 RC4 is an old stream cipher that can also double duty as a PRNG in a pinch. You ``key'' it by
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2303 calling add\_entropy() and setup the key by calling ready(). You can only add upto 256 bytes via
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2304 add\_entropy().
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2305
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2306 When you read from RC4 the output of the RC4 algorithm is XOR'd against your buffer you provide. In this
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2307 manner you can use rc4\_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	2308
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2309 You really shouldn't use RC4 anymore. This isn't because RC4 is weak (though biases are known to exist) just
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2310 simply that faster alternatives exist.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2311
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2312 \subsubsection{SOBER-128}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2313
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2314 SOBER-128 is a stream cipher designed by the QUALCOMM Australia team. Like RC4 you ``key'' it by
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2315 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	2316
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2317 Note that this cipher has several oddities about how it operates. The first time you call
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2318 add\_entropy() that sets the cipher's key. Every other time you call the same function it sets
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2319 the cipher's IV variable. The IV mechanism allows you to encrypt several messages with the same
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2320 key and not re--use the same key material.
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 Unlike Yarrow and Fortuna all of the entropy (and hence security) of this algorithm rests in the data
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2323 you pass it on the first call to add\_entropy(). All buffers sent to add\_entropy() must have a length
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2324 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	2325
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2326 Like RC4 the output of SOBER--128 is XOR'ed against the buffer you provide it. In this manner you can use
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2327 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	2328
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2329 Since SOBER-128 has a fixed keying scheme and is very fast (faster than RC4) the ideal usage of SOBER-128 is to
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2330 key it from the output of Fortuna (or Yarrow) and use it to encrypt messages. It is also ideal for
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2331 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	2332
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2333 \subsubsection{Example Usage}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2334 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2335 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2336 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2337 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2338 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2339 prng_state prng;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2340 unsigned char buf[32];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2341 int err;
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 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	2344 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	2345 exit(-1);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2346 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2347
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2348 /* use ``key'' as the key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2349 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	2350 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	2351 exit(-1);
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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2354 /* setup RC4 for use */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2355 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	2356 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	2357 exit(-1);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2358 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2359
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2360 /* encrypt buffer */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2361 strcpy(buf,"hello world");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2362 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	2363 printf("RC4 read error\n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2364 exit(-1);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2365 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2366 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2367 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2368 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2369 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2370 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	2371
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2372 \section{The Secure RNG}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2373 \index{Secure RNG}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2374 An RNG is related to a PRNG except that it doesn't expand a smaller seed to get the data. They generate their random bits
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2375 by performing some computation on fresh input bits. Possibly the hardest thing to get correctly in a cryptosystem is the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2376 PRNG. Computers are deterministic beasts that try hard not to stray from pre-determined paths. That makes gathering
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2377 entropy needed to seed the PRNG a hard task.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2378
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2379 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	2380 \index{rng\_get\_bytes()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2381 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2382 unsigned long rng_get_bytes(unsigned char *buf, unsigned long len,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2383 void (*callback)(void));
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2384 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2385
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2386 Which will try one of three methods of getting random data. The first is to open the popular ``/dev/random'' device which
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2387 on most *NIX platforms provides cryptographic random bits\footnote{This device is available in Windows through the Cygwin compiler suite. It emulates ``/dev/random'' via the Microsoft CSP.}.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2388 The second method is to try the Microsoft Cryptographic Service Provider and read the RNG. The third method is an ANSI C
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2389 clock drift method that is also somewhat popular but gives bits of lower entropy. The ``callback'' parameter is a pointer to a function that returns void. Its used when the slower ANSI C RNG must be
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2390 used so the calling application can still work. This is useful since the ANSI C RNG has a throughput of three
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2391 bytes a second. The callback pointer may be set to {\bf NULL} to avoid using it if you don't want to. The function
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2392 returns the number of bytes actually read from any RNG source. There is a function to help setup a PRNG as well:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2393 \index{rng\_make\_prng()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2394 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2395 int rng_make_prng(int bits, int wprng, prng_state *prng,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2396 void (*callback)(void));
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2397 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2398 This will try to setup the prng with a state of at least ``bits'' of entropy. The ``callback'' parameter works much like
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2399 the callback in ``rng\_get\_bytes()''. It is highly recommended that you use this function to setup your PRNGs unless you have a
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2400 platform where the RNG doesn't work well. Example usage of this function is given below.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2401
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2402 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2403 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2404 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2405 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2406 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2407 ecc_key mykey;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2408 prng_state prng;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2409 int err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2410
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2411 /* register yarrow */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2412 if (register_prng(&yarrow_desc) == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2413 printf("Error registering Yarrow\n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2414 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2415 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2416
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2417 /* setup the PRNG */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2418 if ((err = rng_make_prng(128, find_prng("yarrow"), &prng, NULL)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2419 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	2420 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2421 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2422
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2423 /* make a 192-bit ECC key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2424 if ((err = ecc_make_key(&prng, find_prng("yarrow"), 24, &mykey)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2425 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	2426 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2427 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2428 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2429 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2430 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2431 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2432
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2433 \subsection{The Secure PRNG Interface}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2434 It is possible to access the secure RNG through the PRNG interface and in turn use it within dependent functions such
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2435 as the PK API. This simplifies the cryptosystem on platforms where the secure RNG is fast. The secure PRNG never
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2436 requires to be started, that is you need not call the start, add\_entropy or ready functions. For example, consider
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2437 the previous example using this PRNG.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2438
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2439 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2440 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2441 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2442 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2443 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2444 ecc_key mykey;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2445 int err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2446
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2447 /* register SPRNG */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2448 if (register_prng(&sprng_desc) == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2449 printf("Error registering SPRNG\n");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2450 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2451 }
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 /* make a 192-bit ECC key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2454 if ((err = ecc_make_key(NULL, find_prng("sprng"), 24, &mykey)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2455 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	2456 return -1;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2457 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2458 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2459 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2460 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2461 \end{small}
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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2464
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2465 \chapter{RSA Public Key Cryptography}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2466
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2467 \section{Introduction}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2468 RSA wrote the PKCS \#1 specifications which detail RSA Public Key Cryptography. In the specifications are
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2469 padding algorithms for encryption and signatures. The standard includes the ``v2.1'' algorithms.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2470 To simplify matters a little the v2.1 encryption and signature padding algorithms are called OAEP and PSS
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2471 respectively.
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 \section{PKCS \#1 Encryption}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2474
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2475 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	2476 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	2477
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2478 \subsection{OAEP Encoding}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2479
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2480 \index{pkcs\_1\_oaep\_encode()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2481 \begin{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2482 int pkcs_1_oaep_encode(const unsigned char *msg, unsigned long msglen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2483 const unsigned char *lparam, unsigned long lparamlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2484 unsigned long modulus_bitlen, prng_state *prng,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2485 int prng_idx, int hash_idx,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2486 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2487 \end{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2488
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2489 This accepts ``msg'' as input of length ``msglen'' which will be OAEP padded. The ``lparam'' variable is an additional system specific
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2490 tag that can be applied to the encoding. This is useful to identify which system encoded the message. If no variance is desired then
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2491 ``lparam'' can be set to \textbf{NULL}.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2492
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2493 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2494 ``modulus\_bitlen''. ``hash\_idx'' is the index into the hash descriptor table of the hash desired. PKCS \#1 allows any hash to be
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2495 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2496 sized input message. ``prng\_idx'' and ``prng'' are the random number generator arguments required to randomize the padding process.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2497 The padded message is stored in ``out'' along with the length in ``outlen''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2498
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2499 If $h$ is the length of the hash and $m$ the length of the modulus (both in octets) then the maximum payload for ``msg'' is
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2500 $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	2501
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2502 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	2503 rsa\_exptmod() to encrypt it.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2504
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2505 \subsection{OAEP Decoding}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2506
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2507 \index{pkcs\_1\_oaep\_decode()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2508 \begin{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2509 int pkcs_1_oaep_decode(const unsigned char *msg, unsigned long msglen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2510 const unsigned char *lparam, unsigned long lparamlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2511 unsigned long modulus_bitlen, int hash_idx,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2512 unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2513 int *res);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2514 \end{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2515
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2516 This function decodes an OAEP encoded message and outputs the original message that was passed to the OAEP encoder. ``msg'' is the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2517 output of pkcs\_1\_oaep\_encode() of length ``msglen''. ``lparam'' is the same system variable passed to the OAEP encoder. If it does not
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2518 match what was used during encoding this function will not decode the packet. ``modulus\_bitlen'' is the size of the RSA modulus in bits
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2519 and must match what was used during encoding. Similarly the ``hash\_idx'' index into the hash descriptor table must match what was used
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2520 during encoding.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2521
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2522 If the function succeeds it decodes the OAEP encoded message into ``out'' of length ``outlen'' and stores a
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2523 $1$ in ``res''. If the packet is invalid it stores $0$ in ``res'' and if the function fails for another reason
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2524 it returns an error code.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2525
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2526 \section{PKCS \#1 Digital Signatures}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2527
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2528 \subsection{PSS Encoding}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2529 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	2530
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2531 \index{pkcs\_1\_pss\_encode()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2532 \begin{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2533 int pkcs_1_pss_encode(const unsigned char *msghash, unsigned long msghashlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2534 unsigned long saltlen, prng_state *prng,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2535 int prng_idx, int hash_idx,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2536 unsigned long modulus_bitlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2537 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2538 \end{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2539
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2540 This function assumes the message to be PSS encoded has previously been hashed. The input hash ``msghash'' is of length
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2541 ``msghashlen''. PSS allows a variable length random salt (it can be zero length) to be introduced in the signature process.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2542 ``hash\_idx'' is the index into the hash descriptor table of the hash to use. ``prng\_idx'' and ``prng'' are the random
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2543 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	2544
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2545 Similar to OAEP encoding ``modulus\_bitlen'' is the size of the RSA modulus (in bits). It limits the size of the salt. If $m$ is the length
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2546 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	2547
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2548 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	2549
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2550 \subsection{PSS Decoding}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2551
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2552 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	2553
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2554 \index{pkcs\_1\_pss\_decode()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2555 \begin{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2556 int pkcs_1_pss_decode(const unsigned char *msghash, unsigned long msghashlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2557 const unsigned char *sig, unsigned long siglen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2558 unsigned long saltlen, int hash_idx,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2559 unsigned long modulus_bitlen, int *res);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2560 \end{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2561 This will decode the PSS encoded message in ``sig'' of length ``siglen'' and compare it to values in ``msghash'' of length
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2562 ``msghashlen''. If the block is a valid PSS block and the decoded hash equals the hash supplied ``res'' is set to non--zero. Otherwise,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2563 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	2564
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2565 It's important to use the same ``saltlen'' and hash for both encoding and decoding as otherwise the procedure will not work.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2566
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2567 \section{RSA Operations}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2568 \subsection{Background}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2569
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2570 RSA is a public key algorithm that is based on the inability to find the ``e-th'' root modulo a composite of unknown
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2571 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	2572 not strictly equivalent.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2573
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2574 The system begins with with two primes $p$ and $q$ and their product $N = pq$. The order or ``Euler totient'' of the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2575 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	2576 $\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	2577 $\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	2578 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	2579
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2580 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	2581 $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	2582 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	2583 $C^d \equiv \left (M^e \right)^d \equiv M^1 \equiv M\mbox{ }(\mbox{mod }N)$. Similarly the owner of the private key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2584 can sign a message by ``decrypting'' it. Others can verify it by ``encrypting'' it.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2585
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2586 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	2587 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	2588 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	2589 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	2590 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	2591
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2592 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	2593 $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	2594 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	2595 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	2596 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	2597
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2598 \subsection{RSA Key Generation}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2599
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2600 For RSA routines a single ``rsa\_key'' structure is used. To make a new RSA key call:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2601 \index{rsa\_make\_key()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2602 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2603 int rsa_make_key(prng_state *prng,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2604 int wprng, int size,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2605 long e, rsa_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2606 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2607
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2608 Where ``wprng'' is the index into the PRNG descriptor array. ``size'' is the size in bytes of the RSA modulus desired.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2609 ``e'' is the encryption exponent desired, typical values are 3, 17, 257 and 65537. I suggest you stick with 65537 since its big
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2610 enough to prevent trivial math attacks and not super slow. ``key'' is where the key is placed. All keys must be at
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2611 least 128 bytes and no more than 512 bytes in size (\textit{that is from 1024 to 4096 bits}).
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2612
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2613 Note that the ``rsa\_make\_key()'' function allocates memory at runtime when you make the key. Make sure to call
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2614 ``rsa\_free()'' (see below) when you are finished with the key. If ``rsa\_make\_key()'' fails it will automatically
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2615 free the ram allocated itself.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2616
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2617 \index{PK\_PRIVATE} \index{PK\_PUBLIC}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2618 There are two types of RSA keys. The types are {\bf PK\_PRIVATE} and {\bf PK\_PUBLIC}. The first type is a private
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2619 RSA key which includes the CRT parameters\footnote{As of v0.99 the PK\_PRIVATE\_OPTIMIZED type has been deprecated
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2620 and has been replaced by the PK\_PRIVATE type.} in the form of a RSAPrivateKey. The second type is a public RSA key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2621 which only includes the modulus and public exponent. It takes the form of a RSAPublicKey.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2622
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2623 \subsection{RSA Exponentiation}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2624
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2625 To do raw work with the RSA function call:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2626 \index{rsa\_exptmod()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2627 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2628 int rsa_exptmod(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2629 unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2630 int which, prng_state *prng, int prng_idx,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2631 rsa_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2632 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2633 This loads the bignum from ``in'' as a big endian word in the format PKCS specifies, raises it to either ``e'' or ``d'' and stores the result
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2634 in ``out'' and the size of the result in ``outlen''. ``which'' is set to {\bf PK\_PUBLIC} to use ``e''
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2635 (i.e. for encryption/verifying) and set to {\bf PK\_PRIVATE} to use ``d'' as the exponent (i.e. for decrypting/signing).
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2636
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2637 Note that the output of his function is zero-padded as per PKCS \#1 specifications. This allows this routine to
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2638 interoprate with PKCS \#1 padding functions properly.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2639
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2640 \subsection{RSA Key Encryption}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2641 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	2642 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	2643
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2644 \index{rsa\_encrypt\_key()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2645 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2646 int rsa_encrypt_key(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2647 unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2648 const unsigned char *lparam, unsigned long lparamlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2649 prng_state prng, int prng_idx, int hash_idx, rsa_key key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2650 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2651 This function will OAEP pad ``in'' of length inlen bytes then RSA encrypt it and store the ciphertext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2652 in ``out'' of length ``outlen''. The ``lparam'' and ``lparamlen'' are the same parameters you would pass
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2653 to pkcs\_1\_oaep\_encode().
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2654
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2655 \index{rsa\_decrypt\_key()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2656 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2657 int rsa_decrypt_key(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2658 unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2659 const unsigned char *lparam, unsigned long lparamlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2660 int hash_idx, int *stat,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2661 rsa_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2662 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2663 This function will RSA decrypt ``in'' of length ``inlen'' then OAEP depad the resulting data and store it in
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2664 ``out'' of length ``outlen''. The ``lparam'' and ``lparamlen'' are the same parameters you would pass
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2665 to pkcs\_1\_oaep\_decode().
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2666
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2667 If the RSA decrypted data isn't a valid OAEP packet then ``stat'' is set to $0$. Otherwise, it is set to $1$.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2668
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2669 \subsection{RSA Hash Signatures}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2670 Similar to RSA key encryption RSA is also used to ``digitally sign'' message digests (hashes). To facilitate this
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2671 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	2672
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2673 \index{rsa\_sign\_hash()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2674 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2675 int rsa_sign_hash(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2676 unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2677 prng_state *prng, int prng_idx,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2678 int hash_idx, unsigned long saltlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2679 rsa_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2680 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2681
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2682 This will PSS encode the message hash ``in'' of length ``inlen''. Next the PSS encoded message will be RSA ``signed'' and
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2683 the output is stored in ``out'' of length ``outlen''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2684
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2685
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2686 \index{rsa\_verify\_hash()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2687 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2688 int rsa_verify_hash(const unsigned char *sig, unsigned long siglen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2689 const unsigned char *msghash, unsigned long msghashlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2690 int hash_idx, unsigned long saltlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2691 int stat, rsa_key key);
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 This will RSA ``verify'' the signature in ``sig'' of length ``siglen''. Next the RSA decoded data is PSS decoded
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2695 and the extracted hash is compared against the message hash ``msghash'' of length ``msghashlen''.
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 If the RSA decoded data is not a valid PSS message or if the PSS decoded hash does not match the ``msghash''
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2698 the value ``res'' is set to $0$. Otherwise, if the function succeeds and signature is valid ``res'' is set
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2699 to $1$.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2700
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2701 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2702 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2703 int main(void)
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 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	2706 unsigned long l1, l2;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2707 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	2708 rsa_key key;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2709
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2710 /* register prng/hash */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2711 if (register_prng(&sprng_desc) == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2712 printf("Error registering sprng");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2713 return EXIT_FAILURE;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2714 }
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 if (register_hash(&sha1_desc) == -1) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2717 printf("Error registering sha1");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2718 return EXIT_FAILURE;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2719 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2720 hash_idx = find_hash("sha1");
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2721 prng_idx = find_prng("sprng");
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 /* make an RSA-1024 key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2724 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	2725 prng_idx, /* PRNG idx */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2726 1024/8, /* 1024-bit key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2727 65537, /* we like e=65537 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2728 &key) /* where to store the key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2729 ) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2730 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	2731 return EXIT_FAILURE;
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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2734 /* 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	2735 l1 = sizeof(out);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2736 if ((err = rsa_encrypt_key(pt, /* data we wish to encrypt */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2737 16, /* data is 16 bytes long */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2738 out, /* where to store ciphertext */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2739 &l1, /* length of ciphertext */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2740 "TestApp", /* our lparam for this program */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2741 7, /* lparam is 7 bytes long */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2742 NULL, /* PRNG state */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2743 prng_idx, /* prng idx */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2744 hash_idx, /* hash idx */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2745 &key) /* our RSA key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2746 ) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2747 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	2748 return EXIT_FAILURE;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2749 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2750
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2751 /* 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	2752 l2 = sizeof(pt2);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2753 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	2754 l1, /* length of ciphertext */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2755 pt2, /* where to put plaintext */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2756 &l2, /* plaintext length */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2757 "TestApp", /* lparam for this program */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2758 7, /* lparam is 7 bytes long */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2759 hash_idx, /* hash idx */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2760 &res, /* validity of data */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2761 &key) /* our RSA key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2762 ) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2763 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	2764 return EXIT_FAILURE;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2765 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2766 /* 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	2767 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2768 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2769
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 \chapter{Diffie-Hellman Key Exchange}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2772
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2773 \section{Background}
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 Diffie-Hellman was the original public key system proposed. The system is based upon the group structure
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2776 of finite fields. For Diffie-Hellman a prime $p$ is chosen and a ``base'' $b$ such that $b^x\mbox{ }(\mbox{mod }p)$
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2777 generates a large sub-group of prime order (for unique values of $x$).
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 A secret key is an exponent $x$ and a public key is the value of $y \equiv g^x\mbox{ }(\mbox{mod }p)$. The term
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2780 ``discrete logarithm'' denotes the action of finding $x$ given only $y$, $g$ and $p$. The key exchange part of
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2781 Diffie-Hellman arises from the fact that two users A and B with keys $(A_x, A_y)$ and $(B_x, B_y)$ can exchange
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2782 a shared key $K \equiv B_y^{A_x} \equiv A_y^{B_x} \equiv g^{A_xB_x}\mbox{ }(\mbox{mod }p)$.
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 From this public encryption and signatures can be developed. The trivial way to encrypt (for example) using a public key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2785 $y$ is to perform the key exchange offline. The sender invents a key $k$ and its public copy
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2786 $k' \equiv g^k\mbox{ }(\mbox{mod }p)$ and uses $K \equiv k'^{A_x}\mbox{ }(\mbox{mod }p)$ as a key to encrypt
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2787 the message with. Typically $K$ would be sent to a one-way hash and the message digested used as a key in a
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2788 symmetric cipher.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2789
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2790 It is important that the order of the sub-group that $g$ generates not only be large but also prime. There are
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2791 discrete logarithm algorithms that take $\sqrt r$ time given the order $r$. The discrete logarithm can be computed
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2792 modulo each prime factor of $r$ and the results combined using the Chinese Remainder Theorem. In the cases where
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2793 $r$ is ``B-Smooth'' (e.g. all small factors or powers of small prime factors) the solution is trivial to find.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2794
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2795 To thwart such attacks the primes and bases in the library have been designed and fixed. Given a prime $p$ the order of
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2796 the sub-group generated is a large prime namely ${p - 1} \over 2$. Such primes are known as ``strong primes'' and the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2797 smaller prime (e.g. the order of the base) are known as Sophie-Germaine primes.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2798
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2799 \section{Core Functions}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2800
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2801 This library also provides core Diffie-Hellman functions so you can negotiate keys over insecure mediums. The routines
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2802 provided are relatively easy to use and only take two function calls to negotiate a shared key. There is a structure
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2803 called ``dh\_key'' which stores the Diffie-Hellman key in a format these routines can use. The first routine is to
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2804 make a Diffie-Hellman private key pair:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2805 \index{dh\_make\_key()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2806 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2807 int dh_make_key(prng_state *prng, int wprng,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2808 int keysize, dh_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2809 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2810 The ``keysize'' is the size of the modulus you want in bytes. Currently support sizes are 96 to 512 bytes which correspond
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2811 to key sizes of 768 to 4096 bits. The smaller the key the faster it is to use however it will be less secure. When
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2812 specifying a size not explicitly supported by the library it will round {\em up} to the next key size. If the size is
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2813 above 512 it will return an error. So if you pass ``keysize == 32'' it will use a 768 bit key but if you pass
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2814 ``keysize == 20000'' it will return an error. The primes and generators used are built-into the library and were designed
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2815 to meet very specific goals. The primes are strong primes which means that if $p$ is the prime then
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2816 $p-1$ is equal to $2r$ where $r$ is a large prime. The bases are chosen to generate a group of order $r$ to prevent
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2817 leaking a bit of the key. This means the bases generate a very large prime order group which is good to make cryptanalysis
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2818 hard.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2819
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2820 The next two routines are for exporting/importing Diffie-Hellman keys in a binary format. This is useful for transport
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2821 over communication mediums.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2822
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2823 \index{dh\_export()} \index{dh\_import()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2824 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2825 int dh_export(unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2826 int type, dh_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2827
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2828 int dh_import(const unsigned char in, unsigned long inlen, dh_key key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2829 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2830
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2831 These two functions work just like the ``rsa\_export()'' and ``rsa\_import()'' functions except these work with
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2832 Diffie-Hellman keys. Its important to note you do not have to free the ram for a ``dh\_key'' if an import fails. You can free a
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2833 ``dh\_key'' using:
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 void dh_free(dh_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2836 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2837 After you have exported a copy of your public key (using {\bf PK\_PUBLIC} as ``type'') you can now create a shared secret
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2838 with the other user using:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2839 \index{dh\_shared\_secret()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2840 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2841 int dh_shared_secret(dh_key *private_key,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2842 dh_key *public_key,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2843 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2844 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2845
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2846 Where ``private\_key'' is the key you made and ``public\_key'' is the copy of the public key the other user sent you. The result goes
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2847 into ``out'' and the length into ``outlen''. If all went correctly the data in ``out'' should be identical for both parties. It is important to
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2848 note that the two keys have to be the same size in order for this to work. There is a function to get the size of a
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2849 key:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2850 \index{dh\_get\_size()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2851 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2852 int dh_get_size(dh_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2853 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2854 This returns the size in bytes of the modulus chosen for that key.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2855
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2856 \subsection{Remarks on Usage}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2857 Its important that you hash the shared key before trying to use it as a key for a symmetric cipher or something. An
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2858 example program that communicates over sockets, using MD5 and 1024-bit DH keys is\footnote{This function is a small example. It is suggested that proper packaging be used. For example, if the public key sent is truncated these routines will not detect that.}:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2859 \newpage
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2860 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2861 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2862 int establish_secure_socket(int sock, int mode, unsigned char *key,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2863 prng_state *prng, int wprng)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2864 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2865 unsigned char buf[4096], buf2[4096];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2866 unsigned long x, len;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2867 int res, err, inlen;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2868 dh_key mykey, theirkey;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2869
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2870 /* make up our private key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2871 if ((err = dh_make_key(prng, wprng, 128, &mykey)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2872 return err;
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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2875 /* export our key as public */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2876 x = sizeof(buf);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2877 if ((err = dh_export(buf, &x, PK_PUBLIC, &mykey)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2878 res = err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2879 goto done2;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2880 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2881
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2882 if (mode == 0) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2883 /* mode 0 so we send first */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2884 if (send(sock, buf, x, 0) != x) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2885 res = CRYPT_ERROR;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2886 goto done2;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2887 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2888
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2889 /* get their key */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2890 if ((inlen = recv(sock, buf2, sizeof(buf2), 0)) <= 0) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2891 res = CRYPT_ERROR;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2892 goto done2;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2893 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2894 } else {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2895 /* mode >0 so we send second */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2896 if ((inlen = recv(sock, buf2, sizeof(buf2), 0)) <= 0) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2897 res = CRYPT_ERROR;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2898 goto done2;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2899 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2900
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2901 if (send(sock, buf, x, 0) != x) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2902 res = CRYPT_ERROR;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2903 goto done2;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2904 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2905 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2906
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2907 if ((err = dh_import(buf2, inlen, &theirkey)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2908 res = err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2909 goto done2;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2910 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2911
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2912 /* make shared secret */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2913 x = sizeof(buf);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2914 if ((err = dh_shared_secret(&mykey, &theirkey, buf, &x)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2915 res = err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2916 goto done;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2917 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2918
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2919 /* hash it */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2920 len = 16; /* default is MD5 so "key" must be at least 16 bytes long */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2921 if ((err = hash_memory(find_hash("md5"), buf, x, key, &len)) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2922 res = err;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2923 goto done;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2924 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2925
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2926 /* clean up and return */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2927 res = CRYPT_OK;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2928 done:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2929 dh_free(&theirkey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2930 done2:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2931 dh_free(&mykey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2932 zeromem(buf, sizeof(buf));
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2933 zeromem(buf2, sizeof(buf2));
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2934 return res;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2935 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2936 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2937 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2938 \newpage
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2939 \subsection{Remarks on The Snippet}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2940 When the above code snippet is done (assuming all went well) their will be a shared 128-bit key in the ``key'' array
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2941 passed to ``establish\_secure\_socket()''.
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 \section{Other Diffie-Hellman Functions}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2944 In order to test the Diffie-Hellman function internal workings (e.g. the primes and bases) their is a test function made
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2945 available:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2946 \index{dh\_test()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2947 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2948 int dh_test(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2949 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2950
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2951 This function returns {\bf CRYPT\_OK} if the bases and primes in the library are correct. There is one last helper
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2952 function:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2953 \index{dh\_sizes()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2954 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2955 void dh_sizes(int low, int high);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2956 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2957 Which stores the smallest and largest key sizes support into the two variables.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2958
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2959 \section{DH Packet}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2960 Similar to the RSA related functions there are functions to encrypt or decrypt symmetric keys using the DH public key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2961 algorithms.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2962 \index{dh\_encrypt\_key()} \index{dh\_decrypt\_key()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2963 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2964 int dh_encrypt_key(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2965 unsigned char out, unsigned long len,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2966 prng_state *prng, int wprng, int hash,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2967 dh_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2968
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2969 int dh_decrypt_key(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2970 unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2971 dh_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2972 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2973 Where ``in'' is an input symmetric key of no more than 32 bytes. Essentially these routines created a random public key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2974 and find the hash of the shared secret. The message digest is than XOR'ed against the symmetric key. All of the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2975 required data is placed in ``out'' by ``dh\_encrypt\_key()''. The hash must produce a message digest at least as large
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2976 as the symmetric key you are trying to share.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2977
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2978 Similar to the RSA system you can sign and verify a hash of a message.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2979 \index{dh\_sign\_hash()} \index{dh\_verify\_hash()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2980 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2981 int dh_sign_hash(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2982 unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2983 prng_state prng, int wprng, dh_key key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2984
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2985 int dh_verify_hash(const unsigned char *sig, unsigned long siglen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2986 const unsigned char *hash, unsigned long hashlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2987 int stat, dh_key key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2988 \end{verbatim}
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 The ``dh\_sign\_hash'' function signs the message hash in ``in'' of length ``inlen'' and forms a DH packet in ``out''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2991 The ``dh\_verify\_hash'' function verifies the DH signature in ``sig'' against the hash in ``hash''. It sets ``stat''
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2992 to non-zero if the signature passes or zero if it fails.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2993
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2994 \chapter{Elliptic Curve Cryptography}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2995
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2996 \section{Background}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	2997 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	2998 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	2999 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	3000 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	3001 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	3002
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3003 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	3004 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3005 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	3006 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3007
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3008 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	3009 \begin{equation}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3010 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	3011 \end{equation}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3012
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3013 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	3014 provided are very close to $p$ that is $\vert \vert \phi(\beta) \vert \vert \approx \vert \vert p \vert \vert$. The curves
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3015 range in order from $\approx 2^{192}$ points to $\approx 2^{521}$. According to the source document any key size greater
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3016 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	3017
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3018 \section{Key Format}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3019 LibTomCrypt uses it's own format for ECC public and private keys. While ANSI X9.62 partially specifies key formats (it covers public keys) it does it in a less
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3020 than ideally simple manner. In the case of LibTomCrypt it is meant \textbf{solely} for NIST $GF(p)$ curves. The format of the keys is as follows:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3021
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3022 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3023 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3024 ECCPublicKey ::= SEQUENCE {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3025 flags BIT STRING(1), -- public/private flag (always zero),
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3026 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	3027 -- 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	3028 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	3029 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	3030 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3031
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3032 ECCPrivateKey ::= SEQUENCE {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3033 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	3034 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	3035 -- 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	3036 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	3037 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	3038 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	3039 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3040 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3041 \end{small}
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 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	3044
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3045 \section{Core Functions}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3046
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3047 Like the DH routines there is a key structure ``ecc\_key'' used by the functions. There is a function to make a key:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3048 \index{ecc\_make\_key()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3049 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3050 int ecc_make_key(prng_state *prng, int wprng,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3051 int keysize, ecc_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3052 \end{verbatim}
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 The ``keysize'' is the size of the modulus in bytes desired. Currently directly supported values are 24, 28, 32, 48 and 65 bytes which
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3055 correspond to key sizes of 192, 224, 256, 384 and 521 bits respectively. If you pass a key size that is between any key size
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3056 it will round the keysize up to the next available one. The rest of the parameters work like they do in the ``dh\_make\_key()'' function.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3057 To free the ram allocated by a key call:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3058 \index{ecc\_free()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3059 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3060 void ecc_free(ecc_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3061 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3062
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3063 To import and export a key there are:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3064 \index{ecc\_export()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3065 \index{ecc\_import()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3066 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3067 int ecc_export(unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3068 int type, ecc_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3069
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3070 int ecc_import(const unsigned char in, unsigned long inlen, ecc_key key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3071 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3072 These two work exactly like there DH counterparts. Finally when you share your public key you can make a shared secret
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3073 with:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3074 \index{ecc\_shared\_secret()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3075 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3076 int ecc_shared_secret(ecc_key *private_key,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3077 ecc_key *public_key,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3078 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3079 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3080 Which works exactly like the DH counterpart, the ``private\_key'' is your own key and ``public\_key'' is the key the other
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3081 user sent you. Note that this function stores both $x$ and $y$ co-ordinates of the shared
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3082 elliptic point. You should hash the output to get a shared key in a more compact and useful form (most of the entropy is
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3083 in $x$ anyways). Both keys have to be the same size for this to work, to help there is a function to get the size in bytes
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3084 of a key.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3085 \index{ecc\_get\_size()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3086 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3087 int ecc_get_size(ecc_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3088 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3089
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3090 To test the ECC routines and to get the minimum and maximum key sizes there are these two functions:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3091 \index{ecc\_test()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3092 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3093 int ecc_test(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3094 void ecc_sizes(int low, int high);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3095 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3096 Which both work like their DH counterparts.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3097
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3098 \section{ECC Packet}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3099 Similar to the RSA API there are two functions which encrypt and decrypt symmetric keys using the ECC public key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3100 algorithms.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3101
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3102 \index{ecc\_encrypt\_key()} \index{ecc\_decrypt\_key()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3103 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3104 int ecc_encrypt_key(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3105 unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3106 prng_state *prng, int wprng, int hash,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3107 ecc_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3108
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3109 int ecc_decrypt_key(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3110 unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3111 ecc_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3112 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3113
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3114 Where ``in'' is an input symmetric key of no more than 64 bytes. Essentially these routines created a random public key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3115 and find the hash of the shared secret. The message digest is than XOR'ed against the symmetric key. All of the required
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3116 data is placed in ``out'' by ``ecc\_encrypt\_key()''. The hash chosen must produce a message digest at least as large
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3117 as the symmetric key you are trying to share.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3118
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3119 \subsection{Encrypt Packet Format}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3120
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3121 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	3122
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3123 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3124 ECCEncrypt ::= SEQUENCE {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3125 hashID OBJECT IDENTIFIER, -- OID of hash used
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3126 pubkey OCTET STRING , -- Encapsulated ECCPublicKey (see above)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3127 skey OCTET STRING -- xor of plaintext and "hash of shared secret"
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3128 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3129 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3130
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3131 There are also functions to sign and verify the hash of a message.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3132 \index{ecc\_sign\_hash()} \index{ecc\_verify\_hash()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3133 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3134 int ecc_sign_hash(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3135 unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3136 prng_state prng, int wprng, ecc_key key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3137
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3138 int ecc_verify_hash(const unsigned char *sig, unsigned long siglen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3139 const unsigned char *hash, unsigned long hashlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3140 int stat, ecc_key key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3141 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3142
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3143 The ``ecc\_sign\_hash'' function signs the message hash in ``in'' of length ``inlen'' and forms a ECC packet in ``out''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3144 The ``ecc\_verify\_hash'' function verifies the ECC signature in ``sig'' against the hash in ``hash''. It sets ``stat''
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3145 to non-zero if the signature passes or zero if it fails.
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 \subsection{Signature Format}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3148 The signature code is an implementation of X9.62 EC-DSA and the output is comformant for GF(p) curves.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3149
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3150 \section{ECC Keysizes}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3151 With ECC if you try and sign a hash that is bigger than your ECC key you can run into problems. The math will still work
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3152 and in effect the signature will still work. With ECC keys the strength of the signature is limited by the size of
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3153 the hash or the size of they key, whichever is smaller. For example, if you sign with SHA256 and an ECC-192 key in effect
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3154 you have 192-bits of security.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3155
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3156 The library will not warn you if you make this mistake so it is important to check yourself before using the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3157 signatures.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3158
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3159 \chapter{Digital Signature Algorithm}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3160 \section{Introduction}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3161 The Digital Signature Algorithm (or DSA) is a variant of the ElGamal Signature scheme which has been modified to
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3162 reduce the bandwidth of a signature. For example, to have ``80-bits of security'' with ElGamal you need a group of
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3163 order at least 1024-bits. With DSA you need a group of order at least 160-bits. By comparison the ElGamal signature
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3164 would require at least 256 bytes where as the DSA signature would require only at least 40 bytes.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3165
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3166 The API for the DSA is essentially the same as the other PK algorithms. Except in the case of DSA no encryption or
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3167 decryption routines are provided.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3168
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3169 \section{Key Format}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3170 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	3171 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	3172
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3173 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3174 DSAPublicKey ::= SEQUENCE {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3175 publicFlags BIT STRING(1), -- must be 0
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3176 g INTEGER , -- base generator, check that g^q mod p == 1
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3177 -- and that 1 < g < p - 1
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3178 p INTEGER , -- prime modulus
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3179 q INTEGER , -- order of sub-group (must be prime)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3180 y INTEGER , -- public key, specifically, g^x mod p,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3181 -- 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	3182 -- and that 1 < y < p - 1
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3183 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3184
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3185 DSAPrivateKey ::= SEQUENCE {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3186 publicFlags BIT STRING(1), -- must be 1
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3187 g INTEGER , -- base generator, check that g^q mod p == 1
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3188 -- and that 1 < g < p - 1
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3189 p INTEGER , -- prime modulus
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3190 q INTEGER , -- order of sub-group (must be prime)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3191 y INTEGER , -- public key, specifically, g^x mod p,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3192 -- 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	3193 -- and that 1 < y < p - 1
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3194 x INTEGER -- private key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3195 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3196 \end{verbatim}
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 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 and easy
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3199 to work with.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3200
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3201 \section{Key Generation}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3202 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	3203 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3204 int dsa_make_key(prng_state *prng, int wprng,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3205 int group_size, int modulus_size,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3206 dsa_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3207 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3208 The variable ``prng'' is an active PRNG state and ``wprng'' the index to the descriptor. ``group\_size'' and
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3209 ``modulus\_size'' control the difficulty of forging a signature. Both parameters are in bytes. The larger the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3210 ``group\_size'' the more difficult a forgery becomes upto a limit. The value of $group\_size$ is limited by
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3211 $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	3212
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3213 \begin{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3214 \begin{tabular}{\|c\|c\|c\|}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3215 \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	3216 \hline 80 & 20 & 128 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3217 \hline 120 & 30 & 256 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3218 \hline 140 & 35 & 384 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3219 \hline 160 & 40 & 512 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3220 \hline
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3221 \end{tabular}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3222 \end{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3223
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3224 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	3225 \index{dsa\_free()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3226 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3227 void dsa_free(dsa_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3228 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3229
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3230 \section{Key Verification}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3231 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	3232
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3233 \begin{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3234 \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	3235 \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	3236 \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	3237 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	3238 \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	3239 \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	3240 \end{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3241
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3242 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	3243
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3244 \begin{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3245 \item $q$ must be prime.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3246 \item $p$ must be prime.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3247 \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	3248 \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	3249 \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	3250 \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	3251 \item $1 < y < p - 1$
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3252 \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	3253 \end{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3254
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3255 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	3256 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	3257 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	3258 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	3259 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	3260 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	3261
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3262 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	3263
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3264 \index{dsa\_verify\_key()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3265 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3266 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	3267 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3268
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3269 This will test ``key'' and store the result in ``stat''. If the result is $stat = 0$ the DSA key failed one of the tests
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3270 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	3271
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3272 \section{Signatures}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3273 To generate a DSA signature call the following function
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{dsa\_sign\_hash()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3276 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3277 int dsa_sign_hash(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3278 unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3279 prng_state prng, int wprng, dsa_key key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3280 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3281
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3282 Which will sign the data in ``in'' of length ``inlen'' bytes. The signature is stored in ``out'' and the size
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3283 of the signature in ``outlen''. If the signature is longer than the size you initially specify in ``outlen'' nothing
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3284 is stored and the function returns an error code. The DSA ``key'' must be of the \textbf{PK\_PRIVATE} persuasion.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3285
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3286 To verify a hash created with that function use the following function
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3287
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3288 \index{dsa\_verify\_hash()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3289 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3290 int dsa_verify_hash(const unsigned char *sig, unsigned long siglen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3291 const unsigned char *hash, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3292 int stat, dsa_key key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3293 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3294 Which will verify the data in ``hash'' of length ``inlen'' against the signature stored in ``sig'' of length ``siglen''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3295 It will set ``stat'' to $1$ if the signature is valid, otherwise it sets ``stat'' to $0$.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3296
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3297 \section{Import and Export}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3298
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3299 To export a DSA key so that it can be transported use the following function
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3300 \index{dsa\_export()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3301 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3302 int dsa_export(unsigned char out, unsigned long outlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3303 int type,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3304 dsa_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3305 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3306 This will export the DSA ``key'' to the buffer ``out'' and set the length in ``outlen'' (which must have been previously
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3307 initialized to the maximum buffer size). The ``type`` variable may be either \textbf{PK\_PRIVATE} or \textbf{PK\_PUBLIC}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3308 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	3309
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3310 To import an exported DSA key use the following function
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3311
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3312 \index{dsa\_import()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3313 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3314 int dsa_import(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3315 dsa_key *key);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3316 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3317
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3318 This will import the DSA key from the buffer ``in'' of length ``inlen'' to the ``key''. If the process fails the function
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3319 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	3320
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3321 \chapter{Standards Support}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3322 \section{ASN.1 Formats}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3323 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	3324 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3325 format and two functions have been dedicated to encoding and decoding the format.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3326
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3327 On top of the basic data types are the SEQUENCE and\footnote{Planned for LTC 1.06} SET data types which are collections of other ASN.1 types. They are provided
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3328 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3329
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3330 \index{ltc\_asn1\_list structure}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3331 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3332 typedef struct {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3333 int type;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3334 void *data;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3335 unsigned long size;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3336 int used;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3337 } ltc_asn1_list;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3338 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3339
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3340 The ``type'' field is one of the following ASN.1 field definitions. The ``data'' pointer is a void pointer to the data to be encoded (or the destination) and the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3341 ``size'' field is specific to what you are encoding (e.g. number of bits in the BIT STRING data type). The ``used'' field is primarily for the CHOICE decoder
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3342 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3343 ``LTC\_SET\_ASN1(list, index, Type, Data, Size)'' has been provided.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3344
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3345 It will assign to the ``index''th position in the ``list'' the tripplet (Type, Data, Size). An example usage would be:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3346
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3347 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3348 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3349 ...
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3350 ltc_asn1_list sequence[3];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3351 unsigned long three=3;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3352
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3353 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	3354 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	3355 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	3356 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3357 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3358
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3359 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	3360
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3361 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3362 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3363 ...
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3364 ltc_asn1_list sequence[3];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3365 unsigned long three=3;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3366 int x=0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3367 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	3368 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	3369 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	3370 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3371 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3372
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3373 \begin{figure}[here]
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3374 \begin{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3375 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3376 \begin{tabular}{\|l\|l\|}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3377 \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	3378 \hline LTC\_ASN1\_EOL & End of a ASN.1 list structure. \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3379 \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	3380 \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	3381 \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	3382 \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	3383 \hline LTC\_ASN1\_NULL & NULL \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3384 \hline LTC\_ASN1\_OBJECT\_IDENTIFIER & OBJECT IDENTIFIER (words are in unsigned long) \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3385 \hline LTC\_ASN1\_IA5\_STRING & IA5 STRING (one octet per char) \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3386 \hline LTC\_ASN1\_PRINTABLE\_STRING & PRINTABLE STIRNG (one octet per char) \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3387 \hline LTC\_ASN1\_UTCTIME & UTCTIME (see ltc\_utctime structure) \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3388 \hline LTC\_ASN1\_SEQUENCE & SEQUENCE OF \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3389 \hline LTC\_ASN1\_CHOICE & CHOICE \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3390 \hline
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3391 \end{tabular}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3392 \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	3393 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3394 \end{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3395 \end{figure}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3396
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3397 \subsection{SEQUENCE Type}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3398 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	3399
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3400 \subsubsection{SEUQNECE Encoding}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3401 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	3402 with the following function.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3403
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3404 \index{der\_encode\_sequence()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3405 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3406 int der_encode_sequence(ltc_asn1_list *list, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3407 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3408 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3409 This encodes a sequence of items pointed to by ``list'' where the list has ``inlen'' items in it. The SEQUENCE will be encoded to ``out'' and of length ``outlen''. The
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3410 function will terminate when it reads all the items out of the list (upto ``inlen'') or it encounters an item in the list with a type of \textbf{LTC\_ASN1\_EOL}.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3411
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3412 The ``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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3413 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3414 the ``data'' pointer is simply a pointer to another \textbf{ltc\_asn1\_list}.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3415
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3416 \subsubsection{SEQUENCE Decoding}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3417
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3418 \index{der\_decode\_sequence()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3419
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3420 Decoding a SEQUENCE is similar to encoding. You set up an array of \textbf{ltc\_asn1\_list} where in this case the ``size'' member is the maximum size
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3421 (in certain cases). For types such as IA5 STRING, BIT STRING, OCTET STRING (etc) the ``size'' field is updated after successful decoding to reflect how many
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3422 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	3423
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3424 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3425 int der_decode_sequence(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3426 ltc_asn1_list *list, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3427 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3428
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3429 This will decode upto ``outlen'' items from the input buffer ``in'' of length ``inlen'' octets. The function will stop (gracefully) when it runs out of items to decode.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3430 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 occured.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3431
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3432 For the following types the ``size'' field will be updated to reflect the number of units read of the given type.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3433 \begin{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3434 \item BIT STRING
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3435 \item OCTET STRING
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3436 \item OBJECT IDENTIFIER
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3437 \item IA5 STRING
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3438 \item PRINTABLE STRING
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3439 \end{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3440
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3441 \subsubsection{SEQUENCE Length}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3442
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3443 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	3444
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3445 \index{der\_length\_sequence()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3446 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3447 int der_length_sequence(ltc_asn1_list *list, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3448 unsigned long *outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3449 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3450
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3451 This will get the encoding size for the given ``list'' of length ``inlen'' and store it in ``outlen''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3452
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3453 \subsubsection{SEQUENCE Multiple Argument Lists}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3454
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3455 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	3456
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3457 \index{der\_encode\_sequence\_multi()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3458 \index{der\_decode\_sequence\_multi()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3459
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3460 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3461 int der_encode_sequence_multi(unsigned char out, unsigned long outlen, ...);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3462 int der_decode_sequence_multi(const unsigned char *in, unsigned long inlen, ...);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3463 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3464
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3465 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	3466
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3467 The list of items are specified as a triple of the form ``(type, size, data)'' where ``type'' is an \textbf{int}, ``size'' is a \textbf{unsigned long}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3468 and ``data'' is \textbf{void} pointer. The list of items must be terminated with an item with the type \textbf{LTC\_ASN1\_EOL}.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3469
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3470 It's ideal that you cast the ``size'' values to unsigned long to ensure that the proper data type is passed to the function. Constants such as ``1'' without
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3471 a cast or prototype are of type \textbf{int} by default. Appending \textit{UL} or prepending \textit{(unsigned long)} is enough to cast it to the correct type.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3472
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3473 \subsection{ASN.1 INTEGER}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3474
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3475 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	3476
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3477 \index{der\_encode\_integer()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3478 \index{der\_decode\_integer()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3479 \index{der\_length\_integer()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3480 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3481 int der_encode_integer(mp_int num, unsigned char out, unsigned long *outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3482 int der_decode_integer(const unsigned char in, unsigned long inlen, mp_int num);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3483 int der_length_integer(mp_int num, unsigned long len);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3484 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3485
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3486 These will encode or decode a signed INTEGER data type using the ``mp\_int'' data type to store the large INTEGER. To encode smaller values without allocating
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3487 an mp\_int to store the value the ``short'' INTEGER functions were made available.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3488
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3489 \index{der\_encode\_short\_integer()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3490 \index{der\_decode\_short\_integer()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3491 \index{der\_length\_short\_integer()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3492 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3493 int der_encode_short_integer(unsigned long num,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3494 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3495
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3496 int der_decode_short_integer(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3497 unsigned long *num);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3498
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3499 int der_length_short_integer(unsigned long num, unsigned long *outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3500 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3501
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3502 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	3503 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	3504
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3505 \subsection{ASN.1 BIT STRING}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3506
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3507 \index{der\_encode\_bit\_string()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3508 \index{der\_decode\_bit\_string()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3509 \index{der\_length\_bit\_string()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3510 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3511 int der_encode_bit_string(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3512 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3513
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3514 int der_decode_bit_string(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3515 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3516
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3517 int der_length_bit_string(unsigned long nbits, unsigned long *outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3518 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3519
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3520 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 interpretted
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3521 as a one bit and a zero value a zero bit.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3522
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3523 \subsection{ASN.1 OCTET STRING}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3524
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3525 \index{der\_encode\_octet\_string()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3526 \index{der\_decode\_octet\_string()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3527 \index{der\_length\_octet\_string()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3528 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3529 int der_encode_octet_string(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3530 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3531
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3532 int der_decode_octet_string(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3533 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3534
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3535 int der_length_octet_string(unsigned long noctets, unsigned long *outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3536 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3537
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3538 These will encode or decode an OCTET STRING data type. The octets are stored using one \textbf{char} each.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3539
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3540 \subsection{ASN.1 OBJECT IDENTIFIER}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3541
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3542 \index{der\_encode\_object\_identifier()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3543 \index{der\_decode\_object\_identifier()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3544 \index{der\_length\_object\_identifier()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3545 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3546 int der_encode_object_identifier(unsigned long *words, unsigned long nwords,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3547 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3548
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3549 int der_decode_object_identifier(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3550 unsigned long words, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3551
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3552 int der_length_object_identifier(unsigned long *words, unsigned long nwords,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3553 unsigned long *outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3554 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3555
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3556 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3557 $0 \ldots 2^{32} - 1$.
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 \subsection{ASN.1 IA5 STRING}
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 \index{der\_encode\_ia5\_string()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3562 \index{der\_decode\_ia5\_string()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3563 \index{der\_length\_ia5\_string()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3564 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3565 int der_encode_ia5_string(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3566 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3567
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3568 int der_decode_ia5_string(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3569 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3570
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3571 int der_length_ia5_string(const unsigned char *octets, unsigned long noctets,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3572 unsigned long *outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3573 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3574
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3575 These will encode or decode an IA5 STRING. The characters are read or stored in individual \textbf{char} elements. This functions performs internal character
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3576 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3577 say a SPARC machine. Internally these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3578 that the build platform honours the runtime platforms character conventions.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3579
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3580 If you're worried try building the test suite and running it. It has hard coded test vectors to ensure it is operating properly.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3581
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3582 \subsection{ASN.1 PRINTABLE STRING}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3583
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3584 \index{der\_encode\_printable\_string()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3585 \index{der\_decode\_printable\_string()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3586 \index{der\_length\_printable\_string()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3587 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3588 int der_encode_printable_string(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3589 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3590
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3591 int der_decode_printable_string(const unsigned char *in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3592 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3593
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3594 int der_length_printable_string(const unsigned char *octets, unsigned long noctets,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3595 unsigned long *outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3596 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3597
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3598 These will encode or decode an PRINTABLE STRING. The characters are read or stored in individual \textbf{char} elements. This functions performs internal character
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3599 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3600 say a SPARC machine. Internally these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3601 that the build platform honours the runtime platforms character conventions.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3602
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3603 If you're worried try building the test suite and running it. It has hard coded test vectors to ensure it is operating properly.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3604
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3605 \subsection{ASN.1 UTCTIME}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3606
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3607 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	3608
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 typedef struct {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3611 unsigned YY, /* year 00--99 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3612 MM, /* month 01--12 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3613 DD, /* day 01--31 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3614 hh, /* hour 00--23 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3615 mm, /* minute 00--59 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3616 ss, /* second 00--59 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3617 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	3618 off_hh, /* timezone offset hours */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3619 off_mm; /* timezone offset minutes */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3620 } ltc_utctime;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3621 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3622
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3623 The time can be offset plus or minus a set amount of hours (off\_hh) and minutes (off\_mm). When ``off\_dir'' is zero the time will be added otherwise it
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3624 will be subtracted.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3625
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3626 For instance, the array $\lbrace 5, 6, 20, 22, 4, 00, 0, 5, 0 \rbrace$ represents the current time of 2005, June 20th, 22:04:00 with a time offset of +05h00.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3627
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3628 \index{der\_encode\_utctime()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3629 \index{der\_decode\_utctime()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3630 \index{der\_length\_utctime()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3631 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3632 int der_encode_utctime(ltc_utctime *utctime,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3633 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3634
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3635 int der_decode_utctime(const unsigned char in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3636 ltc_utctime *out);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3637
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3638 int der_length_utctime(ltc_utctime utctime, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3639 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3640
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3641 The encoder will store time in one of the two ASN.1 formats, either ``YYMMDDhhmmssZ'' or ``YYMMDDhhmmss$\pm$hhmm'' and perform minimal error checking on the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3642 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	3643
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3644 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	3645
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3646 \subsection{ASN.1 CHOICE}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3647
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3648 The CHOICE ASN.1 type represents a union of ASN.1 types all of which are stored in a ``ltc\_asn1\_list''. There is no encoder for the CHOICE type, only a
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3649 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	3650 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	3651
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3652 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	3653
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3654 \index{der\_decode\_choice()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3655 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3656 int der_decode_choice(const unsigned char in, unsigned long inlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3657 ltc_asn1_list *list, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3658 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3659
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3660 This will decode the input in the ``in'' field of length ``inlen''. It uses the provided ASN.1 list specified in the ``list'' field which has ``outlen'' elements.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3661 The ``inlen'' field will be updated with the length of the decoded data type as well as the respective entry in the ``list'' field will have the ``used'' flag
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3662 set to non--zero to reflect it was the data type decoded.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3663
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3664 \section{Password Based Cryptography}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3665 \subsection{PKCS \#5}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3666 \index{PKCS \#5}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3667 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	3668 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	3669 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	3670
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3671 \subsection{Algorithm One}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3672 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3673 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	3674 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	3675
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3676 \index{pkcs\_5\_alg1()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3677 \begin{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3678 int pkcs_5_alg1(const unsigned char *password, unsigned long password_len,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3679 const unsigned char *salt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3680 int iteration_count, int hash_idx,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3681 unsigned char out, unsigned long outlen)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3682 \end{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3683 Where ``password'' is the users password. Since the algorithm allows binary passwords you must also specify the length in ``password\_len''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3684 The ``salt'' is a fixed size 8--byte array which should be random for each user and session. The ``iteration\_count'' is the delay desired
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3685 on the password. The ``hash\_idx'' is the index of the hash you wish to use in the descriptor table.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3686
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3687 The output of length upto ``outlen'' is stored in ``out''. If ``outlen'' is initially larger than the size of the hash functions output
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3688 it is set to the number of bytes stored. If it is smaller than not all of the hash output is stored in ``out''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3689
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3690 \subsection{Algorithm Two}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3691
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3692 Algorithm Two is the recommended algorithm for this task. It allows variable length salts and can produce outputs larger than the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3693 hash functions output. As such it can easily be used to derive session keys for ciphers and MACs as well initial vectors as required
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3694 from a single password and invokation of this algorithm.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3695
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3696 \index{pkcs\_5\_alg2()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3697 \begin{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3698 int pkcs_5_alg2(const unsigned char *password, unsigned long password_len,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3699 const unsigned char *salt, unsigned long salt_len,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3700 int iteration_count, int hash_idx,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3701 unsigned char out, unsigned long outlen)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3702 \end{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3703 Where ``password'' is the users password. Since the algorithm allows binary passwords you must also specify the length in ``password\_len''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3704 The ``salt'' is an array of size ``salt\_len''. It should be random for each user and session. The ``iteration\_count'' is the delay desired
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3705 on the password. The ``hash\_idx'' is the index of the hash you wish to use in the descriptor table. The output of length upto
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3706 ``outlen'' is stored in ``out''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3707
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3708 \begin{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3709 /* demo to show how to make session state material from a password */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3710 #include <tomcrypt.h>
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3711 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3712 \{
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3713 unsigned char password[100], salt[100],
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3714 cipher_key[16], cipher_iv[16],
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3715 mac_key[16], outbuf[48];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3716 int err, hash_idx;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3717 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	3718
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3719 /* 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	3720
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3721 /* 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	3722
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3723 /* 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	3724 outlen = sizeof(outbuf);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3725 if ((err = pkcs_5_alg2(password, password_len, salt, salt_len,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3726 100, hash_idx, outbuf, &outlen)) != CRYPT_OK) \{
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3727 /* error handle */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3728 \}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3729
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3730 /* now extract it */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3731 memcpy(cipher_key, outbuf, 16);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3732 memcpy(cipher_iv, outbuf+16, 16);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3733 memcpy(mac_key, outbuf+32, 16);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3734
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3735 /* use material (recall to store the salt in the output) */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3736 \}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3737 \end{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3738
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3739 \chapter{Miscellaneous}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3740 \section{Base64 Encoding and Decoding}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3741 The library provides functions to encode and decode a RFC1521 base64 coding scheme. This means that it can decode what it
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3742 encodes but the format used does not comply to any known standard. The characters used in the mappings are:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3743 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3744 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3745 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3746 Those characters should are supported in virtually any 7-bit ASCII system which means they can be used for transport over
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3747 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	3748 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	3749 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	3750
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3751 Often it is desirable to line wrap the output to fit nicely in an e-mail or usenet posting. The decoder allows you to
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3752 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	3753 break up the first four characters.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3754
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3755 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	3756 \index{base64\_encode()} \index{base64\_decode()}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3757 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3758 int base64_encode(const unsigned char *in, unsigned long len,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3759 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3760 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3761 Where ``in'' is the binary string and ``out'' is where the ASCII output is placed. You must set the value of ``outlen'' prior
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3762 to calling this function and it sets the length of the base64 output in ``outlen'' when it is done. To decode a base64
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3763 string call:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3764 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3765 int base64_decode(const unsigned char *in, unsigned long len,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3766 unsigned char out, unsigned long outlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3767 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3768
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3769 \section{The Multiple Precision Integer Library (MPI)}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3770 The library comes with a copy of LibTomMath which is a multiple precision integer library written by the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3771 author of LibTomCrypt. LibTomMath is a trivial to use ANSI C compatible large integer library which is free
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3772 for all uses and is distributed freely.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3773
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3774 At the heart of all the functions is the data type ``mp\_int'' (defined in tommath.h). This data type is what
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3775 will hold all large integers. In order to use an mp\_int one must initialize it first, for example:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3776 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3777 #include <tomcrypt.h> /* tomcrypt.h includes mpi.h automatically */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3778 int main(void)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3779 {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3780 mp_int bignum;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3781
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3782 /* initialize it */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3783 mp_init(&bignum);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3784
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3785 return 0;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3786 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3787 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3788 If you are unfamiliar with the syntax of C the \& symbol is used to pass the address of ``bignum'' to the function. All
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3789 LibTomMath functions require the address of the parameters. To free the memory of a mp\_int use (for example):
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3790 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3791 mp_clear(&bignum);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3792 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3793
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3794 The functions also have the basic form of one of the following:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3795 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3796 mp_XXX(mp_int *a);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3797 mp_XXX(mp_int a, mp_int b, mp_int *c);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3798 mp_XXX(mp_int a, mp_int b, mp_int c, mp_int d);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3799 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3800
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3801 Where they perform some operation and store the result in the mp\_int variable passed on the far right.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3802 For example, to compute $c = a + b \mbox{ }(\mbox{mod }m)$ you would call:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3803 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3804 mp_addmod(&a, &b, &m, &c);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3805 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3806
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3807 \subsection{Binary Forms of ``mp\_int'' Variables}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3808
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3809 Often it is required to store a ``mp\_int'' in binary form for transport (e.g. exporting a key, packet
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3810 encryption, etc.). LibTomMath includes two functions to help when exporting numbers:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3811 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3812 int mp_raw_size(mp_int *num);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3813 mp_toraw(&num, buf);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3814 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3815
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3816 The former function gives the size in bytes of the raw format and the latter function actually stores the raw data. All
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3817 ``mp\_int'' numbers are stored in big endian form (like PKCS demands) with the first byte being the sign of the number. The
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3818 ``rsa\_exptmod()'' function differs slightly since it will take the input in the form exactly as PKCS demands (without the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3819 leading sign byte). All other functions include the sign byte (since its much simpler just to include it). The sign byte
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3820 must be zero for positive numbers and non-zero for negative numbers. For example,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3821 the sequence:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3822 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3823 00 FF 30 04
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3824 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3825 Represents the integer $255 \cdot 256^2 + 48 \cdot 256^1 + 4 \cdot 256^0$ or 16,723,972.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3826
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3827 To read a binary string back into a ``mp\_int'' call:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3828 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3829 mp_read_raw(mp_int num, unsigned char str, int len);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3830 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3831 Where ``num'' is where to store it, ``str'' is the binary string (including the leading sign byte) and ``len'' is the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3832 length of the binary string.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3833
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3834 \subsection{Primality Testing}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3835 \index{Primality Testing}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3836 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	3837 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	3838 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	3839 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	3840 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	3841 $\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	3842
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3843 When making random primes the trial division step is in fact an optimized implementation of ``Implementation of Fast RSA Key Generation on Smart Cards''\footnote{Chenghuai Lu, Andre L. M. dos Santos and Francisco R. Pimentel}.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3844 In essence a table of machine-word sized residues are kept of a candidate modulo a set of primes. When the candiate
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3845 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	3846 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	3847 involved.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3848
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3849 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	3850 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	3851 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	3852 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	3853 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	3854 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	3855
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3856 These are not technically part of the LibTomMath library but this is the best place to document them.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3857 To test if a ``mp\_int'' is prime call:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3858 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3859 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	3860 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3861 This puts a one in ``result'' if the number is probably prime, otherwise it places a zero in it. It is assumed that if
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3862 it returns an error that the value in ``result'' is undefined. To make
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3863 a random prime call:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3864 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3865 int rand_prime(mp_int N, unsigned long len, prng_state prng, int wprng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3866 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3867 Where ``len'' is the size of the prime in bytes ($2 \le len \le 256$). You can set ``len'' to the negative size you want
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3868 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3869 ``len = -128'' to the function. Upon success it will return {\bf CRYPT\_OK} and ``N'' will contain an integer which
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3870 is very likely prime.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3871
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3872 \chapter{Programming Guidelines}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3873
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3874 \section{Secure Pseudo Random Number Generators}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3875 Probably the singal most vulnerable point of any cryptosystem is the PRNG. Without one generating and protecting secrets
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3876 would be impossible. The requirement that one be setup correctly is vitally important and to address this point the library
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3877 does provide two RNG sources that will address the largest amount of end users as possible. The ``sprng'' PRNG provided
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3878 provides and easy to access source of entropy for any application on a *NIX or Windows computer.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3879
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3880 However, when the end user is not on one of these platforms the application developer must address the issue of finding
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3881 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	3882 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	3883
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3884 \section{Preventing Trivial Errors}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3885 Two simple ways to prevent trivial errors is to prevent overflows and to check the return values. All of the functions
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3886 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	3887 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	3888
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3889 Also virtually all of the functions return an error code or {\bf CRYPT\_OK}. You should detect all errors as simple
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3890 typos or such can cause algorithms to fail to work as desired.
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 \section{Registering Your Algorithms}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3893 To avoid linking and other runtime errors it is important to register the ciphers, hashes and PRNGs you intend to use
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3894 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	3895
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3896 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	3897 having to hack the library. For example, suppose you have a hardware specific PRNG on your system. You could easily
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3898 write the few functions required plus a descriptor. After registering your PRNG all of the library functions that
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3899 need a PRNG can instantly take advantage of it.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3900
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3901 \section{Key Sizes}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3902
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3903 \subsection{Symmetric Ciphers}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3904 For symmetric ciphers use as large as of a key as possible. For the most part ``bits are cheap'' so using a 256-bit key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3905 is not a hard thing todo.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3906
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3907 \subsection{Assymetric Ciphers}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3908 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	3909 $n$ is estimated to be
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3910 \begin{equation}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3911 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	3912 \end{equation}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3913
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3914 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	3915 is:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3916 \begin{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3917 \begin{tabular}{\|c\|c\|}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3918 \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	3919 \hline 512 & 63.92 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3920 \hline 768 & 76.50 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3921 \hline 1024 & 86.76 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3922 \hline 1536 & 103.37 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3923 \hline 2048 & 116.88 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3924 \hline 2560 & 128.47 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3925 \hline 3072 & 138.73 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3926 \hline 4096 & 156.49 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3927 \hline
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3928 \end{tabular}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3929 \end{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3930
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3931 The work factor for ECC keys is much higher since the best attack is still fully exponentional. Given a key of magnitude
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3932 $n$ it requires $\sqrt n$ work. The following table sumarizes the work required:
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3933 \begin{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3934 \begin{tabular}{\|c\|c\|}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3935 \hline ECC 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	3936 \hline 192 & 96 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3937 \hline 224 & 112 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3938 \hline 256 & 128 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3939 \hline 384 & 192 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3940 \hline 521 & 260.5 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3941 \hline
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3942 \end{tabular}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3943 \end{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3944
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3945 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	3946 \begin{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3947 \begin{tabular}{\|c\|c\|c\|}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3948 \hline Security Goal & RSA/DH Key Size (bits) & ECC Key Size (bits) \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3949 \hline Short term (less than a year) & 1024 & 160 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3950 \hline Short term (less than five years) & 1536 & 192 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3951 \hline Long Term (less than ten years) & 2560 & 256 \\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3952 \hline
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3953 \end{tabular}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3954 \end{center}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3955
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3956 \section{Thread Safety}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3957 The library is not thread safe but several simple precautions can be taken to avoid any problems. The registry functions
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3958 such as register\_cipher() are not thread safe no matter what you do. Its best to call them from your programs initializtion
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3959 code before threads are initiated.
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 The rest of the code uses state variables you must pass it such as hash\_state, hmac\_state, etc. This means that if each
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3962 thread has its own state variables then they will not affect each other. This is fairly simple with symmetric ciphers
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3963 and hashes. However, the keyring and PRNG support is something the threads will want to share. The simplest workaround
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3964 is create semaphores or mutexes around calls to those functions.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3965
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3966 Since C does not have standard semaphores this support is not native to Libtomcrypt. Even a C based semaphore is not entire
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3967 possible as some compilers may ignore the ``volatile'' keyword or have multiple processors. Provide your host application
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3968 is modular enough putting the locks in the right place should not bloat the code significantly and will solve all thread
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3969 safety issues within the library.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3970
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3971 \chapter{Configuring and Building the Library}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3972 \section{Introduction}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3973 The library is fairly flexible about how it can be built, used and generally distributed. Additions are being made with
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3974 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	3975 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	3976
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3977 \section{Building a Static Library}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3978 The library can be built as a static library which is generally the simplest and most portable method of
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3979 building the library. With a CC or GCC equipped platform you can issue the following
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3980
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3981 \begin{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3982 make install_lib
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3983 \end{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3984
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3985 Which will build the library and install it in /usr/lib (as well as the headers in /usr/include). The destination
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3986 directory of the library and headers can be changed by editing ``makefile''. The variable LIBNAME controls
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3987 where the library is to be installed and INCNAME controls where the headers are to be installed. A developer can
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3988 then use the library by including ``tomcrypt.h'' in their program and linking against ``libtomcrypt.a''.
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 A static library can also be built with the Intel C Compiler (ICC) by issuing the following
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3991
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3992 \begin{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3993 make -f makefile.icc install
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3994 \end{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3995
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3996 This will also build ``libtomcrypt.a'' except that it will use ICC. Additionally Microsoft's Visual C 6.00 can be used
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3997 by issuing
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3998
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	3999 \begin{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4000 nmake -f makefile.msvc
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4001 \end{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4002
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4003 You will have to manually copy ``tomcrypt.lib'' and the headers to your MSVC lib/inc directories.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4004
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4005 \subsection{MPI Control}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4006 If you already have LibTomMath installed you can safely remove it from the build. By commenting the line
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4007 in the appropriate makefile which starts with
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4008
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4009 \begin{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4010 MPIOBJECT=mpi
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4011 \end{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4012
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4013 Simply place a \# at the start and re-build the library. To properly link applications you will have to also
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4014 link in LibTomMath. Removing MPI has the benefit of cutting down the library size as well potentially have access
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4015 to the latest mpi.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4016
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4017 \section{Building a Shared Library}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4018 LibTomCrypt can also be built as a shared library (.so, .dll, etc...). With non-Windows platforms the assumption
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4019 of the presence of gcc and ``libtool'' has been made. These are fairly common on Unix/Linux/BSD platforms. To
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4020 build a .so shared library issue
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4021
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4022 \begin{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4023 make -f makefile.shared
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4024 \end{alltt}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4025 This will use libtool and gcc to build a shared library ``libtomcrypt.la'' as well as a static library ``libtomcrypt.a''
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4026 and install them into /usr/lib (and the headers into /usr/include). To link your application you should use the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4027 libtool program in ``--mode=link''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4028
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4029 \section{tomcrypt\_cfg.h}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4030 The file ``tomcrypt\_cfg.h'' is what lets you control various high level macros which control the behaviour
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4031 of the library.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4032
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4033 \subsubsection{ARGTYPE}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4034 This lets you control how the \_ARGCHK macro will behave. The macro is used to check pointers inside the functions against
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4035 NULL. There are three settings for ARGTYPE. When set to 0 it will have the default behaviour of printing a message to
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4036 stderr and raising a SIGABRT signal. This is provided so all platforms that use libtomcrypt can have an error that functions
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4037 similarly. When set to 1 it will simply pass on to the assert() macro. When set to 2 it will resolve to a empty macro
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4038 and no error checking will be performed.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4039
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4040 \subsubsection{Endianess}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4041 There are five macros related to endianess issues. For little endian platforms define, ENDIAN\_LITTLE. For big endian
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4042 platforms define ENDIAN\_BIG. Similarly when the default word size of an ``unsigned long'' is 32-bits define ENDIAN\_32BITWORD
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4043 or define ENDIAN\_64BITWORD when its 64-bits. If you do not define any of them the library will automatically use ENDIAN\_NEUTRAL
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4044 which will work on all platforms.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4045
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4046 Currently LibTomCrypt will detect x86-32 and x86-64 running GCC as well as x86-32 running MSVC.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4047
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4048 \section{The Configure Script}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4049 There are also options you can specify from the configure script or ``tomcrypt\_custom.h''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4050
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4051 \subsection{X memory routines}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4052 At the top of tomcrypt\_custom.h are four macros denoted as XMALLOC, XCALLOC, XREALLOC and XFREE which resolve to
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4053 the name of the respective functions. This lets you substitute in your own memory routines. If you substitute in
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4054 your own functions they must behave like the standard C library functions in terms of what they expect as input and
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4055 output. By default the library uses the standard C routines.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4056
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4057 \subsection{X clock routines}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4058 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	4059 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	4060
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4061 \subsection{NO\_FILE}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4062 During the build if NO\_FILE is defined then any function in the library that uses file I/O will not call the file I/O
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4063 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	4064 file I/O on embedded platforms.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4065
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4066 \subsection{CLEAN\_STACK}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4067 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	4068 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	4069
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4070 \subsection{LTC\_TEST}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4071 When this has been defined the various self--test functions (for ciphers, hashes, prngs, etc) are included in the build.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4072 When this has been undefined the tests are removed and if called will return CRYPT\_NOP.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4073
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4074 \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	4075 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	4076 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	4077 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	4078 cipher and a hash function.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4079
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4080 \subsection{TWOFISH\_SMALL and TWOFISH\_TABLES}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4081 Twofish is a 128-bit symmetric block cipher that is provided within the library. The cipher itself is flexible enough
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4082 to allow some tradeoffs in the implementation. When TWOFISH\_SMALL is defined the scheduled symmetric key for Twofish
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4083 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	4084 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	4085 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	4086
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4087 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	4088 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	4089 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	4090 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	4091
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4092 \subsection{GCM\_TABLES}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4093 When defined GCM will use a 64KB table (per GCM state) which will greatly speed up the per--packet latency.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4094 It also increases the initialization time and isn't suitable when you are going to use a key a few times only.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4095
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4096 \subsection{SMALL\_CODE}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4097 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	4098 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	4099
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4100 \subsection{LTC\_FAST}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4101 This mode (autodetected with x86\_32,x86\_64 platforms with GCC or MSVC) configures various routines such as ctr\_encrypt() or
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4102 cbc\_encrypt() that it can safely XOR multiple octets in one step by using a larger data type. This has the benefit of
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4103 cutting down the overhead of the respective functions.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4104
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4105 This mode does have one downside. It can cause unaligned reads from memory if you are not careful with the functions. This is why
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4106 it has been enabled by default only for the x86 class of processors where unaligned accesses are allowed. Technically LTC\_FAST
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4107 is not ``portable'' since unaligned accesses are not covered by the ISO C specifications.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4108
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4109 In practice however, you can use it on pretty much any platform (even MIPS) with care.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4110
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4111 By design the ``fast'' mode functions won't get unaligned on their own. For instance, if you call ctr\_encrypt() right after calling
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4112 ctr\_start() and all the inputs you gave are aligned than ctr\_encrypt() will perform aligned memory operations only. However, if you
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4113 call ctr\_encrypt() with an odd amount of plaintext then call it again the CTR pad (the IV) will be partially used. This will
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4114 cause the ctr routine to first use up the remaining pad bytes. Then if there are enough plaintext bytes left it will use
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4115 whole word XOR operations. These operations will be unaligned.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4116
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4117 The simplest precaution is to make sure you process all data in power of two blocks and handle ``remainder'' at the end. e.g. If you are
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4118 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.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4119
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4120 If you do plan on using the ``LTC\_FAST'' mode you have to also define a ``LTC\_FAST\_TYPE'' macro which resolves to an optimal sized
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4121 data type you can perform integer operations with. Ideally it should be four or eight bytes since it must properly divide the size
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4122 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4123 use this mode. So sad.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4124
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4125 \subsection{LTC\_PTHREAD}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4126 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	4127 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	4128
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4129 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	4130 the tables safer.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4131
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4132 \section{MPI Tweaks}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4133 \subsection{RSA Only Tweak}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4134 If you plan on only using RSA with moduli in the range of 1024 to 2560 bits you can enable a series of tweaks
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4135 to reduce the library size. Follow these steps
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4136
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4137 \begin{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4138 \item Undefine MDSA, MECC and MDH from tomcrypt\_custom.h
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4139 \item Undefine LTM\_ALL from tommath\_superclass.h
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4140 \item Define SC\_RSA\_1 from tommath\_superclass.h
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4141 \item Rebuild the library.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4142 \end{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4143
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4144 \chapter{Optimizations}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4145 \section{Introduction}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4146 The entire API was designed with plug and play in mind at the low level. That is you can swap out any cipher, hash or PRNG and dependent API will not require
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4147 updating. This has the nice benefit that I can add ciphers not have to re--write large portions of the API. For the most part LibTomCrypt has also been written
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4148 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	4149 about the platform, etc...
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4150
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4151 That works well for most cases but there are times where time is of the essence. This API also allows optimized routines to be dropped in--place of the existing
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4152 portable routines. For instance, hand optimized assembler versions of AES could be provided and any existing function that uses the cipher could automatically use
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4153 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	4154
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4155 At the heart of this flexibility is the ``descriptor'' system. A descriptor is essentially just a C ``struct'' which describes the algorithm and provides pointers
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4156 to functions that do the work. For a given class of operation (e.g. cipher, hash, prng) the functions have identical prototypes which makes development simple. In most
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4157 dependent routines all a developer has to do is register\_XXX() the descriptor and they're set.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4158
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4159 \section{Ciphers}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4160 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	4161
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4162 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4163 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4164 struct ltc_cipher_descriptor {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4165 /** name of cipher */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4166 char *name;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4167 /** internal ID */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4168 unsigned char ID;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4169 /** min keysize (octets) */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4170 int min_key_length,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4171 /** max keysize (octets) */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4172 max_key_length,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4173 /** block size (octets) */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4174 block_length,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4175 /** default number of rounds */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4176 default_rounds;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4177 /** Setup the cipher
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4178 @param key The input symmetric key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4179 @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	4180 @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	4181 @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	4182 @return CRYPT_OK if successful
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4183 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4184 int (setup)(const unsigned char key, int keylen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4185 int num_rounds, symmetric_key *skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4186 /** Encrypt a block
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4187 @param pt The plaintext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4188 @param ct [out] The ciphertext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4189 @param skey The scheduled key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4190 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4191 void (ecb_encrypt)(const unsigned char pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4192 unsigned char ct, symmetric_key skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4193 /** Decrypt a block
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4194 @param ct The ciphertext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4195 @param pt [out] The plaintext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4196 @param skey The scheduled key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4197 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4198 void (ecb_decrypt)(const unsigned char ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4199 unsigned char pt, symmetric_key skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4200 /** Test the block cipher
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4201 @return CRYPT_OK if successful, CRYPT_NOP if self-testing has been disabled
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4202 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4203 int (*test)(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4204 /** Determine a key size
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4205 @param keysize [in/out] The size of the key desired and the suggested size
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4206 @return CRYPT_OK if successful
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4207 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4208 int (keysize)(int keysize);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4209
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4210 / Accelerators /
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4211 /** Accelerated ECB encryption
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4212 @param pt Plaintext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4213 @param ct Ciphertext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4214 @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	4215 @param skey The scheduled key context
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4216 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4217 void (accel_ecb_encrypt)(const unsigned char pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4218 unsigned char *ct, unsigned long blocks,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4219 symmetric_key *skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4220
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4221 /** Accelerated ECB decryption
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4222 @param pt Plaintext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4223 @param ct Ciphertext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4224 @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	4225 @param skey The scheduled key context
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4226 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4227 void (accel_ecb_decrypt)(const unsigned char ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4228 unsigned char *pt, unsigned long blocks,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4229 symmetric_key *skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4230
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4231 /** Accelerated CBC encryption
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4232 @param pt Plaintext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4233 @param ct Ciphertext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4234 @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	4235 @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	4236 @param skey The scheduled key context
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4237 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4238 void (accel_cbc_encrypt)(const unsigned char pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4239 unsigned char *ct, unsigned long blocks,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4240 unsigned char IV, symmetric_key skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4241
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4242 /** Accelerated CBC decryption
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4243 @param pt Plaintext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4244 @param ct Ciphertext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4245 @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	4246 @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	4247 @param skey The scheduled key context
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4248 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4249 void (accel_cbc_decrypt)(const unsigned char ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4250 unsigned char *pt, unsigned long blocks,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4251 unsigned char IV, symmetric_key skey);
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 /** Accelerated CTR encryption
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4254 @param pt Plaintext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4255 @param ct Ciphertext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4256 @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	4257 @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	4258 @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	4259 @param skey The scheduled key context
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4260 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4261 void (accel_ctr_encrypt)(const unsigned char pt,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4262 unsigned char *ct, unsigned long blocks,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4263 unsigned char IV, int mode, symmetric_key skey);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4264
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4265 /** Accelerated CCM packet (one-shot)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4266 @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	4267 @param keylen The length of the secret key (octets)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4268 @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	4269 @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	4270 @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	4271 @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	4272 @param pt [out] The plaintext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4273 @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	4274 @param ct [out] The ciphertext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4275 @param tag [out] The destination tag
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4276 @param taglen [in/out] The max size and resulting size of the authentication tag
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4277 @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	4278 @return CRYPT_OK if successful
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4279 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4280 void (*accel_ccm_memory)(
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4281 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	4282 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	4283 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	4284 unsigned char *pt, unsigned long ptlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4285 unsigned char *ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4286 unsigned char tag, unsigned long taglen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4287 int direction);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4288
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4289 /** Accelerated GCM packet (one shot)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4290 @param key The secret key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4291 @param keylen The length of the secret key
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4292 @param IV The initial vector
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4293 @param IVlen The length of the initial vector
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4294 @param adata The additional authentication data (header)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4295 @param adatalen The length of the adata
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4296 @param pt The plaintext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4297 @param ptlen The length of the plaintext (ciphertext length is the same)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4298 @param ct The ciphertext
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4299 @param tag [out] The MAC tag
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4300 @param taglen [in/out] The MAC tag length
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4301 @param direction Encrypt or Decrypt mode (GCM_ENCRYPT or GCM_DECRYPT)
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 void (*accel_gcm_memory)(
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4304 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	4305 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	4306 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	4307 unsigned char *pt, unsigned long ptlen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4308 unsigned char *ct,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4309 unsigned char tag, unsigned long taglen,
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4310 int direction);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4311
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4312 };
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4313 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4314 \end{small}
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 \subsection{Name}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4317 The ``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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4318 tables.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4319
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4320 \subsection{Internal ID}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4321 This is a single byte Internal ID you can use to distingish ciphers from each other.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4322
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4323 \subsection{Key Lengths}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4324 The minimum key length is ``min\_key\_length'' and is measured in octets. Similarly the maximum key length is ``max\_key\_length''. They can be equal
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4325 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	4326
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4327 \subsection{Block Length}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4328 The size of the ciphers plaintext or ciphertext is ``block\_length'' and is measured in octets.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4329
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4330 \subsection{Rounds}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4331 Some ciphers allow different number of rounds to be used. Usually you just use the default. The default round count is ``default\_rounds''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4332
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4333 \subsection{Setup}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4334 To initialize a cipher (for ECB mode) the function setup() was provided. It accepts an array of key octets ``key'' of length ``keylen'' octets. The user
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4335 can specify the number of rounds they want through ``num\_rounds'' where $num\_rounds = 0$ means use the default. The destination of a scheduled key is stored
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4336 in ``skey''.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4337
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4338 Inside the ``symmetric\_key'' union there is a ``void *data'' which you can use to allocate data if you need a data structure that doesn't fit with the existing
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4339 ones provided. Just make sure in your ``done()'' function that you free the allocated memory.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4340
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4341 \subsection{Single block ECB}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4342 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	4343 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	4344
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4345 \subsection{Testing}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4346 The test() function is used to self--test the ``device''. It takes no arguments and returns \textbf{CRYPT\_OK} if all is working properly.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4347
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4348 \subsection{Key Sizing}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4349 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4350 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	4351 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	4352 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	4353
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4354 \subsection{Acceleration}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4355 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4356 it is not supported. In those cases the software fallbacks are used (using the single ECB block routines).
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4357
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4358 \subsubsection{Accelerated ECB}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4359 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4360 through the accel\_ecb\_encrypt and accel\_ecb\_decrypt pointers. The ``blocks'' count is 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	4361
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4362 \subsubsection{Accelerated CBC}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4363 These two functions are meant for accelerated CBC encryption. These functions are accessed through the accel\_cbc\_encrypt and accel\_cbc\_decrypt pointers.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4364 The ``blocks'' value is the number of complete blocks to process. The ``IV'' is the CBC initial vector. It is an input upon calling this function and must be
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4365 updated by the function before returning.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4366
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4367 \subsubsection{Accelerated CTR}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4368 This function is meant for accelerated CTR encryption. It is accessible through the accel\_ctr\_encrypt pointer.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4369 The ``blocks'' value is the number of complete blocks to process. The ``IV'' is the CTR counter vector. It is an input upon calling this function and must be
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4370 updated by the function before returning. The ``mode'' value indicates whether the counter is big (mode = CTR\_COUNTER\_BIG\_ENDIAN) or
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4371 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	4372
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4373 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	4374 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	4375
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4376 \begin{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4377 \item The accelerator is present
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4378 \item The CTR pad is empty
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4379 \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	4380 \end{enumerate}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4381
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4382 The ``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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4383 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	4384 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	4385
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4386 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	4387
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4388 \subsubsection{Accelerated CCM}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4389 This function is meant for accelerated CCM encryption or decryption. It processes the entire packet in one call. Note that the setup() function will not
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4390 be called prior to this. This function must handle scheduling the key provided on its own.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4391
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4392 \subsubsection{Accelerated GCM}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4393 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
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4394 be called prior to this. This function must handle scheduling the key provided on its own.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4395
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4396 \section{One--Way Hashes}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4397 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	4398
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4399 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4400 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4401 struct ltc_hash_descriptor {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4402 /** name of hash */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4403 char *name;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4404 /** internal ID */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4405 unsigned char ID;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4406 /** Size of digest in octets */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4407 unsigned long hashsize;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4408 /** Input block size in octets */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4409 unsigned long blocksize;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4410 /** ASN.1 OID */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4411 unsigned long OID[16];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4412 /** Length of DER encoding */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4413 unsigned long OIDlen;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4414 /** Init a hash state
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4415 @param hash The hash to initialize
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4416 @return CRYPT_OK if successful
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4417 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4418 int (init)(hash_state hash);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4419 /** Process a block of data
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4420 @param hash The hash state
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4421 @param in The data to hash
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4422 @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	4423 @return CRYPT_OK if successful
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 int (process)(hash_state hash, const unsigned char *in, unsigned long inlen);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4426 /** Produce the digest and store it
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4427 @param hash The hash state
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4428 @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	4429 @return CRYPT_OK if successful
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4430 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4431 int (done)(hash_state hash, unsigned char *out);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4432 /** Self-test
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4433 @return CRYPT_OK if successful, CRYPT_NOP if self-tests have been disabled
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4434 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4435 int (*test)(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4436 };
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4437 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4438 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4439
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4440 \subsection{Name}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4441 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	4442
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4443 \subsection{Internal ID}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4444 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	4445
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4446 \subsection{Digest Size}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4447 The ``hashsize'' variable indicates the length of the output in octets.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4448
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4449 \subsection{Block Size}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4450 The `blocksize'' variable indicates the length of input (in octets) that the hash processes in a given
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4451 invokation.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4452
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4453 \subsection{OID Identifier}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4454 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	4455
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4456 \subsection{Initialization}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4457 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	4458
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4459 \subsection{Process}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4460 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	4461 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	4462
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4463 \subsection{Done}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4464 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	4465
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4466 \subsection{Acceleration}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4467 A compatible accelerator must allow processing data in any granularity which may require internal padding on the driver side.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4468
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4469 \section{Pseudo--Random Number Generators}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4470 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	4471
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4472 \begin{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4473 \begin{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4474 struct ltc_prng_descriptor {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4475 /** Name of the PRNG */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4476 char *name;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4477 /** size in bytes of exported state */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4478 int export_size;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4479 /** Start a PRNG state
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4480 @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	4481 @return CRYPT_OK if successful
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4482 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4483 int (start)(prng_state prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4484 /** Add entropy to the PRNG
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4485 @param in The entropy
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4486 @param inlen Length of the entropy (octets)\
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4487 @param prng The PRNG state
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4488 @return CRYPT_OK if successful
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4489 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4490 int (add_entropy)(const unsigned char in, unsigned long inlen, prng_state *prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4491 /** 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	4492 @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	4493 @return CRYPT_OK if successful
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4494 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4495 int (ready)(prng_state prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4496 /** Read from the PRNG
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4497 @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	4498 @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	4499 @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	4500 @return Number of octets read
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4501 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4502 unsigned long (read)(unsigned char out, unsigned long outlen, prng_state *prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4503 /** Terminate a PRNG state
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4504 @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	4505 @return CRYPT_OK if successful
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4506 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4507 int (done)(prng_state prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4508 /** Export a PRNG state
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4509 @param out [out] The destination for the state
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4510 @param outlen [in/out] The max size and resulting size of the PRNG state
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4511 @param prng The PRNG to export
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4512 @return CRYPT_OK if successful
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4513 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4514 int (pexport)(unsigned char out, unsigned long outlen, prng_state prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4515 /** Import a PRNG state
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4516 @param in The data to import
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4517 @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	4518 @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	4519 @return CRYPT_OK if successful
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4520 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4521 int (pimport)(const unsigned char in, unsigned long inlen, prng_state *prng);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4522 /** Self-test the PRNG
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4523 @return CRYPT_OK if successful, CRYPT_NOP if self-testing has been disabled
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4524 */
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4525 int (*test)(void);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4526 };
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4527 \end{verbatim}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4528 \end{small}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4529
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4530 \subsection{Name}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4531 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	4532
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4533 \subsection{Export Size}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4534 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	4535
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4536 \subsection{Start}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4537 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	4538
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4539 \subsection{Entropy Addition}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4540 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	4541
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4542 \subsection{Ready}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4543 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	4544 on the specific PRNG used.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4545
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4546 \subsection{Read}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4547 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	4548 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	4549
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4550 \subsection{Done}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4551 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	4552
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4553 \subsection{Exporting and Importing}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4554 An exported PRNG state is data that the PRNG can later import to resume activity. They're not meant to resume ``the same session''
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4555 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	4556
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4557 \input{crypt.ind}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4558
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4559 \end{document}
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4560
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4561 % $Source: /cvs/libtom/libtomcrypt/crypt.tex,v $
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4562 % $Revision: 1.39 $
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating. Matt Johnston <matt@ucc.asn.au> parents: diff changeset	4563 % $Date: 2005/06/27 13:08:28 $

Mercurial > dropbear

annotate crypt.tex @ 281:997e6f7dc01e libtomcrypt-dropbear