Mercurial > dropbear

annotate libtomcrypt/crypt.tex @ 356:1085ceab122d debug-unrandom

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
blah, forgot PAM options.h
author Matt Johnston <matt@ucc.asn.au>
date Wed, 09 Aug 2006 16:45:50 +0000
parents 1b9e69c058d2
children 0cbe8f6dbf9e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1 \documentclass[a4paper]{book}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2 \usepackage{hyperref}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3 \usepackage{makeidx}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4 \usepackage{amssymb}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5 \usepackage{color}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6 \usepackage{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
7 \usepackage{graphicx}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
8 \usepackage{layout}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
9 \def\union{\cup}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
10 \def\intersect{\cap}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
11 \def\getsrandom{\stackrel{\rm R}{\gets}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
12 \def\cross{\times}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
13 \def\cat{\hspace{0.5em} \| \hspace{0.5em}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
14 \def\catn{$\|$}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
15 \def\divides{\hspace{0.3em} | \hspace{0.3em}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
16 \def\nequiv{\not\equiv}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
17 \def\approx{\raisebox{0.2ex}{\mbox{\small $\sim$}}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
18 \def\lcm{{\rm lcm}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
19 \def\gcd{{\rm gcd}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
20 \def\log{{\rm log}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
21 \def\ord{{\rm ord}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
22 \def\abs{{\mathit abs}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
23 \def\rep{{\mathit rep}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
24 \def\mod{{\mathit\ mod\ }}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
25 \renewcommand{\pmod}[1]{\ ({\rm mod\ }{#1})}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
26 \newcommand{\floor}[1]{\left\lfloor{#1}\right\rfloor}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
27 \newcommand{\ceil}[1]{\left\lceil{#1}\right\rceil}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
28 \def\Or{{\rm\ or\ }}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
29 \def\And{{\rm\ and\ }}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
30 \def\iff{\hspace{1em}\Longleftrightarrow\hspace{1em}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
31 \def\implies{\Rightarrow}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
32 \def\undefined{{\rm ``undefined"}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
33 \def\Proof{\vspace{1ex}\noindent {\bf Proof:}\hspace{1em}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
34 \let\oldphi\phi
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
35 \def\phi{\varphi}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
36 \def\Pr{{\rm Pr}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
37 \newcommand{\str}[1]{{\mathbf{#1}}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
38 \def\F{{\mathbb F}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
39 \def\N{{\mathbb N}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
40 \def\Z{{\mathbb Z}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
41 \def\R{{\mathbb R}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
42 \def\C{{\mathbb C}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
43 \def\Q{{\mathbb Q}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
44
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
45 \def\twiddle{\raisebox{0.3ex}{\mbox{\tiny $\sim$}}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
46
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
47 \def\gap{\vspace{0.5ex}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
48 \makeindex
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
49 \begin{document}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
50 \title{LibTomCrypt \\ Version 1.05}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
51 \author{Tom St Denis \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
52 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
53 [email protected] \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
54 http://libtomcrypt.org
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
55 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
56 \maketitle
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
58 formatted for A4 paper using the \LaTeX{} {\em book} macro package.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
59
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
60 \vspace{15cm}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
61
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
62 \begin{flushright}Open Source. Open Academia. Open Minds.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
63
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
64 \mbox{ }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
65
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
66 Tom St Denis,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
67
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
68 Phone: 1-613-836-3160
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
69
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
70 111 Banning Rd
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
71
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
72 Kanata, Ontario
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
73
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
74 K2L 1C3
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
75
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
76 Canada
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
77 \end{flushright}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
78 \newpage
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
79 \tableofcontents
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
80 \chapter{Introduction}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
81 \section{What is the LibTomCrypt?}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
83 designing a cryptosystem. It supports symmetric ciphers, one-way hashes, pseudo-random number generators,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
85 routines.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
86
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
91
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
92 \subsection{What the library IS for?}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
93
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
97 was not tied to any particular cryptographic problem.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
98
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
99 \section{Why did I write it?}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
101 two categories:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
102 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
104 \item It was (still is) good coding practice.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
105 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
106
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
108 {\bf own} crypto library and hopefully along the way others will appreciate the work.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
109
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
115 application can support all ciphers/hashes/prngs without changing the source code.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
116
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
120 tools may be limited (e.g. no autoconf).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
121
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
123 robustness and efficiency. LibTomCrypt traps and returns a series of errors ranging from invalid
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
126 Crypto++.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
127
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
128 \subsection{Modular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
131 are essentially structures with pointers to functions. While you can still call particular functions
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
133 usage of the library.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
134
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
140 with zero modifications to the end applications provided they are written properly.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
141
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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})
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
148 can make use of the cipher right away.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
149
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
150 \section{License}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
151
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
153 under a public domain license:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
154
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
155 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
156 \item rc2.c
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
157 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
158
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
160 my LibTomMath library which is public domain.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
161
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
163
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
164 The project is hereby released as public domain.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
165
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
166 \section{Patent Disclosure}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
167
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
172
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
174 the ciphers you just can't advertise that you are doing so.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
175
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
176 \section{Thanks}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
178 early on:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
179 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
180 \item Richard van de Laarschot
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
181 \item Richard Heathfield
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
182 \item Ajay K. Agrawal
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
183 \item Brian Gladman
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
184 \item Svante Seleborg
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
185 \item Clay Culver
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
186 \item Jason Klapste
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
187 \item Dobes Vandermeer
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
188 \item Daniel Richards
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
189 \item Wayne Scott
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
190 \item Andrew Tyler
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
191 \item Sky Schulz
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
192 \item Christopher Imes
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
193 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
194
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
196 time to time.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
197
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
198 \chapter{The Application Programming Interface (API)}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
199 \section{Introduction}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
200 \index{CRYPT\_ERROR} \index{CRYPT\_OK}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
201
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
206
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
207 \index{error\_to\_string()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
208 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
209 const char *error_to_string(int err);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
210 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
211
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
212 An example of handling an error is:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
213 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
214 void somefunc(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
215 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
216 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
217
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
218 /* call a cryptographic function */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
219 if ((err = some_crypto_function(...)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
220 printf("A crypto error occured, %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
221 /* perform error handling */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
222 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
223 /* continue on if no error occured */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
224 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
225 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
226
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
229 that is not an issue.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
230
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
232 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
233 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
234 int main(void) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
235 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
236 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
237 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
238
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
240 ``ltc\_tommath.h'' (the bignum library routines).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
241
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
242 \section{Macros}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
243
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
245 32/64-bit words in little/big endian format. The macros are:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
246
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
248 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
249 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
250 \begin{tabular}{|c|c|c|}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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]$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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]$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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]$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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]$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
259 \hline BSWAP(x) & {\bf unsigned long} x & Swaps byte order (32--bits only) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
260 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
261 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
262 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
263 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
264
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
265 There are 32 and 64-bit cyclic rotations as well:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
267 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
268 \begin{tabular}{|c|c|c|}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
273 \hline && \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
278 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
279 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
280 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
281
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
282 \section{Functions with Variable Length Output}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
285 the output will be stored. For example:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
286 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
287 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
288 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
289 int main(void) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
290 rsa_key key;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
291 unsigned char buffer[1024];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
292 unsigned long x;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
293 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
294
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
295 /* ... Make up the RSA key somehow ... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
296
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
297 /* lets export the key, set x to the size of the output buffer */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
298 x = sizeof(buffer);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
299 if ((err = rsa_export(buffer, &x, PK_PUBLIC, &key)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
300 printf("Export error: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
301 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
302 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
303
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
304 /* if rsa_export() was successful then x will have the size of the output */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
305 printf("RSA exported key takes %d bytes\n", x);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
306
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
307 /* ... do something with the buffer */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
308
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
309 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
310 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
311 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
312 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
316
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
317 \section{Functions that need a PRNG}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
318 \index{Pseudo Random Number Generator} \index{PRNG}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
321
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
323 may be passed as \textbf{NULL} in such situations.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
324
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
325 \section{Functions that use Arrays of Octets}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
331
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
333 type ``byte'' will be synonymous with an array of type ``unsigned char''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
334
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
335 \chapter{Symmetric Block Ciphers}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
336 \section{Core Functions}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
337
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
341 the API to grow in a modular fashion.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
342
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
343 \subsection{Key Scheduling}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
347 functions which are (given that XXX is the name of the cipher):
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
348 \index{Cipher Setup}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
349 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
350 int XXX_setup(const unsigned char *key, int keylen, int rounds,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
351 symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
352 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
353
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
356
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
361
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
362 \subsection{ECB Encryption and Decryption}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
364 \index{Cipher Encrypt} \index{Cipher Decrypt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
365 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
366 void XXX_ecb_encrypt(const unsigned char *pt, unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
367 symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
368
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
369 void XXX_ecb_decrypt(const unsigned char *ct, unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
370 symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
371 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
377
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
378 \subsection{Self--Testing}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
379 \index{Cipher Testing}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
380 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
381 int XXX_test(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
382 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
384 based upon.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
385
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
386 \subsection{Key Sizing}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
388 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
389 int XXX_keysize(int *keysize);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
390 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
392 return {\bf CRYPT\_OK} if the key size specified is acceptable. For example:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
393 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
394 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
395 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
396 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
397 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
398 int keysize, err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
399
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
400 /* now given a 20 byte key what keysize does Twofish want to use? */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
401 keysize = 20;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
402 if ((err = twofish_keysize(&keysize)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
403 printf("Error getting key size: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
404 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
405 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
406 printf("Twofish suggested a key size of %d\n", keysize);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
407 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
408 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
409 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
410 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
411 This should indicate a keysize of sixteen bytes is suggested.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
412
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
413 \subsection{Cipher Termination}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
415 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
416 void XXX_done(symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
417 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
420 setup function must also call the respective cipher done function when finished.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
421
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
422 \subsection{Simple Encryption Demonstration}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
423 An example snippet that encodes a block with Blowfish in ECB mode is below.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
424
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
425 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
426 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
427 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
428 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
429 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
430 unsigned char pt[8], ct[8], key[8];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
431 symmetric_key skey;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
432 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
433
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
434 /* ... key is loaded appropriately in ``key'' ... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
435 /* ... load a block of plaintext in ``pt'' ... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
436
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
437 /* schedule the key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
438 if ((err = blowfish_setup(key, /* the key we will use */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
439 8, /* key is 8 bytes (64-bits) long */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
440 0, /* 0 == use default # of rounds */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
441 &skey) /* where to put the scheduled key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
442 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
443 printf("Setup error: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
444 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
445 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
446
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
447 /* encrypt the block */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
448 blowfish_ecb_encrypt(pt, /* encrypt this 8-byte array */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
449 ct, /* store encrypted data here */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
450 &skey); /* our previously scheduled key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
451
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
452 /* now ct holds the encrypted version of pt */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
453
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
454 /* decrypt the block */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
455 blowfish_ecb_decrypt(ct, /* decrypt this 8-byte array */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
456 pt, /* store decrypted data here */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
457 &skey); /* our previously scheduled key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
458
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
459 /* now we have decrypted ct to the original plaintext in pt */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
460
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
461 /* Terminate the cipher context */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
462 blowfish_done(&skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
463
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
464 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
465 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
466 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
467 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
468
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
469 \section{Key Sizes and Number of Rounds}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
470 \index{Symmetric Keys}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
477 only 53 bits of entropy.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
478
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
482 size.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
483
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
484 \section{The Cipher Descriptors}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
485 \index{Cipher Descriptor}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
487 of this array has the following format:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
488
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
489 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
490 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
491 struct _cipher_descriptor {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
492 char *name;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
493 unsigned char ID;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
494 int min_key_length,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
495 max_key_length,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
496 block_length,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
497 default_rounds;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
498 int (*setup)(const unsigned char *key, int keylen, int num_rounds, symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
499 void (*ecb_encrypt)(const unsigned char *pt, unsigned char *ct, symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
500 void (*ecb_decrypt)(const unsigned char *ct, unsigned char *pt, symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
501 int (*test)(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
502 void (*done)(symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
503 int (*keysize)(int *keysize);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
504
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
505 void (*accel_ecb_encrypt)(const unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
506 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
507 unsigned long blocks, symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
508 void (*accel_ecb_decrypt)(const unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
509 unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
510 unsigned long blocks, symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
511 void (*accel_cbc_encrypt)(const unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
512 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
513 unsigned long blocks, unsigned char *IV,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
514 symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
515 void (*accel_cbc_decrypt)(const unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
516 unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
517 unsigned long blocks, unsigned char *IV,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
518 symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
519 void (*accel_ctr_encrypt)(const unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
520 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
521 unsigned long blocks, unsigned char *IV,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
522 int mode, symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
523 void (*accel_ccm_memory)(
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
524 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
525 const unsigned char *nonce, unsigned long noncelen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
526 const unsigned char *header, unsigned long headerlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
527 unsigned char *pt, unsigned long ptlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
528 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
529 unsigned char *tag, unsigned long *taglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
530 int direction);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
531
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
532 };
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
533 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
534 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
535
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
540 of rounds that will be used.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
541
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
543 marked when ``name'' equals {\bf NULL}.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
544
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
545 As of this release the current cipher\_descriptors elements are
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
546
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
547 \index{Cipher descriptor table}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
548 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
549 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
550 \begin{tabular}{|c|c|c|c|c|c|}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
551 \hline Name & Descriptor Name & Block Size & Key Range & Rounds \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
552 \hline Blowfish & blowfish\_desc & 8 & 8 $\ldots$ 56 & 16 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
553 \hline X-Tea & xtea\_desc & 8 & 16 & 32 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
554 \hline RC2 & rc2\_desc & 8 & 8 $\ldots$ 128 & 16 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
555 \hline RC5-32/12/b & rc5\_desc & 8 & 8 $\ldots$ 128 & 12 $\ldots$ 24 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
556 \hline RC6-32/20/b & rc6\_desc & 16 & 8 $\ldots$ 128 & 20 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
557 \hline SAFER+ & saferp\_desc &16 & 16, 24, 32 & 8, 12, 16 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
558 \hline AES & aes\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
559 & aes\_enc\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
560 \hline Twofish & twofish\_desc & 16 & 16, 24, 32 & 16 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
561 \hline DES & des\_desc & 8 & 7 & 16 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
562 \hline 3DES (EDE mode) & des3\_desc & 8 & 21 & 16 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
563 \hline CAST5 (CAST-128) & cast5\_desc & 8 & 5 $\ldots$ 16 & 12, 16 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
564 \hline Noekeon & noekeon\_desc & 16 & 16 & 16 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
565 \hline Skipjack & skipjack\_desc & 8 & 10 & 32 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
566 \hline Anubis & anubis\_desc & 16 & 16 $\ldots$ 40 & 12 $\ldots$ 18 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
567 \hline Khazad & khazad\_desc & 8 & 16 & 8 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
568 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
569 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
570 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
571 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
572
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
573 \subsection{Notes}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
574 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
575 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
576 \item
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
583 should not be called.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
584
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
587 Rijndael as it makes the most sense for this cipher.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
588
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
589 \item
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
592 byte string from the real 7/21 byte key.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
593
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
594 \item
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
602 Twofish round function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
603
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
604 \index{Twofish build options}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
605 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
606 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
607 \begin{tabular}{|l|l|l|}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
608 \hline TWOFISH\_SMALL & TWOFISH\_TABLES & Speed and Memory (per key) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
609 \hline undefined & undefined & Very fast, 4.2KB of ram. \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
610 \hline undefined & defined & Faster keysetup, larger code. \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
611 \hline defined & undefined & Very slow, 0.2KB of ram. \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
612 \hline defined & defined & Faster, 0.2KB of ram, larger code. \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
613 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
614 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
615 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
616 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
617
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
618 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
619 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
620
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
621 To work with the cipher\_descriptor array there is a function:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
622 \index{find\_cipher()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
623 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
624 int find_cipher(char *name)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
625 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
628 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
629 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
630 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
631 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
632 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
633 unsigned char key[8];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
634 symmetric_key skey;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
635 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
636
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
637 /* you must register a cipher before you use it */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
638 if (register_cipher(&blowfish_desc)) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
639 printf("Unable to register Blowfish cipher.");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
640 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
641 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
642
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
643 /* generic call to function (assuming the key in key[] was already setup) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
644 if ((err = cipher_descriptor[find_cipher("blowfish")].setup(key, 8, 0, &skey)) !=
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
645 CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
646 printf("Error setting up Blowfish: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
647 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
648 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
649
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
650 /* ... use cipher ... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
651 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
652 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
653 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
654
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
656 to use a cipher with the descriptor table you must register it first using:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
657 \index{register\_cipher()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
658 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
659 int register_cipher(const struct _cipher_descriptor *cipher);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
660 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
664 \index{unregister\_cipher()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
665 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
666 int unregister_cipher(const struct _cipher_descriptor *cipher);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
667 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
669 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
670 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
671 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
672 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
673 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
674 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
675
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
676 /* register the cipher */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
677 if (register_cipher(&rijndael_desc) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
678 printf("Error registering Rijndael\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
679 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
680 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
681
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
682 /* use Rijndael */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
683
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
684 /* remove it */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
685 if ((err = unregister_cipher(&rijndael_desc)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
686 printf("Error removing Rijndael: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
687 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
688 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
689
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
690 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
691 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
692 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
693 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
694 This snippet is a small program that registers only Rijndael only.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
695
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
696 \section{Symmetric Modes of Operations}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
697 \subsection{Background}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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}$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
701
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
702 \subsubsection{ECB Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
703 \index{ECB mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
705 \begin{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
706 C_i = E_k(P_i)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
707 \end{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
709 than once.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
710
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
711 \subsubsection{CBC Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
712 \index{CBC mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
714 It is given as:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
715 \begin{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
716 C_i = E_k(P_i \oplus C_{i - 1})
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
717 \end{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
719
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
720 \subsubsection{CTR Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
721 \index{CTR mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
723 treated as a large binary counter the CTR mode is given as:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
724 \begin{eqnarray}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
725 C_{-1} = C_{-1} + 1\mbox{ }(\mbox{mod }2^W) \nonumber \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
726 C_i = P_i \oplus E_k(C_{-1})
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
727 \end{eqnarray}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
731
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
732 \subsubsection{CFB Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
733 \index{CFB mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
735 \begin{eqnarray}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
736 C_i = P_i \oplus C_{-1} \nonumber \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
737 C_{-1} = E_k(C_i)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
738 \end{eqnarray}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
742
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
743 \subsubsection{OFB Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
744 \index{OFB mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
746 \begin{eqnarray}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
747 C_{-1} = E_k(C_{-1}) \nonumber \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
748 C_i = P_i \oplus C_{-1}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
749 \end{eqnarray}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
752
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
753 \subsection{Choice of Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
754 My personal preference is for the CTR mode since it has several key benefits:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
755 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
756 \item No short cycles which is possible in the OFB and CFB modes.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
758 \item Technically does not require the decryption routine of the cipher.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
759 \item Allows random access to the plaintext.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
761 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
764 block of memory with either of the three modes.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
765
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
767 other modes.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
768
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
769 \subsection{Initialization}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
770 \index{CBC Mode} \index{CTR Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
771 \index{OFB Mode} \index{CFB Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
774 use that mode. They have identical setup routines (except CTR and ECB mode):
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
776 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
777 int XXX_start(int cipher, const unsigned char *IV,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
778 const unsigned char *key, int keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
779 int num_rounds, symmetric_XXX *XXX);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
780
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
781 int ctr_start( int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
782 const unsigned char *IV,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
783 const unsigned char *key, int keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
784 int num_rounds, int ctr_mode,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
785 symmetric_CTR *ctr);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
786
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
787 int ecb_start(int cipher, const unsigned char *key, int keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
788 int num_rounds, symmetric_ECB *ecb);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
789 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
790
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
797
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
798
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
802
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
804
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
805 \subsection{Encryption and Decryption}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
806 To actually encrypt or decrypt the following routines are provided:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
807 \index{ecb\_encrypt()} \index{ecb\_decrypt()} \index{cfb\_encrypt()} \index{cfb\_decrypt()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
809 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
810 int XXX_encrypt(const unsigned char *pt, unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
811 unsigned long len, symmetric_YYY *YYY);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
812 int XXX_decrypt(const unsigned char *ct, unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
813 unsigned long len, symmetric_YYY *YYY);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
814 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
815 Where ``XXX'' is one of $\lbrace ecb, cbc, ctr, cfb, ofb \rbrace$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
816
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
821
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
823 zeroes or with whatever your protocol requires).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
824
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
826 and use the decrypt routine on all of the blocks.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
827
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
828 \subsection{IV Manipulation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
830
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
832 \index{ctr\_setiv()} \index{ctr\_getiv()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
833 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
834 int XXX_getiv(unsigned char *IV, unsigned long *len, symmetric_XXX *XXX);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
835 int XXX_setiv(const unsigned char *IV, unsigned long len, symmetric_XXX *XXX);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
836 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
837
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
840 of the IV passed in must be the size of the ciphers block size.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
841
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
843
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
844 \subsection{Stream Termination}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
845 To terminate an open stream call the done function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
846
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
848 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
849 int XXX_done(symmetric_XXX *XXX);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
850 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
851
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
853
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
854 \subsection{Examples}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
855
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
856 \newpage
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
857 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
858 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
859 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
860 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
861 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
862 unsigned char key[16], IV[16], buffer[512];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
863 symmetric_CTR ctr;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
864 int x, err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
865
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
866 /* register twofish first */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
867 if (register_cipher(&twofish_desc) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
868 printf("Error registering cipher.\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
869 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
870 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
871
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
872 /* somehow fill out key and IV */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
873
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
874 /* start up CTR mode */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
875 if ((err = ctr_start(
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
876 find_cipher("twofish"), /* index of desired cipher */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
877 IV, /* the initial vector */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
878 key, /* the secret key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
879 16, /* length of secret key (16 bytes, 128 bits) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
880 0, /* 0 == default # of rounds */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
881 CTR_COUNTER_LITTLE_ENDIAN, /* Little endian counter */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
882 &ctr) /* where to store initialized CTR state */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
883 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
884 printf("ctr_start error: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
885 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
886 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
887
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
888 /* somehow fill buffer than encrypt it */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
889 if ((err = ctr_encrypt( buffer, /* plaintext */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
890 buffer, /* ciphertext */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
891 sizeof(buffer), /* length of data to encrypt */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
892 &ctr) /* previously initialized CTR state */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
893 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
894 printf("ctr_encrypt error: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
895 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
896 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
897
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
898 /* make use of ciphertext... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
899
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
900 /* now we want to decrypt so let's use ctr_setiv */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
901 if ((err = ctr_setiv( IV, /* the initial IV we gave to ctr_start */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
902 16, /* the IV is 16 bytes long */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
903 &ctr) /* the ctr state we wish to modify */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
904 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
905 printf("ctr_setiv error: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
906 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
907 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
908
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
909 if ((err = ctr_decrypt( buffer, /* ciphertext */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
910 buffer, /* plaintext */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
911 sizeof(buffer), /* length of data to encrypt */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
912 &ctr) /* previously initialized CTR state */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
913 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
914 printf("ctr_decrypt error: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
915 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
916 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
917
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
918 /* terminate the stream */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
919 if ((err = ctr_done(&ctr)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
920 printf("ctr_done error: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
921 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
922 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
923
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
924 /* clear up and return */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
925 zeromem(key, sizeof(key));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
926 zeromem(&ctr, sizeof(ctr));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
927
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
928 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
929 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
930 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
931 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
932
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
933 \section{Encrypt and Authenticate Modes}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
934
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
935 \subsection{EAX Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
936 LibTomCrypt provides support for a mode called EAX\footnote{See
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.}.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
941 secret symmetric key.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
942
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
945 be detected by changes in the output tag.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
946
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
950 of operation.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
951
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
952 The mode is initialized with the following function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
953 \index{eax\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
954 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
955 int eax_init(eax_state *eax, int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
956 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
957 const unsigned char *nonce, unsigned long noncelen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
958 const unsigned char *header, unsigned long headerlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
959 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
960
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
964 ``headerlen''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
965
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
968 there is no initial header data.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
969
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
970 To encrypt or decrypt data in a streaming mode use the following.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
971 \index{eax\_encrypt()} \index{eax\_decrypt()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
972 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
973 int eax_encrypt(eax_state *eax, const unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
974 unsigned char *ct, unsigned long length);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
975
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
976 int eax_decrypt(eax_state *eax, const unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
977 unsigned char *pt, unsigned long length);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
978 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
982 ``pt'' and ``ct'' to be the same region in memory.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
983
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
985 will need to initialize two EAX contexts (preferably with different headers and nonces).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
986
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
989 EAX stream with the following.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
990
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
991 \index{eax\_addheader()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
992 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
993 int eax_addheader(eax_state *eax,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
994 const unsigned char *header, unsigned long length);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
995 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
996
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
998 ``tag'' (checksum) may be computed with the following function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
999
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1000 \index{eax\_done()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1001 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1002 int eax_done(eax_state *eax,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1003 unsigned char *tag, unsigned long *taglen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1004 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1006 then stores how many bytes of the tag were written out back into ``taglen''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1007
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1009 \index{eax\_test()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1010 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1011 int eax_test(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1012 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1014
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1015 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1016 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1017 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1018 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1019 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1020 eax_state eax;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1021 unsigned char pt[64], ct[64], nonce[16], key[16], tag[16];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1022 unsigned long taglen;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1023
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1024 if (register_cipher(&rijndael_desc) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1025 printf("Error registering Rijndael");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1026 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1027 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1028
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1029 /* ... make up random nonce and key ... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1030
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1031 /* initialize context */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1032 if ((err = eax_init( &eax, /* the context */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1033 find_cipher("rijndael"), /* cipher we want to use */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1034 nonce, /* our state nonce */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1035 16, /* none is 16 bytes */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1036 "TestApp", /* example header, identifies this program */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1037 7) /* length of the header */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1038 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1039 printf("Error eax_init: %s", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1040 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1041 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1042
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1043 /* now encrypt data, say in a loop or whatever */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1044 if ((err = eax_encrypt( &eax, /* eax context */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1045 pt, /* plaintext (source) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1046 ct, /* ciphertext (destination) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1047 sizeof(pt) /* size of plaintext */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1048 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1049 printf("Error eax_encrypt: %s", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1050 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1051 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1052
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1053 /* finish message and get authentication tag */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1054 taglen = sizeof(tag);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1055 if ((err = eax_done( &eax, /* eax context */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1056 tag, /* where to put tag */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1057 &taglen /* length of tag space */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1058 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1059 printf("Error eax_done: %s", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1060 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1061 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1062
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1063 /* now we have the authentication tag in "tag" and it's taglen bytes long */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1064
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1065 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1066 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1067
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1069 following functions.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1070
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1071
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1072 \index{eax\_encrypt\_authenticate\_memory} \index{eax\_decrypt\_verify\_memory}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1073 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1074 int eax_encrypt_authenticate_memory(int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1075 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1076 const unsigned char *nonce, unsigned long noncelen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1077 const unsigned char *header, unsigned long headerlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1078 const unsigned char *pt, unsigned long ptlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1079 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1080 unsigned char *tag, unsigned long *taglen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1081
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1082 int eax_decrypt_verify_memory(int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1083 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1084 const unsigned char *nonce, unsigned long noncelen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1085 const unsigned char *header, unsigned long headerlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1086 const unsigned char *ct, unsigned long ctlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1087 unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1088 unsigned char *tag, unsigned long taglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1089 int *res);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1090 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1091
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1093 have the same meaning as with those respective functions.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1094
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1097
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1098 \subsection{OCB Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1099 LibTomCrypt provides support for a mode called OCB\footnote{See
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1102 but is less flexible. Let's review how to initialize an OCB context.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1103
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1104 \index{ocb\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1105 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1106 int ocb_init(ocb_state *ocb, int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1107 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1108 const unsigned char *nonce);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1109 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1110
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1113 block size (e.g. 16 bytes for AES).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1114
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1116 To encrypt or decrypt data use the following.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1117
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1118 \index{ocb\_encrypt()} \index{ocb\_decrypt()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1119 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1120 int ocb_encrypt(ocb_state *ocb, const unsigned char *pt, unsigned char *ct);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1121 int ocb_decrypt(ocb_state *ocb, const unsigned char *ct, unsigned char *pt);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1122 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1123
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1128
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1129 \subsubsection{State Termination}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1130
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1132
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1133 \index{ocb\_done\_encrypt()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1134 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1135 int ocb_done_encrypt(ocb_state *ocb,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1136 const unsigned char *pt, unsigned long ptlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1137 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1138 unsigned char *tag, unsigned long *taglen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1139 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1140
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1143 store upto ``taglen'' bytes of the tag into ``tag''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1144
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1147
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1148 To terminate a decrypt stream and compared the tag you call the following.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1149
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1150 \index{ocb\_done\_decrypt()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1151 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1152 int ocb_done_decrypt(ocb_state *ocb,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1153 const unsigned char *ct, unsigned long ctlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1154 unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1155 const unsigned char *tag, unsigned long taglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1156 int *res);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1157 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1158
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1162 message).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1163
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1164 \subsubsection{Packet Functions}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1165 To make life simpler the following two functions are provided for memory bound OCB.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1166
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1167 \index{ocb\_encrypt\_authenticate\_memory()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1168 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1169 int ocb_encrypt_authenticate_memory(int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1170 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1171 const unsigned char *nonce,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1172 const unsigned char *pt, unsigned long ptlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1173 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1174 unsigned char *tag, unsigned long *taglen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1175 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1176
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1178 can be any arbitrary length.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1179
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1180 \index{ocb\_decrypt\_verify\_memory()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1181 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1182 int ocb_decrypt_verify_memory(int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1183 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1184 const unsigned char *nonce,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1185 const unsigned char *ct, unsigned long ctlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1186 unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1187 const unsigned char *tag, unsigned long taglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1188 int *res);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1189 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1190
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1192 appropriately.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1193
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1194 \subsection{CCM Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1197 function that performs the protocol.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1198
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1199 \index{ccm\_memory()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1200 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1201 int ccm_memory(int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1202 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1203 const unsigned char *nonce, unsigned long noncelen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1204 const unsigned char *header, unsigned long headerlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1205 unsigned char *pt, unsigned long ptlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1206 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1207 unsigned char *tag, unsigned long *taglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1208 int direction);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1209 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1210
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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}).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1215
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1218 decryption (direction $=$ \textbf{CCM\_DECRYPT}) is to be performed.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1219
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1221
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1222 You can test the implementation of CCM with the following function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1223
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1224 \index{ccm\_test()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1225 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1226 int ccm_test(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1227 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1228
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1229 This will return \textbf{CRYPT\_OK} if the CCM routine passes known test vectors.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1230
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1231 \subsection{GCM Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1234 byte block.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1235
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1238
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1239 \subsubsection{Initialization}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1240 To initialize the GCM context with a secret key call the following function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1241
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1242 \index{gcm\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1243 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1244 int gcm_init(gcm_state *gcm, int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1245 const unsigned char *key, int keylen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1246 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1248 must have a 16--byte block size (e.g. AES).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1249
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1250 \subsubsection{Initial Vector}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1252
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1253 \index{gcm\_add\_iv()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1254 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1255 int gcm_add_iv(gcm_state *gcm,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1256 const unsigned char *IV, unsigned long IVlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1257 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1258
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1260 to process the entire IV.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1261
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1264
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1265 \subsubsection{Additional Authentication Data}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1269
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1270 \index{gcm\_add\_aad()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1271 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1272 int gcm_add_aad(gcm_state *gcm,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1273 const unsigned char *adata, unsigned long adatalen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1274 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1276
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1277 \subsubsection{Plaintext Processing}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1279
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1280 \index{gcm\_process()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1281 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1282 int gcm_process(gcm_state *gcm,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1283 unsigned char *pt, unsigned long ptlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1284 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1285 int direction);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1286 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1289 in the ciphertext buffer. When ``direction'' equals \textbf{GCM\_DECRYPT} the opposite occurs.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1290
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1291 \subsubsection{State Termination}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1293
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1294 \index{gcm\_done()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1295 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1296 int gcm_done(gcm_state *gcm,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1297 unsigned char *tag, unsigned long *taglen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1298 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1300
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1301 \subsubsection{State Reset}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1304
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1305 \index{gcm\_reset()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1306 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1307 int gcm_reset(gcm_state *gcm);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1308 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1309
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1311
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1312 \subsubsection{One--Shot Packet}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1314
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1315 \index{gcm\_memory()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1316 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1317 int gcm_memory( int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1318 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1319 const unsigned char *IV, unsigned long IVlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1320 const unsigned char *adata, unsigned long adatalen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1321 unsigned char *pt, unsigned long ptlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1322 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1323 unsigned char *tag, unsigned long *taglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1324 int direction);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1325 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1326
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1329
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1331
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1332 \subsubsection{Example Usage}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1334
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1335 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1336 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1337 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1338
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1339 int send_packet(const unsigned char *pt, unsigned long ptlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1340 const unsigned char *iv, unsigned long ivlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1341 const unsigned char *aad, unsigned long aadlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1342 gcm_state *gcm)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1343 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1344 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1345 unsigned long taglen;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1346 unsigned char tag[16];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1347
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1348 /* reset the state */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1349 if ((err = gcm_reset(gcm)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1350 return err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1351 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1352
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1353 /* Add the IV */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1354 if ((err = gcm_add_iv(gcm, iv, ivlen)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1355 return err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1356 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1357
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1358 /* Add the AAD (note: aad can be NULL if aadlen == 0) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1359 if ((err = gcm_add_aad(gcm, aad, aadlen)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1360 return err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1361 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1362
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1363 /* process the plaintext */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1364 if ((err = gcm_process(gcm, pt, ptlen, pt, GCM_ENCRYPT)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1365 return err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1366 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1367
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1368 /* Finish up and get the MAC tag */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1369 taglen = sizeof(tag);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1370 if ((err = gcm_done(gcm, tag, &taglen)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1371 return err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1372 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1373
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1374 /* ... send a header describing the lengths ... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1375
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1377 send(socket, iv, ivlen, 0);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1378
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1379 /* send the aad */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1380 send(socket, aad, aadlen, 0);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1381
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1382 /* send the ciphertext */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1383 send(socket, pt, ptlen, 0);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1384
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1385 /* send the tag */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1386 send(socket, tag, taglen, 0);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1387
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1388 return CRYPT_OK;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1389 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1390
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1391 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1392 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1393 gcm_state gcm;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1394 unsigned char key[16], IV[12], pt[PACKET_SIZE];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1395 int err, x;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1396 unsigned long ptlen;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1397
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1398 /* somehow fill key/IV with random values */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1399
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1400 /* register AES */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1401 register_cipher(&aes_desc);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1402
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1403 /* init the GCM state */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1404 if ((err = gcm_init(&gcm, find_cipher("aes"), key, 16)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1405 whine_and_pout(err);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1406 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1407
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1408 /* handle us some packets */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1409 for (;;) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1410 ptlen = make_packet_we_want_to_send(pt);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1411
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1412 /* use IV as counter (12 byte counter) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1413 for (x = 11; x >= 0; x--) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1414 if (++IV[x]) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1415 break;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1416 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1417 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1418
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1419 if ((err = send_packet(pt, ptlen, iv, 12, NULL, 0, &gcm)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1420 whine_and_pout(err);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1421 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1422 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1423 return EXIT_SUCCESS;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1424 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1425 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1426 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1427
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1428 \chapter{One-Way Cryptographic Hash Functions}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1429 \section{Core Functions}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1430
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1432 To initialize hash XXX (where XXX is the name) call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1433 \index{Hash Functions}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1434 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1435 void XXX_init(hash_state *md);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1436 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1437
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1439 message being hashed call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1440 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1441 int XXX_process(hash_state *md, const unsigned char *in, unsigned long inlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1442 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1443
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1446 (hash output) will be the same. For example, this means that:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1447 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1448 md5_process(&md, "hello ", 6);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1449 md5_process(&md, "world", 5);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1450 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1451 Will produce the same message digest as the single call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1452 \index{Message Digest}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1453 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1454 md5_process(&md, "hello world", 11);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1455 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1456
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1457 To finally get the message digest (the hash) call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1458 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1459 int XXX_done(hash_state *md,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1460 unsigned char *out);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1461 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1462
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1465 will wipe the ``md'' variable before returning automatically.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1466
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1467 To test a hash function call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1468 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1469 int XXX_test(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1470 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1471
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1473 example snippet that hashes a message with md5 is given below.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1474 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1475 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1476 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1477 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1478 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1479 hash_state md;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1480 unsigned char *in = "hello world", out[16];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1481
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1482 /* setup the hash */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1483 md5_init(&md);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1484
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1485 /* add the message */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1486 md5_process(&md, in, strlen(in));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1487
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1488 /* get the hash in out[0..15] */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1489 md5_done(&md, out);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1490
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1491 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1492 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1493 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1494 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1495
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1496 \section{Hash Descriptors}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1498 are defined by:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1499 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1500 struct _hash_descriptor {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1501 char *name;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1502 unsigned long hashsize; /* digest output size in bytes */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1503 unsigned long blocksize; /* the block size the hash uses */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1504 void (*init) (hash_state *hash);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1505 int (*process)(hash_state *hash,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1506 const unsigned char *in, unsigned long inlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1507 int (*done) (hash_state *hash, unsigned char *out);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1508 int (*test) (void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1509 };
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1510 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1511
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1515 position in the descriptor table of the hash.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1516
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1518 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1519 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1520 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1521 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1522 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1523 unsigned char buffer[100], hash[MAXBLOCKSIZE];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1524 int idx, x;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1525 hash_state md;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1526
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1527 /* register hashes .... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1528 if (register_hash(&md5_desc) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1529 printf("Error registering MD5.\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1530 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1531 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1532
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1533 /* register other hashes ... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1534
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1535 /* prompt for name and strip newline */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1536 printf("Enter hash name: \n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1537 fgets(buffer, sizeof(buffer), stdin);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1538 buffer[strlen(buffer) - 1] = 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1539
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1540 /* get hash index */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1541 idx = find_hash(buffer);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1542 if (idx == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1543 printf("Invalid hash name!\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1544 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1545 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1546
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1547 /* hash input until blank line */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1548 hash_descriptor[idx].init(&md);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1549 while (fgets(buffer, sizeof(buffer), stdin) != NULL)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1550 hash_descriptor[idx].process(&md, buffer, strlen(buffer));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1551 hash_descriptor[idx].done(&md, hash);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1552
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1553 /* dump to screen */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1554 for (x = 0; x < hash_descriptor[idx].hashsize; x++)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1555 printf("%02x ", hash[x]);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1556 printf("\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1557 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1558 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1559 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1560 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1561
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1564
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1565 There are three helper functions as well:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1566 \index{hash\_memory()} \index{hash\_file()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1567 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1568 int hash_memory(int hash,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1569 const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1570 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1571
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1572 int hash_file(int hash, const char *fname,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1573 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1574
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1575 int hash_filehandle(int hash, FILE *in,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1576 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1577 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1578
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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()}).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1584
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1585 To perform the above hash with md5 the following code could be used:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1586 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1587 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1588 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1589 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1590 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1591 int idx, err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1592 unsigned long len;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1593 unsigned char out[MAXBLOCKSIZE];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1594
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1595 /* register the hash */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1596 if (register_hash(&md5_desc) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1597 printf("Error registering MD5.\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1598 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1599 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1600
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1601 /* get the index of the hash */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1602 idx = find_hash("md5");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1603
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1604 /* call the hash */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1605 len = sizeof(out);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1606 if ((err = hash_memory(idx, "hello world", 11, out, &len)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1607 printf("Error hashing data: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1608 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1609 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1610 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1611 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1612 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1613 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1614
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1615 The following hashes are provided as of this release:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1616 \index{Hash descriptor table}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1617 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1618 \begin{tabular}{|c|c|c|}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1619 \hline Name & Descriptor Name & Size of Message Digest (bytes) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1620 \hline WHIRLPOOL & whirlpool\_desc & 64 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1621 \hline SHA-512 & sha512\_desc & 64 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1622 \hline SHA-384 & sha384\_desc & 48 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1623 \hline SHA-256 & sha256\_desc & 32 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1624 \hline SHA-224 & sha224\_desc & 28 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1625 \hline TIGER-192 & tiger\_desc & 24 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1626 \hline SHA-1 & sha1\_desc & 20 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1627 \hline RIPEMD-160 & rmd160\_desc & 20 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1628 \hline RIPEMD-128 & rmd128\_desc & 16 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1629 \hline MD5 & md5\_desc & 16 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1630 \hline MD4 & md4\_desc & 16 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1631 \hline MD2 & md2\_desc & 16 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1632 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1633 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1634 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1635
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1637 work exactly like those of the cipher registration code. The functions are:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1638 \index{register\_hash()} \index{unregister\_hash()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1639 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1640 int register_hash(const struct _hash_descriptor *hash);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1641 int unregister_hash(const struct _hash_descriptor *hash);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1642 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1643
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1644 \section{Cipher Hash Construction}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1645 \index{Cipher Hash Construction}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1648 particular this allows a cryptosystem to be designed using very few moving parts.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1649
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1653 via the chc\_register() function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1654
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1655 \index{chc\_register()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1656 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1657 int chc_register(int cipher);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1658 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1659
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1663
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1664 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1665 \item The cipher must have a block size greater than 64--bits.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1666 \item The cipher must allow an input key the size of the block size.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1667 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1668
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1669 Example of using CHC with the AES block cipher.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1670
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1671 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1672 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1673 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1674 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1675 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1676
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1677 /* register cipher and hash */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1678 if (register_cipher(&aes_enc_desc) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1679 printf("Could not register cipher\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1680 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1681 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1682 if (register_hash(&chc_desc) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1683 printf("Could not register hash\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1684 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1685 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1686
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1687 /* start chc with AES */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1688 if ((err = chc_register(find_cipher("aes"))) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1689 printf("Error binding AES to CHC: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1690 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1691
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1692 /* now you can use chc_hash in any LTC function [aside from pkcs...] */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1693 /* ... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1694 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1695
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1696
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1697 \section{Notice}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1700 (e.g. Yarrow).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1701
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1703 for all purposes you would normally use a hash for.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1704
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1705 \chapter{Message Authentication Codes}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1706 \section{HMAC Protocol}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1710 eavesdropper will not be able to verify the authenticity of a message.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1711
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1714 chars. The initialization routine is:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1715 \index{hmac\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1716 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1717 int hmac_init(hmac_state *hmac, int hash,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1718 const unsigned char *key, unsigned long keylen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1719 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1723 \index{hmac\_process()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1724 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1725 int hmac_process(hmac_state *hmac,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1726 const unsigned char *in, unsigned long inlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1727 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1731 \index{hmac\_done()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1732 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1733 int hmac_done(hmac_state *hmac,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1734 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1735 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1740
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1743 calling the three step process yourself.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1744
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1745 \index{hmac\_memory()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1746 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1747 int hmac_memory(int hash,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1748 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1749 const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1750 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1751 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1756 \index{hmac\_file()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1757 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1758 int hmac_file(int hash, const char *fname,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1759 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1760 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1761 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1764 result should be stored.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1765
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1766 To test if the HMAC code is working there is the following function:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1767 \index{hmac\_test()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1768 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1769 int hmac_test(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1770 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1772 HMAC system is given below.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1773
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1774 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1775 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1776 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1777 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1778 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1779 int idx, err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1780 hmac_state hmac;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1781 unsigned char key[16], dst[MAXBLOCKSIZE];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1782 unsigned long dstlen;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1783
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1784 /* register SHA-1 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1785 if (register_hash(&sha1_desc) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1786 printf("Error registering SHA1\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1787 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1788 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1789
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1790 /* get index of SHA1 in hash descriptor table */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1791 idx = find_hash("sha1");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1792
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1793 /* we would make up our symmetric key in "key[]" here */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1794
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1795 /* start the HMAC */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1796 if ((err = hmac_init(&hmac, idx, key, 16)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1797 printf("Error setting up hmac: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1798 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1799 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1800
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1801 /* process a few octets */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1802 if((err = hmac_process(&hmac, "hello", 5) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1803 printf("Error processing hmac: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1804 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1805 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1806
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1807 /* get result (presumably to use it somehow...) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1808 dstlen = sizeof(dst);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1809 if ((err = hmac_done(&hmac, dst, &dstlen)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1810 printf("Error finishing hmac: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1811 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1812 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1813 printf("The hmac is %lu bytes long\n", dstlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1814
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1815 /* return */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1816 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1817 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1818 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1819 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1820
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1821 \section{OMAC Support}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1825
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1826 To start an OMAC state you call
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1827 \index{omac\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1828 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1829 int omac_init(omac_state *omac, int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1830 const unsigned char *key, unsigned long keylen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1831 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1834 wish to use. ``key'' and ``keylen'' are the keys used to authenticate the data.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1835
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1836 To send data through the algorithm call
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1837 \index{omac\_process()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1838 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1839 int omac_process(omac_state *state,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1840 const unsigned char *in, unsigned long inlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1841 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1844
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1845 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1846 omac_process(&mystate, "hello", 5);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1847 omac_process(&mystate, " world", 6);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1848 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1849
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1850 Would produce the same result as,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1851
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1852 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1853 omac_process(&mystate, "hello world", 11);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1854 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1855
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1857
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1858 \index{omac\_done()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1859 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1860 int omac_done(omac_state *state,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1861 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1862 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1867 size to show how many bytes were actually used.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1868
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1870 following function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1871
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1872 \index{omac\_memory()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1873 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1874 int omac_memory(int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1875 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1876 const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1877 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1878 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1881 rules as omac\_done.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1882
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1883 To OMAC a file use
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1884 \index{omac\_file()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1885 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1886 int omac_file(int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1887 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1888 const char *filename,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1889 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1890 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1891
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1894 the same rules as omac\_done.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1895
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1896 To test if the OMAC code is working there is the following function:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1897 \index{omac\_test()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1898 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1899 int omac_test(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1900 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1902 OMAC system is given below.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1903
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1904 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1905 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1906 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1907 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1908 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1909 int idx, err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1910 omac_state omac;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1911 unsigned char key[16], dst[MAXBLOCKSIZE];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1912 unsigned long dstlen;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1913
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1914 /* register Rijndael */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1915 if (register_cipher(&rijndael_desc) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1916 printf("Error registering Rijndael\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1917 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1918 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1919
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1920 /* get index of Rijndael in cipher descriptor table */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1921 idx = find_cipher("rijndael");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1922
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1923 /* we would make up our symmetric key in "key[]" here */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1924
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1925 /* start the OMAC */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1926 if ((err = omac_init(&omac, idx, key, 16)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1927 printf("Error setting up omac: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1928 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1929 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1930
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1931 /* process a few octets */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1932 if((err = omac_process(&omac, "hello", 5) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1933 printf("Error processing omac: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1934 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1935 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1936
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1937 /* get result (presumably to use it somehow...) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1938 dstlen = sizeof(dst);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1939 if ((err = omac_done(&omac, dst, &dstlen)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1940 printf("Error finishing omac: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1941 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1942 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1943 printf("The omac is %lu bytes long\n", dstlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1944
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1945 /* return */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1946 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1947 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1948 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1949 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1950
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1951 \section{PMAC Support}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1954 API as the provided OMAC code.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1955
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1956 A PMAC state is initialized with the following.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1957
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1958 \index{pmac\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1959 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1960 int pmac_init(pmac_state *pmac, int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1961 const unsigned char *key, unsigned long keylen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1962 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1964 must have a 64 or 128 bit block size (e.x. AES).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1965
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1966 To MAC data simply send it through the process function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1967
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1968 \index{pmac\_process()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1969 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1970 int pmac_process(pmac_state *state,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1971 const unsigned char *in, unsigned long inlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1972 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1974 data. For example,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1975
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1976 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1977 pmac_process(&mystate, "hello", 5);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1978 pmac_process(&mystate, " world", 6);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1979 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1980
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1981 Would produce the same result as,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1982
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1983 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1984 pmac_process(&mystate, "hello world", 11);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1985 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1986
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1988
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1989 \index{pmac\_done()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1990 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1991 int pmac_done(pmac_state *state,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1992 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1993 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1996
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1998 following function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1999
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2000 \index{pmac\_memory()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2001 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2002 int pmac_memory(int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2003 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2004 const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2005 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2006 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2009 rules as omac\_done.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2010
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2011 To PMAC a file use
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2012 \index{pmac\_file()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2013 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2014 int pmac_file(int cipher,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2015 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2016 const char *filename,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2017 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2018 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2019
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2022 the same rules as omac\_done.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2023
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2024 To test if the PMAC code is working there is the following function:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2025 \index{pmac\_test()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2026 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2027 int pmac_test(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2028 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2030
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2031 \section{Pelican MAC}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2034 as it calls AES directly.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2035
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2036 \index{pelican\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2037 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2038 int pelican_init(pelican_state *pelmac, const unsigned char *key, unsigned long keylen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2039 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2041
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2042 \index{pelican\_process()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2043 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2044 int pelican_process(pelican_state *pelmac, const unsigned char *in, unsigned long inlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2045 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2048 an entire message.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2049
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2050 \index{pelican\_done()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2051 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2052 int pelican_done(pelican_state *pelmac, unsigned char *out);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2053 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2054 This terminates a Pelican MAC and writes the 16--octet tag to ``out''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2055
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2056 \subsection{Example}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2057
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2058 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2059 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2060 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2061 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2062 pelican_state pelstate;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2063 unsigned char key[32], tag[16];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2064 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2065
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2066 /* somehow initialize a key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2067
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2068 /* initialize pelican mac */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2069 if ((err = pelican_init(&pelstate, /* the state */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2070 key, /* user key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2071 32 /* key length in octets */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2072 )) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2073 printf("Error initializing Pelican: %s", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2074 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2075 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2076
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2077 /* MAC some data */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2078 if ((err = pelican_process(&pelstate, /* the state */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2079 "hello world", /* data to mac */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2080 11 /* length of data */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2081 )) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2082 printf("Error processing Pelican: %s", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2083 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2084 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2085
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2086 /* Terminate the MAC */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2087 if ((err = pelican_done(&pelstate, /* the state */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2088 tag /* where to store the tag */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2089 )) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2090 printf("Error terminating Pelican: %s", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2091 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2092 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2093
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2094 /* tag[0..15] has the MAC output now */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2095
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2096 return EXIT_SUCCESS;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2097 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2098 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2099
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2100
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2101 \chapter{Pseudo-Random Number Generators}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2102 \section{Core Functions}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2106 \index{PRNG start}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2107 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2108 int XXX_start(prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2109 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2110
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2113 \index{PRNG add\_entropy}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2114 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2115 int XXX_add_entropy(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2116 prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2117 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2118
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2120 function to put the entropy into action.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2121 \index{PRNG ready}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2122 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2123 int XXX_ready(prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2124 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2125
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2127 \index{PRNG read}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2128 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2129 unsigned long XXX_read(unsigned char *out, unsigned long outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2130 prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2131 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2132
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2134 the following.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2135
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2136 \index{PRNG done}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2137 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2138 void XXX_done(prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2139 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2140
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2142 so that you can later resume the PRNG call the following.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2143
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2144 \index{PRNG export}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2145 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2146 int XXX_export(unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2147 prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2148 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2149
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2153
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2154 \index{PRNG import}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2155 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2156 int XXX_import(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2157 prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2158 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2159
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2162 by the corresponding export function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2163
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2166 specifically equal the 8 bytes you generated previously.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2167
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2168 When a program is first executed the normal course of operation is
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2169
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2170 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2172 \item Start, use your entropy via add\_entropy and ready the PRNG yourself.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2173 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2174
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2179 being given a chance to exit properly.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2180
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2182 there is less pressure to do so.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2183
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2184 To test a PRNG for operational conformity call the following functions.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2185
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2186 \index{PRNG test}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2187 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2188 int XXX_test(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2189 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2190
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2191 This will return \textbf{CRYPT\_OK} if PRNG is operating properly.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2192
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2193 \subsection{Remarks}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2194
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2199
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2200 \subsection{Example}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2201
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2203 {\bf NOT} secure since the entropy added is not random.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2204
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2205 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2206 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2207 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2208 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2209 prng_state prng;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2210 unsigned char buf[10];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2211 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2212
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2213 /* start it */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2214 if ((err = yarrow_start(&prng)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2215 printf("Start error: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2216 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2217 /* add entropy */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2218 if ((err = yarrow_add_entropy("hello world", 11, &prng)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2219 printf("Add_entropy error: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2220 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2221 /* ready and read */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2222 if ((err = yarrow_ready(&prng)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2223 printf("Ready error: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2224 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2225 printf("Read %lu bytes from yarrow\n", yarrow_read(buf, 10, &prng));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2226 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2227 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2228 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2229
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2230 \section{PRNG Descriptors}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2231 \index{PRNG Descriptor}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2233 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2234 struct _prng_descriptor {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2235 char *name;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2236 int export_size; /* size in bytes of exported state */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2237 int (*start) (prng_state *);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2238 int (*add_entropy)(const unsigned char *, unsigned long, prng_state *);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2239 int (*ready) (prng_state *);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2240 unsigned long (*read)(unsigned char *, unsigned long len, prng_state *);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2241 void (*done)(prng_state *);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2242 int (*export)(unsigned char *, unsigned long *, prng_state *);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2243 int (*import)(const unsigned char *, unsigned long, prng_state *);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2244 int (*test)(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2245 };
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2246 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2247
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2249 the position in the prng\_descriptor array.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2250
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2252 exactly as those for the cipher registry functions. They are:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2253 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2254 int register_prng(const struct _prng_descriptor *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2255 int unregister_prng(const struct _prng_descriptor *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2256 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2257
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2258 \subsection{PRNGs Provided}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2259 \begin{figure}[here]
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2260 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2261 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2262 \begin{tabular}{|c|c|l|}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2263 \hline \textbf{Name} & \textbf{Descriptor} & \textbf{Usage} \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2264 \hline Yarrow & yarrow\_desc & Fast short-term PRNG \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2265 \hline Fortuna & fortuna\_desc & Fast long-term PRNG (recommended) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2266 \hline RC4 & rc4\_desc & Stream Cipher \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2267 \hline SOBER-128 & sober128\_desc & Stream Cipher (also very fast PRNG) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2268 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2269 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2270 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2271 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2272 \caption{List of Provided PRNGs}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2273 \end{figure}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2274
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2275 \subsubsection{Yarrow}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2276 Yarrow is fast PRNG meant to collect an unspecified amount of entropy from sources
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2277 (keyboard, mouse, interrupts, etc) and produce an unbounded string of random bytes.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2278
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2280 should use Fortuna instead.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2281
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2282 \subsubsection{Fortuna}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2283
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2287 providing more security.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2288
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2292 it has been fixed to those choices.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2293
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2299
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2300 \subsubsection{RC4}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2301
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2304 add\_entropy().
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2305
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2307 manner you can use rc4\_read() as an encrypt (and decrypt) function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2308
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2310 simply that faster alternatives exist.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2311
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2312 \subsubsection{SOBER-128}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2313
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2316
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2320 key and not re--use the same key material.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2321
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2324 that is a multiple of four bytes.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2325
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2327 sober128\_read() as an encrypt (and decrypt) function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2328
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2331 simulations which need a high quality (and fast) stream of bytes.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2332
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2333 \subsubsection{Example Usage}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2334 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2335 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2336 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2337 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2338 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2339 prng_state prng;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2340 unsigned char buf[32];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2341 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2342
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2343 if ((err = rc4_start(&prng)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2344 printf("RC4 init error: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2345 exit(-1);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2346 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2347
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2348 /* use ``key'' as the key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2349 if ((err = rc4_add_entropy("key", 3, &prng)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2350 printf("RC4 add entropy error: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2351 exit(-1);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2352 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2353
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2354 /* setup RC4 for use */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2355 if ((err = rc4_ready(&prng)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2356 printf("RC4 ready error: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2357 exit(-1);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2358 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2359
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2360 /* encrypt buffer */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2361 strcpy(buf,"hello world");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2362 if (rc4_read(buf, 11, &prng) != 11) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2363 printf("RC4 read error\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2364 exit(-1);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2365 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2366 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2367 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2368 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2369 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2370 To decrypt you have to do the exact same steps.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2371
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2372 \section{The Secure RNG}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2373 \index{Secure RNG}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2377 entropy needed to seed the PRNG a hard task.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2378
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2379 There is one small function that may help on certain platforms:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2380 \index{rng\_get\_bytes()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2381 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2382 unsigned long rng_get_bytes(unsigned char *buf, unsigned long len,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2383 void (*callback)(void));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2384 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2385
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.}.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2393 \index{rng\_make\_prng()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2394 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2395 int rng_make_prng(int bits, int wprng, prng_state *prng,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2396 void (*callback)(void));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2397 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2401
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2402 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2403 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2404 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2405 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2406 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2407 ecc_key mykey;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2408 prng_state prng;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2409 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2410
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2411 /* register yarrow */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2412 if (register_prng(&yarrow_desc) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2413 printf("Error registering Yarrow\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2414 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2415 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2416
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2417 /* setup the PRNG */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2418 if ((err = rng_make_prng(128, find_prng("yarrow"), &prng, NULL)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2419 printf("Error setting up PRNG, %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2420 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2421 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2422
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2423 /* make a 192-bit ECC key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2424 if ((err = ecc_make_key(&prng, find_prng("yarrow"), 24, &mykey)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2425 printf("Error making key: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2426 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2427 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2428 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2429 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2430 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2431 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2432
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2433 \subsection{The Secure PRNG Interface}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2437 the previous example using this PRNG.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2438
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2439 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2440 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2441 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2442 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2443 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2444 ecc_key mykey;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2445 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2446
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2447 /* register SPRNG */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2448 if (register_prng(&sprng_desc) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2449 printf("Error registering SPRNG\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2450 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2451 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2452
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2453 /* make a 192-bit ECC key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2454 if ((err = ecc_make_key(NULL, find_prng("sprng"), 24, &mykey)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2455 printf("Error making key: %s\n", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2456 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2457 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2458 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2459 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2460 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2461 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2462
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2463
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2464
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2465 \chapter{RSA Public Key Cryptography}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2466
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2467 \section{Introduction}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2469 padding algorithms for encryption and signatures. The standard includes the ``v2.1'' algorithms.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2471 respectively.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2472
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2473 \section{PKCS \#1 Encryption}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2474
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2477
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2478 \subsection{OAEP Encoding}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2479
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2480 \index{pkcs\_1\_oaep\_encode()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2481 \begin{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2482 int pkcs_1_oaep_encode(const unsigned char *msg, unsigned long msglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2483 const unsigned char *lparam, unsigned long lparamlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2484 unsigned long modulus_bitlen, prng_state *prng,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2485 int prng_idx, int hash_idx,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2486 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2487 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2488
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2491 ``lparam'' can be set to \textbf{NULL}.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2492
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2497 The padded message is stored in ``out'' along with the length in ``outlen''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2498
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2501
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2503 rsa\_exptmod() to encrypt it.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2504
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2505 \subsection{OAEP Decoding}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2506
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2507 \index{pkcs\_1\_oaep\_decode()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2508 \begin{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2509 int pkcs_1_oaep_decode(const unsigned char *msg, unsigned long msglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2510 const unsigned char *lparam, unsigned long lparamlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2511 unsigned long modulus_bitlen, int hash_idx,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2512 unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2513 int *res);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2514 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2515
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2520 during encoding.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2521
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2524 it returns an error code.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2525
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2526 \section{PKCS \#1 Digital Signatures}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2527
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2528 \subsection{PSS Encoding}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2530
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2531 \index{pkcs\_1\_pss\_encode()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2532 \begin{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2533 int pkcs_1_pss_encode(const unsigned char *msghash, unsigned long msghashlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2534 unsigned long saltlen, prng_state *prng,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2535 int prng_idx, int hash_idx,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2536 unsigned long modulus_bitlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2537 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2538 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2539
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2543 number generator information required for the salt.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2544
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2547
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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().
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2549
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2550 \subsection{PSS Decoding}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2551
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2552 To decode a PSS encoded signature block you have to use the following.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2553
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2554 \index{pkcs\_1\_pss\_decode()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2555 \begin{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2556 int pkcs_1_pss_decode(const unsigned char *msghash, unsigned long msghashlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2557 const unsigned char *sig, unsigned long siglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2558 unsigned long saltlen, int hash_idx,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2559 unsigned long modulus_bitlen, int *res);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2560 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2564
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2566
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2567 \section{RSA Operations}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2568 \subsection{Background}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2569
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2572 not strictly equivalent.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2573
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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)$
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2578 often simply denoted as $de \equiv 1\mbox{ }(\mbox{mod }\phi(N))$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2579
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2584 can sign a message by ``decrypting'' it. Others can verify it by ``encrypting'' it.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2585
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2590 designed for fast exponentiation (requires 16 squarings and one multiplication).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2591
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2597
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2598 \subsection{RSA Key Generation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2599
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2601 \index{rsa\_make\_key()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2602 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2603 int rsa_make_key(prng_state *prng,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2604 int wprng, int size,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2605 long e, rsa_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2606 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2607
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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}).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2612
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2615 free the ram allocated itself.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2616
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2617 \index{PK\_PRIVATE} \index{PK\_PUBLIC}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2622
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2623 \subsection{RSA Exponentiation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2624
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2625 To do raw work with the RSA function call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2626 \index{rsa\_exptmod()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2627 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2628 int rsa_exptmod(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2629 unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2630 int which, prng_state *prng, int prng_idx,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2631 rsa_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2632 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2636
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2638 interoprate with PKCS \#1 padding functions properly.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2639
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2640 \subsection{RSA Key Encryption}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2642 To facilitate encrypting short keys the following functions have been provided.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2643
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2644 \index{rsa\_encrypt\_key()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2645 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2646 int rsa_encrypt_key(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2647 unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2648 const unsigned char *lparam, unsigned long lparamlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2649 prng_state *prng, int prng_idx, int hash_idx, rsa_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2650 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2653 to pkcs\_1\_oaep\_encode().
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2654
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2655 \index{rsa\_decrypt\_key()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2656 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2657 int rsa_decrypt_key(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2658 unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2659 const unsigned char *lparam, unsigned long lparamlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2660 int hash_idx, int *stat,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2661 rsa_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2662 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2665 to pkcs\_1\_oaep\_decode().
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2666
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2668
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2669 \subsection{RSA Hash Signatures}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2671 process the following functions have been provided.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2672
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2673 \index{rsa\_sign\_hash()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2674 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2675 int rsa_sign_hash(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2676 unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2677 prng_state *prng, int prng_idx,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2678 int hash_idx, unsigned long saltlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2679 rsa_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2680 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2681
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2683 the output is stored in ``out'' of length ``outlen''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2684
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2685
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2686 \index{rsa\_verify\_hash()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2687 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2688 int rsa_verify_hash(const unsigned char *sig, unsigned long siglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2689 const unsigned char *msghash, unsigned long msghashlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2690 int hash_idx, unsigned long saltlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2691 int *stat, rsa_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2692 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2693
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2695 and the extracted hash is compared against the message hash ``msghash'' of length ``msghashlen''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2696
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2699 to $1$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2700
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2701 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2702 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2703 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2704 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2705 int err, hash_idx, prng_idx, res;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2706 unsigned long l1, l2;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2707 unsigned char pt[16], pt2[16], out[1024];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2708 rsa_key key;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2709
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2710 /* register prng/hash */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2711 if (register_prng(&sprng_desc) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2712 printf("Error registering sprng");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2713 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2714 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2715
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2716 if (register_hash(&sha1_desc) == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2717 printf("Error registering sha1");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2718 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2719 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2720 hash_idx = find_hash("sha1");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2721 prng_idx = find_prng("sprng");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2722
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2723 /* make an RSA-1024 key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2724 if ((err = rsa_make_key(NULL, /* PRNG state */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2725 prng_idx, /* PRNG idx */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2726 1024/8, /* 1024-bit key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2727 65537, /* we like e=65537 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2728 &key) /* where to store the key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2729 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2730 printf("rsa_make_key %s", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2731 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2732 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2733
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2734 /* fill in pt[] with a key we want to send ... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2735 l1 = sizeof(out);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2736 if ((err = rsa_encrypt_key(pt, /* data we wish to encrypt */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2737 16, /* data is 16 bytes long */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2738 out, /* where to store ciphertext */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2739 &l1, /* length of ciphertext */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2740 "TestApp", /* our lparam for this program */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2741 7, /* lparam is 7 bytes long */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2742 NULL, /* PRNG state */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2743 prng_idx, /* prng idx */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2744 hash_idx, /* hash idx */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2745 &key) /* our RSA key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2746 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2747 printf("rsa_encrypt_key %s", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2748 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2749 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2750
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2751 /* now let's decrypt the encrypted key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2752 l2 = sizeof(pt2);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2753 if ((err = rsa_decrypt_key(out, /* encrypted data */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2754 l1, /* length of ciphertext */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2755 pt2, /* where to put plaintext */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2756 &l2, /* plaintext length */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2757 "TestApp", /* lparam for this program */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2758 7, /* lparam is 7 bytes long */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2759 hash_idx, /* hash idx */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2760 &res, /* validity of data */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2761 &key) /* our RSA key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2762 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2763 printf("rsa_decrypt_key %s", error_to_string(err));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2764 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2765 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2766 /* if all went well pt == pt2, l2 == 16, res == 1 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2767 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2768 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2769
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2770
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2771 \chapter{Diffie-Hellman Key Exchange}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2772
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2773 \section{Background}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2774
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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)$
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2777 generates a large sub-group of prime order (for unique values of $x$).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2778
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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)$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2783
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2788 symmetric cipher.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2789
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2794
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2798
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2799 \section{Core Functions}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2800
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2804 make a Diffie-Hellman private key pair:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2805 \index{dh\_make\_key()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2806 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2807 int dh_make_key(prng_state *prng, int wprng,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2808 int keysize, dh_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2809 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2818 hard.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2819
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2821 over communication mediums.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2822
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2823 \index{dh\_export()} \index{dh\_import()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2824 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2825 int dh_export(unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2826 int type, dh_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2827
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2828 int dh_import(const unsigned char *in, unsigned long inlen, dh_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2829 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2830
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2833 ``dh\_key'' using:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2834 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2835 void dh_free(dh_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2836 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2838 with the other user using:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2839 \index{dh\_shared\_secret()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2840 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2841 int dh_shared_secret(dh_key *private_key,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2842 dh_key *public_key,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2843 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2844 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2845
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2849 key:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2850 \index{dh\_get\_size()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2851 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2852 int dh_get_size(dh_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2853 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2854 This returns the size in bytes of the modulus chosen for that key.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2855
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2856 \subsection{Remarks on Usage}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.}:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2859 \newpage
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2860 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2861 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2862 int establish_secure_socket(int sock, int mode, unsigned char *key,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2863 prng_state *prng, int wprng)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2864 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2865 unsigned char buf[4096], buf2[4096];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2866 unsigned long x, len;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2867 int res, err, inlen;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2868 dh_key mykey, theirkey;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2869
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2870 /* make up our private key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2871 if ((err = dh_make_key(prng, wprng, 128, &mykey)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2872 return err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2873 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2874
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2875 /* export our key as public */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2876 x = sizeof(buf);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2877 if ((err = dh_export(buf, &x, PK_PUBLIC, &mykey)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2878 res = err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2879 goto done2;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2880 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2881
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2882 if (mode == 0) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2883 /* mode 0 so we send first */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2884 if (send(sock, buf, x, 0) != x) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2885 res = CRYPT_ERROR;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2886 goto done2;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2887 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2888
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2889 /* get their key */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2890 if ((inlen = recv(sock, buf2, sizeof(buf2), 0)) <= 0) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2891 res = CRYPT_ERROR;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2892 goto done2;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2893 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2894 } else {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2895 /* mode >0 so we send second */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2896 if ((inlen = recv(sock, buf2, sizeof(buf2), 0)) <= 0) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2897 res = CRYPT_ERROR;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2898 goto done2;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2899 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2900
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2901 if (send(sock, buf, x, 0) != x) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2902 res = CRYPT_ERROR;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2903 goto done2;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2904 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2905 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2906
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2907 if ((err = dh_import(buf2, inlen, &theirkey)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2908 res = err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2909 goto done2;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2910 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2911
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2912 /* make shared secret */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2913 x = sizeof(buf);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2914 if ((err = dh_shared_secret(&mykey, &theirkey, buf, &x)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2915 res = err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2916 goto done;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2917 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2918
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2919 /* hash it */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2920 len = 16; /* default is MD5 so "key" must be at least 16 bytes long */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2921 if ((err = hash_memory(find_hash("md5"), buf, x, key, &len)) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2922 res = err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2923 goto done;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2924 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2925
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2926 /* clean up and return */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2927 res = CRYPT_OK;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2928 done:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2929 dh_free(&theirkey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2930 done2:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2931 dh_free(&mykey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2932 zeromem(buf, sizeof(buf));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2933 zeromem(buf2, sizeof(buf2));
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2934 return res;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2935 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2936 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2937 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2938 \newpage
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2939 \subsection{Remarks on The Snippet}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2941 passed to ``establish\_secure\_socket()''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2942
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2943 \section{Other Diffie-Hellman Functions}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2945 available:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2946 \index{dh\_test()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2947 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2948 int dh_test(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2949 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2950
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2952 function:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2953 \index{dh\_sizes()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2954 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2955 void dh_sizes(int *low, int *high);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2956 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2957 Which stores the smallest and largest key sizes support into the two variables.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2958
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2959 \section{DH Packet}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2961 algorithms.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2962 \index{dh\_encrypt\_key()} \index{dh\_decrypt\_key()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2963 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2964 int dh_encrypt_key(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2965 unsigned char *out, unsigned long *len,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2966 prng_state *prng, int wprng, int hash,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2967 dh_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2968
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2969 int dh_decrypt_key(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2970 unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2971 dh_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2972 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2976 as the symmetric key you are trying to share.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2977
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2979 \index{dh\_sign\_hash()} \index{dh\_verify\_hash()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2980 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2981 int dh_sign_hash(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2982 unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2983 prng_state *prng, int wprng, dh_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2984
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2985 int dh_verify_hash(const unsigned char *sig, unsigned long siglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2986 const unsigned char *hash, unsigned long hashlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2987 int *stat, dh_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2988 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2989
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2992 to non-zero if the signature passes or zero if it fails.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2993
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2994 \chapter{Elliptic Curve Cryptography}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2995
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2996 \section{Background}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3002
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3003 The curves in this library are taken from the following website:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3004 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3005 http://csrc.nist.gov/cryptval/dss.htm
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3006 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3007
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3009 \begin{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3010 y^2 = x^3 - 3x + b\mbox{ }(\mbox{mod }p)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3011 \end{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3012
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3016 than or equal to 256-bits is sufficient for long term security.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3017
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3018 \section{Key Format}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3021
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3022 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3023 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3024 ECCPublicKey ::= SEQUENCE {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3025 flags BIT STRING(1), -- public/private flag (always zero),
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3026 keySize INTEGER, -- Curve size (in bits) divided by eight
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3027 -- and rounded down, e.g. 521 => 65
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3028 pubkey.x INTEGER, -- The X co-ordinate of the public key point
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3029 pubkey.y INTEGER, -- The Y co-ordinate of the public key point
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3030 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3031
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3032 ECCPrivateKey ::= SEQUENCE {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3033 flags BIT STRING(1), -- public/private flag (always one),
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3034 keySize INTEGER, -- Curve size (in bits) divided by eight
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3035 -- and rounded down, e.g. 521 => 65
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3036 pubkey.x INTEGER, -- The X co-ordinate of the public key point
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3037 pubkey.y INTEGER, -- The Y co-ordinate of the public key point
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3038 secret.k INTEGER, -- The secret key scalar
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3039 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3040 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3041 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3042
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3043 The first flags bit denotes whether the key is public (zero) or private (one).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3044
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3045 \section{Core Functions}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3046
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3048 \index{ecc\_make\_key()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3049 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3050 int ecc_make_key(prng_state *prng, int wprng,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3051 int keysize, ecc_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3052 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3053
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3057 To free the ram allocated by a key call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3058 \index{ecc\_free()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3059 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3060 void ecc_free(ecc_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3061 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3062
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3063 To import and export a key there are:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3064 \index{ecc\_export()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3065 \index{ecc\_import()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3066 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3067 int ecc_export(unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3068 int type, ecc_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3069
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3070 int ecc_import(const unsigned char *in, unsigned long inlen, ecc_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3071 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3073 with:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3074 \index{ecc\_shared\_secret()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3075 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3076 int ecc_shared_secret(ecc_key *private_key,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3077 ecc_key *public_key,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3078 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3079 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3084 of a key.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3085 \index{ecc\_get\_size()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3086 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3087 int ecc_get_size(ecc_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3088 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3089
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3091 \index{ecc\_test()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3092 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3093 int ecc_test(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3094 void ecc_sizes(int *low, int *high);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3095 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3096 Which both work like their DH counterparts.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3097
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3098 \section{ECC Packet}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3100 algorithms.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3101
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3102 \index{ecc\_encrypt\_key()} \index{ecc\_decrypt\_key()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3103 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3104 int ecc_encrypt_key(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3105 unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3106 prng_state *prng, int wprng, int hash,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3107 ecc_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3108
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3109 int ecc_decrypt_key(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3110 unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3111 ecc_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3112 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3113
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3117 as the symmetric key you are trying to share.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3118
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3119 \subsection{Encrypt Packet Format}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3120
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3121 The packet format for the encrypted keys is the following ASN.1 SEQUENCE:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3122
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3123 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3124 ECCEncrypt ::= SEQUENCE {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3125 hashID OBJECT IDENTIFIER, -- OID of hash used
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3126 pubkey OCTET STRING , -- Encapsulated ECCPublicKey (see above)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3127 skey OCTET STRING -- xor of plaintext and "hash of shared secret"
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3128 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3129 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3130
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3131 There are also functions to sign and verify the hash of a message.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3132 \index{ecc\_sign\_hash()} \index{ecc\_verify\_hash()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3133 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3134 int ecc_sign_hash(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3135 unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3136 prng_state *prng, int wprng, ecc_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3137
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3138 int ecc_verify_hash(const unsigned char *sig, unsigned long siglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3139 const unsigned char *hash, unsigned long hashlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3140 int *stat, ecc_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3141 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3142
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3145 to non-zero if the signature passes or zero if it fails.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3146
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3147 \subsection{Signature Format}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3149
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3150 \section{ECC Keysizes}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3154 you have 192-bits of security.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3155
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3157 signatures.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3158
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3159 \chapter{Digital Signature Algorithm}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3160 \section{Introduction}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3165
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3167 decryption routines are provided.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3168
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3169 \section{Key Format}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3171 now so that others can interoperate with this library.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3172
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3173 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3174 DSAPublicKey ::= SEQUENCE {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3175 publicFlags BIT STRING(1), -- must be 0
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3176 g INTEGER , -- base generator, check that g^q mod p == 1
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3177 -- and that 1 < g < p - 1
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3178 p INTEGER , -- prime modulus
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3179 q INTEGER , -- order of sub-group (must be prime)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3180 y INTEGER , -- public key, specifically, g^x mod p,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3181 -- check that y^q mod p == 1
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3182 -- and that 1 < y < p - 1
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3183 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3184
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3185 DSAPrivateKey ::= SEQUENCE {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3186 publicFlags BIT STRING(1), -- must be 1
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3187 g INTEGER , -- base generator, check that g^q mod p == 1
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3188 -- and that 1 < g < p - 1
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3189 p INTEGER , -- prime modulus
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3190 q INTEGER , -- order of sub-group (must be prime)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3191 y INTEGER , -- public key, specifically, g^x mod p,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3192 -- check that y^q mod p == 1
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3193 -- and that 1 < y < p - 1
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3194 x INTEGER -- private key
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3195 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3196 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3197
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3199 to work with.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3200
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3201 \section{Key Generation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3202 To make a DSA key you must call the following function
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3203 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3204 int dsa_make_key(prng_state *prng, int wprng,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3205 int group_size, int modulus_size,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3206 dsa_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3207 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3212
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3213 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3214 \begin{tabular}{|c|c|c|}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3215 \hline \textbf{Bits of Security} & \textbf{group\_size} & \textbf{modulus\_size} \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3216 \hline 80 & 20 & 128 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3217 \hline 120 & 30 & 256 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3218 \hline 140 & 35 & 384 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3219 \hline 160 & 40 & 512 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3220 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3221 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3222 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3223
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3225 \index{dsa\_free()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3226 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3227 void dsa_free(dsa_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3228 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3229
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3230 \section{Key Verification}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3231 Each DSA key is composed of the following variables.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3232
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3233 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3234 \item $q$ a small prime of magnitude $256^{group\_size}$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3238 \item $x$ a random secret (the secret key) in the range $1 < x < q$
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3239 \item $y = g^x \mbox{ (mod }p\mbox{)}$ the public key.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3240 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3241
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3242 A DSA key is considered valid if it passes all of the following tests.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3243
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3244 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3245 \item $q$ must be prime.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3246 \item $p$ must be prime.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3247 \item $g$ cannot be one of $\lbrace -1, 0, 1 \rbrace$ (modulo $p$).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3248 \item $g$ must be less than $p$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3249 \item $(p-1) \equiv 0 \mbox{ (mod }q\mbox{)}$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3250 \item $g^q \equiv 1 \mbox{ (mod }p\mbox{)}$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3251 \item $1 < y < p - 1$
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3252 \item $y^q \equiv 1 \mbox{ (mod }p\mbox{)}$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3253 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3254
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3260 that $y$ belongs to a multiplicative sub-group of order $q$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3261
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3262 The following function will perform these tests.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3263
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3264 \index{dsa\_verify\_key()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3265 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3266 int dsa_verify_key(dsa_key *key, int *stat);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3267 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3268
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3271
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3272 \section{Signatures}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3273 To generate a DSA signature call the following function
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3274
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3275 \index{dsa\_sign\_hash()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3276 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3277 int dsa_sign_hash(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3278 unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3279 prng_state *prng, int wprng, dsa_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3280 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3281
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3286 To verify a hash created with that function use the following function
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3287
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3288 \index{dsa\_verify\_hash()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3289 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3290 int dsa_verify_hash(const unsigned char *sig, unsigned long siglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3291 const unsigned char *hash, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3292 int *stat, dsa_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3293 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3296
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3297 \section{Import and Export}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3298
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3300 \index{dsa\_export()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3301 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3302 int dsa_export(unsigned char *out, unsigned long *outlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3303 int type,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3304 dsa_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3305 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3309
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3310 To import an exported DSA key use the following function
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3311
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3312 \index{dsa\_import()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3313 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3314 int dsa_import(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3315 dsa_key *key);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3316 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3317
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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()).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3320
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3321 \chapter{Standards Support}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3322 \section{ASN.1 Formats}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3325 format and two functions have been dedicated to encoding and decoding the format.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3326
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3329
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3330 \index{ltc\_asn1\_list structure}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3331 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3332 typedef struct {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3333 int type;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3334 void *data;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3335 unsigned long size;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3336 int used;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3337 } ltc_asn1_list;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3338 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3339
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3343 ``LTC\_SET\_ASN1(list, index, Type, Data, Size)'' has been provided.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3344
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3346
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3347 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3348 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3349 ...
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3350 ltc_asn1_list sequence[3];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3351 unsigned long three=3;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3352
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3353 LTC_SET_ASN1(sequence, 0, LTC_ASN1_IA5_STRING, "hello", 5);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3354 LTC_SET_ASN1(sequence, 1, LTC_ASN1_SHORT_INTEGER, &three, 1);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3355 LTC_SET_ASN1(sequence, 2, LTC_ASN1_NULL, NULL, 0);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3356 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3357 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3358
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3360
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3361 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3362 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3363 ...
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3364 ltc_asn1_list sequence[3];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3365 unsigned long three=3;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3366 int x=0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3367 LTC_SET_ASN1(sequence, x++, LTC_ASN1_IA5_STRING, "hello", 5);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3368 LTC_SET_ASN1(sequence, x++, LTC_ASN1_SHORT_INTEGER, &three, 1);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3369 LTC_SET_ASN1(sequence, x++, LTC_ASN1_NULL, NULL, 0);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3370 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3371 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3372
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3373 \begin{figure}[here]
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3374 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3375 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3376 \begin{tabular}{|l|l|}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3377 \hline \textbf{Definition} & \textbf{ASN.1 Type} \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3378 \hline LTC\_ASN1\_EOL & End of a ASN.1 list structure. \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3379 \hline LTC\_ASN1\_INTEGER & INTEGER (uses mp\_int) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3380 \hline LTC\_ASN1\_SHORT\_INTEGER & INTEGER (32--bit using unsigned long) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3381 \hline LTC\_ASN1\_BIT\_STRING & BIT STRING (one bit per char) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3382 \hline LTC\_ASN1\_OCTET\_STRING & OCTET STRING (one octet per char) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3383 \hline LTC\_ASN1\_NULL & NULL \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3384 \hline LTC\_ASN1\_OBJECT\_IDENTIFIER & OBJECT IDENTIFIER (words are in unsigned long) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3385 \hline LTC\_ASN1\_IA5\_STRING & IA5 STRING (one octet per char) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3386 \hline LTC\_ASN1\_PRINTABLE\_STRING & PRINTABLE STIRNG (one octet per char) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3387 \hline LTC\_ASN1\_UTCTIME & UTCTIME (see ltc\_utctime structure) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3388 \hline LTC\_ASN1\_SEQUENCE & SEQUENCE OF \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3389 \hline LTC\_ASN1\_CHOICE & CHOICE \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3390 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3391 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3392 \caption{List of ASN.1 Supported Types}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3393 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3394 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3395 \end{figure}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3396
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3397 \subsection{SEQUENCE Type}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3399
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3400 \subsubsection{SEUQNECE Encoding}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3402 with the following function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3403
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3404 \index{der\_encode\_sequence()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3405 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3406 int der_encode_sequence(ltc_asn1_list *list, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3407 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3408 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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}.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3411
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3414 the ``data'' pointer is simply a pointer to another \textbf{ltc\_asn1\_list}.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3415
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3416 \subsubsection{SEQUENCE Decoding}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3417
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3418 \index{der\_decode\_sequence()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3419
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3422 units of the respective type has been loaded.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3423
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3424 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3425 int der_decode_sequence(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3426 ltc_asn1_list *list, unsigned long outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3427 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3428
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3431
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3433 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3434 \item BIT STRING
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3435 \item OCTET STRING
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3436 \item OBJECT IDENTIFIER
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3437 \item IA5 STRING
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3438 \item PRINTABLE STRING
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3439 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3440
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3441 \subsubsection{SEQUENCE Length}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3442
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3443 The length of a SEQUENCE can be determined with the following function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3444
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3445 \index{der\_length\_sequence()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3446 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3447 int der_length_sequence(ltc_asn1_list *list, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3448 unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3449 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3450
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3452
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3453 \subsubsection{SEQUENCE Multiple Argument Lists}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3454
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3456
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3457 \index{der\_encode\_sequence\_multi()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3458 \index{der\_decode\_sequence\_multi()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3459
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3460 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3461 int der_encode_sequence_multi(unsigned char *out, unsigned long *outlen, ...);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3462 int der_decode_sequence_multi(const unsigned char *in, unsigned long inlen, ...);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3463 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3464
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3466
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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}.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3469
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3472
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3473 \subsection{ASN.1 INTEGER}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3474
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3475 To encode or decode INTEGER data types use the following functions.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3476
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3477 \index{der\_encode\_integer()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3478 \index{der\_decode\_integer()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3479 \index{der\_length\_integer()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3480 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3481 int der_encode_integer(mp_int *num, unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3482 int der_decode_integer(const unsigned char *in, unsigned long inlen, mp_int *num);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3483 int der_length_integer(mp_int *num, unsigned long *len);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3484 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3485
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3487 an mp\_int to store the value the ``short'' INTEGER functions were made available.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3488
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3489 \index{der\_encode\_short\_integer()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3490 \index{der\_decode\_short\_integer()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3491 \index{der\_length\_short\_integer()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3492 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3493 int der_encode_short_integer(unsigned long num,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3494 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3495
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3496 int der_decode_short_integer(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3497 unsigned long *num);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3498
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3499 int der_length_short_integer(unsigned long num, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3500 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3501
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3503 and short integer functions can encode and decode each others outputs.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3504
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3505 \subsection{ASN.1 BIT STRING}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3506
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3507 \index{der\_encode\_bit\_string()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3508 \index{der\_decode\_bit\_string()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3509 \index{der\_length\_bit\_string()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3510 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3511 int der_encode_bit_string(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3512 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3513
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3514 int der_decode_bit_string(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3515 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3516
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3517 int der_length_bit_string(unsigned long nbits, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3518 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3519
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3521 as a one bit and a zero value a zero bit.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3522
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3523 \subsection{ASN.1 OCTET STRING}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3524
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3525 \index{der\_encode\_octet\_string()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3526 \index{der\_decode\_octet\_string()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3527 \index{der\_length\_octet\_string()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3528 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3529 int der_encode_octet_string(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3530 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3531
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3532 int der_decode_octet_string(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3533 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3534
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3535 int der_length_octet_string(unsigned long noctets, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3536 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3537
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3539
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3540 \subsection{ASN.1 OBJECT IDENTIFIER}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3541
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3542 \index{der\_encode\_object\_identifier()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3543 \index{der\_decode\_object\_identifier()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3544 \index{der\_length\_object\_identifier()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3545 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3546 int der_encode_object_identifier(unsigned long *words, unsigned long nwords,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3547 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3548
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3549 int der_decode_object_identifier(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3550 unsigned long *words, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3551
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3552 int der_length_object_identifier(unsigned long *words, unsigned long nwords,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3553 unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3554 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3555
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3557 $0 \ldots 2^{32} - 1$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3558
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3559 \subsection{ASN.1 IA5 STRING}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3560
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3561 \index{der\_encode\_ia5\_string()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3562 \index{der\_decode\_ia5\_string()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3563 \index{der\_length\_ia5\_string()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3564 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3565 int der_encode_ia5_string(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3566 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3567
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3568 int der_decode_ia5_string(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3569 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3570
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3571 int der_length_ia5_string(const unsigned char *octets, unsigned long noctets,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3572 unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3573 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3574
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3578 that the build platform honours the runtime platforms character conventions.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3579
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3581
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3582 \subsection{ASN.1 PRINTABLE STRING}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3583
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3584 \index{der\_encode\_printable\_string()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3585 \index{der\_decode\_printable\_string()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3586 \index{der\_length\_printable\_string()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3587 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3588 int der_encode_printable_string(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3589 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3590
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3591 int der_decode_printable_string(const unsigned char *in, unsigned long inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3592 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3593
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3594 int der_length_printable_string(const unsigned char *octets, unsigned long noctets,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3595 unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3596 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3597
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3601 that the build platform honours the runtime platforms character conventions.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3602
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3604
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3605 \subsection{ASN.1 UTCTIME}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3606
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3608
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3609 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3610 typedef struct {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3611 unsigned YY, /* year 00--99 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3612 MM, /* month 01--12 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3613 DD, /* day 01--31 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3614 hh, /* hour 00--23 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3615 mm, /* minute 00--59 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3616 ss, /* second 00--59 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3617 off_dir, /* timezone offset direction 0 == +, 1 == - */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3618 off_hh, /* timezone offset hours */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3619 off_mm; /* timezone offset minutes */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3620 } ltc_utctime;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3621 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3622
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3624 will be subtracted.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3625
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3627
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3628 \index{der\_encode\_utctime()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3629 \index{der\_decode\_utctime()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3630 \index{der\_length\_utctime()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3631 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3632 int der_encode_utctime(ltc_utctime *utctime,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3633 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3634
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3635 int der_decode_utctime(const unsigned char *in, unsigned long *inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3636 ltc_utctime *out);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3637
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3638 int der_length_utctime(ltc_utctime *utctime, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3639 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3640
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3643
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3645
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3646 \subsection{ASN.1 CHOICE}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3647
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3651
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3653
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3654 \index{der\_decode\_choice()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3655 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3656 int der_decode_choice(const unsigned char *in, unsigned long *inlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3657 ltc_asn1_list *list, unsigned long outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3658 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3659
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3662 set to non--zero to reflect it was the data type decoded.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3663
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3664 \section{Password Based Cryptography}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3665 \subsection{PKCS \#5}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3666 \index{PKCS \#5}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3670
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3671 \subsection{Algorithm One}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3674 algorithm and produces an output no longer than the output of the hash.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3675
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3676 \index{pkcs\_5\_alg1()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3677 \begin{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3678 int pkcs_5_alg1(const unsigned char *password, unsigned long password_len,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3679 const unsigned char *salt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3680 int iteration_count, int hash_idx,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3681 unsigned char *out, unsigned long *outlen)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3682 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3686
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3689
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3690 \subsection{Algorithm Two}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3691
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3694 from a single password and invokation of this algorithm.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3695
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3696 \index{pkcs\_5\_alg2()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3697 \begin{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3698 int pkcs_5_alg2(const unsigned char *password, unsigned long password_len,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3699 const unsigned char *salt, unsigned long salt_len,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3700 int iteration_count, int hash_idx,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3701 unsigned char *out, unsigned long *outlen)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3702 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3706 ``outlen'' is stored in ``out''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3707
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3708 \begin{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3709 /* demo to show how to make session state material from a password */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3710 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3711 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3712 \{
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3713 unsigned char password[100], salt[100],
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3714 cipher_key[16], cipher_iv[16],
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3715 mac_key[16], outbuf[48];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3716 int err, hash_idx;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3717 unsigned long outlen, password_len, salt_len;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3718
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3719 /* register hash and get it's idx .... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3720
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3721 /* get users password and make up a salt ... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3722
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3723 /* create the material (100 iterations in algorithm) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3724 outlen = sizeof(outbuf);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3725 if ((err = pkcs_5_alg2(password, password_len, salt, salt_len,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3726 100, hash_idx, outbuf, &outlen)) != CRYPT_OK) \{
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3727 /* error handle */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3728 \}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3729
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3730 /* now extract it */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3731 memcpy(cipher_key, outbuf, 16);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3732 memcpy(cipher_iv, outbuf+16, 16);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3733 memcpy(mac_key, outbuf+32, 16);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3734
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3735 /* use material (recall to store the salt in the output) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3736 \}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3737 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3738
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3739 \chapter{Miscellaneous}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3740 \section{Base64 Encoding and Decoding}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3743 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3744 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3745 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3749 original input. After the first four characters is the rest of the message.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3750
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3753 break up the first four characters.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3754
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3755 To encode a binary string in base64 call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3756 \index{base64\_encode()} \index{base64\_decode()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3757 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3758 int base64_encode(const unsigned char *in, unsigned long len,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3759 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3760 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3763 string call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3764 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3765 int base64_decode(const unsigned char *in, unsigned long len,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3766 unsigned char *out, unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3767 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3768
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3769 \section{The Multiple Precision Integer Library (MPI)}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3772 for all uses and is distributed freely.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3773
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3776 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3777 #include <tomcrypt.h> /* tomcrypt.h includes mpi.h automatically */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3778 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3779 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3780 mp_int bignum;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3781
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3782 /* initialize it */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3783 mp_init(&bignum);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3784
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3785 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3786 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3787 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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):
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3790 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3791 mp_clear(&bignum);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3792 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3793
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3794 The functions also have the basic form of one of the following:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3795 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3796 mp_XXX(mp_int *a);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3797 mp_XXX(mp_int *a, mp_int *b, mp_int *c);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3798 mp_XXX(mp_int *a, mp_int *b, mp_int *c, mp_int *d);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3799 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3800
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3802 For example, to compute $c = a + b \mbox{ }(\mbox{mod }m)$ you would call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3803 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3804 mp_addmod(&a, &b, &m, &c);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3805 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3806
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3807 \subsection{Binary Forms of ``mp\_int'' Variables}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3808
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3810 encryption, etc.). LibTomMath includes two functions to help when exporting numbers:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3811 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3812 int mp_raw_size(mp_int *num);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3813 mp_toraw(&num, buf);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3814 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3815
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3820 must be zero for positive numbers and non-zero for negative numbers. For example,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3821 the sequence:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3822 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3823 00 FF 30 04
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3824 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3826
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3827 To read a binary string back into a ``mp\_int'' call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3828 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3829 mp_read_raw(mp_int *num, unsigned char *str, int len);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3830 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3832 length of the binary string.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3833
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3834 \subsection{Primality Testing}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3835 \index{Primality Testing}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3842
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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}.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3847 involved.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3848
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3854 not equal to $(p - 1)(rs - 1)$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3855
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3857 To test if a ``mp\_int'' is prime call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3858 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3859 int is_prime(mp_int *N, int *result);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3860 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3862 it returns an error that the value in ``result'' is undefined. To make
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3863 a random prime call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3864 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3865 int rand_prime(mp_int *N, unsigned long len, prng_state *prng, int wprng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3866 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3870 is very likely prime.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3871
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3872 \chapter{Programming Guidelines}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3873
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3874 \section{Secure Pseudo Random Number Generators}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3879
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3883
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3884 \section{Preventing Trivial Errors}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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!
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3888
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3890 typos or such can cause algorithms to fail to work as desired.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3891
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3892 \section{Registering Your Algorithms}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3895
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3899 need a PRNG can instantly take advantage of it.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3900
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3901 \section{Key Sizes}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3902
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3903 \subsection{Symmetric Ciphers}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3905 is not a hard thing todo.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3906
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3907 \subsection{Assymetric Ciphers}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3909 $n$ is estimated to be
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3910 \begin{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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}}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3912 \end{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3913
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3915 is:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3916 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3917 \begin{tabular}{|c|c|}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3918 \hline RSA/DH Key Size (bits) & Work Factor ($log_2$) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3919 \hline 512 & 63.92 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3920 \hline 768 & 76.50 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3921 \hline 1024 & 86.76 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3922 \hline 1536 & 103.37 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3923 \hline 2048 & 116.88 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3924 \hline 2560 & 128.47 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3925 \hline 3072 & 138.73 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3926 \hline 4096 & 156.49 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3927 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3928 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3929 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3930
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3932 $n$ it requires $\sqrt n$ work. The following table sumarizes the work required:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3933 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3934 \begin{tabular}{|c|c|}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3935 \hline ECC Key Size (bits) & Work Factor ($log_2$) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3936 \hline 192 & 96 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3937 \hline 224 & 112 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3938 \hline 256 & 128 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3939 \hline 384 & 192 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3940 \hline 521 & 260.5 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3941 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3942 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3943 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3944
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3945 Using the above tables the following suggestions for key sizes seems appropriate:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3946 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3947 \begin{tabular}{|c|c|c|}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3948 \hline Security Goal & RSA/DH Key Size (bits) & ECC Key Size (bits) \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3949 \hline Short term (less than a year) & 1024 & 160 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3950 \hline Short term (less than five years) & 1536 & 192 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3951 \hline Long Term (less than ten years) & 2560 & 256 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3952 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3953 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3954 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3955
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3956 \section{Thread Safety}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3959 code before threads are initiated.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3960
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3964 is create semaphores or mutexes around calls to those functions.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3965
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3969 safety issues within the library.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3970
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3971 \chapter{Configuring and Building the Library}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3972 \section{Introduction}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3976
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3977 \section{Building a Static Library}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3980
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3981 \begin{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3982 make install_lib
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3983 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3984
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3989
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3991
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3992 \begin{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3993 make -f makefile.icc install
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3994 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3995
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3997 by issuing
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3998
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3999 \begin{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4000 nmake -f makefile.msvc
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4001 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4002
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4004
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4005 \subsection{MPI Control}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4007 in the appropriate makefile which starts with
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4008
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4009 \begin{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4010 MPIOBJECT=mpi
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4011 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4012
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4015 to the latest mpi.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4016
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4017 \section{Building a Shared Library}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4020 build a .so shared library issue
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4021
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4022 \begin{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4023 make -f makefile.shared
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4024 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4027 libtool program in ``--mode=link''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4028
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4029 \section{tomcrypt\_cfg.h}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4031 of the library.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4032
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4033 \subsubsection{ARGTYPE}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4038 and no error checking will be performed.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4039
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4040 \subsubsection{Endianess}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4044 which will work on all platforms.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4045
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4047
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4048 \section{The Configure Script}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4050
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4051 \subsection{X memory routines}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4055 output. By default the library uses the standard C routines.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4056
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4057 \subsection{X clock routines}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4060
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4061 \subsection{NO\_FILE}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4064 file I/O on embedded platforms.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4065
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4066 \subsection{CLEAN\_STACK}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4068 Assumes that you have no memory paging with the stack.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4069
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4070 \subsection{LTC\_TEST}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4073
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4074 \subsection{Symmetric Ciphers, One-way Hashes, PRNGS and Public Key Functions}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4078 cipher and a hash function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4079
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4080 \subsection{TWOFISH\_SMALL and TWOFISH\_TABLES}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4086
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4090 it will not speed up the encryption or decryption functions.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4091
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4092 \subsection{GCM\_TABLES}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4095
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4096 \subsection{SMALL\_CODE}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4098 These variants are slower but can save quite a bit of code space.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4099
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4100 \subsection{LTC\_FAST}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4103 cutting down the overhead of the respective functions.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4104
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4107 is not ``portable'' since unaligned accesses are not covered by the ISO C specifications.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4108
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4110
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4115 whole word XOR operations. These operations will be unaligned.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4116
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4119
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4123 use this mode. So sad.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4124
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4125 \subsection{LTC\_PTHREAD}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4128
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4130 the tables safer.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4131
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4132 \section{MPI Tweaks}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4133 \subsection{RSA Only Tweak}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4135 to reduce the library size. Follow these steps
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4136
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4137 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4138 \item Undefine MDSA, MECC and MDH from tomcrypt\_custom.h
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4139 \item Undefine LTM\_ALL from tommath\_superclass.h
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4140 \item Define SC\_RSA\_1 from tommath\_superclass.h
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4141 \item Rebuild the library.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4142 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4143
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4144 \chapter{Optimizations}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4145 \section{Introduction}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4149 about the platform, etc...
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4150
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4154
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4158
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4159 \section{Ciphers}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4160 The ciphers in LibTomCrypt are accessed through the ltc\_cipher\_descriptor structure.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4161
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4162 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4163 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4164 struct ltc_cipher_descriptor {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4165 /** name of cipher */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4166 char *name;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4167 /** internal ID */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4168 unsigned char ID;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4169 /** min keysize (octets) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4170 int min_key_length,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4171 /** max keysize (octets) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4172 max_key_length,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4173 /** block size (octets) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4174 block_length,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4175 /** default number of rounds */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4176 default_rounds;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4177 /** Setup the cipher
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4178 @param key The input symmetric key
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4179 @param keylen The length of the input key (octets)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4180 @param num_rounds The requested number of rounds (0==default)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4181 @param skey [out] The destination of the scheduled key
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4182 @return CRYPT_OK if successful
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4183 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4184 int (*setup)(const unsigned char *key, int keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4185 int num_rounds, symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4186 /** Encrypt a block
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4187 @param pt The plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4188 @param ct [out] The ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4189 @param skey The scheduled key
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4190 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4191 void (*ecb_encrypt)(const unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4192 unsigned char *ct, symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4193 /** Decrypt a block
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4194 @param ct The ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4195 @param pt [out] The plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4196 @param skey The scheduled key
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4197 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4198 void (*ecb_decrypt)(const unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4199 unsigned char *pt, symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4200 /** Test the block cipher
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4201 @return CRYPT_OK if successful, CRYPT_NOP if self-testing has been disabled
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4202 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4203 int (*test)(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4204 /** Determine a key size
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4205 @param keysize [in/out] The size of the key desired and the suggested size
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4206 @return CRYPT_OK if successful
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4207 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4208 int (*keysize)(int *keysize);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4209
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4210 /** Accelerators **/
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4211 /** Accelerated ECB encryption
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4212 @param pt Plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4213 @param ct Ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4214 @param blocks The number of complete blocks to process
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4215 @param skey The scheduled key context
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4216 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4217 void (*accel_ecb_encrypt)(const unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4218 unsigned char *ct, unsigned long blocks,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4219 symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4220
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4221 /** Accelerated ECB decryption
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4222 @param pt Plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4223 @param ct Ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4224 @param blocks The number of complete blocks to process
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4225 @param skey The scheduled key context
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4226 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4227 void (*accel_ecb_decrypt)(const unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4228 unsigned char *pt, unsigned long blocks,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4229 symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4230
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4231 /** Accelerated CBC encryption
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4232 @param pt Plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4233 @param ct Ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4234 @param blocks The number of complete blocks to process
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4235 @param IV The initial value (input/output)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4236 @param skey The scheduled key context
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4237 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4238 void (*accel_cbc_encrypt)(const unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4239 unsigned char *ct, unsigned long blocks,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4240 unsigned char *IV, symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4241
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4242 /** Accelerated CBC decryption
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4243 @param pt Plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4244 @param ct Ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4245 @param blocks The number of complete blocks to process
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4246 @param IV The initial value (input/output)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4247 @param skey The scheduled key context
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4248 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4249 void (*accel_cbc_decrypt)(const unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4250 unsigned char *pt, unsigned long blocks,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4251 unsigned char *IV, symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4252
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4253 /** Accelerated CTR encryption
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4254 @param pt Plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4255 @param ct Ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4256 @param blocks The number of complete blocks to process
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4257 @param IV The initial value (input/output)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4258 @param mode little or big endian counter (mode=0 or mode=1)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4259 @param skey The scheduled key context
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4260 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4261 void (*accel_ctr_encrypt)(const unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4262 unsigned char *ct, unsigned long blocks,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4263 unsigned char *IV, int mode, symmetric_key *skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4264
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4265 /** Accelerated CCM packet (one-shot)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4266 @param key The secret key to use
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4267 @param keylen The length of the secret key (octets)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4268 @param nonce The session nonce [use once]
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4269 @param noncelen The length of the nonce
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4270 @param header The header for the session
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4271 @param headerlen The length of the header (octets)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4272 @param pt [out] The plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4273 @param ptlen The length of the plaintext (octets)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4274 @param ct [out] The ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4275 @param tag [out] The destination tag
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4276 @param taglen [in/out] The max size and resulting size of the authentication tag
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4277 @param direction Encrypt or Decrypt direction (0 or 1)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4278 @return CRYPT_OK if successful
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4279 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4280 void (*accel_ccm_memory)(
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4281 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4282 const unsigned char *nonce, unsigned long noncelen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4283 const unsigned char *header, unsigned long headerlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4284 unsigned char *pt, unsigned long ptlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4285 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4286 unsigned char *tag, unsigned long *taglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4287 int direction);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4288
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4289 /** Accelerated GCM packet (one shot)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4290 @param key The secret key
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4291 @param keylen The length of the secret key
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4292 @param IV The initial vector
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4293 @param IVlen The length of the initial vector
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4294 @param adata The additional authentication data (header)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4295 @param adatalen The length of the adata
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4296 @param pt The plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4297 @param ptlen The length of the plaintext (ciphertext length is the same)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4298 @param ct The ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4299 @param tag [out] The MAC tag
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4300 @param taglen [in/out] The MAC tag length
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4301 @param direction Encrypt or Decrypt mode (GCM_ENCRYPT or GCM_DECRYPT)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4302 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4303 void (*accel_gcm_memory)(
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4304 const unsigned char *key, unsigned long keylen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4305 const unsigned char *IV, unsigned long IVlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4306 const unsigned char *adata, unsigned long adatalen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4307 unsigned char *pt, unsigned long ptlen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4308 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4309 unsigned char *tag, unsigned long *taglen,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4310 int direction);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4311
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4312 };
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4313 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4314 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4315
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4316 \subsection{Name}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4318 tables.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4319
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4320 \subsection{Internal ID}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4322
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4323 \subsection{Key Lengths}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4326
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4327 \subsection{Block Length}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4329
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4330 \subsection{Rounds}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4332
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4333 \subsection{Setup}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4336 in ``skey''.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4337
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4340
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4341 \subsection{Single block ECB}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4344
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4345 \subsection{Testing}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4347
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4348 \subsection{Key Sizing}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4352 cannot be mapped to a valid key size for the cipher.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4353
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4354 \subsection{Acceleration}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4357
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4358 \subsubsection{Accelerated ECB}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4361
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4362 \subsubsection{Accelerated CBC}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4365 updated by the function before returning.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4366
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4367 \subsubsection{Accelerated CTR}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4371 little (mode = CTR\_COUNTER\_LITTLE\_ENDIAN) endian.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4372
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4374 called if the following conditions are met.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4375
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4376 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4377 \item The accelerator is present
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4378 \item The CTR pad is empty
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4380 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4381
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4384 buffer provided) before encrypting it to create the pad.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4385
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4387
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4388 \subsubsection{Accelerated CCM}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4391
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4392 \subsubsection{Accelerated GCM}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4395
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4396 \section{One--Way Hashes}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4397 The hash functions are accessed through the ltc\_hash\_descriptor structure.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4398
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4399 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4400 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4401 struct ltc_hash_descriptor {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4402 /** name of hash */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4403 char *name;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4404 /** internal ID */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4405 unsigned char ID;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4406 /** Size of digest in octets */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4407 unsigned long hashsize;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4408 /** Input block size in octets */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4409 unsigned long blocksize;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4410 /** ASN.1 OID */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4411 unsigned long OID[16];
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4412 /** Length of DER encoding */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4413 unsigned long OIDlen;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4414 /** Init a hash state
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4415 @param hash The hash to initialize
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4416 @return CRYPT_OK if successful
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4417 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4418 int (*init)(hash_state *hash);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4419 /** Process a block of data
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4420 @param hash The hash state
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4421 @param in The data to hash
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4422 @param inlen The length of the data (octets)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4423 @return CRYPT_OK if successful
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4424 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4425 int (*process)(hash_state *hash, const unsigned char *in, unsigned long inlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4426 /** Produce the digest and store it
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4427 @param hash The hash state
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4428 @param out [out] The destination of the digest
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4429 @return CRYPT_OK if successful
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4430 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4431 int (*done)(hash_state *hash, unsigned char *out);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4432 /** Self-test
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4433 @return CRYPT_OK if successful, CRYPT_NOP if self-tests have been disabled
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4434 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4435 int (*test)(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4436 };
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4437 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4438 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4439
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4440 \subsection{Name}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4442
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4443 \subsection{Internal ID}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4444 This is the internal ID byte used to distinguish the hash from other hashes.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4445
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4446 \subsection{Digest Size}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4447 The ``hashsize'' variable indicates the length of the output in octets.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4448
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4449 \subsection{Block Size}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4451 invokation.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4452
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4453 \subsection{OID Identifier}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4454 This is the universal ASN.1 Object Identifier for the hash.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4455
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4456 \subsection{Initialization}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4457 The init function initializes the hash and prepares it to process message bytes.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4458
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4459 \subsection{Process}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4461 guaranteed to be a multiple of the block size in length.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4462
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4463 \subsection{Done}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4464 The done function terminates the hash and returns the message digest.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4465
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4466 \subsection{Acceleration}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4468
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4469 \section{Pseudo--Random Number Generators}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4470 The pseudo--random number generators are accessible through the ltc\_prng\_descriptor structure.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4471
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4472 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4473 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4474 struct ltc_prng_descriptor {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4475 /** Name of the PRNG */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4476 char *name;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4477 /** size in bytes of exported state */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4478 int export_size;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4479 /** Start a PRNG state
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4480 @param prng [out] The state to initialize
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4481 @return CRYPT_OK if successful
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4482 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4483 int (*start)(prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4484 /** Add entropy to the PRNG
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4485 @param in The entropy
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4486 @param inlen Length of the entropy (octets)\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4487 @param prng The PRNG state
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4488 @return CRYPT_OK if successful
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4489 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4490 int (*add_entropy)(const unsigned char *in, unsigned long inlen, prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4491 /** Ready a PRNG state to read from
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4492 @param prng The PRNG state to ready
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4493 @return CRYPT_OK if successful
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4494 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4495 int (*ready)(prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4496 /** Read from the PRNG
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4497 @param out [out] Where to store the data
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4498 @param outlen Length of data desired (octets)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4499 @param prng The PRNG state to read from
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4500 @return Number of octets read
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4501 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4502 unsigned long (*read)(unsigned char *out, unsigned long outlen, prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4503 /** Terminate a PRNG state
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4504 @param prng The PRNG state to terminate
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4505 @return CRYPT_OK if successful
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4506 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4507 int (*done)(prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4508 /** Export a PRNG state
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4509 @param out [out] The destination for the state
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4510 @param outlen [in/out] The max size and resulting size of the PRNG state
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4511 @param prng The PRNG to export
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4512 @return CRYPT_OK if successful
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4513 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4514 int (*pexport)(unsigned char *out, unsigned long *outlen, prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4515 /** Import a PRNG state
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4516 @param in The data to import
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4517 @param inlen The length of the data to import (octets)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4518 @param prng The PRNG to initialize/import
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4519 @return CRYPT_OK if successful
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4520 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4521 int (*pimport)(const unsigned char *in, unsigned long inlen, prng_state *prng);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4522 /** Self-test the PRNG
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4523 @return CRYPT_OK if successful, CRYPT_NOP if self-testing has been disabled
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4524 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4525 int (*test)(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4526 };
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4527 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4528 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4529
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4530 \subsection{Name}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4531 The name by which find\_prng() will find the PRNG.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4532
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4533 \subsection{Export Size}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4535
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4536 \subsection{Start}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4537 Initialize the PRNG and make it ready to accept entropy.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4538
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4539 \subsection{Entropy Addition}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4541
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4542 \subsection{Ready}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4544 on the specific PRNG used.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4545
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4546 \subsection{Read}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4549
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4550 \subsection{Done}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4552
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4553 \subsection{Exporting and Importing}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
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''
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4555 but should at least maintain the same level of state entropy.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4556
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4557 \input{crypt.ind}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4558
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4559 \end{document}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4560
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4561 % $Source: /cvs/libtom/libtomcrypt/crypt.tex,v $
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4562 % $Revision: 1.39 $
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4563 % $Date: 2005/06/27 13:08:28 $