Mercurial > dropbear

annotate libtomcrypt/crypt.tex @ 1435:f849a5ca2efc

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
update to libtomcrypt 1.17 (with Dropbear changes)
author Matt Johnston <matt@ucc.asn.au>
date Sat, 24 Jun 2017 17:50:50 +0800
parents 0cbe8f6dbf9e
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1 \documentclass[synpaper]{book}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2 \usepackage[dvips]{geometry}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3 \usepackage{hyperref}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4 \usepackage{makeidx}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5 \usepackage{amssymb}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6 \usepackage{color}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
7 \usepackage{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
8 \usepackage{graphicx}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
9 \usepackage{layout}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
10 \usepackage{fancyhdr}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
11 \def\union{\cup}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
12 \def\intersect{\cap}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
13 \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
14 \def\cross{\times}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
15 \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
16 \def\catn{$\|$}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
17 \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
18 \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
19 \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
20 \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
21 \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
22 \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
23 \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
24 \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
25 \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
26 \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
27 \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
28 \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
29 \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
30 \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
31 \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
32 \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
33 \def\implies{\Rightarrow}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
34 \def\undefined{{\rm \textit{undefined}}}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
35 \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
36 \let\oldphi\phi
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
37 \def\phi{\varphi}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
38 \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
39 \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
40 \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
41 \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
42 \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
43 \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
44 \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
45 \def\Q{{\mathbb Q}}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
46 \definecolor{DGray}{gray}{0.5}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
47 \newcommand{\emailaddr}[1]{\mbox{$<${#1}$>$}}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
48 \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
49 \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
50 \makeindex
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
51 \newcommand{\mysection}[1] % Re-define the chaptering command to use
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
52 { % THESE headers.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
53 \section{#1}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
54 \markboth{\textsf{www.libtom.org}}{\thesection ~ {#1}}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
55 }
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
56
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
57 \newcommand{\mystarsection}[1] % Re-define the chaptering command to use
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
58 { % THESE headers.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
59 \section*{#1}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
60 \markboth{\textsf{www.libtom.org}}{{#1}}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
61 }
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
62 \pagestyle{empty}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
63 \begin{document}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
64 \frontmatter
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
65 \pagestyle{empty}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
66
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
67 ~
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
68
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
69 \vspace{2in}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
70
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
71 ~
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
72
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
73 \begin{center}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
74 \begin{Huge}LibTomCrypt\end{Huge}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
75
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
76 ~
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
77
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
78 \begin{large}Developer Manual\end{large}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
79
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
80 ~
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
81
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
82 \vspace{15mm}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
83
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
84
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
85 \begin{tabular}{c}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
86 Tom St Denis \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
87 LibTom Projects
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
88 \end{tabular}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
89 \end{center}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
90 \vfil
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
91 \newpage
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
92 This document is part of the LibTomCrypt package and is hereby released into the public domain.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
93
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
94 ~
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
95
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
96 Open Source. Open Academia. Open Minds.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
97
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
98 ~
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
99
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
100 \begin{flushright}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
101 Tom St Denis
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
102 ~
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
103
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
104 Ottawa, Ontario
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
105 ~
285
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 Canada
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
108 ~
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
109 \vfil
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
110 \end{flushright}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
111 \newpage
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
112
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
113 \tableofcontents
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
114 \listoffigures
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
115 \pagestyle{myheadings}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
116 \mainmatter
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
117 \chapter{Introduction}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
118 \mysection{What is the LibTomCrypt?}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
119 LibTomCrypt is a portable ISO C cryptographic library meant to be a tool set for cryptographers who are
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
120 designing cryptosystems. It supports symmetric ciphers, one-way hashes, pseudo-random number generators,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
121 public key cryptography (via PKCS \#1 RSA, DH or ECCDH), and a plethora of support routines.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
122
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
123 The library was designed such that new ciphers/hashes/PRNGs can be added at run-time and the existing API
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
124 (and helper API functions) are able to use the new designs automatically. There exists self-check functions for each
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
125 block cipher and hash function to ensure that they compile and execute to the published design specifications. The library
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
126 also performs extensive parameter error checking to prevent any number of run-time exploits or errors.
285
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{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
129
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
130 The library serves as a toolkit for developers who have to solve cryptographic problems. Out of the box LibTomCrypt
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
131 does not process SSL or OpenPGP messages, it doesn't read X.509 certificates, or write PEM encoded data. It does, however,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
132 provide all of the tools required to build such functionality. LibTomCrypt was designed to be a flexible library that
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
133 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
134
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
135 \mysection{Why did I write it?}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
136 You may be wondering, \textit{Tom, why did you write a crypto library. I already have one.} Well the reason falls into
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
137 two categories:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
138 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
139 \item I am too lazy to figure out someone else's API. I'd rather invent my own simpler API and use that.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
140 \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
141 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
142
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
143 The idea is that I am not striving to replace OpenSSL or Crypto++ or Cryptlib or etc. I'm trying to write my
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
144 {\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
145
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
146 With this library all core functions (ciphers, hashes, prngs, and bignum) have the same prototype definition. They all load
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
147 and store data in a format independent of the platform. This means if you encrypt with Blowfish on a PPC it should decrypt
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
148 on an x86 with zero problems. The consistent API also means that if you learn how to use Blowfish with the library you
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
149 know how to use Safer+, RC6, or Serpent as well. With all of the core functions there are central descriptor tables
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
150 that can be used to make a program automatically pick between ciphers, hashes and PRNGs at run-time. That means your
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
151 application can support all ciphers/hashes/prngs/bignum without changing the source code.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
152
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
153 Not only did I strive to make a consistent and simple API to work with but I also attempted to make the library
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
154 configurable in terms of its build options. Out of the box the library will build with any modern version of GCC
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
155 without having to use configure scripts. This means that the library will work with platforms where development
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
156 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
157
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
158 On top of making the build simple and the API approachable I've also attempted for a reasonably high level of
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
159 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
160 arguments to buffer overflows/overruns. It is mostly thread safe and has been clocked on various platforms
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
161 with \textit{cycles per byte} timings that are comparable (and often favourable) to other libraries such as OpenSSL and
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
162 Crypto++.
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 \subsection{Modular}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
165 The LibTomCrypt package has also been written to be very modular. The block ciphers, one--way hashes,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
166 pseudo--random number generators (PRNG), and bignum math routines are all used within the API through \textit{descriptor} tables which
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
167 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
168 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
169 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
170
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
171 For example, consider a hardware platform with a specialized RNG device. Obviously one would like to tap
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
172 that for the PRNG needs within the library (\textit{e.g. making a RSA key}). All the developer has to do
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
173 is write a descriptor and the few support routines required for the device. After that the rest of the
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
174 API can make use of it without change. Similarly imagine a few years down the road when AES2
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
175 (\textit{or whatever they call it}) has been invented. It can be added to the library and used within applications
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
176 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
177
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
178 This flexibility within the library means it can be used with any combination of primitive algorithms and
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
179 unlike libraries like OpenSSL is not tied to direct routines. For instance, in OpenSSL there are CBC block
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
180 mode routines for every single cipher. That means every time you add or remove a cipher from the library
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
181 you have to update the associated support code as well. In LibTomCrypt the associated code (\textit{chaining modes in this case})
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
182 are not directly tied to the ciphers. That is a new cipher can be added to the library by simply providing
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
183 the key setup, ECB decrypt and encrypt and test vector routines. After that all five chaining mode routines
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
184 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
185
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
186 \mysection{License}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
187
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
188 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
189
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
190 \mysection{Patent Disclosure}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
191
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
192 The author (Tom St Denis) is not a patent lawyer so this section is not to be treated as legal advice. To the best
1435
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
193 of the author's knowledge the only patent related issues within the library are the RC5 and RC6 symmetric block ciphers.
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
194 They can be removed from a build by simply commenting out the two appropriate lines in \textit{tomcrypt\_custom.h}. The rest
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
195 of the ciphers and hashes are patent free or under patents that have since expired.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
196
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
197 The RC2 and RC4 symmetric ciphers are not under patents but are under trademark regulations. This means you can use
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
198 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
199
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
200 \mysection{Thanks}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
201 I would like to give thanks to the following people (in no particular order) for helping me develop this project from
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
202 early on:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
203 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
204 \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
205 \item Richard Heathfield
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
206 \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
207 \item Brian Gladman
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
208 \item Svante Seleborg
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
209 \item Clay Culver
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
210 \item Jason Klapste
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
211 \item Dobes Vandermeer
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
212 \item Daniel Richards
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
213 \item Wayne Scott
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
214 \item Andrew Tyler
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
215 \item Sky Schulz
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
216 \item Christopher Imes
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
217 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
218
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
219 There have been quite a few other people as well. Please check the change log to see who else has contributed from
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
220 time to time.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
221
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
222 \chapter{The Application Programming Interface (API)}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
223 \mysection{Introduction}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
224 \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
225
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
226 In general the API is very simple to memorize and use. Most of the functions return either {\bf void} or {\bf int}. Functions
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
227 that return {\bf int} will return {\bf CRYPT\_OK} if the function was successful, or one of the many error codes
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
228 if it failed. Certain functions that return int will return $-1$ to indicate an error. These functions will be explicitly
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
229 commented upon. When a function does return a CRYPT error code it can be translated into a string with
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 \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
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 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
234 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
235
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
236 An example of handling an error is:
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
237 \begin{small}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
238 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
239 void somefunc(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
240 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
241 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
242
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
243 /* 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
244 if ((err = some_crypto_function(...)) != CRYPT_OK) {
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
245 printf("A crypto error occurred, %s\n", error_to_string(err));
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
246 /* perform error handling */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
247 }
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
248 /* continue on if no error occurred */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
249 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
250 \end{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
251 \end{small}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
252
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
253 There is no initialization routine for the library and for the most part the code is thread safe. The only thread
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
254 related issue is if you use the same symmetric cipher, hash or public key state data in multiple threads. Normally
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
255 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
256
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
257 To include the prototypes for \textit{LibTomCrypt.a} into your own program simply include \textit{tomcrypt.h} like so:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
258 \begin{small}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
259 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
260 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
261 int main(void) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
262 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
263 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
264 \end{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
265 \end{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
266
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
267 The header file \textit{tomcrypt.h} also includes \textit{stdio.h}, \textit{string.h}, \textit{stdlib.h}, \textit{time.h} and \textit{ctype.h}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
268
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
269 \mysection{Macros}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
270
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
271 There are a few helper macros to make the coding process a bit easier. The first set are related to loading and storing
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
272 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
273
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
274 \index{STORE32L} \index{STORE64L} \index{LOAD32L} \index{LOAD64L} \index{STORE32H} \index{STORE64H} \index{LOAD32H} \index{LOAD64H} \index{BSWAP}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
275 \newpage
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
276 \begin{figure}[hpbt]
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
277 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
278 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
279 \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
280 \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
281 \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
282 \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
283 \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
284 \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
285 \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
286 \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
287 \hline LOAD64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[7 \ldots 0] \to x$ \\
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
288 \hline BSWAP(x) & {\bf unsigned long} x & Swap bytes \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
289 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
290 \end{tabular}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
291 \caption{Load And Store Macros}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
292 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
293 \end{small}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
294 \end{figure}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
295
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
296 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
297 \index{ROL} \index{ROR} \index{ROL64} \index{ROR64} \index{ROLc} \index{RORc} \index{ROL64c} \index{ROR64c}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
298 \begin{figure}[hpbt]
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
299 \begin{small}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
300 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
301 \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
302 \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
303 \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
304 \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
305 \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
306 \hline && \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
307 \hline ROL64(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x << y, 0 \le y \le 63$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
308 \hline ROL64c(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x << y, 0 \le y \le 63$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
309 \hline ROR64(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x >> y, 0 \le y \le 63$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
310 \hline ROR64c(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x >> y, 0 \le y \le 63$ \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
311 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
312 \end{tabular}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
313 \caption{Rotate Macros}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
314 \end{center}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
315 \end{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
316 \end{figure}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
317
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
318 \mysection{Functions with Variable Length Output}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
319 Certain functions such as (for example) \textit{rsa\_export()} give an output that is variable length. To prevent buffer overflows you
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
320 must pass it the length of the buffer where the output will be stored. For example:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
321 \index{rsa\_export()} \index{error\_to\_string()} \index{variable length output}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
322 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
323 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
324 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
325 int main(void) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
326 rsa_key key;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
327 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
328 unsigned long x;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
329 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
330
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
331 /* ... 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
332
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
333 /* lets export the key, set x to the size of the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
334 * output buffer */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
335 x = sizeof(buffer);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
336 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
337 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
338 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
339 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
340
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
341 /* if rsa_export() was successful then x will have
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
342 * the size of the output */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
343 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
344
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
345 /* ... 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
346
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
347 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
348 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
349 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
350 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
351 In the above example if the size of the RSA public key was more than 1024 bytes this function would return an error code
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
352 indicating a buffer overflow would have occurred. If the function succeeds, it stores the length of the output back into
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
353 \textit{x} so that the calling application will know how many bytes were used.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
354
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
355 As of v1.13, most functions will update your length on failure to indicate the size required by the function. Not all functions
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
356 support this so please check the source before you rely on it doing that.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
357
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
358 \mysection{Functions that need a PRNG}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
359 \index{Pseudo Random Number Generator} \index{PRNG}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
360 Certain functions such as \textit{rsa\_make\_key()} require a Pseudo Random Number Generator (PRNG). These functions do not setup
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
361 the PRNG themselves so it is the responsibility of the calling function to initialize the PRNG before calling them.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
362
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
363 Certain PRNG algorithms do not require a \textit{prng\_state} argument (sprng for example). The \textit{prng\_state} argument
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
364 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
365
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
366 \index{register\_prng()} \index{rsa\_make\_key()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
367 \begin{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
368 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
369 #include <tomcrypt.h>
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
370 int main(void) {
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
371 rsa_key key;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
372 int err;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
373
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
374 /* register the system RNG */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
375 register_prng(&sprng_desc)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
376
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
377 /* make a 1024-bit RSA key with the system RNG */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
378 if ((err = rsa_make_key(NULL, find_prng("sprng"), 1024/8, 65537, &key))
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
379 != CRYPT_OK) {
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
380 printf("make_key error: %s\n", error_to_string(err));
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
381 return -1;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
382 }
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
383
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
384 /* use the key ... */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
385
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
386 return 0;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
387 }
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
388 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
389 \end{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
390
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
391 \mysection{Functions that use Arrays of Octets}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
392 Most functions require inputs that are arrays of the data type \textit{unsigned char}. Whether it is a symmetric key, IV
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
393 for a chaining mode or public key packet it is assumed that regardless of the actual size of \textit{unsigned char} only the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
394 lower eight bits contain data. For example, if you want to pass a 256 bit key to a symmetric ciphers setup routine, you
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
395 must pass in (a pointer to) an array of 32 \textit{unsigned char} variables. Certain routines (such as SAFER+) take
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
396 special care to work properly on platforms where an \textit{unsigned char} is not eight bits.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
397
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
398 For the purposes of this library, the term \textit{byte} will refer to an octet or eight bit word. Typically an array of
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
399 type \textit{byte} will be synonymous with an array of type \textit{unsigned char.}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
400
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
401 \chapter{Symmetric Block Ciphers}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
402 \mysection{Core Functions}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
403 LibTomCrypt provides several block ciphers with an ECB block mode interface. It is important to first note that you
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
404 should never use the ECB modes directly to encrypt data. Instead you should use the ECB functions to make a chaining mode,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
405 or use one of the provided chaining modes. All of the ciphers are written as ECB interfaces since it allows the rest of
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
406 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
407
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
408 \subsection{Key Scheduling}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
409 All ciphers store their scheduled keys in a single data type called \textit{symmetric\_key}. This allows all ciphers to
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
410 have the same prototype and store their keys as naturally as possible. This also removes the need for dynamic memory
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
411 allocation, and allows you to allocate a fixed sized buffer for storing scheduled keys. All ciphers must provide six visible
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
412 functions which are (given that XXX is the name of the cipher) the following:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
413 \index{Cipher Setup}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
414 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
415 int XXX_setup(const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
416 int keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
417 int rounds,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
418 symmetric_key *skey);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
419 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
420
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
421 The XXX\_setup() routine will setup the cipher to be used with a given number of rounds and a given key length (in bytes).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
422 The number of rounds can be set to zero to use the default, which is generally a good idea.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
423
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
424 If the function returns successfully the variable \textit{skey} will have a scheduled key stored in it. It's important to note
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
425 that you should only used this scheduled key with the intended cipher. For example, if you call \textit{blowfish\_setup()} do not
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
426 pass the scheduled key onto \textit{rc5\_ecb\_encrypt()}. All built--in setup functions do not allocate memory off the heap so
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
427 when you are done with a key you can simply discard it (e.g. they can be on the stack). However, to maintain proper coding
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
428 practices you should always call the respective XXX\_done() function. This allows for quicker porting to applications with
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
429 externally supplied plugins.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
430
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
431 \subsection{ECB Encryption and Decryption}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
432 To encrypt or decrypt a block in ECB mode there are these two functions per cipher:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
433 \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
434 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
435 int XXX_ecb_encrypt(const unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
436 unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
437 symmetric_key *skey);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
438
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
439 int XXX_ecb_decrypt(const unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
440 unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
441 symmetric_key *skey);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
442 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
443 These two functions will encrypt or decrypt (respectively) a single block of text\footnote{The size of which depends on
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
444 which cipher you are using.}, storing the result in the \textit{ct} buffer (\textit{pt} resp.). It is possible that the input and output buffer are
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
445 the same buffer. For the encrypt function \textit{pt}\footnote{pt stands for plaintext.} is the input and
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
446 \textit{ct}\footnote{ct stands for ciphertext.} is the output. For the decryption function it's the opposite. They both
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
447 return \textbf{CRYPT\_OK} on success. To test a particular cipher against test vectors\footnote{As published in their design papers.}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
448 call the following self-test function.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
449
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
450 \subsection{Self--Testing}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
451 \index{Cipher Testing}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
452 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
453 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
454 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
455 This function will return {\bf CRYPT\_OK} if the cipher matches the test vectors from the design publication it is
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
456 based upon.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
457
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
458 \subsection{Key Sizing}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
459 For each cipher there is a function which will help find a desired key size. It is specified as follows:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
460 \index{Key Sizing}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
461 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
462 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
463 \end{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
464 Essentially, it will round the input keysize in \textit{keysize} down to the next appropriate key size. This function
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
465 will return {\bf CRYPT\_OK} if the key size specified is acceptable. For example:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
466 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
467 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
468 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
469 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
470 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
471 int keysize, err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
472
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
473 /* 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
474 keysize = 20;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
475 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
476 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
477 return -1;
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 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
480 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
481 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
482 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
483 \end{small}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
484 This should indicate a keysize of sixteen bytes is suggested by storing 16 in \textit{keysize.}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
485
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
486 \subsection{Cipher Termination}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
487 When you are finished with a cipher you can de--initialize it with the done function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
488 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
489 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
490 \end{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
491 For the software based ciphers within LibTomCrypt, these functions will not do anything. However, user supplied
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
492 cipher descriptors may require to be called for resource management purposes. To be compliant, all functions which call a cipher
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
493 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
494
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
495 \subsection{Simple Encryption Demonstration}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
496 An example snippet that encodes a block with Blowfish in ECB mode.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
497
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
498 \index{blowfish\_setup()} \index{blowfish\_ecb\_encrypt()} \index{blowfish\_ecb\_decrypt()} \index{blowfish\_done()}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
499 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
500 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
501 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
502 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
503 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
504 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
505 symmetric_key skey;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
506 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
507
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
508 /* ... key is loaded appropriately in key ... */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
509 /* ... load a block of plaintext in pt ... */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
510
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
511 /* schedule the key */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
512 if ((err = blowfish_setup(key, /* the key we will use */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
513 8, /* key is 8 bytes (64-bits) long */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
514 0, /* 0 == use default # of rounds */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
515 &skey) /* where to put the scheduled key */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
516 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
517 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
518 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
519 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
520
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
521 /* encrypt the block */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
522 blowfish_ecb_encrypt(pt, /* encrypt this 8-byte array */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
523 ct, /* store encrypted data here */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
524 &skey); /* our previously scheduled key */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
525
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
526 /* 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
527
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
528 /* decrypt the block */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
529 blowfish_ecb_decrypt(ct, /* decrypt this 8-byte array */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
530 pt, /* store decrypted data here */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
531 &skey); /* our previously scheduled key */
285
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 /* 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
534
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
535 /* 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
536 blowfish_done(&skey);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
537
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
538 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
539 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
540 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
541 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
542
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
543 \mysection{Key Sizes and Number of Rounds}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
544 \index{Symmetric Keys}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
545 As a general rule of thumb, do not use symmetric keys under 80 bits if you can help it. Only a few of the ciphers support smaller
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
546 keys (mainly for test vectors anyways). Ideally, your application should be making at least 256 bit keys. This is not
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
547 because you are to be paranoid. It is because if your PRNG has a bias of any sort the more bits the better. For
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
548 example, if you have $\mbox{Pr}\left[X = 1\right] = {1 \over 2} \pm \gamma$ where $\vert \gamma \vert > 0$ then the
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
549 total amount of entropy in N bits is $N \cdot -log_2\left ({1 \over 2} + \vert \gamma \vert \right)$. So if $\gamma$
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
550 were $0.25$ (a severe bias) a 256-bit string would have about 106 bits of entropy whereas a 128-bit string would have
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
551 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
552
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
553 The number of rounds of most ciphers is not an option you can change. Only RC5 allows you to change the number of
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
554 rounds. By passing zero as the number of rounds all ciphers will use their default number of rounds. Generally the
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
555 ciphers are configured such that the default number of rounds provide adequate security for the given block and key
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
556 size.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
557
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
558 \mysection{The Cipher Descriptors}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
559 \index{Cipher Descriptor}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
560 To facilitate automatic routines an array of cipher descriptors is provided in the array \textit{cipher\_descriptor}. An element
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
561 of this array has the following (partial) format (See Section \ref{sec:cipherdesc}):
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
562
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
563 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
564 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
565 struct _cipher_descriptor {
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
566 /** name of cipher */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
567 char *name;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
568
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
569 /** internal ID */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
570 unsigned char ID;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
571
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
572 /** min keysize (octets) */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
573 int min_key_length,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
574
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
575 /** max keysize (octets) */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
576 max_key_length,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
577
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
578 /** block size (octets) */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
579 block_length,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
580
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
581 /** default number of rounds */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
582 default_rounds;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
583 ...<snip>...
285
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 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
586 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
587
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
588 Where \textit{name} is the lower case ASCII version of the name. The fields \textit{min\_key\_length} and \textit{max\_key\_length}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
589 are the minimum and maximum key sizes in bytes. The \textit{block\_length} member is the block size of the cipher
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
590 in bytes. As a good rule of thumb it is assumed that the cipher supports
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
591 the min and max key lengths but not always everything in between. The \textit{default\_rounds} field is the default number
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
592 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
593
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
594 For a plugin to be compliant it must provide at least each function listed before the accelerators begin. Accelerators are optional,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
595 and if missing will be emulated in software.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
596
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
597 The remaining fields are all pointers to the core functions for each cipher. The end of the cipher\_descriptor array is
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
598 marked when \textit{name} equals {\bf NULL}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
599
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
600 As of this release the current cipher\_descriptors elements are the following:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
601 \vfil
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
602 \index{Cipher descriptor table}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
603 \index{blowfish\_desc} \index{xtea\_desc} \index{rc2\_desc} \index{rc5\_desc} \index{rc6\_desc} \index{saferp\_desc} \index{aes\_desc} \index{twofish\_desc}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
604 \index{des\_desc} \index{des3\_desc} \index{noekeon\_desc} \index{skipjack\_desc} \index{anubis\_desc} \index{khazad\_desc} \index{kseed\_desc} \index{kasumi\_desc}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
605 \begin{figure}[hpbt]
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
606 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
607 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
608 \begin{tabular}{|c|c|c|c|c|c|}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
609 \hline \textbf{Name} & \textbf{Descriptor Name} & \textbf{Block Size} & \textbf{Key Range} & \textbf{Rounds} \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
610 \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
611 \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
612 \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
613 \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
614 \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
615 \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
616 \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
617 & 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
618 \hline Twofish & twofish\_desc & 16 & 16, 24, 32 & 16 \\
1435
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
619 \hline DES & des\_desc & 8 & 8 & 16 \\
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
620 \hline 3DES (EDE mode) & des3\_desc & 8 & 24 & 16 \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
621 \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
622 \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
623 \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
624 \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
625 \hline Khazad & khazad\_desc & 8 & 16 & 8 \\
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
626 \hline SEED & kseed\_desc & 16 & 16 & 16 \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
627 \hline KASUMI & kasumi\_desc & 8 & 16 & 8 \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
628 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
629 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
630 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
631 \end{small}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
632 \caption{Built--In Software Ciphers}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
633 \end{figure}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
634
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
635 \subsection{Notes}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
636 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
637 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
638 \item
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
639 For AES, (also known as Rijndael) there are four descriptors which complicate issues a little. The descriptors
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
640 rijndael\_desc and rijndael\_enc\_desc provide the cipher named \textit{rijndael}. The descriptors aes\_desc and
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
641 aes\_enc\_desc provide the cipher name \textit{aes}. Functionally both \textit{rijndael} and \textit{aes} are the same cipher. The
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
642 only difference is when you call find\_cipher() you have to pass the correct name. The cipher descriptors with \textit{enc}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
643 in the middle (e.g. rijndael\_enc\_desc) are related to an implementation of Rijndael with only the encryption routine
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
644 and tables. The decryption and self--test function pointers of both \textit{encrypt only} descriptors are set to \textbf{NULL} and
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
645 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
646
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
647 The \textit{encrypt only} descriptors are useful for applications that only use the encryption function of the cipher. Algorithms such
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
648 as EAX, PMAC and OMAC only require the encryption function. So far this \textit{encrypt only} functionality has only been implemented for
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
649 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
650
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
651 \item
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
652 Note that for \textit{DES} and \textit{3DES} they use 8 and 24 byte keys but only 7 and 21 [respectively] bytes of the keys are in
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
653 fact used for the purposes of encryption. My suggestion is just to use random 8/24 byte keys instead of trying to make a 8/24
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
654 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
655
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
656 \item
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
657 Note that \textit{Twofish} has additional configuration options (Figure \ref{fig:twofishopts}) that take place at build time. These options are found in
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
658 the file \textit{tomcrypt\_cfg.h}. The first option is \textit{TWOFISH\_SMALL} which when defined will force the Twofish code
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
659 to not pre-compute the Twofish \textit{$g(X)$} function as a set of four $8 \times 32$ s-boxes. This means that a scheduled
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
660 key will require less ram but the resulting cipher will be slower. The second option is \textit{TWOFISH\_TABLES} which when
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
661 defined will force the Twofish code to use pre-computed tables for the two s-boxes $q_0, q_1$ as well as the multiplication
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
662 by the polynomials 5B and EF used in the MDS multiplication. As a result the code is faster and slightly larger. The
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
663 speed increase is useful when \textit{TWOFISH\_SMALL} is defined since the s-boxes and MDS multiply form the heart of the
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
664 Twofish round function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
665
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
666 \begin{figure}[hpbt]
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
667 \index{Twofish build options} \index{TWOFISH\_SMALL} \index{TWOFISH\_TABLES}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
668 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
669 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
670 \begin{tabular}{|l|l|l|}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
671 \hline \textbf{TWOFISH\_SMALL} & \textbf{TWOFISH\_TABLES} & \textbf{Speed and Memory (per key)} \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
672 \hline undefined & undefined & Very fast, 4.2KB of ram. \\
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
673 \hline undefined & defined & Faster key setup, larger code. \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
674 \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
675 \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
676 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
677 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
678 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
679 \end{small}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
680 \caption{Twofish Build Options}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
681 \label{fig:twofishopts}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
682 \end{figure}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
683 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
684 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
685
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
686 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
687 \index{find\_cipher()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
688 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
689 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
690 \end{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
691 Which will search for a given name in the array. It returns $-1$ if the cipher is not found, otherwise it returns
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
692 the location in the array where the cipher was found. For example, to indirectly setup Blowfish you can also use:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
693 \begin{small}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
694 \index{register\_cipher()} \index{find\_cipher()} \index{error\_to\_string()}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
695 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
696 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
697 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
698 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
699 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
700 symmetric_key skey;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
701 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
702
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
703 /* 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
704 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
705 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
706 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
707 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
708
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
709 /* generic call to function (assuming the key
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
710 * in key[] was already setup) */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
711 if ((err =
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
712 cipher_descriptor[find_cipher("blowfish")].
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
713 setup(key, 8, 0, &skey)) != CRYPT_OK) {
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
714 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
715 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
716 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
717
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
718 /* ... use cipher ... */
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 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
721 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
722
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
723 A good safety would be to check the return value of \textit{find\_cipher()} before accessing the desired function. In order
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
724 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
725 \index{register\_cipher()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
726 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
727 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
728 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
729 Which accepts a pointer to a descriptor and returns the index into the global descriptor table. If an error occurs such
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
730 as there is no more room (it can have 32 ciphers at most) it will return {\bf{-1}}. If you try to add the same cipher more
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
731 than once it will just return the index of the first copy. To remove a cipher call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
732 \index{unregister\_cipher()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
733 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
734 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
735 \end{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
736 Which returns {\bf CRYPT\_OK} if it removes the cipher, otherwise it returns {\bf CRYPT\_ERROR}.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
737 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
738 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
739 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
740 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
741 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
742 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
743
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
744 /* register the cipher */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
745 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
746 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
747 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
748 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
749
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
750 /* use Rijndael */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
751
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
752 /* remove it */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
753 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
754 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
755 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
756 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
757
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
758 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
759 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
760 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
761 \end{small}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
762 This snippet is a small program that registers Rijndael.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
763
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
764 \mysection{Symmetric Modes of Operations}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
765 \subsection{Background}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
766 A typical symmetric block cipher can be used in chaining modes to effectively encrypt messages larger than the block
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
767 size of the cipher. Given a key $k$, a plaintext $P$ and a cipher $E$ we shall denote the encryption of the block
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
768 $P$ under the key $k$ as $E_k(P)$. In some modes there exists an initial vector denoted as $C_{-1}$.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
769
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
770 \subsubsection{ECB Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
771 \index{ECB mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
772 ECB or Electronic Codebook Mode is the simplest method to use. It is given as:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
773 \begin{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
774 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
775 \end{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
776 This mode is very weak since it allows people to swap blocks and perform replay attacks if the same key is used more
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
777 than once.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
778
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
779 \subsubsection{CBC Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
780 \index{CBC mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
781 CBC or Cipher Block Chaining mode is a simple mode designed to prevent trivial forms of replay and swap attacks on ciphers.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
782 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
783 \begin{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
784 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
785 \end{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
786 It is important that the initial vector be unique and preferably random for each message encrypted under the same key.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
787
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
788 \subsubsection{CTR Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
789 \index{CTR mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
790 CTR or Counter Mode is a mode which only uses the encryption function of the cipher. Given a initial vector which is
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
791 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
792 \begin{eqnarray}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
793 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
794 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
795 \end{eqnarray}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
796 Where $W$ is the size of a block in bits (e.g. 64 for Blowfish). As long as the initial vector is random for each message
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
797 encrypted under the same key replay and swap attacks are infeasible. CTR mode may look simple but it is as secure
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
798 as the block cipher is under a chosen plaintext attack (provided the initial vector is unique).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
799
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
800 \subsubsection{CFB Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
801 \index{CFB mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
802 CFB or Ciphertext Feedback Mode is a mode akin to CBC. It is given as:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
803 \begin{eqnarray}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
804 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
805 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
806 \end{eqnarray}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
807 Note that in this library the output feedback width is equal to the size of the block cipher. That is this mode is used
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
808 to encrypt whole blocks at a time. However, the library will buffer data allowing the user to encrypt or decrypt partial
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
809 blocks without a delay. When this mode is first setup it will initially encrypt the initial vector as required.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
810
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
811 \subsubsection{OFB Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
812 \index{OFB mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
813 OFB or Output Feedback Mode is a mode akin to CBC as well. It is given as:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
814 \begin{eqnarray}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
815 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
816 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
817 \end{eqnarray}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
818 Like the CFB mode the output width in CFB mode is the same as the width of the block cipher. OFB mode will also
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
819 buffer the output which will allow you to encrypt or decrypt partial blocks without delay.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
820
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
821 \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
822 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
823 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
824 \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
825 \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
826 \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
827 \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
828 \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
829 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
830 The CTR, CFB and OFB routines provided allow you to encrypt block sizes that differ from the ciphers block size. They
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
831 accomplish this by buffering the data required to complete a block. This allows you to encrypt or decrypt any size
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
832 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
833
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
834 The ECB and CBC modes process blocks of the same size as the cipher at a time. Therefore, they are less flexible than the
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
835 other modes.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
836
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
837 \subsection{Ciphertext Stealing}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
838 \index{Ciphertext stealing}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
839 Ciphertext stealing is a method of dealing with messages in CBC mode which are not a multiple of the block length. This is accomplished
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
840 by encrypting the last ciphertext block in ECB mode, and XOR'ing the output against the last partial block of plaintext. LibTomCrypt does not
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
841 support this mode directly but it is fairly easy to emulate with a call to the cipher's ecb\_encrypt() callback function.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
842
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
843 The more sane way to deal with partial blocks is to pad them with zeroes, and then use CBC normally.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
844
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
845 \subsection{Initialization}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
846 \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
847 \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
848 The library provides simple support routines for handling CBC, CTR, CFB, OFB and ECB encoded messages. Assuming the mode
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
849 you want is XXX there is a structure called \textit{symmetric\_XXX} that will contain the information required to
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
850 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
851 \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
852 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
853 int XXX_start( int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
854 const unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
855 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
856 int keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
857 int num_rounds,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
858 symmetric_XXX *XXX);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
859
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
860 int ctr_start( int cipher,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
861 const unsigned char *IV,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
862 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
863 int keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
864 int num_rounds,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
865 int ctr_mode,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
866 symmetric_CTR *ctr);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
867
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
868 int ecb_start( int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
869 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
870 int keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
871 int num_rounds,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
872 symmetric_ECB *ecb);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
873 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
874
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
875 In each case, \textit{cipher} is the index into the cipher\_descriptor array of the cipher you want to use. The \textit{IV} value is
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
876 the initialization vector to be used with the cipher. You must fill the IV yourself and it is assumed they are the same
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
877 length as the block size\footnote{In other words the size of a block of plaintext for the cipher, e.g. 8 for DES, 16 for AES, etc.}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
878 of the cipher you choose. It is important that the IV be random for each unique message you want to encrypt. The
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
879 parameters \textit{key}, \textit{keylen} and \textit{num\_rounds} are the same as in the XXX\_setup() function call. The final parameter
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
880 is a pointer to the structure you want to hold the information for the mode of operation.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
881
1435
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
882 The routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise, they return an error code.
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
883
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
884 \subsubsection{CTR Mode}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
885 In the case of CTR mode there is an additional parameter \textit{ctr\_mode} which specifies the mode that the counter is to be used in.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
886 If \textbf{CTR\_COUNTER\_ LITTLE\_ENDIAN} was specified then the counter will be treated as a little endian value. Otherwise, if
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
887 \textbf{CTR\_COUNTER\_BIG\_ENDIAN} was specified the counter will be treated as a big endian value. As of v1.15 the RFC 3686 style of
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
888 increment then encrypt is also supported. By OR'ing \textbf{LTC\_CTR\_RFC3686} with the CTR \textit{mode} value, ctr\_start() will increment
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
889 the counter before encrypting it for the first time.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
890
1435
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
891 As of V1.17, the library supports variable length counters for CTR mode. The (optional) counter length is specified by OR'ing the octet
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
892 length of the counter against the \textit{ctr\_mode} parameter. The default, zero, indicates that a full block length counter will be used. This also
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
893 ensures backwards compatibility with software that uses older versions of the library.
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
894
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
895 \begin{small}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
896 \begin{verbatim}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
897 symmetric_CTR ctr;
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
898 int err;
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
899 unsigned char IV[16], key[16];
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
900
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
901 /* use a 32-bit little endian counter */
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
902 if ((err = ctr_start(find_cipher("aes"),
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
903 IV, key, 16, 0,
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
904 CTR_COUNTER_LITTLE_ENDIAN | 4,
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
905 &ctr)) != CRYPT_OK) {
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
906 handle_error(err);
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
907 }
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
908 \end{verbatim}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
909 \end{small}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
910
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
911 Changing the counter size has little (really no) effect on the performance of the CTR chaining mode. It is provided for compatibility
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
912 with other software (and hardware) which have smaller fixed sized counters.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
913
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
914 \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
915 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
916 \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
917 \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
918 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
919 int XXX_encrypt(const unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
920 unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
921 unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
922 symmetric_YYY *YYY);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
923
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
924 int XXX_decrypt(const unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
925 unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
926 unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
927 symmetric_YYY *YYY);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
928 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
929 Where \textit{XXX} is one of $\lbrace ecb, cbc, ctr, cfb, ofb \rbrace$.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
930
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
931 In all cases, \textit{len} is the size of the buffer (as number of octets) to encrypt or decrypt. The CTR, OFB and CFB modes are order sensitive but not
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
932 chunk sensitive. That is you can encrypt \textit{ABCDEF} in three calls like \textit{AB}, \textit{CD}, \textit{EF} or two like \textit{ABCDE} and \textit{F}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
933 and end up with the same ciphertext. However, encrypting \textit{ABC} and \textit{DABC} will result in different ciphertexts. All
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
934 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
935
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
936 In the ECB and CBC cases, \textit{len} must be a multiple of the ciphers block size. In the CBC case, you must manually pad the end of your message (either with
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
937 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
938
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
939 To decrypt in either mode, perform the setup like before (recall you have to fetch the IV value you used), and use the decrypt routine on all of the blocks.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
940
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
941 \subsection{IV Manipulation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
942 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
943 \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
944 \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
945 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
946 int XXX_getiv(unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
947 unsigned long *len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
948 symmetric_XXX *XXX);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
949
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
950 int XXX_setiv(const unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
951 unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
952 symmetric_XXX *XXX);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
953 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
954
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
955 The XXX\_getiv() functions will read the IV out of the chaining mode and store it into \textit{IV} along with the length of the IV
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
956 stored in \textit{len}. The XXX\_setiv will initialize the chaining mode state as if the original IV were the new IV specified. The length
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
957 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
958
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
959 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
960
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
961 What the \textit{setiv} function will do depends on the mode being changed. In CBC mode, the new IV replaces the existing IV as if it
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
962 were the last ciphertext block. In CFB mode, the IV is encrypted as if it were the prior encrypted pad. In CTR mode, the IV is encrypted without
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
963 first incrementing it (regardless of the LTC\_RFC\_3686 flag presence). In F8 mode, the IV is encrypted and becomes the new pad. It does not change
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
964 the salted IV, and is only meant to allow seeking within a session. In LRW, it changes the tweak, forcing a computation of the tweak pad, allowing for
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
965 seeking within the session. In OFB mode, the IV is encrypted and becomes the new pad.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
966
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
967 \subsection{Stream Termination}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
968 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
969
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
970 \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
971 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
972 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
973 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
974
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
975 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
976
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
977 \newpage
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
978 \subsection{Examples}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
979 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
980 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
981 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
982 int main(void)
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 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
985 symmetric_CTR ctr;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
986 int x, err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
987
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
988 /* register twofish first */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
989 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
990 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
991 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
992 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
993
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
994 /* 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
995
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
996 /* 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
997 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
998 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
999 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
1000 key, /* the secret key */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1001 16, /* length of secret key (16 bytes) */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1002 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
1003 CTR_COUNTER_LITTLE_ENDIAN, /* Little endian counter */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1004 &ctr) /* where to store the CTR state */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1005 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1006 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
1007 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1008 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1009
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1010 /* 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
1011 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
1012 buffer, /* ciphertext */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1013 sizeof(buffer), /* length of plaintext pt */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1014 &ctr) /* CTR state */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1015 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1016 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
1017 return -1;
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1020 /* 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
1021
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1022 /* 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
1023 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
1024 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
1025 &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
1026 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1027 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
1028 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1029 }
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 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
1032 buffer, /* plaintext */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1033 sizeof(buffer), /* length of plaintext */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1034 &ctr) /* CTR state */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1035 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1036 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
1037 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1038 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1039
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1040 /* terminate the stream */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1041 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
1042 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
1043 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1044 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1045
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1046 /* 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
1047 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
1048 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
1049
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1050 return 0;
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 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1053 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1054
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1055 \subsection{LRW Mode}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1056 LRW mode is a cipher mode which is meant for indexed encryption like used to handle storage media. It is meant to have efficient seeking and overcome the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1057 security problems of ECB mode while not increasing the storage requirements. It is used much like any other chaining mode except with two key differences.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1058
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1059 The key is specified as two strings the first key $K_1$ is the (normally AES) key and can be any length (typically 16, 24 or 32 octets long). The second key
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1060 $K_2$ is the \textit{tweak} key and is always 16 octets long. The tweak value is \textbf{NOT} a nonce or IV value it must be random and secret.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1061
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1062 To initialize LRW mode use:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1063
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1064 \index{lrw\_start()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1065 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1066 int lrw_start( int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1067 const unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1068 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1069 int keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1070 const unsigned char *tweak,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1071 int num_rounds,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1072 symmetric_LRW *lrw);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1073 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1074
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1075 This will initialize the LRW context with the given (16 octet) \textit{IV}, cipher $K_1$ \textit{key} of length \textit{keylen} octets and the (16 octet) $K_2$ \textit{tweak}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1076 While LRW was specified to be used only with AES, LibTomCrypt will allow any 128--bit block cipher to be specified as indexed by \textit{cipher}. The
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1077 number of rounds for the block cipher \textit{num\_rounds} can be 0 to use the default number of rounds for the given cipher.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1078
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1079 To process data use the following functions:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1080
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1081 \index{lrw\_encrypt()} \index{lrw\_decrypt()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1082 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1083 int lrw_encrypt(const unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1084 unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1085 unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1086 symmetric_LRW *lrw);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1087
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1088 int lrw_decrypt(const unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1089 unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1090 unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1091 symmetric_LRW *lrw);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1092 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1093
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1094 These will encrypt (or decrypt) the plaintext to the ciphertext buffer (or vice versa). The length is specified by \textit{len} in octets but must be a multiple
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1095 of 16. The LRW code uses a fast tweak update such that consecutive blocks are encrypted faster than if random seeking where used.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1096
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1097 To manipulate the IV use the following functions:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1098
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1099 \index{lrw\_getiv()} \index{lrw\_setiv()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1100 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1101 int lrw_getiv(unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1102 unsigned long *len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1103 symmetric_LRW *lrw);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1104
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1105 int lrw_setiv(const unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1106 unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1107 symmetric_LRW *lrw);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1108 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1109 These will get or set the 16--octet IV. Note that setting the IV is the same as \textit{seeking} and unlike other modes is not a free operation. It requires
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1110 updating the entire tweak which is slower than sequential use. Avoid seeking excessively in performance constrained code.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1111
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1112 To terminate the LRW state use the following:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1113
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1114 \index{lrw\_done()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1115 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1116 int lrw_done(symmetric_LRW *lrw);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1117 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1118
1435
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1119 \subsection{XTS Mode}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1120 As of v1.17, LibTomCrypt supports XTS mode with code donated by Elliptic Semiconductor Inc.\footnote{www.ellipticsemi.com}.
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1121 XTS is a chaining mode for 128--bit block ciphers, recommended by IEEE (P1619)
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1122 for disk encryption. It is meant to be an encryption mode with random access to the message data without compromising privacy. It requires two private keys (of equal
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1123 length) to perform the encryption process. Each encryption invocation includes a sector number or unique identifier specified as a 128--bit string.
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1124
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1125 To initialize XTS mode use the following function call:
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1126
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1127 \index{xts\_start()}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1128 \begin{verbatim}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1129 int xts_start( int cipher,
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1130 const unsigned char *key1,
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1131 const unsigned char *key2,
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1132 unsigned long keylen,
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1133 int num_rounds,
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1134 symmetric_xts *xts)
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1135 \end{verbatim}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1136 This will start the XTS mode with the two keys pointed to by \textit{key1} and \textit{key2} of length \textit{keylen} octets each.
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1137
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1138 To encrypt or decrypt a sector use the following calls:
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1139
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1140 \index{xts\_encrypt()} \index{xts\_decrypt()}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1141 \begin{verbatim}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1142 int xts_encrypt(
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1143 const unsigned char *pt, unsigned long ptlen,
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1144 unsigned char *ct,
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1145 const unsigned char *tweak,
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1146 symmetric_xts *xts);
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1147
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1148 int xts_decrypt(
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1149 const unsigned char *ct, unsigned long ptlen,
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1150 unsigned char *pt,
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1151 const unsigned char *tweak,
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1152 symmetric_xts *xts);
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1153 \end{verbatim}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1154 The first will encrypt the plaintext pointed to by \textit{pt} of length \textit{ptlen} octets, and store the ciphertext in the array pointed to by
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1155 \textit{ct}. It uses the 128--bit tweak pointed to by \textit{tweak} to encrypt the block. The decrypt function performs the opposite operation. Both
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1156 functions support ciphertext stealing (blocks that are not multiples of 16 bytes).
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1157
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1158 The P1619 specification states the tweak for sector number shall be represented as a 128--bit little endian string.
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1159
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1160 To terminate the XTS state call the following function:
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1161
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1162 \index{xts\_done()}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1163 \begin{verbatim}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1164 void xts_done(symmetric_xts *xts);
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1165 \end{verbatim}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1166
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
1167
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1168 \subsection{F8 Mode}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1169 \index{F8 Mode}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1170 The F8 Chaining mode (see RFC 3711 for instance) is yet another chaining mode for block ciphers. It behaves much like CTR mode in that it XORs a keystream
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1171 against the plaintext to encrypt. F8 mode comes with the additional twist that the counter value is secret, encrypted by a \textit{salt key}. We
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1172 initialize F8 mode with the following function call:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1173
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1174 \index{f8\_start()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1175 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1176 int f8_start( int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1177 const unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1178 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1179 int keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1180 const unsigned char *salt_key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1181 int skeylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1182 int num_rounds,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1183 symmetric_F8 *f8);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1184 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1185 This will start the F8 mode state using \textit{key} as the secret key, \textit{IV} as the counter. It uses the \textit{salt\_key} as IV encryption key
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1186 (\textit{m} in the RFC 3711). The salt\_key can be shorter than the secret key but it should not be longer.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1187
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1188 To encrypt or decrypt data we use the following two functions:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1189
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1190 \index{f8\_encrypt()} \index{f8\_decrypt()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1191 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1192 int f8_encrypt(const unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1193 unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1194 unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1195 symmetric_F8 *f8);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1196
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1197 int f8_decrypt(const unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1198 unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1199 unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1200 symmetric_F8 *f8);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1201 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1202 These will encrypt or decrypt a variable length array of bytes using the F8 mode state specified. The length is specified in bytes and does not have to be a multiple
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1203 of the ciphers block size.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1204
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1205 To change or retrieve the current counter IV value use the following functions:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1206 \index{f8\_getiv()} \index{f8\_setiv()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1207 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1208 int f8_getiv(unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1209 unsigned long *len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1210 symmetric_F8 *f8);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1211
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1212 int f8_setiv(const unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1213 unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1214 symmetric_F8 *f8);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1215 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1216 These work with the current IV value only and not the encrypted IV value specified during the call to f8\_start(). The purpose of these two functions is to be
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1217 able to seek within a current session only. If you want to change the session IV you will have to call f8\_done() and then start a new state with
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1218 f8\_start().
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1219
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1220 To terminate an F8 state call the following function:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1221
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1222 \index{f8\_done()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1223 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1224 int f8_done(symmetric_F8 *f8);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1225 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1226
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1227 \vfil
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1228 \mysection{Encrypt and Authenticate Modes}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1229
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1230 \subsection{EAX Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1231 LibTomCrypt provides support for a mode called EAX\footnote{See
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1232 M. Bellare, P. Rogaway, D. Wagner, A Conventional Authenticated-Encryption Mode.} in a manner similar to the way it was intended to be used
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1233 by the designers. First, a short description of what EAX mode is before we explain how to use it. EAX is a mode that requires a cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1234 CTR and OMAC support and provides encryption and
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1235 authentication\footnote{Note that since EAX only requires OMAC and CTR you may use \textit{encrypt only} cipher descriptors with this mode.}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1236 It is initialized with a random \textit{nonce} that can be shared publicly, a \textit{header} which can be fixed and public, and a random secret symmetric key.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1237
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1238 The \textit{header} data is meant to be meta--data associated with a stream that isn't private (e.g., protocol messages). It can
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1239 be added at anytime during an EAX stream, and is part of the authentication tag. That is, changes in the meta-data can be detected by changes in the output tag.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1240
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1241 The mode can then process plaintext producing ciphertext as well as compute a partial checksum. The actual checksum
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1242 called a \textit{tag} is only emitted when the message is finished. In the interim, the user can process any arbitrary
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1243 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
1244 of operation.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1245
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1246 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
1247 \index{eax\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1248 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1249 int eax_init( eax_state *eax,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1250 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1251 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1252 unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1253 const unsigned char *nonce,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1254 unsigned long noncelen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1255 const unsigned char *header,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1256 unsigned long headerlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1257 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1258
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1259 Where \textit{eax} is the EAX state. The \textit{cipher} parameter is the index of the desired cipher in the descriptor table.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1260 The \textit{key} parameter is the shared secret symmetric key of length \textit{keylen} octets. The \textit{nonce} parameter is the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1261 random public string of length \textit{noncelen} octets. The \textit{header} parameter is the random (or fixed or \textbf{NULL}) header for the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1262 message of length \textit{headerlen} octets.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1263
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1264 When this function completes, the \textit{eax} state will be initialized such that you can now either have data decrypted or
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1265 encrypted in EAX mode. Note: if \textit{headerlen} is zero you may pass \textit{header} as \textbf{NULL} to indicate there is no initial header data.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1266
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1267 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
1268 \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
1269 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1270 int eax_encrypt( eax_state *eax,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1271 const unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1272 unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1273 unsigned long length);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1274
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1275 int eax_decrypt( eax_state *eax,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1276 const unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1277 unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1278 unsigned long length);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1279 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1280 The function \textit{eax\_encrypt} will encrypt the bytes in \textit{pt} of \textit{length} octets, and store the ciphertext in
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1281 \textit{ct}. Note: \textit{ct} and \textit{pt} may be the same region in memory. This function will also send the ciphertext
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1282 through the OMAC function. The function \textit{eax\_decrypt} decrypts \textit{ct}, and stores it in \textit{pt}. This also allows
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1283 \textit{pt} and \textit{ct} to be the same region in memory.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1284
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1285 You cannot both encrypt or decrypt with the same \textit{eax} context. For bi--directional communication you will need to initialize
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1286 two EAX contexts (preferably with different headers and nonces).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1287
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1288 Note: both of these functions allow you to send the data in any granularity but the order is important. While
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1289 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
1290 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
1291
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1292 \index{eax\_addheader()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1293 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1294 int eax_addheader( eax_state *eax,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1295 const unsigned char *header,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1296 unsigned long length);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1297 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1298 This will add the \textit{length} octet from \textit{header} to the given \textit{eax} header. Once the message is finished, the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1299 \textit{tag} (checksum) may be computed with the following function:
285
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 \index{eax\_done()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1302 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1303 int eax_done( eax_state *eax,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1304 unsigned char *tag,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1305 unsigned long *taglen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1306 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1307 This will terminate the EAX state \textit{eax}, and store up to \textit{taglen} bytes of the message tag in \textit{tag}. The function
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1308 then stores how many bytes of the tag were written out back in to \textit{taglen}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1309
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1310 The EAX mode code can be tested to ensure it matches the test vectors by calling the following function:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1311 \index{eax\_test()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1312 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1313 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
1314 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1315 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
1316
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1317 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1318 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1319 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1320 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1321 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1322 eax_state eax;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1323 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
1324 unsigned long taglen;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1325
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1326 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
1327 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
1328 return EXIT_FAILURE;
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1331 /* ... 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
1332
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1333 /* initialize context */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1334 if ((err = eax_init( &eax, /* context */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1335 find_cipher("rijndael"), /* cipher id */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1336 nonce, /* the nonce */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1337 16, /* nonce is 16 bytes */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1338 "TestApp", /* example header */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1339 7) /* header length */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1340 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1341 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
1342 return EXIT_FAILURE;
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1345 /* now encrypt data, say in a loop or whatever */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1346 if ((err = eax_encrypt( &eax, /* eax context */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1347 pt, /* plaintext (source) */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1348 ct, /* ciphertext (destination) */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1349 sizeof(pt) /* size of plaintext */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1350 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1351 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
1352 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1353 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1354
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1355 /* 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
1356 taglen = sizeof(tag);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1357 if ((err = eax_done( &eax, /* eax context */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1358 tag, /* where to put tag */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1359 &taglen /* length of tag space */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1360 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1361 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
1362 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1363 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1364
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1365 /* now we have the authentication tag in "tag" and
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1366 * it's taglen bytes long */
285
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 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1369
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1370 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
1371 following functions.
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 \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
1375 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1376 int eax_encrypt_authenticate_memory(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1377 int cipher,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1378 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
1379 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
1380 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
1381 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
1382 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1383 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
1384
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1385 int eax_decrypt_verify_memory(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1386 int cipher,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1387 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
1388 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
1389 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
1390 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
1391 unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1392 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
1393 int *res);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1394 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1395
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1396 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
1397 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
1398
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1399 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1400 the tag it computed while decrypting the message. If the tags match then it stores a $1$ in \textit{res}, otherwise it stores a $0$.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1401
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1402 \subsection{OCB Mode}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1403 LibTomCrypt provides support for a mode called OCB\footnote{See
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1404 P. Rogaway, M. Bellare, J. Black, T. Krovetz, \textit{OCB: A Block Cipher Mode of Operation for Efficient Authenticated Encryption}.}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1405 . 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
1406 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
1407
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1408 \index{ocb\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1409 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1410 int ocb_init( ocb_state *ocb,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1411 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1412 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1413 unsigned long keylen,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1414 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
1415 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1416
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1417 This will initialize the \textit{ocb} context using cipher descriptor \textit{cipher}. It will use a \textit{key} of length \textit{keylen}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1418 and the random \textit{nonce}. Note that \textit{nonce} must be a random (public) string the same length as the block ciphers
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1419 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
1420
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1421 This mode has no \textit{Associated Data} like EAX mode does which means you cannot authenticate metadata along with the stream.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1422 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
1423
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1424 \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
1425 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1426 int ocb_encrypt( ocb_state *ocb,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1427 const unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1428 unsigned char *ct);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1429
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1430 int ocb_decrypt( ocb_state *ocb,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1431 const unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1432 unsigned char *pt);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1433 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1434
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1435 This will encrypt (or decrypt for the latter) a fixed length of data from \textit{pt} to \textit{ct} (vice versa for the latter).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1436 They assume that \textit{pt} and \textit{ct} are the same size as the block cipher's block size. Note that you cannot call
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1437 both functions given a single \textit{ocb} state. For bi-directional communication you will have to initialize two \textit{ocb}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1438 states (with different nonces). Also \textit{pt} and \textit{ct} may point to the same location in memory.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1439
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1440 \subsubsection{State Termination}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1441
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1442 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
1443
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1444 \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
1445 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1446 int ocb_done_encrypt( ocb_state *ocb,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1447 const unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1448 unsigned long ptlen,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1449 unsigned char *ct,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1450 unsigned char *tag,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1451 unsigned long *taglen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1452 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1453
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1454 This will terminate an encrypt stream \textit{ocb}. If you have trailing bytes of plaintext that will not complete a block
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1455 you can pass them here. This will also encrypt the \textit{ptlen} bytes in \textit{pt} and store them in \textit{ct}. It will also
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1456 store up to \textit{taglen} bytes of the tag into \textit{tag}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1457
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1458 Note that \textit{ptlen} must be less than or equal to the block size of block cipher chosen. Also note that if you have
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1459 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
1460
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1461 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
1462
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1463 \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
1464 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1465 int ocb_done_decrypt( ocb_state *ocb,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1466 const unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1467 unsigned long ctlen,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1468 unsigned char *pt,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1469 const unsigned char *tag,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1470 unsigned long taglen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1471 int *res);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1472 \end{verbatim}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1473 Similarly to the previous function you can pass trailing message bytes into this function. This will compute the
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1474 tag of the message (internally) and then compare it against the \textit{taglen} bytes of \textit{tag} provided. By default
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1475 \textit{res} is set to zero. If all \textit{taglen} bytes of \textit{tag} can be verified then \textit{res} is set to one (authenticated
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1476 message).
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1477
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1478 \subsubsection{Packet Functions}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1479 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
1480
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1481 %\index{ocb\_encrypt\_authenticate\_memory()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1482 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1483 int ocb_encrypt_authenticate_memory(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1484 int cipher,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1485 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
1486 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
1487 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
1488 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1489 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
1490 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1491
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1492 This will OCB encrypt the message \textit{pt} of length \textit{ptlen}, and store the ciphertext in \textit{ct}. The length \textit{ptlen}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1493 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
1494
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1495 \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
1496 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1497 int ocb_decrypt_verify_memory(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1498 int cipher,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1499 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
1500 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
1501 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
1502 unsigned char *pt,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1503 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
1504 int *res);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1505 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1506
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1507 Similarly, this will OCB decrypt, and compare the internally computed tag against the tag provided. \textit{res} is set
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1508 appropriately.
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 \subsection{CCM Mode}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1511 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,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1512 it is only meant for \textit{packet} mode where the length of the input is known in advance. Since it is a packet mode function, CCM only has one
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1513 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
1514
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1515 \index{ccm\_memory()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1516 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1517 int ccm_memory(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1518 int cipher,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1519 const unsigned char *key, unsigned long keylen,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1520 symmetric_key *uskey,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1521 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
1522 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
1523 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
1524 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1525 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
1526 int direction);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1527 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1528
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1529 This performs the \textit{CCM} operation on the data. The \textit{cipher} variable indicates which cipher in the descriptor table to use. It must have a
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1530 16--byte block size for CCM.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1531
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1532 The key can be specified in one of two fashions. First, it can be passed as an array of octets in \textit{key} of length \textit{keylen}. Alternatively,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1533 it can be passed in as a previously scheduled key in \textit{uskey}. The latter fashion saves time when the same key is used for multiple packets. If
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1534 \textit{uskey} is not \textbf{NULL}, then \textit{key} may be \textbf{NULL} (and vice-versa).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1535
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1536 The nonce or salt is \textit{nonce} of length \textit{noncelen} octets. The header is meta--data you want to send with the message but not have
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1537 encrypted, it is stored in \textit{header} of length \textit{headerlen} octets. The header can be zero octets long (if $headerlen = 0$ then
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1538 you can pass \textit{header} as \textbf{NULL}).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1539
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1540 The plaintext is stored in \textit{pt}, and the ciphertext in \textit{ct}. The length of both are expected to be equal and is passed in as \textit{ptlen}. It is
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1541 allowable that $pt = ct$. The \textit{direction} variable indicates whether encryption (direction $=$ \textbf{CCM\_ENCRYPT}) or
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1542 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
1543
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1544 As implemented, this version of CCM cannot handle header or plaintext data longer than $2^{32} - 1$ octets long.
285
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 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
1547
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1548 \index{ccm\_test()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1549 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1550 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
1551 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1552
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1553 This will return \textbf{CRYPT\_OK} if the CCM routine passes known test vectors. It requires AES or Rijndael to be registered previously, otherwise it will
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1554 return \textbf{CRYPT\_NOP}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1555
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1556 \subsubsection{CCM Example}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1557 The following is a sample of how to call CCM.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1558
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1559 \begin{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1560 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1561 #include <tomcrypt.h>
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1562 int main(void)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1563 {
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1564 unsigned char key[16], nonce[12], pt[32], ct[32],
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1565 tag[16], tagcp[16];
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1566 unsigned long taglen;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1567 int err;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1568
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1569 /* register cipher */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1570 register_cipher(&aes_desc);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1571
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1572 /* somehow fill key, nonce, pt */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1573
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1574 /* encrypt it */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1575 taglen = sizeof(tag);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1576 if ((err =
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1577 ccm_memory(find_cipher("aes"),
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1578 key, 16, /* 128-bit key */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1579 NULL, /* not prescheduled */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1580 nonce, 12, /* 96-bit nonce */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1581 NULL, 0, /* no header */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1582 pt, 32, /* 32-byte plaintext */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1583 ct, /* ciphertext */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1584 tag, &taglen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1585 CCM_ENCRYPT)) != CRYPT_OK) {
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1586 printf("ccm_memory error %s\n", error_to_string(err));
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1587 return -1;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1588 }
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1589 /* ct[0..31] and tag[0..15] now hold the output */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1590
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1591 /* decrypt it */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1592 taglen = sizeof(tagcp);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1593 if ((err =
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1594 ccm_memory(find_cipher("aes"),
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1595 key, 16, /* 128-bit key */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1596 NULL, /* not prescheduled */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1597 nonce, 12, /* 96-bit nonce */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1598 NULL, 0, /* no header */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1599 ct, 32, /* 32-byte ciphertext */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1600 pt, /* plaintext */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1601 tagcp, &taglen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1602 CCM_DECRYPT)) != CRYPT_OK) {
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1603 printf("ccm_memory error %s\n", error_to_string(err));
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1604 return -1;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1605 }
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1606
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1607 /* now pt[0..31] should hold the original plaintext,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1608 tagcp[0..15] and tag[0..15] should have the same contents */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1609 }
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1610 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1611 \end{small}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1612
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1613 \subsection{GCM Mode}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1614 Galois counter mode is an IEEE proposal for authenticated encryption (also it is a planned NIST standard). Like EAX and OCB mode, it can be used in a streaming capacity
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1615 however, unlike EAX it cannot accept \textit{additional authentication data} (meta--data) after plaintext has been processed. This mode also only works with
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1616 block ciphers with a 16--byte block.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1617
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1618 A GCM stream is meant to be processed in three modes, one after another. First, the initial vector (per session) data is processed. This should be
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1619 unique to every session. Next, the the optional additional authentication data is processed, and finally the plaintext (or ciphertext depending on the direction).
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1620
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1621 \subsubsection{Initialization}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1622 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
1623
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1624 \index{gcm\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1625 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1626 int gcm_init( gcm_state *gcm,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1627 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1628 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1629 int keylen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1630 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1631 This initializes the GCM state \textit{gcm} for the given cipher indexed by \textit{cipher}, with a secret key \textit{key} of length \textit{keylen} octets. The cipher
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1632 chosen must have a 16--byte block size (e.g., AES).
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1633
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1634 \subsubsection{Initial Vector}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1635 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
1636
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1637 \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
1638 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1639 int gcm_add_iv( gcm_state *gcm,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1640 const unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1641 unsigned long IVlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1642 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1643 This adds the initial vector octets from \textit{IV} of length \textit{IVlen} to the GCM state \textit{gcm}. You can call this function as many times as required
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1644 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
1645
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1646 Note: the GCM protocols provides a \textit{shortcut} for 12--byte IVs where no pre-processing is to be done. If you want to minimize per packet latency it is ideal
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1647 to only use 12--byte IVs. You can just increment it like a counter for each packet.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1648
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1649 \subsubsection{Additional Authentication Data}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1650 After the entire IV has been processed, the additional authentication data can be processed. Unlike the IV, a packet/session does not require additional
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1651 authentication data (AAD) for security. The AAD is meant to be used as side--channel data you want to be authenticated with the packet. Note: once
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1652 you begin adding AAD to the GCM state you cannot return to adding IV data until the state has been reset.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1653
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1654 \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
1655 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1656 int gcm_add_aad( gcm_state *gcm,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1657 const unsigned char *adata,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1658 unsigned long adatalen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1659 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1660 This adds the additional authentication data \textit{adata} of length \textit{adatalen} to the GCM state \textit{gcm}.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1661
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1662 \subsubsection{Plaintext Processing}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1663 After the AAD has been processed, the plaintext (or ciphertext depending on the direction) can be processed.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1664
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1665 \index{gcm\_process()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1666 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1667 int gcm_process( gcm_state *gcm,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1668 unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1669 unsigned long ptlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1670 unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1671 int direction);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1672 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1673 This processes message data where \textit{pt} is the plaintext and \textit{ct} is the ciphertext. The length of both are equal and stored in \textit{ptlen}. Depending on
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1674 the mode \textit{pt} is the input and \textit{ct} is the output (or vice versa). When \textit{direction} equals \textbf{GCM\_ENCRYPT} the plaintext is read,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1675 encrypted and stored in the ciphertext buffer. When \textit{direction} equals \textbf{GCM\_DECRYPT} the opposite occurs.
285
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 \subsubsection{State Termination}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1678 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
1679
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1680 \index{gcm\_done()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1681 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1682 int gcm_done( gcm_state *gcm,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1683 unsigned char *tag,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1684 unsigned long *taglen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1685 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1686 This terminates the GCM state \textit{gcm} and stores the tag in \textit{tag} of length \textit{taglen} octets.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1687
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1688 \subsubsection{State Reset}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1689 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1690 it is very costly to have to call it repeatedly. To aid in this endeavour, the reset function has been provided.
285
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 \index{gcm\_reset()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1693 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1694 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
1695 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1696
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1697 This will reset the GCM state \textit{gcm} to the state that gcm\_init() left it. The user would then call gcm\_add\_iv(), gcm\_add\_aad(), etc.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1698
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1699 \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
1700 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
1701
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1702 \index{gcm\_memory()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1703 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1704 int gcm_memory(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1705 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1706 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1707 unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1708 const unsigned char *IV, unsigned long IVlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1709 const unsigned char *adata, unsigned long adatalen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1710 unsigned char *pt, unsigned long ptlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1711 unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1712 unsigned char *tag, unsigned long *taglen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1713 int direction);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1714 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1715
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1716 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
1717 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
1718
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1719 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
1720
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1721 \subsubsection{Example Usage}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1722 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
1723
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1724 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1725 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1726 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1727
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1728 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
1729 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
1730 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
1731 gcm_state *gcm)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1732 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1733 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1734 unsigned long taglen;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1735 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
1736
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1737 /* reset the state */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1738 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
1739 return err;
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1742 /* Add the IV */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1743 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
1744 return err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1745 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1746
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1747 /* 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
1748 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
1749 return err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1750 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1751
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1752 /* process the plaintext */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1753 if ((err =
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1754 gcm_process(gcm, pt, ptlen, pt, GCM_ENCRYPT)) != CRYPT_OK) {
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1755 return err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1756 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1757
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1758 /* 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
1759 taglen = sizeof(tag);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1760 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
1761 return err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1762 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1763
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1764 /* ... 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
1765
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1766 /* depending on the protocol and how IV is
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1767 * generated you may have to send it too... */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1768 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
1769
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1770 /* send the aad */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1771 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
1772
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1773 /* send the ciphertext */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1774 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
1775
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1776 /* send the tag */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1777 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
1778
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1779 return CRYPT_OK;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1780 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1781
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1782 int main(void)
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 gcm_state gcm;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1785 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
1786 int err, x;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1787 unsigned long ptlen;
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 /* 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
1790
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1791 /* register AES */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1792 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
1793
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1794 /* init the GCM state */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1795 if ((err =
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1796 gcm_init(&gcm, find_cipher("aes"), key, 16)) != CRYPT_OK) {
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1797 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
1798 }
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 /* 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
1801 for (;;) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1802 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
1803
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1804 /* 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
1805 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
1806 if (++IV[x]) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1807 break;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1808 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1809 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1810
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1811 if ((err = send_packet(pt, ptlen, iv, 12, NULL, 0, &gcm))
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1812 != CRYPT_OK) {
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1813 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
1814 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1815 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1816 return EXIT_SUCCESS;
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 \chapter{One-Way Cryptographic Hash Functions}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1822 \mysection{Core Functions}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1823 Like the ciphers, there are hash core functions and a universal data type to hold the hash state called \textit{hash\_state}. To initialize hash
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1824 XXX (where XXX is the name) call:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1825 \index{Hash Functions}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1826 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1827 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
1828 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1829
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1830 This simply sets up the hash to the default state governed by the specifications of the hash. To add data to the message being hashed call:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1831 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1832 int XXX_process( hash_state *md,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1833 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1834 unsigned long inlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1835 \end{verbatim}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1836 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1837 are buffered. The data can be passed in any sized chunks as long as the order of the bytes are the same the message digest (hash output) will be the same. For example,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1838 this means that:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1839 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1840 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
1841 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
1842 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1843 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
1844 \index{Message Digest}
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 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
1847 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1848
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1849 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
1850 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1851 int XXX_done( hash_state *md,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1852 unsigned char *out);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1853 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1854
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1855 This function will finish up the hash and store the result in the \textit{out} array. You must ensure that \textit{out} is long
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1856 enough for the hash in question. Often hashes are used to get keys for symmetric ciphers so the \textit{XXX\_done()} functions
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1857 will wipe the \textit{md} variable before returning automatically.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1858
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1859 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
1860 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1861 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
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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1864 This will return {\bf CRYPT\_OK} if the hash matches the test vectors, otherwise it returns an error code. An
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1865 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
1866 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1867 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1868 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1869 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1870 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1871 hash_state md;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1872 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
1873
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1874 /* setup the hash */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1875 md5_init(&md);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1876
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1877 /* add the message */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1878 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
1879
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1880 /* 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
1881 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
1882
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1883 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1884 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1885 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1886 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1887
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1888 \mysection{Hash Descriptors}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1889 Like the set of ciphers, the set of hashes have descriptors as well. They are stored in an array called \textit{hash\_descriptor} and
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1890 are defined by:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1891 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1892 struct _hash_descriptor {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1893 char *name;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1894
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1895 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
1896 unsigned long blocksize; /* the block size the hash uses */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1897
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1898 void (*init) (hash_state *hash);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1899
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1900 int (*process)( hash_state *hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1901 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1902 unsigned long inlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1903
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1904 int (*done) (hash_state *hash, unsigned char *out);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1905
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1906 int (*test) (void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1907 };
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1908 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1909
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1910 \index{find\_hash()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1911 The \textit{name} member is the name of the hash function (all lowercase). The \textit{hashsize} member is the size of the digest output
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1912 in bytes, while \textit{blocksize} is the size of blocks the hash expects to the compression function. Technically, this detail is not important
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1913 for high level developers but is useful to know for performance reasons.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1914
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1915 The \textit{init} member initializes the hash, \textit{process} passes data through the hash, \textit{done} terminates the hash and retrieves the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1916 digest. The \textit{test} member tests the hash against the specified test vectors.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1917
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1918 There is a function to search the array as well called \textit{int find\_hash(char *name)}. It returns -1 if the hash is not found, otherwise, the
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1919 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
1920
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1921 In addition, there is also find\_hash\_oid() which finds a hash by the ASN.1 OBJECT IDENTIFIER string.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1922 \index{find\_hash\_oid()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1923 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1924 int find_hash_oid(const unsigned long *ID, unsigned long IDlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1925 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1926
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1927 You can use the table to indirectly call a hash function that is chosen at run-time. For example:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1928 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1929 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1930 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1931 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1932 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1933 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
1934 int idx, x;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1935 hash_state md;
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 /* register hashes .... */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1938 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
1939 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
1940 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1941 }
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 /* register other hashes ... */
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 /* 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
1946 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
1947 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
1948 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
1949
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1950 /* get hash index */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1951 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
1952 if (idx == -1) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1953 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
1954 return -1;
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1957 /* 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
1958 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
1959 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
1960 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
1961 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
1962
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1963 /* dump to screen */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1964 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
1965 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
1966 printf("\n");
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1967 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1968 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1969 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1970 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1971
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1972 Note the usage of \textbf{MAXBLOCKSIZE}. In LibTomCrypt, no symmetric block, key or hash digest is larger than \textbf{MAXBLOCKSIZE} in
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1973 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
1974
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1975 There are three helper functions to make working with hashes easier. The first is a function to hash a buffer, and produce the digest in a single
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1976 function call.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1977
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1978 \index{hash\_memory()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1979 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1980 int hash_memory( int hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1981 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1982 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1983 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1984 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1985 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1986
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1987 This will hash the data pointed to by \textit{in} of length \textit{inlen}. The hash used is indexed by the \textit{hash} parameter. The message
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1988 digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1989
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1990 The next helper function allows for the hashing of a file based on a file name.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1991 \index{hash\_file()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1992 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1993 int hash_file( int hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1994 const char *fname,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1995 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1996 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1997 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1998
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
1999 This will hash the file named by \textit{fname} using the hash indexed by \textit{hash}. The file named in this function call must be readable by the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2000 user owning the process performing the request. This function can be omitted by the \textbf{LTC\_NO\_FILE} define, which forces it to return \textbf{CRYPT\_NOP}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2001 when it is called. The message digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2002
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2003 \index{hash\_filehandle()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2004 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2005 int hash_filehandle( int hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2006 FILE *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2007 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2008 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2009 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2010
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2011 This will hash the file identified by the handle \textit{in} using the hash indexed by \textit{hash}. This will begin hashing from the current file pointer position, and
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2012 will not rewind the file pointer when finished. This function can be omitted by the \textbf{LTC\_NO\_FILE} define, which forces it to return \textbf{CRYPT\_NOP}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2013 when it is called. The message digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2014
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2015 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
2016 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2017 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2018 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2019 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2020 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2021 int idx, err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2022 unsigned long len;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2023 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
2024
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2025 /* register the hash */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2026 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
2027 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
2028 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2029 }
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 /* 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
2032 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
2033
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2034 /* call the hash */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2035 len = sizeof(out);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2036 if ((err =
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2037 hash_memory(idx, "hello world", 11, out, &len)) != CRYPT_OK) {
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2038 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
2039 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2040 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2041 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2042 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2043 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2044 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2045
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2046 \subsection{Hash Registration}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2047 Similar to the cipher descriptor table you must register your hash algorithms before you can use them. These functions
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2048 work exactly like those of the cipher registration code. The functions are:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2049 \index{register\_hash()} \index{unregister\_hash()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2050 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2051 int register_hash(const struct _hash_descriptor *hash);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2052
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2053 int unregister_hash(const struct _hash_descriptor *hash);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2054 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2055
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2056 The following hashes are provided as of this release within the LibTomCrypt library:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2057 \index{Hash descriptor table}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2058
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2059 \begin{figure}[here]
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2060 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2061 \begin{tabular}{|c|c|c|}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2062 \hline \textbf{Name} & \textbf{Descriptor Name} & \textbf{Size of Message Digest (bytes)} \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2063 \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
2064 \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
2065 \hline SHA-384 & sha384\_desc & 48 \\
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2066 \hline RIPEMD-320 & rmd160\_desc & 40 \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2067 \hline SHA-256 & sha256\_desc & 32 \\
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2068 \hline RIPEMD-256 & rmd160\_desc & 32 \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2069 \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
2070 \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
2071 \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
2072 \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
2073 \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
2074 \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
2075 \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
2076 \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
2077 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2078 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2079 \end{center}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2080 \caption{Built--In Software Hashes}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2081 \end{figure}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2082 \vfil
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2083
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2084 \mysection{Cipher Hash Construction}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2085 \index{Cipher Hash Construction}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2086 An addition to the suite of hash functions is the \textit{Cipher Hash Construction} or \textit{CHC} mode. In this mode
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2087 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
2088 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
2089
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2090 In order to use the CHC system the developer will have to take a few extra steps. First the \textit{chc\_desc} hash
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2091 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
2092 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
2093 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
2094
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2095 \index{chc\_register()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2096 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2097 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
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 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
2101 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
2102 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
2103
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2104 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2105 \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
2106 \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
2107 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2108
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2109 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
2110
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2111 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2112 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2113 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2114 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2115 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2116
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2117 /* 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
2118 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
2119 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
2120 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2121 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2122 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
2123 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
2124 return EXIT_FAILURE;
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2127 /* 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
2128 if ((err = chc_register(find_cipher("aes"))) != CRYPT_OK) {
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2129 printf("Error binding AES to CHC: %s\n",
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2130 error_to_string(err));
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2131 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2132
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2133 /* now you can use chc_hash in any LTC function
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2134 * [aside from pkcs...] */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2135 }
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2136 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2137
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2138
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2139 \mysection{Notice}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2140 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
2141 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
2142 (e.g. Yarrow).
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 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
2145 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
2146
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2147 \chapter{Message Authentication Codes}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2148 \mysection{HMAC Protocol}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2149 Thanks to Dobes Vandermeer, the library now includes support for hash based message authentication codes, or HMAC for short. An HMAC
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2150 of a message is a keyed authentication code that only the owner of a private symmetric key will be able to verify. The purpose is
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2151 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
2152 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
2153
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2154 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
2155 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2156 unsigned characters. The initialization routine is:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2157 \index{hmac\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2158 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2159 int hmac_init( hmac_state *hmac,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2160 int hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2161 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2162 unsigned long keylen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2163 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2164 The \textit{hmac} parameter is the state for the HMAC code. The \textit{hash} parameter is the index into the descriptor table of the hash you want
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2165 to use to authenticate the message. The \textit{key} parameter is the pointer to the array of chars that make up the key. The \textit{keylen} parameter is the
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2166 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
2167 \index{hmac\_process()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2168 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2169 int hmac_process( hmac_state *hmac,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2170 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2171 unsigned long inlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2172 \end{verbatim}
1435
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
2173 \textit{hmac} is the HMAC state you are working with. \textit{in} is the array of octets to send into the HMAC process. \textit{inlen} is the
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
2174 number of octets to process. Like the hash process routines, you can send the data in arbitrarily sized chunks. When you
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2175 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
2176 \index{hmac\_done()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2177 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2178 int hmac_done( hmac_state *hmac,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2179 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2180 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2181 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2182 The \textit{hmac} parameter is the HMAC state you are working with. The \textit{out} parameter is the array of octets where the HMAC code should be stored.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2183 You must set \textit{outlen} to the size of the destination buffer before calling this function. It is updated with the length of the HMAC code
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2184 produced (depending on which hash was picked). If \textit{outlen} is less than the size of the message digest (and ultimately
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2185 the HMAC code) then the HMAC code is truncated as per FIPS-198 specifications (e.g. take the first \textit{outlen} bytes).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2186
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2187 There are two utility functions provided to make using HMACs easier to do. They accept the key and information about the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2188 message (file pointer, address in memory), and produce the HMAC result in one shot. These are useful if you want to avoid
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2189 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
2190
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2191 \index{hmac\_memory()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2192 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2193 int hmac_memory(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2194 int hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2195 const unsigned char *key, unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2196 const unsigned char *in, unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2197 unsigned char *out, unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2198 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2199 This will produce an HMAC code for the array of octets in \textit{in} of length \textit{inlen}. The index into the hash descriptor
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2200 table must be provided in \textit{hash}. It uses the key from \textit{key} with a key length of \textit{keylen}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2201 The result is stored in the array of octets \textit{out} and the length in \textit{outlen}. The value of \textit{outlen} must be set
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2202 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
2203 \index{hmac\_file()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2204 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2205 int hmac_file(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2206 int hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2207 const char *fname,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2208 const unsigned char *key, unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2209 unsigned char *out, unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2210 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2211 \textit{hash} is the index into the hash descriptor table of the hash you want to use. \textit{fname} is the filename to process.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2212 \textit{key} is the array of octets to use as the key of length \textit{keylen}. \textit{out} is the array of octets where the
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2213 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
2214
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2215 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
2216 \index{hmac\_test()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2217 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2218 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
2219 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2220 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
2221 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
2222
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2223 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2224 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2225 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2226 int main(void)
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 int idx, err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2229 hmac_state hmac;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2230 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
2231 unsigned long dstlen;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2232
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2233 /* register SHA-1 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2234 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
2235 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
2236 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2237 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2238
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2239 /* 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
2240 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
2241
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2242 /* 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
2243
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2244 /* start the HMAC */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2245 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
2246 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
2247 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2248 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2249
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2250 /* 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
2251 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
2252 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
2253 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2254 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2255
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2256 /* 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
2257 dstlen = sizeof(dst);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2258 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
2259 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
2260 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2261 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2262 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
2263
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2264 /* return */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2265 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2266 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2267 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2268 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2269
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2270 \mysection{OMAC Support}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2271 \index{OMAC} \index{CMAC}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2272 OMAC\footnote{\url{http://crypt.cis.ibaraki.ac.jp/omac/omac.html}}, which stands for \textit{One-Key CBC MAC} is an
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2273 algorithm which produces a Message Authentication Code (MAC) using only a block cipher such as AES. Note: OMAC has been standardized as
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2274 CMAC within NIST, for the purposes of this library OMAC and CMAC are synonymous. From an API standpoint, the OMAC routines work much like the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2275 HMAC routines. Instead, in this case a cipher is used instead of a hash.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2276
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2277 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
2278 \index{omac\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2279 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2280 int omac_init( omac_state *omac,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2281 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2282 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2283 unsigned long keylen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2284 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2285 The \textit{omac} parameter is the state for the OMAC algorithm. The \textit{cipher} parameter is the index into the cipher\_descriptor table
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2286 of the cipher\footnote{The cipher must have a 64 or 128 bit block size. Such as CAST5, Blowfish, DES, AES, Twofish, etc.} you
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2287 wish to use. The \textit{key} and \textit{keylen} parameters are the keys used to authenticate the data.
285
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 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
2290 \index{omac\_process()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2291 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2292 int omac_process( omac_state *state,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2293 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2294 unsigned long inlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2295 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2296 This will send \textit{inlen} bytes from \textit{in} through the active OMAC state \textit{state}. Returns \textbf{CRYPT\_OK} if the
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2297 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
2298
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2299 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2300 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
2301 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
2302 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2303
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2304 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
2305
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2306 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2307 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
2308 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2309
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2310 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
2311
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2312 \index{omac\_done()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2313 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2314 int omac_done( omac_state *state,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2315 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2316 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2317 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2318 Which will terminate the OMAC and output the \textit{tag} (MAC) to \textit{out}. Note that unlike the HMAC and other code
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2319 \textit{outlen} can be smaller than the default MAC size (for instance AES would make a 16-byte tag). Part of the OMAC
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2320 specification states that the output may be truncated. So if you pass in $outlen = 5$ and use AES as your cipher than
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2321 the output MAC code will only be five bytes long. If \textit{outlen} is larger than the default size it is set to the default
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2322 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
2323
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2324 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
2325 following function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2326
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2327 \index{omac\_memory()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2328 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2329 int omac_memory(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2330 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2331 const unsigned char *key, unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2332 const unsigned char *in, unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2333 unsigned char *out, unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2334 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2335 This will compute the OMAC of \textit{inlen} bytes of \textit{in} using the key \textit{key} of length \textit{keylen} bytes and the cipher
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2336 specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2337 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
2338
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2339 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
2340 \index{omac\_file()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2341 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2342 int omac_file(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2343 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2344 const unsigned char *key, unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2345 const char *filename,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2346 unsigned char *out, unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2347 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2348
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2349 Which will OMAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2350 and the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2351 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
2352
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2353 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
2354 \index{omac\_test()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2355 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2356 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
2357 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2358 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
2359 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
2360
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2361 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2362 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2363 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2364 int main(void)
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 int idx, err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2367 omac_state omac;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2368 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
2369 unsigned long dstlen;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2370
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2371 /* register Rijndael */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2372 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
2373 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
2374 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2375 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2376
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2377 /* 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
2378 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
2379
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2380 /* 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
2381
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2382 /* start the OMAC */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2383 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
2384 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
2385 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2386 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2387
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2388 /* 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
2389 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
2390 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
2391 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2392 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2393
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2394 /* 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
2395 dstlen = sizeof(dst);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2396 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
2397 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
2398 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2399 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2400 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
2401
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2402 /* return */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2403 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2404 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2405 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2406 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2407
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2408 \mysection{PMAC Support}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2409 The PMAC\footnote{J.Black, P.Rogaway, \textit{A Block--Cipher Mode of Operation for Parallelizable Message Authentication}}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2410 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
2411 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
2412
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2413 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
2414
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2415 \index{pmac\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2416 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2417 int pmac_init( pmac_state *pmac,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2418 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2419 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2420 unsigned long keylen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2421 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2422 Which initializes the \textit{pmac} state with the given \textit{cipher} and \textit{key} of length \textit{keylen} bytes. The chosen cipher
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2423 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
2424
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2425 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
2426
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2427 \index{pmac\_process()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2428 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2429 int pmac_process( pmac_state *state,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2430 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2431 unsigned long inlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2432 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2433 This will process \textit{inlen} bytes of \textit{in} in the given \textit{state}. The function is not sensitive to the granularity of the
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2434 data. For example,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2435
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2436 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2437 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
2438 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
2439 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2440
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2441 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
2442
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2443 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2444 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
2445 \end{verbatim}
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 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
2448
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2449 \index{pmac\_done()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2450 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2451 int pmac_done( pmac_state *state,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2452 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2453 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2454 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2455 This will store up to \textit{outlen} bytes of the tag for the given \textit{state} into \textit{out}. Note that if \textit{outlen} is larger
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2456 than the size of the tag it is set to the amount of bytes stored in \textit{out}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2457
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2458 Similar to the OMAC code the file and memory functions are also provided. To PMAC a buffer of memory in one shot use the
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2459 following function.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2460
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2461 \index{pmac\_memory()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2462 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2463 int pmac_memory(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2464 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2465 const unsigned char *key, unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2466 const unsigned char *in, unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2467 unsigned char *out, unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2468 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2469 This will compute the PMAC of \textit{msglen} bytes of \textit{msg} using the key \textit{key} of length \textit{keylen} bytes, and the cipher
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2470 specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2471 rules as pmac\_done().
285
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 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
2474 \index{pmac\_file()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2475 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2476 int pmac_file(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2477 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2478 const unsigned char *key, unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2479 const char *filename,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2480 unsigned char *out, unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2481 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2482
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2483 Which will PMAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2484 and the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2485 the same rules as pmac\_done().
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2486
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2487 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
2488 \index{pmac\_test()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2489 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2490 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
2491 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2492 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
2493
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2494 \mysection{Pelican MAC}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2495 Pelican MAC is a new (experimental) MAC by the AES team that uses four rounds of AES as a \textit{mixing function}. It achieves a very high
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2496 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
2497 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
2498
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2499 \index{pelican\_init()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2500 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2501 int pelican_init( pelican_state *pelmac,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2502 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2503 unsigned long keylen);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2504 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2505 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
2506
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2507 \index{pelican\_process()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2508 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2509 int pelican_process( pelican_state *pelmac,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2510 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2511 unsigned long inlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2512 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2513 This will process \textit{inlen} bytes of \textit{in} through the Pelican MAC. It's best that you pass in multiples of 16 bytes as it makes the
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2514 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
2515 an entire message.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2516
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2517 \index{pelican\_done()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2518 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2519 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
2520 \end{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2521 This terminates a Pelican MAC and writes the 16--octet tag to \textit{out}.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2522
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2523 \subsection{Example}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2524
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2525 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2526 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2527 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2528 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2529 pelican_state pelstate;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2530 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
2531 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2532
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2533 /* 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
2534
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2535 /* initialize pelican mac */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2536 if ((err = pelican_init(&pelstate, /* the state */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2537 key, /* user key */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2538 32 /* key length in octets */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2539 )) != CRYPT_OK) {
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2540 printf("Error initializing Pelican: %s",
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2541 error_to_string(err));
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2542 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2543 }
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 /* MAC some data */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2546 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
2547 "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
2548 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
2549 )) != CRYPT_OK) {
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2550 printf("Error processing Pelican: %s",
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2551 error_to_string(err));
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2552 return EXIT_FAILURE;
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2555 /* Terminate the MAC */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2556 if ((err = pelican_done(&pelstate,/* the state */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2557 tag /* where to store the tag */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2558 )) != CRYPT_OK) {
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2559 printf("Error terminating Pelican: %s",
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2560 error_to_string(err));
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2561 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2562 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2563
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2564 /* 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
2565
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2566 return EXIT_SUCCESS;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2567 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2568 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2569
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2570 \mysection{XCBC-MAC}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2571 As of LibTomCrypt v1.15, XCBC-MAC (RFC 3566) has been provided to support TLS encryption suites. Like OMAC, it computes a message authentication code
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2572 by using a cipher in CBC mode. It also uses a single key which it expands into the requisite three keys for the MAC function. A XCBC--MAC state is
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2573 initialized with the following function:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2574
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2575 \index{xcbc\_init()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2576 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2577 int xcbc_init( xcbc_state *xcbc,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2578 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2579 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2580 unsigned long keylen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2581 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2582
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2583 This will initialize the XCBC--MAC state \textit{xcbc}, with the key specified in \textit{key} of length \textit{keylen} octets. The cipher indicated
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2584 by the \textit{cipher} index can be either a 64 or 128--bit block cipher. This will return \textbf{CRYPT\_OK} on success.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2585
1435
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
2586 \index{LTC\_XCBC\_PURE}
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
2587 It is possible to use XCBC in a three key mode by OR'ing the value \textbf{LTC\_XCBC\_PURE} against the \textit{keylen} parameter. In this mode, the key is
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
2588 interpretted as three keys. If the cipher has a block size of $n$ octets, the first key is then $keylen - 2n$ octets and is the encryption key. The next
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
2589 $2n$ octets are the $K_1$ and $K_2$ padding keys (used on the last block). For example, to use AES--192 \textit{keylen} should be $24 + 2 \cdot 16 = 56$ octets.
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
2590 The three keys are interpretted as if they were concatenated in the \textit{key} buffer.
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
2591
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
2592
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2593 To process data through XCBC--MAC use the following function:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2594
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2595 \index{xcbc\_process()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2596 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2597 int xcbc_process( xcbc_state *state,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2598 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2599 unsigned long inlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2600 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2601
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2602 This will add the message octets pointed to by \textit{in} of length \textit{inlen} to the XCBC--MAC state pointed to by \textit{state}. Like the other MAC functions,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2603 the granularity of the input is not important but the order is. This will return \textbf{CRYPT\_OK} on success.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2604
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2605 To compute the MAC tag value use the following function:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2606
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2607 \index{xcbc\_done()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2608 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2609 int xcbc_done( xcbc_state *state,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2610 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2611 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2612 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2613
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2614 This will retrieve the XCBC--MAC tag from the state pointed to by \textit{state}, and store it in the array pointed to by \textit{out}. The \textit{outlen} parameter
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2615 specifies the maximum size of the destination buffer, and is updated to hold the final size of the tag when the function returns. This will return \textbf{CRYPT\_OK} on success.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2616
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2617 Helper functions are provided to make parsing memory buffers and files easier. The following functions are provided:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2618
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2619 \index{xcbc\_memory()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2620 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2621 int xcbc_memory(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2622 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2623 const unsigned char *key, unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2624 const unsigned char *in, unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2625 unsigned char *out, unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2626 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2627 This will compute the XCBC--MAC of \textit{msglen} bytes of \textit{msg}, using the key \textit{key} of length \textit{keylen} bytes, and the cipher
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2628 specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same rules as xcbc\_done().
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2629
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2630 To xcbc a file use
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2631 \index{xcbc\_file()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2632 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2633 int xcbc_file(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2634 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2635 const unsigned char *key, unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2636 const char *filename,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2637 unsigned char *out, unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2638 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2639
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2640 Which will XCBC--MAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, and the cipher
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2641 specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same rules as xcbc\_done().
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2642
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2643
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2644 To test XCBC--MAC for RFC 3566 compliance use the following function:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2645
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2646 \index{xcbc\_test()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2647 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2648 int xcbc_test(void);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2649 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2650
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2651 This will return \textbf{CRYPT\_OK} on success. This requires the AES or Rijndael descriptor be previously registered, otherwise, it will return
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2652 \textbf{CRYPT\_NOP}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2653
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2654 \mysection{F9--MAC}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2655 The F9--MAC is yet another CBC--MAC variant proposed for the 3GPP standard. Originally specified to be used with the KASUMI block cipher, it can also be used
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2656 with other ciphers. For LibTomCrypt, the F9--MAC code can use any cipher.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2657
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2658 \subsection{Usage Notice}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2659 F9--MAC differs slightly from the other MAC functions in that it requires the caller to perform the final message padding. The padding quite simply is a direction
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2660 bit followed by a 1 bit and enough zeros to make the message a multiple of the cipher block size. If the message is byte aligned, the padding takes on the form of
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2661 a single 0x40 or 0xC0 byte followed by enough 0x00 bytes to make the message proper multiple.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2662
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2663 If the user simply wants a MAC function (hint: use OMAC) padding with a single 0x40 byte should be sufficient for security purposes and still be reasonably compatible
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2664 with F9--MAC.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2665
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2666 \subsection{F9--MAC Functions}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2667 A F9--MAC state is initialized with the following function:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2668 \index{f9\_init()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2669 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2670 int f9_init( f9_state *f9,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2671 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2672 const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2673 unsigned long keylen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2674 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2675
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2676 This will initialize the F9--MAC state \textit{f9}, with the key specified in \textit{key} of length \textit{keylen} octets. The cipher indicated
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2677 by the \textit{cipher} index can be either a 64 or 128--bit block cipher. This will return \textbf{CRYPT\_OK} on success.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2678
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2679 To process data through F9--MAC use the following function:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2680 \index{f9\_process()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2681 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2682 int f9_process( f9_state *state,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2683 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2684 unsigned long inlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2685 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2686
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2687 This will add the message octets pointed to by \textit{in} of length \textit{inlen} to the F9--MAC state pointed to by \textit{state}. Like the other MAC functions,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2688 the granularity of the input is not important but the order is. This will return \textbf{CRYPT\_OK} on success.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2689
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2690 To compute the MAC tag value use the following function:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2691
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2692 \index{f9\_done()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2693 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2694 int f9_done( f9_state *state,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2695 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2696 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2697 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2698
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2699 This will retrieve the F9--MAC tag from the state pointed to by \textit{state}, and store it in the array pointed to by \textit{out}. The \textit{outlen} parameter
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2700 specifies the maximum size of the destination buffer, and is updated to hold the final size of the tag when the function returns. This will return
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2701 \textbf{CRYPT\_OK} on success.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2702
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2703 Helper functions are provided to make parsing memory buffers and files easier. The following functions are provided:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2704
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2705 \index{f9\_memory()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2706 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2707 int f9_memory(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2708 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2709 const unsigned char *key, unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2710 const unsigned char *in, unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2711 unsigned char *out, unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2712 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2713 This will compute the F9--MAC of \textit{msglen} bytes of \textit{msg}, using the key \textit{key} of length \textit{keylen} bytes, and the cipher
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2714 specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same rules as f9\_done().
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2715
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2716 To F9--MAC a file use
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2717 \index{f9\_file()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2718 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2719 int f9_file(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2720 int cipher,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2721 const unsigned char *key, unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2722 const char *filename,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2723 unsigned char *out, unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2724 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2725
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2726 Which will F9--MAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, and the cipher
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2727 specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same rules as f9\_done().
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2728
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2729
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2730 To test f9--MAC for RFC 3566 compliance use the following function:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2731
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2732 \index{f9\_test()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2733 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2734 int f9_test(void);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2735 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2736
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2737 This will return \textbf{CRYPT\_OK} on success. This requires the AES or Rijndael descriptor be previously registered, otherwise, it will return
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2738 \textbf{CRYPT\_NOP}.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2739
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2740 \chapter{Pseudo-Random Number Generators}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2741 \mysection{Core Functions}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2742 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
2743 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)
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2744 key generation. There is a universal structure called \textit{prng\_state}. To initialize a PRNG call:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2745 \index{PRNG start}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2746 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2747 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
2748 \end{verbatim}
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 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
2751 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
2752 \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
2753 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2754 int XXX_add_entropy(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2755 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2756 prng_state *prng);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2757 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2758 Which returns {\bf CRYPT\_OK} if the entropy was accepted. Once you think you have enough entropy you call another
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2759 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
2760 \index{PRNG ready}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2761 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2762 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
2763 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2764
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2765 Which returns {\bf CRYPT\_OK} if it is ready. Finally to actually read bytes call:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2766 \index{PRNG read}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2767 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2768 unsigned long XXX_read(unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2769 unsigned long outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2770 prng_state *prng);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2771 \end{verbatim}
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 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
2774 the following.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2775
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2776 \index{PRNG done}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2777 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2778 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
2779 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2780
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2781 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
2782 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
2783
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2784 \index{PRNG export}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2785 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2786 int XXX_export(unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2787 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2788 prng_state *prng);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2789 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2790
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2791 This will write a \textit{PRNG state} to the buffer \textit{out} of length \textit{outlen} bytes. The idea of
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2792 the export is meant to be used as a \textit{seed file}. That is, when the program starts up there will not likely
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2793 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
2794
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2795 \index{PRNG import}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2796 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2797 int XXX_import(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2798 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2799 prng_state *prng);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2800 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2801
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2802 This will call the start and add\_entropy functions of the given PRNG. It will use the state in
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2803 \textit{in} of length \textit{inlen} as the initial seed. You must pass the same seed length as was exported
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2804 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
2805
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2806 Note that importing a state will not \textit{resume} the PRNG from where it left off. That is, if you export
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2807 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
2808 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
2809
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2810 When a program is first executed the normal course of operation is:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2811
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2812 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2813 \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
2814 \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
2815 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2816
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2817 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
2818 flash memory, etc). The next time your application starts up you can detect the state, feed it to the
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2819 import function and go on your way. It is ideal that (as soon as possible) after start up you export a
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2820 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
2821 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
2822
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2823 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
2824 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
2825
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2826 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
2827
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2828 \index{PRNG test}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2829 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2830 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
2831 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2832
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2833 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
2834
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2835 \subsection{Remarks}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2836
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2837 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
2838 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
2839 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2840 checking is guaranteed to see if the entropy is sufficient, or if the PRNG is even in a ready state before reading.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2841
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2842 \subsection{Example}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2843 Below is a simple snippet to read 10 bytes from Yarrow. It is important to note that this snippet is {\bf NOT} secure since
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2844 the entropy added is not random.
285
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 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2847 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2848 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2849 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2850 prng_state prng;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2851 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
2852 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2853
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2854 /* start it */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2855 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
2856 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
2857 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2858 /* add entropy */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2859 if ((err = yarrow_add_entropy("hello world", 11, &prng))
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2860 != CRYPT_OK) {
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2861 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
2862 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2863 /* ready and read */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2864 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
2865 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
2866 }
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2867 printf("Read %lu bytes from yarrow\n",
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2868 yarrow_read(buf, sizeof(buf), &prng));
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2869 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2870 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2871 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2872
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2873 \mysection{PRNG Descriptors}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2874 \index{PRNG Descriptor}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2875 PRNGs have descriptors that allow plugin driven functions to be created using PRNGs. The plugin descriptors are stored in the structure \textit{prng\_descriptor}. The
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2876 format of an element is:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2877 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2878 struct _prng_descriptor {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2879 char *name;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2880 int export_size; /* size in bytes of exported state */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2881
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2882 int (*start) (prng_state *);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2883
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2884 int (*add_entropy)(const unsigned char *, unsigned long,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2885 prng_state *);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2886
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2887 int (*ready) (prng_state *);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2888
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2889 unsigned long (*read)(unsigned char *, unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2890 prng_state *);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2891
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2892 void (*done)(prng_state *);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2893
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2894 int (*export)(unsigned char *, unsigned long *, prng_state *);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2895
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2896 int (*import)(const unsigned char *, unsigned long, prng_state *);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2897
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2898 int (*test)(void);
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 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2901
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2902 To find a PRNG in the descriptor table the following function can be used:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2903 \index{find\_prng()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2904 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2905 int find_prng(const char *name);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2906 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2907 This will search the PRNG descriptor table for the PRNG named \textit{name}. It will return -1 if the PRNG is not found, otherwise, it returns
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2908 the index into the descriptor table.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2909
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2910 Just like the ciphers and hashes, you must register your prng before you can use it. The two functions provided work exactly as those for the cipher registry functions.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2911 They are the following:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2912 \index{register\_prng()} \index{unregister\_prng()}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2913 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2914 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
2915 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
2916 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2917
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2918 The register function will register the PRNG, and return the index into the table where it was placed (or -1 for error). It will avoid registering the same
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2919 descriptor twice, and will return the index of the current placement in the table if the caller attempts to register it more than once. The unregister function
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2920 will return \textbf{CRYPT\_OK} if the PRNG was found and removed. Otherwise, it returns \textbf{CRYPT\_ERROR}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2921
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2922 \subsection{PRNGs Provided}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2923 \begin{figure}[here]
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2924 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2925 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2926 \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
2927 \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
2928 \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
2929 \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
2930 \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
2931 \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
2932 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2933 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2934 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2935 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2936 \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
2937 \end{figure}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2938
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2939 \subsubsection{Yarrow}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2940 Yarrow is fast PRNG meant to collect an unspecified amount of entropy from sources
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2941 (keyboard, mouse, interrupts, etc), and produce an unbounded string of random bytes.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2942
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2943 \textit{Note:} This PRNG is still secure for most tasks but is no longer recommended. Users
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2944 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
2945
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2946 \subsubsection{Fortuna}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2947
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2948 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
2949 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
2950 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
2951 providing more security.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2952
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2953 Fortuna is slightly less flexible than Yarrow in the sense that it only works with the AES block cipher
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2954 and SHA--256 hash function. Technically, Fortuna will work with any block cipher that accepts a 256--bit
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2955 key, and any hash that produces at least a 256--bit output. However, to make the implementation simpler
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2956 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
2957
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2958 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
2959 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
2960 details Fortuna has the ability to recover from state determination attacks where the attacker starts
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2961 to learn information from the PRNGs output about the internal state. Yarrow on the other hand, cannot
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2962 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
2963
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2964 \subsubsection{RC4}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2965
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2966 RC4 is an old stream cipher that can also double duty as a PRNG in a pinch. You key RC4 by
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2967 calling add\_entropy(), and setup the key by calling ready(). You can only add up to 256 bytes via
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2968 add\_entropy().
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2969
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2970 When you read from RC4, the output is XOR'ed against your buffer you provide. In this manner, you can use rc4\_read()
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2971 as an encrypt (and decrypt) function.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2972
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2973 You really should not use RC4. This is not because RC4 is weak, (though biases are known to exist) but simply due to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2974 the fact that faster alternatives exist.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2975
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2976 \subsubsection{SOBER-128}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2977
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2978 SOBER--128 is a stream cipher designed by the QUALCOMM Australia team. Like RC4, you key it by
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2979 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
2980
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2981 Note: this cipher has several oddities about how it operates. The first call to add\_entropy() sets the cipher's key.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2982 Every other time call to the add\_entropy() function sets the cipher's IV variable. The IV mechanism allows you to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2983 encrypt several messages with the same key, and not re--use the same key material.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2984
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2985 Unlike Yarrow and Fortuna, all of the entropy (and hence security) of this algorithm rests in the data
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2986 you pass it on the \textbf{first} call to add\_entropy(). All buffers sent to add\_entropy() must have a length
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2987 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
2988
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2989 Like RC4, the output of SOBER--128 is XOR'ed against the buffer you provide it. In this manner, you can use
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2990 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
2991
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2992 Since SOBER-128 has a fixed keying scheme, and is very fast (faster than RC4) the ideal usage of SOBER-128 is to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
2993 key it from the output of Fortuna (or Yarrow), and use it to encrypt messages. It is also ideal for
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2994 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
2995
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2996 \subsubsection{Example Usage}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2997 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2998 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2999 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3000 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3001 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3002 prng_state prng;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3003 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
3004 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3005
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3006 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
3007 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
3008 exit(-1);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3009 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3010
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3011 /* use "key" as the key */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3012 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
3013 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
3014 exit(-1);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3015 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3016
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3017 /* 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
3018 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
3019 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
3020 exit(-1);
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3023 /* encrypt buffer */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3024 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
3025 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
3026 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
3027 exit(-1);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3028 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3029 return 0;
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 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3032 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3033 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
3034
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3035 \mysection{The Secure RNG}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3036 \index{Secure RNG}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3037 An RNG is related to a PRNG in many ways, except that it does not expand a smaller seed to get the data. They generate their random bits
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3038 by performing some computation on fresh input bits. Possibly the hardest thing to get correctly in a cryptosystem is the
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3039 PRNG. Computers are deterministic that try hard not to stray from pre--determined paths. This makes gathering entropy needed to seed a PRNG
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3040 a hard task.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3041
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3042 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
3043 \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
3044 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3045 unsigned long rng_get_bytes(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3046 unsigned char *buf,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3047 unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3048 void (*callback)(void));
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3049 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3050
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3051 Which will try one of three methods of getting random data. The first is to open the popular \textit{/dev/random} device which
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3052 on most *NIX platforms provides cryptographic random bits\footnote{This device is available in Windows through the Cygwin compiler suite. It emulates \textit{/dev/random} via the Microsoft CSP.}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3053 The second method is to try the Microsoft Cryptographic Service Provider, and read the RNG. The third method is an ANSI C
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3054 clock drift method that is also somewhat popular but gives bits of lower entropy. The \textit{callback} parameter is a pointer to a function that returns void. It is
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3055 used when the slower ANSI C RNG must be used so the calling application can still work. This is useful since the ANSI C RNG has a throughput of roughly three
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3056 bytes a second. The callback pointer may be set to {\bf NULL} to avoid using it if you do not want to. The function returns the number of bytes actually read from
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3057 any RNG source. There is a function to help setup a PRNG as well:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3058 \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
3059 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3060 int rng_make_prng( int bits,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3061 int wprng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3062 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3063 void (*callback)(void));
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3064 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3065 This will try to initialize the prng with a state of at least \textit{bits} of entropy. The \textit{callback} parameter works much like
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3066 the callback in \textit{rng\_get\_bytes()}. It is highly recommended that you use this function to setup your PRNGs unless you have a
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3067 platform where the RNG does not work well. Example usage of this function is given below:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3068
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3069 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3070 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3071 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3072 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3073 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3074 ecc_key mykey;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3075 prng_state prng;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3076 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3077
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3078 /* register yarrow */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3079 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
3080 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
3081 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3082 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3083
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3084 /* setup the PRNG */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3085 if ((err = rng_make_prng(128, find_prng("yarrow"), &prng, NULL))
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3086 != CRYPT_OK) {
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3087 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
3088 return -1;
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3091 /* make a 192-bit ECC key */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3092 if ((err = ecc_make_key(&prng, find_prng("yarrow"), 24, &mykey))
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3093 != CRYPT_OK) {
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3094 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
3095 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3096 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3097 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3098 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3099 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3100 \end{small}
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 \subsection{The Secure PRNG Interface}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3103 It is possible to access the secure RNG through the PRNG interface, and in turn use it within dependent functions such
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3104 as the PK API. This simplifies the cryptosystem on platforms where the secure RNG is fast. The secure PRNG never
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3105 requires to be started, that is you need not call the start, add\_entropy, or ready functions. For example, consider
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3106 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
3107
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3108 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3109 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3110 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3111 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3112 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3113 ecc_key mykey;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3114 int err;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3115
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3116 /* register SPRNG */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3117 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
3118 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
3119 return -1;
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3122 /* make a 192-bit ECC key */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3123 if ((err = ecc_make_key(NULL, find_prng("sprng"), 24, &mykey))
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3124 != CRYPT_OK) {
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3125 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
3126 return -1;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3127 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3128 return 0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3129 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3130 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3131 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3132
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3133 \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
3134
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3135 \mysection{Introduction}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3136 RSA wrote the PKCS \#1 specifications which detail RSA Public Key Cryptography. In the specifications are
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3137 padding algorithms for encryption and signatures. The standard includes the \textit{v1.5} and \textit{v2.1} algorithms.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3138 To simplify matters a little the v2.1 encryption and signature padding algorithms are called OAEP and PSS respectively.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3139
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3140 \mysection{PKCS \#1 Padding}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3141 PKCS \#1 v1.5 padding is so simple that both signature and encryption padding are performed by the same function. Note: the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3142 signature padding does \textbf{not} include the ASN.1 padding required. That is performed by the rsa\_sign\_hash\_ex() function
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3143 documented later on in this chapter.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3144
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3145 \subsection{PKCS \#1 v1.5 Encoding}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3146 The following function performs PKCS \#1 v1.5 padding:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3147 \index{pkcs\_1\_v1\_5\_encode()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3148 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3149 int pkcs_1_v1_5_encode(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3150 const unsigned char *msg,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3151 unsigned long msglen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3152 int block_type,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3153 unsigned long modulus_bitlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3154 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3155 int prng_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3156 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3157 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3158 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3159
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3160 This will encode the message pointed to by \textit{msg} of length \textit{msglen} octets. The \textit{block\_type} parameter must be set to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3161 \textbf{LTC\_PKCS\_1\_EME} to perform encryption padding. It must be set to \textbf{LTC\_PKCS\_1\_EMSA} to perform signature padding. The \textit{modulus\_bitlen}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3162 parameter indicates the length of the modulus in bits. The padded data is stored in \textit{out} with a length of \textit{outlen} octets. The output will not be
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3163 longer than the modulus which helps allocate the correct output buffer size.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3164
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3165 Only encryption padding requires a PRNG. When performing signature padding the \textit{prng\_idx} parameter may be left to zero as it is not checked for validity.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3166
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3167 \subsection{PKCS \#1 v1.5 Decoding}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3168 The following function performs PKCS \#1 v1.5 de--padding:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3169 \index{pkcs\_1\_v1\_5\_decode()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3170 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3171 int pkcs_1_v1_5_decode(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3172 const unsigned char *msg,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3173 unsigned long msglen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3174 int block_type,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3175 unsigned long modulus_bitlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3176 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3177 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3178 int *is_valid);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3179 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3180 \index{LTC\_PKCS\_1\_EME} \index{LTC\_PKCS\_1\_EMSA}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3181 This will remove the PKCS padding data pointed to by \textit{msg} of length \textit{msglen}. The decoded data is stored in \textit{out} of length
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3182 \textit{outlen}. If the padding is valid, a 1 is stored in \textit{is\_valid}, otherwise, a 0 is stored. The \textit{block\_type} parameter must be set to either
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3183 \textbf{LTC\_PKCS\_1\_EME} or \textbf{LTC\_PKCS\_1\_EMSA} depending on whether encryption or signature padding is being removed.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3184
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3185 \mysection{PKCS \#1 v2.1 Encryption}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3186 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
3187 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
3188
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3189 \subsection{OAEP Encoding}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3190
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3191 The following function performs PKCS \#1 v2.1 encryption padding:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3192
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3193 \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
3194 \begin{alltt}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3195 int pkcs_1_oaep_encode(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3196 const unsigned char *msg,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3197 unsigned long msglen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3198 const unsigned char *lparam,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3199 unsigned long lparamlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3200 unsigned long modulus_bitlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3201 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3202 int prng_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3203 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3204 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3205 unsigned long *outlen);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3206 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3207
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3208 This accepts \textit{msg} as input of length \textit{msglen} which will be OAEP padded. The \textit{lparam} variable is an additional system specific
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3209 tag that can be applied to the encoding. This is useful to identify which system encoded the message. If no variance is desired then
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3210 \textit{lparam} can be set to \textbf{NULL}.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3211
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3212 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3213 \textit{modulus\_bitlen}. \textit{hash\_idx} is the index into the hash descriptor table of the hash desired. PKCS \#1 allows any hash to be
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3214 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3215 sized input message. \textit{prng\_idx} and \textit{prng} are the random number generator arguments required to randomize the padding process.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3216 The padded message is stored in \textit{out} along with the length in \textit{outlen}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3217
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3218 If $h$ is the length of the hash and $m$ the length of the modulus (both in octets) then the maximum payload for \textit{msg} is
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3219 $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
3220
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3221 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
3222 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
3223
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3224 \subsection{OAEP Decoding}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3225
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3226 \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
3227 \begin{alltt}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3228 int pkcs_1_oaep_decode(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3229 const unsigned char *msg,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3230 unsigned long msglen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3231 const unsigned char *lparam,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3232 unsigned long lparamlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3233 unsigned long modulus_bitlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3234 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3235 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3236 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3237 int *res);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3238 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3239
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3240 This function decodes an OAEP encoded message and outputs the original message that was passed to the OAEP encoder. \textit{msg} is the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3241 output of pkcs\_1\_oaep\_encode() of length \textit{msglen}. \textit{lparam} is the same system variable passed to the OAEP encoder. If it does not
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3242 match what was used during encoding this function will not decode the packet. \textit{modulus\_bitlen} is the size of the RSA modulus in bits
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3243 and must match what was used during encoding. Similarly the \textit{hash\_idx} index into the hash descriptor table must match what was used
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3244 during encoding.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3245
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3246 If the function succeeds it decodes the OAEP encoded message into \textit{out} of length \textit{outlen} and stores a
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3247 $1$ in \textit{res}. If the packet is invalid it stores $0$ in \textit{res} and if the function fails for another reason
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3248 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
3249
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3250 \mysection{PKCS \#1 Digital Signatures}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3251
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3252 \subsection{PSS Encoding}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3253 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
3254
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3255 \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
3256 \begin{alltt}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3257 int pkcs_1_pss_encode(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3258 const unsigned char *msghash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3259 unsigned long msghashlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3260 unsigned long saltlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3261 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3262 int prng_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3263 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3264 unsigned long modulus_bitlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3265 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3266 unsigned long *outlen);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3267 \end{alltt}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3268
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3269 This function assumes the message to be PSS encoded has previously been hashed. The input hash \textit{msghash} is of length
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3270 \textit{msghashlen}. PSS allows a variable length random salt (it can be zero length) to be introduced in the signature process.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3271 \textit{hash\_idx} is the index into the hash descriptor table of the hash to use. \textit{prng\_idx} and \textit{prng} are the random
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3272 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
3273
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3274 Similar to OAEP encoding \textit{modulus\_bitlen} is the size of the RSA modulus (in bits). It limits the size of the salt. If $m$ is the length
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3275 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
3276
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3277 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
3278
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3279 \subsection{PSS Decoding}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3280
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3281 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
3282
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3283 \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
3284 \begin{alltt}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3285 int pkcs_1_pss_decode(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3286 const unsigned char *msghash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3287 unsigned long msghashlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3288 const unsigned char *sig,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3289 unsigned long siglen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3290 unsigned long saltlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3291 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3292 unsigned long modulus_bitlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3293 int *res);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3294 \end{alltt}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3295 This will decode the PSS encoded message in \textit{sig} of length \textit{siglen} and compare it to values in \textit{msghash} of length
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3296 \textit{msghashlen}. If the block is a valid PSS block and the decoded hash equals the hash supplied \textit{res} is set to non--zero. Otherwise,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3297 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
3298
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3299 It's important to use the same \textit{saltlen} and hash for both encoding and decoding as otherwise the procedure will not work.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3300
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3301 \mysection{RSA Key Operations}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3302 \subsection{Background}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3303
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3304 RSA is a public key algorithm that is based on the inability to find the \textit{e-th} root modulo a composite of unknown
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3305 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
3306 not strictly equivalent.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3307
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3308 The system begins with with two primes $p$ and $q$ and their product $N = pq$. The order or \textit{Euler totient} of the
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3309 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
3310 $\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
3311 $\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
3312 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
3313
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3314 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
3315 $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
3316 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
3317 $C^d \equiv \left (M^e \right)^d \equiv M^1 \equiv M\mbox{ }(\mbox{mod }N)$. Similarly the owner of the private key
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3318 can sign a message by \textit{decrypting} it. Others can verify it by \textit{encrypting} it.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3319
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3320 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
3321 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
3322 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
3323 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
3324 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
3325
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3326 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
3327 $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
3328 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
3329 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
3330 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
3331
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3332 \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
3333
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3334 For RSA routines a single \textit{rsa\_key} structure is used. To make a new RSA key call:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3335 \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
3336 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3337 int rsa_make_key(prng_state *prng,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3338 int wprng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3339 int size,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3340 long e,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3341 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3342 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3343
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3344 Where \textit{wprng} is the index into the PRNG descriptor array. The \textit{size} parameter is the size in bytes of the RSA modulus desired.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3345 The \textit{e} parameter is the encryption exponent desired, typical values are 3, 17, 257 and 65537. Stick with 65537 since it is big enough to prevent
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3346 trivial math attacks, and not super slow. The \textit{key} parameter is where the constructed key is placed. All keys must be at
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3347 least 128 bytes, and no more than 512 bytes in size (\textit{that is from 1024 to 4096 bits}).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3348
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3349 \index{rsa\_free()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3350 Note: the \textit{rsa\_make\_key()} function allocates memory at run--time when you make the key. Make sure to call
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3351 \textit{rsa\_free()} (see below) when you are finished with the key. If \textit{rsa\_make\_key()} fails it will automatically
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3352 free the memory allocated.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3353
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3354 \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
3355 There are two types of RSA keys. The types are {\bf PK\_PRIVATE} and {\bf PK\_PUBLIC}. The first type is a private
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3356 RSA key which includes the CRT parameters\footnote{As of v0.99 the PK\_PRIVATE\_OPTIMIZED type has been deprecated, and has been replaced by the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3357 PK\_PRIVATE type.} in the form of a RSAPrivateKey (PKCS \#1 compliant). The second type, is a public RSA key which only includes the modulus and public exponent.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3358 It takes the form of a RSAPublicKey (PKCS \#1 compliant).
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3359
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3360 \subsection{RSA Exponentiation}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3361 To do raw work with the RSA function, that is without padding, use the following function:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3362 \index{rsa\_exptmod()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3363 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3364 int rsa_exptmod(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3365 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3366 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3367 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3368 int which,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3369 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3370 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3371 This will load the bignum from \textit{in} as a big endian integer in the format PKCS \#1 specifies, raises it to either \textit{e} or \textit{d} and stores the result
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3372 in \textit{out} and the size of the result in \textit{outlen}. \textit{which} is set to {\bf PK\_PUBLIC} to use \textit{e}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3373 (i.e. for encryption/verifying) and set to {\bf PK\_PRIVATE} to use \textit{d} as the exponent (i.e. for decrypting/signing).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3374
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3375 Note: the output of this function is zero--padded as per PKCS \#1 specification. This allows this routine to work with PKCS \#1 padding functions properly.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3376
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3377 \mysection{RSA Key Encryption}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3378 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
3379 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
3380
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3381 \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
3382 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3383 int rsa_encrypt_key(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3384 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3385 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3386 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3387 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3388 const unsigned char *lparam,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3389 unsigned long lparamlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3390 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3391 int prng_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3392 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3393 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3394 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3395 This function will OAEP pad \textit{in} of length \textit{inlen} bytes, RSA encrypt it, and store the ciphertext
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3396 in \textit{out} of length \textit{outlen} octets. The \textit{lparam} and \textit{lparamlen} are the same parameters you would pass
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3397 to \index{pkcs\_1\_oaep\_encode()} pkcs\_1\_oaep\_encode().
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3398
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3399 \subsection{Extended Encryption}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3400 As of v1.15, the library supports both v1.5 and v2.1 PKCS \#1 style paddings in these higher level functions. The following is the extended
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3401 encryption function:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3402
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3403 \index{rsa\_encrypt\_key\_ex()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3404 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3405 int rsa_encrypt_key_ex(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3406 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3407 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3408 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3409 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3410 const unsigned char *lparam,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3411 unsigned long lparamlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3412 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3413 int prng_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3414 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3415 int padding,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3416 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3417 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3418
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3419 \index{LTC\_PKCS\_1\_OAEP} \index{LTC\_PKCS\_1\_V1\_5}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3420 The parameters are all the same as for rsa\_encrypt\_key() except for the addition of the \textit{padding} parameter. It must be set to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3421 \textbf{LTC\_PKCS\_1\_V1\_5} to perform v1.5 encryption, or set to \textbf{LTC\_PKCS\_1\_OAEP} to perform v2.1 encryption.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3422
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3423 When performing v1.5 encryption, the hash and lparam parameters are totally ignored and can be set to \textbf{NULL} or zero (respectively).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3424
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3425 \mysection{RSA Key Decryption}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3426 \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
3427 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3428 int rsa_decrypt_key(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3429 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3430 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3431 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3432 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3433 const unsigned char *lparam,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3434 unsigned long lparamlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3435 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3436 int *stat,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3437 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3438 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3439 This function will RSA decrypt \textit{in} of length \textit{inlen} then OAEP de-pad the resulting data and store it in
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3440 \textit{out} of length \textit{outlen}. The \textit{lparam} and \textit{lparamlen} are the same parameters you would pass
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3441 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
3442
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3443 If the RSA decrypted data is not a valid OAEP packet then \textit{stat} is set to $0$. Otherwise, it is set to $1$.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3444
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3445 \subsection{Extended Decryption}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3446 As of v1.15, the library supports both v1.5 and v2.1 PKCS \#1 style paddings in these higher level functions. The following is the extended
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3447 decryption function:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3448
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3449 \index{rsa\_decrypt\_key\_ex()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3450 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3451 int rsa_decrypt_key_ex(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3452 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3453 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3454 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3455 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3456 const unsigned char *lparam,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3457 unsigned long lparamlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3458 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3459 int padding,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3460 int *stat,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3461 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3462 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3463
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3464 Similar to the extended encryption, the new parameter \textit{padding} indicates which version of the PKCS \#1 standard to use.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3465 It must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to perform v1.5 decryption, or set to \textbf{LTC\_PKCS\_1\_OAEP} to perform v2.1 decryption.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3466
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3467 When performing v1.5 decryption, the hash and lparam parameters are totally ignored and can be set to \textbf{NULL} or zero (respectively).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3468
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3469
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3470 \mysection{RSA Signature Generation}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3471 Similar to RSA key encryption RSA is also used to \textit{digitally sign} message digests (hashes). To facilitate this
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3472 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
3473
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3474 \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
3475 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3476 int rsa_sign_hash(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3477 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3478 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3479 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3480 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3481 int prng_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3482 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3483 unsigned long saltlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3484 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3485 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3486
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3487 This will PSS encode the message digest pointed to by \textit{in} of length \textit{inlen} octets. Next, the PSS encoded hash will be RSA
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3488 \textit{signed} and the output stored in the buffer pointed to by \textit{out} of length \textit{outlen} octets.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3489
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3490 The \textit{hash\_idx} parameter indicates which hash will be used to create the PSS encoding. It should be the same as the hash used to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3491 hash the message being signed. The \textit{saltlen} parameter indicates the length of the desired salt, and should typically be small. A good
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3492 default value is between 8 and 16 octets. Strictly, it must be small than $modulus\_len - hLen - 2$ where \textit{modulus\_len} is the size of
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3493 the RSA modulus (in octets), and \textit{hLen} is the length of the message digest produced by the chosen hash.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3494
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3495 \subsection{Extended Signatures}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3496
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3497 As of v1.15, the library supports both v1.5 and v2.1 signatures. The extended signature generation function has the following prototype:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3498
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3499 \index{rsa\_sign\_hash\_ex()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3500 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3501 int rsa_sign_hash_ex(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3502 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3503 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3504 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3505 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3506 int padding,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3507 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3508 int prng_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3509 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3510 unsigned long saltlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3511 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3512 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3513
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3514 This will PKCS encode the message digest pointed to by \textit{in} of length \textit{inlen} octets. Next, the PKCS encoded hash will be RSA
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3515 \textit{signed} and the output stored in the buffer pointed to by \textit{out} of length \textit{outlen} octets. The \textit{padding} parameter
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3516 must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to produce a v1.5 signature, otherwise, it must be set to \textbf{LTC\_PKCS\_1\_PSS} to produce a
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3517 v2.1 signature.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3518
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3519 When performing a v1.5 signature the \textit{prng}, \textit{prng\_idx}, and \textit{hash\_idx} parameters are not checked and can be left to any
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3520 values such as $\lbrace$\textbf{NULL}, 0, 0$\rbrace$.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3521
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3522 \mysection{RSA Signature Verification}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3523 \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
3524 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3525 int rsa_verify_hash(const unsigned char *sig,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3526 unsigned long siglen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3527 const unsigned char *msghash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3528 unsigned long msghashlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3529 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3530 unsigned long saltlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3531 int *stat,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3532 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3533 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3534
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3535 This will RSA \textit{verify} the signature pointed to by \textit{sig} of length \textit{siglen} octets. Next, the RSA decoded data is PSS decoded
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3536 and the extracted hash is compared against the message digest pointed to by \textit{msghash} of length \textit{msghashlen} octets.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3537
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3538 If the RSA decoded data is not a valid PSS message, or if the PSS decoded hash does not match the \textit{msghash}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3539 value, \textit{res} is set to $0$. Otherwise, if the function succeeds, and signature is valid \textit{res} is set to $1$.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3540
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3541 \subsection{Extended Verification}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3542
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3543 As of v1.15, the library supports both v1.5 and v2.1 signature verification. The extended signature verification function has the following prototype:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3544
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3545 \index{rsa\_verify\_hash\_ex()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3546 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3547 int rsa_verify_hash_ex(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3548 const unsigned char *sig,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3549 unsigned long siglen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3550 const unsigned char *hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3551 unsigned long hashlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3552 int padding,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3553 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3554 unsigned long saltlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3555 int *stat,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3556 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3557 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3558
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3559 This will RSA \textit{verify} the signature pointed to by \textit{sig} of length \textit{siglen} octets. Next, the RSA decoded data is PKCS decoded
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3560 and the extracted hash is compared against the message digest pointed to by \textit{msghash} of length \textit{msghashlen} octets.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3561
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3562 If the RSA decoded data is not a valid PSS message, or if the PKCS decoded hash does not match the \textit{msghash}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3563 value, \textit{res} is set to $0$. Otherwise, if the function succeeds, and signature is valid \textit{res} is set to $1$.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3564
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3565 The \textit{padding} parameter must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to perform a v1.5 verification. Otherwise, it must be set to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3566 \textbf{LTC\_PKCS\_1\_PSS} to perform a v2.1 verification. When performing a v1.5 verification the \textit{hash\_idx} parameter is ignored.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3567
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3568 \mysection{RSA Encryption Example}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3569 \begin{small}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3570 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3571 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3572 int main(void)
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3573 {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3574 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
3575 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
3576 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
3577 rsa_key key;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3578
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3579 /* register prng/hash */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3580 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
3581 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
3582 return EXIT_FAILURE;
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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3585 /* register a math library (in this case TomsFastMath)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3586 ltc_mp = tfm_desc;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3587
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3588 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
3589 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
3590 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3591 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3592 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
3593 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
3594
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3595 /* 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
3596 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
3597 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
3598 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
3599 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
3600 &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
3601 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3602 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
3603 return EXIT_FAILURE;
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
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3606 /* 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
3607 l1 = sizeof(out);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3608 if ((err = rsa_encrypt_key(pt, /* data we wish to encrypt */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3609 16, /* data is 16 bytes long */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3610 out, /* where to store ciphertext */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3611 &l1, /* length of ciphertext */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3612 "TestApp", /* our lparam for this program */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3613 7, /* lparam is 7 bytes long */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3614 NULL, /* PRNG state */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3615 prng_idx, /* prng idx */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3616 hash_idx, /* hash idx */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3617 &key) /* our RSA key */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3618 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3619 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
3620 return EXIT_FAILURE;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3621 }
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 /* 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
3624 l2 = sizeof(pt2);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3625 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
3626 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
3627 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
3628 &l2, /* plaintext length */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3629 "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
3630 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
3631 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
3632 &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
3633 &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
3634 ) != CRYPT_OK) {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3635 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
3636 return EXIT_FAILURE;
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 /* 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
3639 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3640 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3641 \end{small}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3642
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3643 \mysection{RSA Key Format}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3644
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3645 The RSA key format adopted for exporting and importing keys is the PKCS \#1 format defined by the ASN.1 constructs known as
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3646 RSAPublicKey and RSAPrivateKey. Additionally, the OpenSSL key format is supported by the import function only.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3647
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3648 \subsection{RSA Key Export}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3649 To export a RSA key use the following function.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3650
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3651 \index{rsa\_export()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3652 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3653 int rsa_export(unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3654 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3655 int type,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3656 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3657 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3658 This will export the RSA key in either a RSAPublicKey or RSAPrivateKey (PKCS \#1 types) depending on the value of \textit{type}. When it is
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3659 set to \textbf{PK\_PRIVATE} the export format will be RSAPrivateKey and otherwise it will be RSAPublicKey.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3660
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3661 \subsection{RSA Key Import}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3662 To import a RSA key use the following function.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3663
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3664 \index{rsa\_import()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3665 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3666 int rsa_import(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3667 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3668 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3669 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3670
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3671 This will import the key stored in \textit{inlen} and import it to \textit{key}. If the function fails it will automatically free any allocated memory. This
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3672 function can import both RSAPublicKey and RSAPrivateKey formats.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3673
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3674 As of v1.06 this function can also import OpenSSL DER formatted public RSA keys. They are essentially encapsulated RSAPublicKeys. LibTomCrypt will
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3675 import the key, strip off the additional data (it's the preferred hash) and fill in the rsa\_key structure as if it were a native RSAPublicKey. Note that
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3676 there is no function provided to export in this format.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3677
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3678 \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
3679
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3680 \mysection{Background}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3681 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
3682 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
3683 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
3684 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
3685 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
3686
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3687 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
3688 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3689 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
3690 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3691
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3692 As of v1.15 three new curves from the SECG standards are also included they are the secp112r1, secp128r1, and secp160r1 curves. These curves were added to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3693 support smaller devices which do not need as large keys for security.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3694
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3695 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
3696 \begin{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3697 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
3698 \end{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3699
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3700 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
3701 provided are very close to $p$ that is $\vert \vert \phi(\beta) \vert \vert \approx \vert \vert p \vert \vert$. The curves
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3702 range in order from $\approx 2^{112}$ points to $\approx 2^{521}$. According to the source document any key size greater
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3703 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
3704
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3705 \mysection{Fixed Point Optimizations}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3706 \index{Fixed Point ECC}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3707 \index{MECC\_FP}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3708 As of v1.12 of LibTomCrypt, support for Fixed Point ECC point multiplication has been added. It is a generic optimization that is
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3709 supported by any conforming math plugin. It is enabled by defining \textbf{MECC\_FP} during the build, such as
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3710
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3711 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3712 CFLAGS="-DTFM_DESC -DMECC_FP" make
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3713 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3714
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3715 which will build LTC using the TFM math library and enabling this new feature. The feature is not enabled by default as it is \textbf{NOT} thread
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3716 safe (by default). It supports the LTC locking macros (such as by enabling LTC\_PTHREAD), but by default is not locked.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3717
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3718 \index{FP\_ENTRIES}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3719 The optimization works by using a Fixed Point multiplier on any base point you use twice or more in a short period of time. It has a limited size
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3720 cache (of FP\_ENTRIES entries) which it uses to hold recent bases passed to ltc\_ecc\_mulmod(). Any base detected to be used twice is sent through the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3721 pre--computation phase, and then the fixed point algorithm can be used. For example, if you use a NIST base point twice in a row, the 2$^{nd}$ and
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3722 all subsequent point multiplications with that point will use the faster algorithm.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3723
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3724 \index{FP\_LUT}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3725 The optimization uses a window on the multiplicand of FP\_LUT bits (default: 8, min: 2, max: 12), and this controls the memory/time trade-off. The larger the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3726 value the faster the algorithm will be but the more memory it will take. The memory usage is $3 \cdot 2^{FP\_LUT}$ integers which by default
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3727 with TFM amounts to about 400kB of memory. Tuning TFM (by changing FP\_SIZE) can decrease the usage by a fair amount. Memory is only used by a cache entry
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3728 if it is active. Both FP\_ENTRIES and FP\_LUT are definable on the command line if you wish to override them. For instance,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3729
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3730 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3731 CFLAGS="-DTFM_DESC -DMECC_FP -DFP_ENTRIES=8 -DFP_LUT=6" make
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3732 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3733
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3734 \begin{flushleft}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3735 \index{FP\_SIZE} \index{TFM} \index{tfm.h}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3736 would define a window of 6 bits and limit the cache to 8 entries. Generally, it is better to first tune TFM by adjusting FP\_SIZE (from tfm.h). It defaults
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3737 to 4096 bits (512 bytes) which is way more than what is required by ECC. At most, you need 1152 bits to accommodate ECC--521. If you're only using (say)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3738 ECC--256 you will only need 576 bits, which would reduce the memory usage by 700\%.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3739 \end{flushleft}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3740
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3741 \mysection{Key Format}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3742 LibTomCrypt uses a unique format for ECC public and private keys. While ANSI X9.63 partially specifies key formats, it does it in a less than ideally simple manner. \
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3743 In the case of LibTomCrypt, it is meant \textbf{solely} for NIST and SECG $GF(p)$ curves. The format of the keys is as follows:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3744
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3745 \index{ECC Key Format}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3746 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3747 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3748 ECCPublicKey ::= SEQUENCE {
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3749 flags BIT STRING(0), -- public/private flag (always zero),
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3750 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
3751 -- 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
3752 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
3753 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
3754 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3755
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3756 ECCPrivateKey ::= SEQUENCE {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3757 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
3758 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
3759 -- 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
3760 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
3761 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
3762 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
3763 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3764 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3765 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3766
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3767 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
3768
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3769 \vfil
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3770
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3771 \mysection{ECC Curve Parameters}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3772 The library uses the following structure to describe an elliptic curve. This is used internally, as well as by the new
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3773 extended ECC functions which allow the user to specify their own curves.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3774
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3775 \index{ltc\_ecc\_set\_type}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3776 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3777 /** Structure defines a NIST GF(p) curve */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3778 typedef struct {
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3779 /** The size of the curve in octets */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3780 int size;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3781
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3782 /** name of curve */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3783 char *name;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3784
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3785 /** The prime that defines the field (encoded in hex) */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3786 char *prime;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3787
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3788 /** The fields B param (hex) */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3789 char *B;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3790
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3791 /** The order of the curve (hex) */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3792 char *order;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3793
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3794 /** The x co-ordinate of the base point on the curve (hex) */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3795 char *Gx;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3796
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3797 /** The y co-ordinate of the base point on the curve (hex) */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3798 char *Gy;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3799 } ltc_ecc_set_type;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3800 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3801
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3802 The curve must be of the form $y^2 = x^3 - 3x + b$, and all of the integer parameters are encoded in hexadecimal format.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3803
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3804 \mysection{Core Functions}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3805 \subsection{ECC Key Generation}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3806 There is a key structure called \textit{ecc\_key} used by the ECC functions. There is a function to make a key:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3807 \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
3808 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3809 int ecc_make_key(prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3810 int wprng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3811 int keysize,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3812 ecc_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3813 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3814
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3815 The \textit{keysize} is the size of the modulus in bytes desired. Currently directly supported values are 12, 16, 20, 24, 28, 32, 48, and 65 bytes which
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3816 correspond to key sizes of 112, 128, 160, 192, 224, 256, 384, and 521 bits respectively. If you pass a key size that is between any key size it will round
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3817 the keysize up to the next available one.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3818
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3819 The function will free any internally allocated resources if there is an error.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3820
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3821 \subsection{Extended Key Generation}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3822 As of v1.16, the library supports an extended key generation routine which allows the user to specify their own curve. It is specified as follows:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3823
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3824 \index{ecc\_make\_key\_ex()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3825 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3826 int ecc_make_key_ex(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3827 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3828 int wprng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3829 ecc_key *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3830 const ltc_ecc_set_type *dp);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3831 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3832
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3833 This function generates a random ECC key over the curve specified by the parameters by \textit{dp}. The rest of the parameters are equivalent to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3834 those from the original key generation function.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3835
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3836 \subsection{ECC Key Free}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3837 To free the memory allocated by a ecc\_make\_key(), ecc\_make\_key\_ex(), ecc\_import(), or ecc\_import\_ex() call use the following function:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3838 \index{ecc\_free()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3839 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3840 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
3841 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3842
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3843 \subsection{ECC Key Export}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3844 To export an ECC key using the LibTomCrypt format call the following function:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3845 \index{ecc\_export()}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3846 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3847 int ecc_export(unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3848 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3849 int type,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3850 ecc_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3851 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3852 This will export the key with the given \textit{type} (\textbf{PK\_PUBLIC} or \textbf{PK\_PRIVATE}), and store it to \textit{out}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3853
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3854 \subsection{ECC Key Import}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3855 The following function imports a LibTomCrypt format ECC key:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3856 \index{ecc\_import()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3857 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3858 int ecc_import(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3859 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3860 ecc_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3861 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3862 This will import the ECC key from \textit{in}, and store it in the ecc\_key structure pointed to by \textit{key}. If the operation fails it will free
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3863 any allocated memory automatically.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3864
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3865 \subsection{Extended Key Import}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3866
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3867 The following function imports a LibTomCrypt format ECC key using a specified set of curve parameters:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3868 \index{ecc\_import\_ex()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3869 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3870 int ecc_import_ex(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3871 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3872 ecc_key *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3873 const ltc_ecc_set_type *dp);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3874 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3875 This will import the key from the array pointed to by \textit{in} of length \textit{inlen} octets. The key is stored in
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3876 the ECC structure pointed to by \textit{key}. The curve is specified by the parameters pointed to by \textit{dp}. The function will free
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3877 all internally allocated memory upon error.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3878
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3879 \subsection{ANSI X9.63 Export}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3880 The following function exports an ECC public key in the ANSI X9.63 format:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3881
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3882 \index{ecc\_ansi\_x963\_export()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3883 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3884 int ecc_ansi_x963_export( ecc_key *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3885 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3886 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3887 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3888 The ECC key pointed to by \textit{key} is exported in public fashion to the array pointed to by \textit{out}. The ANSI X9.63 format used is from
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3889 section 4.3.6 of the standard. It does not allow for the export of private keys.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3890
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3891 \subsection{ANSI X9.63 Import}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3892 The following function imports an ANSI X9.63 section 4.3.6 format public ECC key:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3893
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3894 \index{ecc\_ansi\_x963\_import()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3895 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3896 int ecc_ansi_x963_import(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3897 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3898 ecc_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3899 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3900 This will import the key stored in the array pointed to by \textit{in} of length \textit{inlen} octets. The imported key is stored in the ECC key pointed to by
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3901 \textit{key}. The function will free any allocated memory upon error.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3902
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3903 \subsection{Extended ANSI X9.63 Import}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3904 The following function allows the importing of an ANSI x9.63 section 4.3.6 format public ECC key using user specified domain parameters:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3905
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3906 \index{ecc\_ansi\_x963\_import\_ex()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3907 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3908 int ecc_ansi_x963_import_ex(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3909 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3910 ecc_key *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3911 ltc_ecc_set_type *dp);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3912 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3913 This will import the key stored in the array pointed to by \textit{in} of length \textit{inlen} octets using the domain parameters pointed to by \textit{dp}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3914 The imported key is stored in the ECC key pointed to by \textit{key}. The function will free any allocated memory upon error.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3915
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3916 \subsection{ECC Shared Secret}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3917 To construct a Diffie-Hellman shared secret with a private and public ECC key, use the following function:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3918 \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
3919 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3920 int ecc_shared_secret( ecc_key *private_key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3921 ecc_key *public_key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3922 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3923 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3924 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3925 The \textit{private\_key} is typically the local private key, and \textit{public\_key} is the key the remote party has shared.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3926 Note: this function stores only the $x$ co-ordinate of the shared elliptic point as described in ANSI X9.63 ECC--DH.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3927
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3928 \mysection{ECC Diffie-Hellman Encryption}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3929 ECC--DH Encryption is performed by producing a random key, hashing it, and XOR'ing the digest against the plaintext. It is not strictly ANSI X9.63 compliant
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3930 but it is very similar. It has been extended by using an ASN.1 sequence and hash object identifiers to allow portable usage. The following function
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3931 encrypts a short string (no longer than the message digest) using this technique:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3932
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3933 \subsection{ECC-DH Encryption}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3934 \index{ecc\_encrypt\_key()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3935 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3936 int ecc_encrypt_key(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3937 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3938 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3939 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3940 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3941 int wprng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3942 int hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3943 ecc_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3944 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3945
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3946 As the name implies this function encrypts a (symmetric) key, and is not intended for encrypting long messages directly. It will encrypt the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3947 plaintext in the array pointed to by \textit{in} of length \textit{inlen} octets. It uses the public ECC key pointed to by \textit{key}, and
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3948 hash algorithm indexed by \textit{hash} to construct a shared secret which may be XOR'ed against the plaintext. The ciphertext is stored in
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3949 the output buffer pointed to by \textit{out} of length \textit{outlen} octets.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3950
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3951 The data is encrypted to the public ECC \textit{key} such that only the holder of the private key can decrypt the payload. To have multiple
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3952 recipients multiple call to this function for each public ECC key is required.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3953
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3954 \subsection{ECC-DH Decryption}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3955 \index{ecc\_decrypt\_key()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3956 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3957 int ecc_decrypt_key(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3958 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3959 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3960 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3961 ecc_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3962 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3963
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3964 This function will decrypt an encrypted payload. The \textit{key} provided must be the private key corresponding to the public key
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3965 used during encryption. If the wrong key is provided the function will not specifically return an error code. It is important
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3966 to use some form of challenge response in that case (e.g. compute a MAC of a known string).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3967
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3968 \subsection{ECC Encryption Format}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3969 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
3970
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3971 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3972 ECCEncrypt ::= SEQUENCE {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3973 hashID OBJECT IDENTIFIER, -- OID of hash used
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3974 pubkey OCTET STRING , -- Encapsulated ECCPublicKey
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3975 skey OCTET STRING -- xor of plaintext and
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3976 --"hash of shared secret"
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3977 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3978 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3979
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3980 \mysection{EC DSA Signatures}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3981
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3982 There are also functions to sign and verify messages. They use the ANSI X9.62 EC-DSA algorithm to generate and verify signatures in the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3983 ANSI X9.62 format.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3984
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3985 \subsection{EC-DSA Signature Generation}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3986 To sign a message digest (hash) use the following function:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3987
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3988 \index{ecc\_sign\_hash()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3989 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3990 int ecc_sign_hash(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3991 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3992 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3993 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3994 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3995 int wprng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3996 ecc_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3997 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3998
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
3999 This function will EC--DSA sign the message digest stored in the array pointed to by \textit{in} of length \textit{inlen} octets. The signature
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4000 will be stored in the array pointed to by \textit{out} of length \textit{outlen} octets. The function requires a properly seeded PRNG, and
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4001 the ECC \textit{key} provided must be a private key.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4002
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4003 \subsection{EC-DSA Signature Verification}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4004 \index{ecc\_verify\_hash()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4005 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4006 int ecc_verify_hash(const unsigned char *sig,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4007 unsigned long siglen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4008 const unsigned char *hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4009 unsigned long hashlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4010 int *stat,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4011 ecc_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4012 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4013
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4014 This function will verify the EC-DSA signature in the array pointed to by \textit{sig} of length \textit{siglen} octets, against the message digest
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4015 pointed to by the array \textit{hash} of length \textit{hashlen}. It will store a non--zero value in \textit{stat} if the signature is valid. Note:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4016 the function will not return an error if the signature is invalid. It will return an error, if the actual signature payload is an invalid format.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4017 The ECC \textit{key} must be the public (or private) ECC key corresponding to the key that performed the signature.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4018
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4019 \subsection{Signature Format}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4020 The signature code is an implementation of X9.62 EC--DSA, and the output is compliant for GF(p) curves.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4021
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4022 \mysection{ECC Keysizes}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4023 With ECC if you try to sign a hash that is bigger than your ECC key you can run into problems. The math will still work, and in effect the signature will still
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4024 work. With ECC keys the strength of the signature is limited by the size of the hash, or the size of they key, whichever is smaller. For example, if you sign with
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4025 SHA256 and an ECC-192 key, you in effect have 96--bits of security.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4026
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4027 The library will not warn you if you make this mistake, so it is important to check yourself before using the signatures.
285
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 \chapter{Digital Signature Algorithm}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4030 \mysection{Introduction}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4031 The Digital Signature Algorithm (or DSA) is a variant of the ElGamal Signature scheme which has been modified to
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4032 reduce the bandwidth of the signatures. For example, to have \textit{80-bits of security} with ElGamal, you need a group with an order of at least 1024--bits.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4033 With DSA, you need a group of order at least 160--bits. By comparison, the ElGamal signature would require at least 256 bytes of storage, whereas the DSA signature
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4034 would require only at least 40 bytes.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4035
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4036 \mysection{Key Format}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4037 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
4038 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
4039
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4040 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4041 DSAPublicKey ::= SEQUENCE {
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4042 publicFlags BIT STRING(0), -- must be 0
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4043 g INTEGER , -- base generator
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4044 -- check that g^q mod p == 1
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4045 -- 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
4046 p INTEGER , -- prime modulus
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4047 q INTEGER , -- order of sub-group
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4048 -- (must be prime)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4049 y INTEGER , -- public key, specifically,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4050 -- g^x mod p,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4051 -- 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
4052 -- 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
4053 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4054
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4055 DSAPrivateKey ::= SEQUENCE {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4056 publicFlags BIT STRING(1), -- must be 1
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4057 g INTEGER , -- base generator
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4058 -- check that g^q mod p == 1
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4059 -- 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
4060 p INTEGER , -- prime modulus
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4061 q INTEGER , -- order of sub-group
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4062 -- (must be prime)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4063 y INTEGER , -- public key, specifically,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4064 -- g^x mod p,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4065 -- 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
4066 -- 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
4067 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
4068 }
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4069 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4070
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4071 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,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4072 and easy to work with.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4073
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4074 \mysection{Key Generation}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4075 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
4076 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4077 int dsa_make_key(prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4078 int wprng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4079 int group_size,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4080 int modulus_size,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4081 dsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4082 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4083 The variable \textit{prng} is an active PRNG state and \textit{wprng} the index to the descriptor. \textit{group\_size} and
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4084 \textit{modulus\_size} control the difficulty of forging a signature. Both parameters are in bytes. The larger the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4085 \textit{group\_size} the more difficult a forgery becomes upto a limit. The value of $group\_size$ is limited by
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4086 $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
4087
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4088 \begin{figure}[here]
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4089 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4090 \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
4091 \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
4092 \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
4093 \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
4094 \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
4095 \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
4096 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4097 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4098 \end{center}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4099 \caption{DSA Key Sizes}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4100 \end{figure}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4101
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4102 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
4103 \index{dsa\_free()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4104 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4105 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
4106 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4107
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4108 \mysection{Key Verification}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4109 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
4110
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4111 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4112 \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
4113 \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
4114 \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
4115 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
4116 \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
4117 \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
4118 \end{enumerate}
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 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
4121
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4122 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4123 \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
4124 \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
4125 \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
4126 \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
4127 \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
4128 \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
4129 \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
4130 \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
4131 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4132
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4133 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
4134 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
4135 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
4136 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
4137 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
4138 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
4139
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4140 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
4141
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4142 \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
4143 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4144 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
4145 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4146
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4147 This will test \textit{key} and store the result in \textit{stat}. If the result is $stat = 0$ the DSA key failed one of the tests
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4148 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
4149
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4150 \mysection{Signatures}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4151 \subsection{Signature Generation}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4152 To generate a DSA signature call the following function:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4153
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4154 \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
4155 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4156 int dsa_sign_hash(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4157 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4158 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4159 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4160 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4161 int wprng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4162 dsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4163 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4164
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4165 Which will sign the data in \textit{in} of length \textit{inlen} bytes. The signature is stored in \textit{out} and the size
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4166 of the signature in \textit{outlen}. If the signature is longer than the size you initially specify in \textit{outlen} nothing
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4167 is stored and the function returns an error code. The DSA \textit{key} must be of the \textbf{PK\_PRIVATE} persuasion.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4168
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4169 \subsection{Signature Verification}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4170 To verify a hash created with that function use the following function:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4171
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4172 \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
4173 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4174 int dsa_verify_hash(const unsigned char *sig,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4175 unsigned long siglen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4176 const unsigned char *hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4177 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4178 int *stat,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4179 dsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4180 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4181 Which will verify the data in \textit{hash} of length \textit{inlen} against the signature stored in \textit{sig} of length \textit{siglen}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4182 It will set \textit{stat} to $1$ if the signature is valid, otherwise it sets \textit{stat} to $0$.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4183
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4184 \mysection{DSA Encrypt and Decrypt}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4185 As of version 1.07, the DSA keys can be used to encrypt and decrypt small payloads. It works similar to the ECC encryption where
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4186 a shared key is computed, and the hash of the shared key XOR'ed against the plaintext forms the ciphertext. The format used is functional port of
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4187 the ECC encryption format to the DSA algorithm.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4188
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4189 \subsection{DSA Encryption}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4190 This function will encrypt a small payload with a recipients public DSA key.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4191
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4192 \index{dsa\_encrypt\_key()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4193 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4194 int dsa_encrypt_key(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4195 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4196 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4197 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4198 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4199 int wprng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4200 int hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4201 dsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4202 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4203
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4204 This will encrypt the payload in \textit{in} of length \textit{inlen} and store the ciphertext in the output buffer \textit{out}. The
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4205 length of the ciphertext \textit{outlen} must be originally set to the length of the output buffer. The DSA \textit{key} can be
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4206 a public key.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4207
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4208 \subsection{DSA Decryption}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4209
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4210 \index{dsa\_decrypt\_key()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4211 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4212 int dsa_decrypt_key(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4213 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4214 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4215 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4216 dsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4217 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4218 This will decrypt the ciphertext \textit{in} of length \textit{inlen}, and store the original payload in \textit{out} of length \textit{outlen}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4219 The DSA \textit{key} must be a private key.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4220
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4221 \mysection{DSA Key Import and Export}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4222
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4223 \subsection{DSA Key Export}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4224 To export a DSA key so that it can be transported use the following function:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4225 \index{dsa\_export()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4226 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4227 int dsa_export(unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4228 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4229 int type,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4230 dsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4231 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4232 This will export the DSA \textit{key} to the buffer \textit{out} and set the length in \textit{outlen} (which must have been previously
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4233 initialized to the maximum buffer size). The \textit{type} variable may be either \textbf{PK\_PRIVATE} or \textbf{PK\_PUBLIC}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4234 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
4235
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4236 \subsection{DSA Key Import}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4237 To import an exported DSA key use the following function
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4238 :
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4239 \index{dsa\_import()}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4240 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4241 int dsa_import(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4242 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4243 dsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4244 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4245
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4246 This will import the DSA key from the buffer \textit{in} of length \textit{inlen} to the \textit{key}. If the process fails the function
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4247 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
4248
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4249 \chapter{Standards Support}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4250 \mysection{ASN.1 Formats}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4251 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
4252 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4253 format, and two functions have been dedicated to encoding and decoding the format.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4254
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4255 On top of the basic data types are the SEQUENCE and SET data types which are collections of other ASN.1 types. They are provided
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4256 in the same manner as the other data types except they use list of objects known as the \textbf{ltc\_asn1\_list} structure. It is defined as the following:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4257
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4258 \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
4259 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4260 typedef struct {
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4261 int type;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4262 void *data;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4263 unsigned long size;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4264 int used;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4265 struct ltc_asn1_list_ *prev, *next,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4266 *child, *parent;
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4267 } ltc_asn1_list;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4268 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4269
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4270 \index{LTC\_SET\_ASN1 macro}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4271 The \textit{type} field is one of the following ASN.1 field definitions. The \textit{data} pointer is a void pointer to the data to be encoded (or the destination) and the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4272 \textit{size} field is specific to what you are encoding (e.g. number of bits in the BIT STRING data type). The \textit{used} field is primarily for the CHOICE decoder
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4273 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4274 \textit{LTC\_SET\_ASN1(list, index, Type, Data, Size)} has been provided.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4275
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4276 It will assign to the \textit{index}th position in the \textit{list} the triplet (Type, Data, Size). An example usage would be:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4277
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4278 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4279 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4280 ...
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4281 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
4282 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
4283
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4284 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
4285 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
4286 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
4287 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4288 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4289
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4290 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
4291
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4292 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4293 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4294 ...
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4295 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
4296 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
4297 int x=0;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4298 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
4299 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
4300 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
4301 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4302 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4303
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4304 \begin{figure}[here]
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4305 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4306 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4307 \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
4308 \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
4309 \hline LTC\_ASN1\_EOL & End of a ASN.1 list structure. \\
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4310 \hline LTC\_ASN1\_BOOLEAN & BOOLEAN type \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4311 \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
4312 \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
4313 \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
4314 \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
4315 \hline LTC\_ASN1\_NULL & NULL \\
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4316 \hline LTC\_ASN1\_OBJECT\_IDENTIFIER & OBJECT IDENTIFIER \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4317 \hline LTC\_ASN1\_IA5\_STRING & IA5 STRING (one octet per char) \\
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4318 \hline LTC\_ASN1\_UTF8\_STRING & UTF8 STRING (one wchar\_t per char) \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4319 \hline LTC\_ASN1\_PRINTABLE\_STRING & PRINTABLE STRING (one octet per char) \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4320 \hline LTC\_ASN1\_UTCTIME & UTCTIME (see ltc\_utctime structure) \\
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4321 \hline LTC\_ASN1\_SEQUENCE & SEQUENCE (and SEQUENCE OF) \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4322 \hline LTC\_ASN1\_SET & SET \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4323 \hline LTC\_ASN1\_SETOF & SET OF \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4324 \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
4325 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4326 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4327 \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
4328 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4329 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4330 \end{figure}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4331
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4332 \subsection{SEQUENCE Type}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4333 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
4334
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4335 \subsubsection{SEQUENCE Encoding}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4336 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
4337 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
4338
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4339 \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
4340 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4341 int der_encode_sequence(ltc_asn1_list *list,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4342 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4343 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4344 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4345 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4346 This encodes a sequence of items pointed to by \textit{list} where the list has \textit{inlen} items in it. The SEQUENCE will be encoded to \textit{out} and of length \textit{outlen}. The
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4347 function will terminate when it reads all the items out of the list (upto \textit{inlen}) or it encounters an item in the list with a type of \textbf{LTC\_ASN1\_EOL}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4348
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4349 The \textit{data} pointer in the list would be the same pointer you would pass to the respective ASN.1 encoder (e.g. der\_encode\_bit\_string()) and it is simply passed on
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4350 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4351 the \textit{data} pointer is simply a pointer to another \textbf{ltc\_asn1\_list}.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4352
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4353 \subsubsection{SEQUENCE Decoding}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4354
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4355 \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
4356
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4357 Decoding a SEQUENCE is similar to encoding. You set up an array of \textbf{ltc\_asn1\_list} where in this case the \textit{size} member is the maximum size
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4358 (in certain cases). For types such as IA5 STRING, BIT STRING, OCTET STRING (etc) the \textit{size} field is updated after successful decoding to reflect how many
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4359 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
4360
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4361 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4362 int der_decode_sequence(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4363 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4364 ltc_asn1_list *list,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4365 unsigned long outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4366 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4367
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4368 This will decode upto \textit{outlen} items from the input buffer \textit{in} of length \textit{inlen} octets. The function will stop (gracefully) when it runs out of items to decode.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4369 It will fail (for among other reasons) when it runs out of input bytes to read, a data type is invalid or a heap failure occurred.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4370
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4371 For the following types the \textit{size} field will be updated to reflect the number of units read of the given type.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4372 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4373 \item BIT STRING
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4374 \item OCTET STRING
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4375 \item OBJECT IDENTIFIER
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4376 \item IA5 STRING
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4377 \item PRINTABLE STRING
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4378 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4379
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4380 \subsubsection{SEQUENCE Length}
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 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
4383
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4384 \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
4385 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4386 int der_length_sequence(ltc_asn1_list *list,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4387 unsigned long inlen,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4388 unsigned long *outlen);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4389 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4390
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4391 This will get the encoding size for the given \textit{list} of length \textit{inlen} and store it in \textit{outlen}.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4392
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4393 \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
4394
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4395 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
4396
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4397 \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
4398 \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
4399
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4400 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4401 int der_encode_sequence_multi(unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4402 unsigned long *outlen, ...);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4403
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4404 int der_decode_sequence_multi(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4405 unsigned long inlen, ...);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4406 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4407
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4408 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
4409
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4410 The list of items are specified as a triple of the form \textit{(type, size, data)} where \textit{type} is an \textbf{int}, \textit{size} is a \textbf{unsigned long}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4411 and \textit{data} is \textbf{void} pointer. The list of items must be terminated with an item with the type \textbf{LTC\_ASN1\_EOL}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4412
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4413 It is ideal that you cast the \textit{size} values to unsigned long to ensure that the proper data type is passed to the function. Constants such as \textit{1} without
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4414 a cast or prototype are of type \textbf{int} by default. Appending \textit{UL} or pre-pending \textit{(unsigned long)} is enough to cast it to the correct type.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4415
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4416 \begin{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4417 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4418 unsigned char buf[MAXBUFSIZE];
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4419 unsigned long buflen;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4420 int err;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4421
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4422 buflen = sizeof(buf);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4423 if ((err =
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4424 der_encode_sequence_multi(buf, &buflen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4425 LTC_ASN1_IA5_STRING, 5UL, "Hello",
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4426 LTC_ASN1_IA5_STRING, 7UL, " World!",
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4427 LTC_ASN1_EOL, 0UL, NULL)) != CRYPT_OK) {
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4428 // error handling
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4429 }
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4430 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4431 \end{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4432
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4433 This example encodes a SEQUENCE with two IA5 STRING types containing ``Hello'' and `` World!'' respectively. Note the usage of the \textbf{UL} modifier
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4434 on the size parameters. This forces the compiler to pass the numbers as the required \textbf{unsigned long} type that the function expects.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4435
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4436 \subsection{SET and SET OF}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4437
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4438 \index{SET} \index{SET OF}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4439 SET and SET OF are related to the SEQUENCE type in that they can be pretty much be decoded with the same code. However, they are different, and they should
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4440 be carefully noted. The SET type is an unordered array of ASN.1 types sorted by the TAG (type identifier), whereas the SET OF type is an ordered array of
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4441 a \textbf{single} ASN.1 object sorted in ascending order by the DER their respective encodings.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4442
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4443 \subsubsection{SET Encoding}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4444
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4445 SETs use the same array structure of ltc\_asn1\_list that the SEQUENCE functions use. They are encoded with the following function:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4446
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4447 \index{der\_encode\_set()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4448 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4449 int der_encode_set(ltc_asn1_list *list,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4450 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4451 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4452 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4453 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4454
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4455 This will encode the list of ASN.1 objects in \textit{list} of length \textit{inlen} objects, and store the output in \textit{out} of length \textit{outlen} bytes.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4456 The function will make a copy of the list provided, and sort it by the TAG. Objects with identical TAGs are additionally sorted on their original placement in the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4457 array (to make the process deterministic).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4458
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4459 This function will \textbf{NOT} recognize \textit{DEFAULT} objects, and it is the responsibility of the caller to remove them as required.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4460
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4461 \subsubsection{SET Decoding}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4462
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4463 The SET type can be decoded with the following function.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4464
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4465 \index{der\_decode\_set()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4466 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4467 int der_decode_set(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4468 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4469 ltc_asn1_list *list,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4470 unsigned long outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4471 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4472
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4473 This will decode the SET specified by \textit{list} of length \textit{outlen} objects from the input buffer \textit{in} of length \textit{inlen} octets.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4474
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4475 It handles the fact that SETs are not strictly ordered and will make multiple passes (as required) through the list to decode all the objects.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4476
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4477 \subsubsection{SET Length}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4478 The length of a SET can be determined by calling der\_length\_sequence() since they have the same encoding length.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4479
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4480 \subsubsection{SET OF Encoding}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4481 A \textit{SET OF} object is an array of identical objects (e.g. OCTET STRING) sorted in ascending order by the DER encoding of the object. They are
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4482 used to store objects deterministically based solely on their encoding. It uses the same array structure of ltc\_asn1\_list that the SEQUENCE functions
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4483 use. They are encoded with the following function.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4484
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4485 \index{der\_encode\_setof()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4486 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4487 int der_encode_setof(ltc_asn1_list *list,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4488 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4489 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4490 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4491 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4492
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4493 This will encode a \textit{SET OF} containing the \textit{list} of \textit{inlen} ASN.1 objects and store the encoding in the output buffer \textit{out} of length \textit{outlen}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4494
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4495 The routine will first encode the SET OF in an unordered fashion (in a temporary buffer) then sort using the XQSORT macro and copy back to the output buffer. This
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4496 means you need at least enough memory to keep an additional copy of the output on the heap.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4497
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4498 \subsubsection{SET OF Decoding}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4499 Since the decoding of a \textit{SET OF} object is unambiguous it can be decoded with der\_decode\_sequence().
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4500
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4501 \subsubsection{SET OF Length}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4502 Like the SET type the der\_length\_sequence() function can be used to determine the length of a \textit{SET OF} object.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4503
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4504 \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
4505
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4506 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
4507
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4508 \index{der\_encode\_integer()}\index{der\_decode\_integer()}\index{der\_length\_integer()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4509 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4510 int der_encode_integer( void *num,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4511 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4512 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4513
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4514 int der_decode_integer(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4515 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4516 void *num);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4517
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4518 int der_length_integer( void *num,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4519 unsigned long *len);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4520 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4521
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4522 These will encode or decode a signed INTEGER data type using the bignum data type to store the large INTEGER. To encode smaller values without allocating
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4523 a bignum to store the value, the \textit{short} INTEGER functions were made available.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4524
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4525 \index{der\_encode\_short\_integer()}\index{der\_decode\_short\_integer()}\index{der\_length\_short\_integer()}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4526 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4527 int der_encode_short_integer(unsigned long num,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4528 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4529 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4530
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4531 int der_decode_short_integer(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4532 unsigned long inlen,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4533 unsigned long *num);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4534
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4535 int der_length_short_integer(unsigned long num,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4536 unsigned long *outlen);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4537 \end{verbatim}
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 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
4540 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
4541
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4542 \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
4543
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4544 \index{der\_encode\_bit\_string()}\index{der\_decode\_bit\_string()}\index{der\_length\_bit\_string()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4545 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4546 int der_encode_bit_string(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4547 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4548 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4549 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4550
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4551 int der_decode_bit_string(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4552 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4553 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4554 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4555
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4556 int der_length_bit_string(unsigned long nbits,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4557 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4558 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4559
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4560 These will encode or decode a BIT STRING data type. The bits are passed in (or read out) using one \textbf{char} per bit. A non--zero value will be interpreted
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4561 as a one bit, and a zero value a zero bit.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4562
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4563 \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
4564
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4565 \index{der\_encode\_octet\_string()}\index{der\_decode\_octet\_string()}\index{der\_length\_octet\_string()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4566 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4567 int der_encode_octet_string(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4568 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4569 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4570 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4571
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4572 int der_decode_octet_string(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4573 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4574 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4575 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4576
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4577 int der_length_octet_string(unsigned long noctets,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4578 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4579 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4580
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4581 These will encode or decode an OCTET STRING data type. The octets are stored using one \textbf{unsigned char} each.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4582
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4583 \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
4584
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4585 \index{der\_encode\_object\_identifier()}\index{der\_decode\_object\_identifier()}\index{der\_length\_object\_identifier()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4586 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4587 int der_encode_object_identifier(unsigned long *words,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4588 unsigned long nwords,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4589 unsigned char *out,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4590 unsigned long *outlen);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4591
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4592 int der_decode_object_identifier(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4593 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4594 unsigned long *words,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4595 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4596
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4597 int der_length_object_identifier(unsigned long *words,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4598 unsigned long nwords,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4599 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4600 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4601
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4602 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
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4603 $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
4604
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4605 \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
4606
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4607 \index{der\_encode\_ia5\_string()}\index{der\_decode\_ia5\_string()}\index{der\_length\_ia5\_string()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4608 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4609 int der_encode_ia5_string(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4610 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4611 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4612 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4613
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4614 int der_decode_ia5_string(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4615 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4616 unsigned char *out,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4617 unsigned long *outlen);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4618
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4619 int der_length_ia5_string(const unsigned char *octets,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4620 unsigned long noctets,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4621 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4622 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4623
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4624 These will encode or decode an IA5 STRING. The characters are read or stored in individual \textbf{char} elements. These functions performs internal character
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4625 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4626 say a SPARC machine. Internally, these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4627 that the build platform honours the run--time platforms character conventions.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4628
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4629 \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
4630
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4631 \index{der\_encode\_printable\_string()}\index{der\_decode\_printable\_string()}\index{der\_length\_printable\_string()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4632 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4633 int der_encode_printable_string(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4634 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4635 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4636 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4637
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4638 int der_decode_printable_string(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4639 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4640 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4641 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4642
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4643 int der_length_printable_string(const unsigned char *octets,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4644 unsigned long noctets,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4645 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4646 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4647
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4648 These will encode or decode an PRINTABLE STRING. The characters are read or stored in individual \textbf{char} elements. These functions performs internal character
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4649 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4650 say a SPARC machine. Internally, these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4651 that the build platform honours the run-time platforms character conventions.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4652
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4653 \subsection{ASN.1 UTF8 STRING}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4654
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4655 \index{der\_encode\_utf8\_string()}\index{der\_decode\_utf8\_string()}\index{der\_length\_utf8\_string()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4656 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4657 int der_encode_utf8_string(const wchar_t *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4658 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4659 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4660 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4661
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4662 int der_decode_utf8_string(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4663 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4664 wchar_t *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4665 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4666
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4667 int der_length_utf8_string(const wchar_t *octets,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4668 unsigned long noctets,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4669 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4670 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4671
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4672 These will encode or decode an UTF8 STRING. The characters are read or stored in individual \textbf{wchar\_t} elements. These function performs no internal
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4673 mapping and treat the characters as literals.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4674
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4675 These functions use the \textbf{wchar\_t} type which is not universally available. In those cases, the library will typedef it to \textbf{unsigned long}. If you
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4676 intend to use the ISO C functions for working with wide--char arrays, you should make sure that wchar\_t has been defined previously.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4677
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4678 \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
4679
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4680 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
4681
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4682 \index{ltc\_utctime structure}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4683 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4684 typedef struct {
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4685 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
4686 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
4687 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
4688 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
4689 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
4690 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
4691 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
4692 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
4693 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
4694 } ltc_utctime;
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4695 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4696
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4697 The time can be offset plus or minus a set amount of hours (off\_hh) and minutes (off\_mm). When \textit{off\_dir} is zero, the time will be added otherwise it
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4698 will be subtracted. For instance, the array $\lbrace 5, 6, 20, 22, 4, 00, 0, 5, 0 \rbrace$ represents the current time of
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4699 \textit{2005, June 20th, 22:04:00} with a time offset of +05h00.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4700
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4701 \index{der\_encode\_utctime()}\index{der\_decode\_utctime()}\index{der\_length\_utctime()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4702 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4703 int der_encode_utctime( ltc_utctime *utctime,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4704 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4705 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4706
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4707 int der_decode_utctime(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4708 unsigned long *inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4709 ltc_utctime *out);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4710
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4711 int der_length_utctime( ltc_utctime *utctime,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4712 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4713 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4714
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4715 The encoder will store time in one of the two ASN.1 formats, either \textit{YYMMDDhhmmssZ} or \textit{YYMMDDhhmmss$\pm$hhmm}, and perform minimal error checking on the
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4716 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
4717
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4718 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
4719
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4720 \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
4721
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4722 The CHOICE ASN.1 type represents a union of ASN.1 types all of which are stored in a \textit{ltc\_asn1\_list}. There is no encoder for the CHOICE type, only a
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4723 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
4724 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
4725
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4726 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
4727
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4728 \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
4729 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4730 int der_decode_choice(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4731 unsigned long *inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4732 ltc_asn1_list *list,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4733 unsigned long outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4734 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4735
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4736 This will decode the input in the \textit{in} field of length \textit{inlen}. It uses the provided ASN.1 list specified in the \textit{list} field which has
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4737 \textit{outlen} elements. The \textit{inlen} field will be updated with the length of the decoded data type, as well as the respective entry in the \textit{list} field
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4738 will have the \textit{used} flag set to non--zero to reflect it was the data type decoded.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4739
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4740 \subsection{ASN.1 Flexi Decoder}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4741 The ASN.1 \textit{flexi} decoder allows the developer to decode arbitrary ASN.1 DER packets (provided they use data types LibTomCrypt supports) without first knowing
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4742 the structure of the data. Where der\_decode \_sequence() requires the developer to specify the data types to decode in advance the flexi decoder is entirely
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4743 free form.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4744
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4745 The flexi decoder uses the same \textit{ltc\_asn1\_list} but instead of being stored in an array it uses the linked list pointers \textit{prev}, \textit{next}, \textit{parent}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4746 and \textit{child}. The list works as a \textit{doubly-linked list} structure where decoded items at the same level are siblings (using next and prev) and items
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4747 encoded in a SEQUENCE are stored as a child element.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4748
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4749 When a SEQUENCE or SET has been encountered a SEQUENCE (or SET resp.) item will be added as a sibling (e.g. list.type == LTC\_ASN1\_SEQUENCE) and the child
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4750 pointer points to a new list of items contained within the object.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4751
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4752 \index{der\_decode\_sequence\_flexi()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4753 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4754 int der_decode_sequence_flexi(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4755 unsigned long *inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4756 ltc_asn1_list **out);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4757 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4758
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4759 This will decode items in the \textit{in} buffer of max input length \textit{inlen} and store the newly created pointer to the list in \textit{out}. This function allocates
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4760 all required memory for the decoding. It stores the number of octets read back into \textit{inlen}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4761
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4762 The function will terminate when either it hits an invalid ASN.1 tag, or it reads \textit{inlen} octets. An early termination is a soft error, and returns
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4763 normally. The decoded list \textit{out} will point to the very first element of the list (e.g. both parent and prev pointers will be \textbf{NULL}).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4764
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4765 An invalid decoding will terminate the process, and free the allocated memory automatically.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4766
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4767 \textbf{Note:} the list decoded by this function is \textbf{NOT} in the correct form for der\_encode\_sequence() to use directly. You will have to first
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4768 have to convert the list by first storing all of the siblings in an array then storing all the children as sub-lists of a sequence using the \textit{.data}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4769 pointer. Currently no function in LibTomCrypt provides this ability.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4770
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4771 \subsubsection{Sample Decoding}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4772 Suppose we decode the following structure:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4773 \begin{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4774 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4775 User ::= SEQUENCE {
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4776 Name IA5 STRING
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4777 LoginToken SEQUENCE {
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4778 passwdHash OCTET STRING
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4779 pubkey ECCPublicKey
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4780 }
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4781 LastOn UTCTIME
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4782 }
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4783 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4784 \end{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4785 \begin{flushleft}and we decoded it with the following code:\end{flushleft}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4786
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4787 \begin{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4788 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4789 unsigned char inbuf[MAXSIZE];
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4790 unsigned long inbuflen;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4791 ltc_asn1_list *list;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4792 int err;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4793
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4794 /* somehow fill inbuf/inbuflen */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4795 if ((err = der_decode_sequence_flexi(inbuf, inbuflen, &list)) != CRYPT_OK) {
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4796 printf("Error decoding: %s\n", error_to_string(err));
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4797 exit(EXIT_FAILURE);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4798 }
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4799 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4800 \end{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4801
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4802 At this point \textit{list} would point to the SEQUENCE identified by \textit{User}. It would have no sibblings (prev or next), and only a child node. Walking to the child
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4803 node with the following code will bring us to the \textit{Name} portion of the SEQUENCE:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4804 \begin{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4805 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4806 list = list->child;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4807 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4808 \end{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4809 Now \textit{list} points to the \textit{Name} member (with the tag IA5 STRING). The \textit{data}, \textit{size}, and \textit{type} members of \textit{list} should reflect
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4810 that of an IA5 STRING. The sibbling will now be the \textit{LoginToken} SEQUENCE. The sibbling has a child node which points to the \textit{passwdHash} OCTET STRING.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4811 We can walk to this node with the following code:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4812 \begin{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4813 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4814 /* list already pointing to 'Name' */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4815 list = list->next->child;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4816 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4817 \end{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4818 At this point, \textit{list} will point to the \textit{passwdHash} member of the innermost SEQUENCE. This node has a sibbling, the \textit{pubkey} member of the SEQUENCE.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4819 The \textit{LastOn} member of the SEQUENCE is a sibbling of the LoginToken node, if we wanted to walk there we would have to go up and over via:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4820 \begin{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4821 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4822 list = list->parent->next;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4823 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4824 \end{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4825 At this point, we are pointing to the last node of the list. Lists are terminated in all directions by a \textbf{NULL} pointer. All nodes are doubly linked so that you
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4826 can walk up and down the nodes without keeping pointers lying around.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4827
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4828
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4829
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4830
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4831
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4832 \subsubsection{Free'ing a Flexi List}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4833 To free the list use the following function.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4834
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4835 \index{der\_sequence\_free()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4836 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4837 void der_sequence_free(ltc_asn1_list *in);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4838 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4839
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4840 This will free all of the memory allocated by der\_decode\_sequence\_flexi().
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4841
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4842 \mysection{Password Based Cryptography}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4843 \subsection{PKCS \#5}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4844 \index{PKCS \#5}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4845 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
4846 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
4847 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
4848
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4849 \subsection{Algorithm One}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4850 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
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4851 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
4852 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
4853
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4854 \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
4855 \begin{alltt}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4856 int pkcs_5_alg1(const unsigned char *password,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4857 unsigned long password_len,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4858 const unsigned char *salt,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4859 int iteration_count,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4860 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4861 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4862 unsigned long *outlen)
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4863 \end{alltt}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4864 Where \textit{password} is the user's password. Since the algorithm allows binary passwords you must also specify the length in \textit{password\_len}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4865 The \textit{salt} is a fixed size 8--byte array which should be random for each user and session. The \textit{iteration\_count} is the delay desired
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4866 on the password. The \textit{hash\_idx} is the index of the hash you wish to use in the descriptor table.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4867
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4868 The output of length up to \textit{outlen} is stored in \textit{out}. If \textit{outlen} is initially larger than the size of the hash functions output
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4869 it is set to the number of bytes stored. If it is smaller than not all of the hash output is stored in \textit{out}.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4870
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4871 \subsection{Algorithm Two}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4872
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4873 Algorithm Two is the recommended algorithm for this task. It allows variable length salts, and can produce outputs larger than the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4874 hash functions output. As such, it can easily be used to derive session keys for ciphers and MACs as well initial vectors as required
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4875 from a single password and invocation of this algorithm.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4876
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4877 \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
4878 \begin{alltt}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4879 int pkcs_5_alg2(const unsigned char *password,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4880 unsigned long password_len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4881 const unsigned char *salt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4882 unsigned long salt_len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4883 int iteration_count,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4884 int hash_idx,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4885 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4886 unsigned long *outlen)
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4887 \end{alltt}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4888 Where \textit{password} is the users password. Since the algorithm allows binary passwords you must also specify the length in \textit{password\_len}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4889 The \textit{salt} is an array of size \textit{salt\_len}. It should be random for each user and session. The \textit{iteration\_count} is the delay desired
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4890 on the password. The \textit{hash\_idx} is the index of the hash you wish to use in the descriptor table. The output of length up to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4891 \textit{outlen} is stored in \textit{out}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4892
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4893 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4894 /* demo to show how to make session state material
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4895 * from a password */
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4896 #include <tomcrypt.h>
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4897 int main(void)
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4898 {
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4899 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
4900 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
4901 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
4902 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
4903 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
4904
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4905 /* 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
4906
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4907 /* 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
4908
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4909 /* 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
4910 outlen = sizeof(outbuf);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4911 if ((err = pkcs_5_alg2(password, password_len, salt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4912 salt_len, 100, hash_idx, outbuf,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4913 &outlen))
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4914 != CRYPT_OK) {
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4915 /* error handle */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4916 }
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4917
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4918 /* now extract it */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4919 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
4920 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
4921 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
4922
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4923 /* use material (recall to store the salt in the output) */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4924 }
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4925 \end{verbatim}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4926
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4927 \chapter{Miscellaneous}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4928 \mysection{Base64 Encoding and Decoding}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4929 The library provides functions to encode and decode a RFC 1521 base--64 coding scheme. The characters used in the mappings are:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4930 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4931 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4932 \end{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4933 Those characters are supported in the 7-bit ASCII map, which means they can be used for transport over
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4934 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
4935 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
4936 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
4937
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4938 Often, it is desirable to line wrap the output to fit nicely in an e-mail or usenet posting. The decoder allows you to
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4939 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
4940 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
4941
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4942 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
4943 \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
4944 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4945 int base64_encode(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4946 unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4947 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4948 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4949 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4950 Where \textit{in} is the binary string and \textit{out} is where the ASCII output is placed. You must set the value of \textit{outlen} prior
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4951 to calling this function and it sets the length of the base64 output in \textit{outlen} when it is done. To decode a base64
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4952 string call:
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4953 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4954 int base64_decode(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4955 unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4956 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4957 unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4958 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4959
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4960 \mysection{Primality Testing}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4961 \index{Primality Testing}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4962 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
4963 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
4964 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
4965 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
4966 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
4967 $\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
4968
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4969 When making random primes the trial division step is in fact an optimized implementation of \textit{Implementation of Fast RSA Key Generation on Smart Cards}\footnote{Chenghuai Lu, Andre L. M. dos Santos and Francisco R. Pimentel}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4970 In essence a table of machine-word sized residues are kept of a candidate modulo a set of primes. When the candidate
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4971 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
4972 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
4973 involved.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4974
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4975 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
4976 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
4977 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
4978 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
4979 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
4980 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
4981
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4982 These are not technically part of the LibTomMath library but this is the best place to document them.
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4983 To test if a \textit{mp\_int} is prime call:
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4984 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4985 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
4986 \end{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4987 This puts a one in \textit{result} if the number is probably prime, otherwise it places a zero in it. It is assumed that if
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4988 it returns an error that the value in \textit{result} is undefined. To make
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4989 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
4990 \begin{verbatim}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4991 int rand_prime( mp_int *N,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4992 unsigned long len,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4993 prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4994 int wprng);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4995 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4996 Where \textit{len} is the size of the prime in bytes ($2 \le len \le 256$). You can set \textit{len} to the negative size you want
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4997 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
4998 \textit{len = -128} to the function. Upon success it will return {\bf CRYPT\_OK} and \textit{N} will contain an integer which
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4999 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
5000
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5001 \chapter{Programming Guidelines}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5002
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5003 \mysection{Secure Pseudo Random Number Generators}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5004 Probably the single most vulnerable point of any cryptosystem is the PRNG. Without one, generating and protecting secrets
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5005 would be impossible. The requirement that one be setup correctly is vitally important, and to address this point the library
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5006 does provide two RNG sources that will address the largest amount of end users as possible. The \textit{sprng} PRNG provides an easy to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5007 access source of entropy for any application on a UNIX (and the like) or Windows computer.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5008
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5009 However, when the end user is not on one of these platforms, the application developer must address the issue of finding
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5010 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
5011 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
5012
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5013 \mysection{Preventing Trivial Errors}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5014 Two simple ways to prevent trivial errors is to prevent overflows, and to check the return values. All of the functions
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5015 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
5016 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
5017
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5018 Also, virtually all of the functions return an error code or {\bf CRYPT\_OK}. You should detect all errors, as simple
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5019 typos can cause algorithms to fail to work as desired.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5020
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5021 \mysection{Registering Your Algorithms}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5022 To avoid linking and other run--time errors it is important to register the ciphers, hashes and PRNGs you intend to use
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5023 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
5024
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5025 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
5026 having to hack the library. For example, suppose you have a hardware specific PRNG on your system. You could easily
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5027 write the few functions required plus a descriptor. After registering your PRNG, all of the library functions that
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5028 need a PRNG can instantly take advantage of it. The same applies for ciphers, hashes, and bignum math routines.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5029
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5030 \mysection{Key Sizes}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5031
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5032 \subsection{Symmetric Ciphers}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5033 For symmetric ciphers, use as large as of a key as possible. For the most part \textit{bits are cheap} so using a 256--bit key
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5034 is not a hard thing to do. As a good rule of thumb do not use a key smaller than 128 bits.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5035
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5036 \subsection{Asymmetric Ciphers}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5037 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
5038 $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
5039 \begin{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5040 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
5041 \end{equation}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5042
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5043 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
5044 is:
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5045 \begin{figure}[here]
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5046 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5047 \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
5048 \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
5049 \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
5050 \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
5051 \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
5052 \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
5053 \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
5054 \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
5055 \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
5056 \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
5057 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5058 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5059 \end{center}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5060 \caption{RSA/DH Key Strength}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5061 \end{figure}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5062
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5063 The work factor for ECC keys is much higher since the best attack is still fully exponential. Given a key of magnitude
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5064 $n$ it requires $\sqrt n$ work. The following table summarizes the work required:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5065 \begin{figure}[here]
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5066 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5067 \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
5068 \hline ECC Key Size (bits) & Work Factor ($log_2$) \\
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5069 \hline 112 & 56 \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5070 \hline 128 & 64 \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5071 \hline 160 & 80 \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5072 \hline 192 & 96 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5073 \hline 224 & 112 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5074 \hline 256 & 128 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5075 \hline 384 & 192 \\
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5076 \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
5077 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5078 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5079 \end{center}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5080 \caption{ECC Key Strength}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5081 \end{figure}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5082
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5083 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
5084 \begin{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5085 \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
5086 \hline Security Goal & RSA/DH Key Size (bits) & ECC Key Size (bits) \\
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5087 \hline Near term & 1024 & 160 \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5088 \hline Short term & 1536 & 192 \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5089 \hline Long Term & 2560 & 384 \\
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5090 \hline
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5091 \end{tabular}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5092 \end{center}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5093
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5094 \mysection{Thread Safety}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5095 The library is not fully thread safe but several simple precautions can be taken to avoid any problems. The registry functions
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5096 such as register\_cipher() are not thread safe no matter what you do. It is best to call them from your programs initialization
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5097 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
5098
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5099 The rest of the code uses state variables you must pass it such as hash\_state, hmac\_state, etc. This means that if each
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5100 thread has its own state variables then they will not affect each other, and are fully thread safe. This is fairly simple with symmetric ciphers
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5101 and hashes.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5102
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5103 \index{LTC\_PTHREAD}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5104 The only sticky issue is a shared PRNG which can be alleviated with the careful use of mutex devices. Defining LTC\_PTHREAD for instance, enables
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5105 pthreads based mutex locking in various routines such as the Yarrow and Fortuna PRNGs, the fixed point ECC multiplier, and other routines.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5106
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5107 \chapter{Configuring and Building the Library}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5108 \mysection{Introduction}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5109 The library is fairly flexible about how it can be built, used, and generally distributed. Additions are being made with
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5110 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
5111 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
5112
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5113 As of v1.06 of the library, the build process has been moved to two steps for the typical LibTomCrypt application. This is because
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5114 LibTomCrypt no longer provides a math API on its own and relies on third party libraries (such as LibTomMath, GnuMP, or TomsFastMath).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5115
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5116 The build process now consists of installing a math library first, and then building and installing LibTomCrypt with a math library
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5117 configured. Note that LibTomCrypt can be built with no internal math descriptors. This means that one must be provided at either
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5118 build, or run time for the application. LibTomCrypt comes with three math descriptors that provide a standard interface to math
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5119 libraries.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5120
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5121 \mysection{Makefile variables}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5122
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5123 All GNU driven makefiles (including the makefile for ICC) use a set of common variables to control the build and install process. Most of the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5124 settings can be overwritten from the command line which makes custom installation a breeze.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5125
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5126 \index{MAKE}\index{CC}\index{AR}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5127 \subsection{MAKE, CC and AR}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5128 The MAKE, CC and AR flags can all be overwritten. They default to \textit{make}, \textit{\$CC} and \textit{\$AR} respectively.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5129 Changing MAKE allows you to change what program will be invoked to handle sub--directories. For example, this
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5130
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5131 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5132 MAKE=gmake gmake install
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5133 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5134
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5135 \begin{flushleft} will build and install the libraries with the \textit{gmake} tool. Similarly, \end{flushleft}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5136
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5137 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5138 CC=arm-gcc AR=arm-ar make
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5139 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5140
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5141 \begin{flushleft} will build the library using \textit{arm--gcc} as the compiler and \textit{arm--ar} as the archiver. \end{flushleft}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5142
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5143 \subsection{IGNORE\_SPEED}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5144 \index{IGNORE\_SPEED}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5145 When \textbf{IGNORE\_SPEED} has been defined the default optimization flags for CFLAGS will be disabled which allows the developer to specify new
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5146 CFLAGS on the command line. E.g. to add debugging
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5147
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5148 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5149 CFLAGS="-g3" make IGNORE_SPEED=1
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5150 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5151
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5152 This will turn off optimizations and add \textit{-g3} to the CFLAGS which enables debugging.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5153
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5154 \subsection{LIBNAME and LIBNAME\_S}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5155 \index{LIBNAME} \index{LIBNAME\_S}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5156 \textbf{LIBNAME} is the name of the output library (archive) to create. It defaults to \textit{libtomcrypt.a} for static builds and \textit{libtomcrypt.la} for
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5157 shared. The \textbf{LIBNAME\_S} variable is the static name while doing shared builds. Ideally they should have the same prefix but don't have to.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5158
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5159 \index{LIBTEST} \index{LIBTEST\_S}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5160 Similarly \textbf{LIBTEST} and \textbf{LIBTEST\_S} are the names for the profiling and testing library. The default is \textit{libtomcrypt\_prof.a} for
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5161 static and \textit{libtomcrypt\_prof.la} for shared.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5162
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5163 \subsection{Installation Directories}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5164 \index{DESTDIR} \index{LIBPATH} \index{INCPATH} \index{DATADIR}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5165 \textbf{DESTDIR} is the prefix for the installation directories. It defaults to an empty string. \textbf{LIBPATH} is the prefix for the library
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5166 directory which defaults to \textit{/usr/lib}. \textbf{INCPATH} is the prefix for the header file directory which defaults to \textit{/usr/include}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5167 \textbf{DATADIR} is the prefix for the data (documentation) directory which defaults to \textit{/usr/share/doc/libtomcrypt/pdf}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5168
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5169 All four can be used to create custom install locations depending on the nature of the OS and file system in use.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5170
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5171 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5172 make LIBPATH=/home/tom/project/lib INCPATH=/home/tom/project/include \
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5173 DATAPATH=/home/tom/project/docs install
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5174 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5175
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5176 This will build the library and install it to the directories under \textit{/home/tom/project/}. e.g.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5177
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5178 \begin{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5179 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5180 /home/tom/project/:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5181 total 1
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5182 drwxr-xr-x 2 tom users 80 Jul 30 16:02 docs
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5183 drwxr-xr-x 2 tom users 528 Jul 30 16:02 include
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5184 drwxr-xr-x 2 tom users 80 Jul 30 16:02 lib
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5185
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5186 /home/tom/project/docs:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5187 total 452
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5188 -rwxr-xr-x 1 tom users 459009 Jul 30 16:02 crypt.pdf
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5189
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5190 /home/tom/project/include:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5191 total 132
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5192 -rwxr-xr-x 1 tom users 2482 Jul 30 16:02 tomcrypt.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5193 -rwxr-xr-x 1 tom users 702 Jul 30 16:02 tomcrypt_argchk.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5194 -rwxr-xr-x 1 tom users 2945 Jul 30 16:02 tomcrypt_cfg.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5195 -rwxr-xr-x 1 tom users 22763 Jul 30 16:02 tomcrypt_cipher.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5196 -rwxr-xr-x 1 tom users 5174 Jul 30 16:02 tomcrypt_custom.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5197 -rwxr-xr-x 1 tom users 11314 Jul 30 16:02 tomcrypt_hash.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5198 -rwxr-xr-x 1 tom users 11571 Jul 30 16:02 tomcrypt_mac.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5199 -rwxr-xr-x 1 tom users 13614 Jul 30 16:02 tomcrypt_macros.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5200 -rwxr-xr-x 1 tom users 14714 Jul 30 16:02 tomcrypt_math.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5201 -rwxr-xr-x 1 tom users 632 Jul 30 16:02 tomcrypt_misc.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5202 -rwxr-xr-x 1 tom users 10934 Jul 30 16:02 tomcrypt_pk.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5203 -rwxr-xr-x 1 tom users 2634 Jul 30 16:02 tomcrypt_pkcs.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5204 -rwxr-xr-x 1 tom users 7067 Jul 30 16:02 tomcrypt_prng.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5205 -rwxr-xr-x 1 tom users 1467 Jul 30 16:02 tomcrypt_test.h
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5206
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5207 /home/tom/project/lib:
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5208 total 1073
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5209 -rwxr-xr-x 1 tom users 1096284 Jul 30 16:02 libtomcrypt.a
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5210 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5211 \end{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5212
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5213 \mysection{Extra libraries}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5214 \index{EXTRALIBS}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5215 \textbf{EXTRALIBS} specifies any extra libraries required to link the test programs and shared libraries. They are specified in the notation
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5216 that GCC expects for global archives.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5217
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5218 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5219 CFLAGS="-DTFM_DESC -DUSE_TFM" EXTRALIBS=-ltfm make install \
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5220 test timing
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5221 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5222
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5223 This will install the library using the TomsFastMath library and link the \textit{libtfm.a} library out of the default library search path. The two
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5224 defines are explained below. You can specify multiple archives (say if you want to support two math libraries, or add on additional code) to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5225 the \textbf{EXTRALIBS} variable by separating them by a space.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5226
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5227 Note that \textbf{EXTRALIBS} is not required if you are only making and installing the static library but none of the test programs.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5228
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5229 \mysection{Building a Static Library}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5230
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5231 Building a static library is fairly trivial as it only requires one invocation of the GNU make command.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5232
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5233 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5234 CFLAGS="-DTFM_DESC" make install
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5235 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5236
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5237 That will build LibTomCrypt (including the TomsFastMath descriptor), and install it in the default locations indicated previously. You can enable
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5238 the built--in LibTomMath descriptor as well (or in place of the TomsFastMath descriptor). Similarly, you can build the library with no built--in
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5239 math descriptors.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5240
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5241 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5242 make install
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5243 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5244
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5245 In this case, no math descriptors are present in the library and they will have to be made available at build or run time before you can use any of the
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5246 public key functions.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5247
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5248 Note that even if you include the built--in descriptors you must link against the source library as well.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5249
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5250 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5251 gcc -DTFM_DESC myprogram.c -ltomcrypt -ltfm -o myprogram
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5252 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5253
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5254 This will compile \textit{myprogram} and link it against the LibTomCrypt library as well as TomsFastMath (which must have been previously installed). Note that
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5255 we define \textbf{TFM\_DESC} for compilation. This is so that the TFM descriptor symbol will be defined for the client application to make use of without
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5256 giving warnings.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5257
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5258 \mysection{Building a Shared Library}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5259
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5260 LibTomCrypt can also be built as a shared library through the \textit{makefile.shared} make script. It is similar to use as the static script except
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5261 that you \textbf{must} specify the \textbf{EXTRALIBS} variable at install time.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5262
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5263 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5264 CFLAGS="-DTFM_DESC" EXTRALIBS=-ltfm make -f makefile.shared install
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5265 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5266
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5267 This will build and install the library and link the shared object against the TomsFastMath library (which must be installed as a shared object as well). The
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5268 shared build process requires libtool to be installed.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5269
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5270 \mysection{Header Configuration}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5271 The file \textit{tomcrypt\_cfg.h} is what lets you control various high level macros which control the behaviour of the library. Build options are also
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5272 stored in \textit{tomcrypt\_custom.h} which allow the enabling and disabling of various algorithms.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5273
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5274 \subsubsection{ARGTYPE}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5275 This lets you control how the LTC\_ARGCHK macro will behave. The macro is used to check pointers inside the functions against
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5276 NULL. There are four settings for ARGTYPE. When set to 0, it will have the default behaviour of printing a message to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5277 stderr and raising a SIGABRT signal. This is provided so all platforms that use LibTomCrypt can have an error that functions
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5278 similarly. When set to 1, it will simply pass on to the assert() macro. When set to 2, the macro will display the error to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5279 stderr then return execution to the caller. This could lead to a segmentation fault (e.g. when a pointer is \textbf{NULL}) but is useful
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5280 if you handle signals on your own. When set to 3, it will resolve to a empty macro and no error checking will be performed. Finally, when set
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5281 to 4, it will return CRYPT\_INVALID\_ARG to the caller.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5282
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5283 \subsubsection{Endianess}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5284 There are five macros related to endianess issues. For little endian platforms define, \textbf{ENDIAN\_LITTLE}. For big endian
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5285 platforms define \textbf{ENDIAN\_BIG}. Similarly when the default word size of an \textit{unsigned long} is 32-bits define \textbf{ENDIAN\_32BITWORD}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5286 or define \textbf{ENDIAN\_64BITWORD} when its 64-bits. If you do not define any of them the library will automatically use \textbf{ENDIAN\_NEUTRAL}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5287 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
5288
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5289 Currently LibTomCrypt will detect x86-32, x86-64, MIPS R5900, SPARC and SPARC64 running GCC as well as x86-32 running MSVC.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5290
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5291 \mysection{The Configure Script}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5292 There are also options you can specify from the \textit{tomcrypt\_custom.h} header file.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5293
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5294 \subsection{X memory routines}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5295 \index{XMALLOC}\index{XCALLOC}\index{XREALLOC}\index{XFREE}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5296 At the top of tomcrypt\_custom.h are a series of macros denoted as XMALLOC, XCALLOC, XREALLOC, XFREE, and so on. They resolve to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5297 the name of the respective functions from the standard C library by default. This lets you substitute in your own memory routines.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5298 If you substitute in your own functions they must behave like the standard C library functions in terms of what they expect as input and
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5299 output.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5300
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5301 These macros are handy for working with platforms which do not have a standard C library. For instance, the OLPC\footnote{See http://dev.laptop.org/git?p=bios-crypto;a=summary}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5302 bios code uses these macros to redirect to very compact heap and string operations.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5303
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5304 \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
5305 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
5306 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
5307
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5308 \subsection{LTC\_NO\_FILE}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5309 During the build if LTC\_NO\_FILE is defined then any function in the library that uses file I/O will not call the file I/O
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5310 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
5311 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
5312
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5313 \subsection{LTC\_CLEAN\_STACK}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5314 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
5315 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
5316
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5317 \subsection{LTC\_TEST}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5318 When this has been defined the various self--test functions (for ciphers, hashes, prngs, etc) are included in the build. This is the default configuration.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5319 If LTC\_NO\_TEST has been defined, the testing routines will be compacted and only return CRYPT\_NOP.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5320
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5321 \subsection{LTC\_NO\_FAST}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5322 When this has been defined the library will not use faster word oriented operations. By default, they are only enabled for platforms
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5323 which can be auto-detected. This macro ensures that they are never enabled.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5324
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5325 \subsection{LTC\_FAST}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5326 This mode (auto-detected with x86\_32,x86\_64 platforms with GCC or MSVC) configures various routines such as ctr\_encrypt() or
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5327 cbc\_encrypt() that it can safely XOR multiple octets in one step by using a larger data type. This has the benefit of
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5328 cutting down the overhead of the respective functions.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5329
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5330 This mode does have one downside. It can cause unaligned reads from memory if you are not careful with the functions. This is why
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5331 it has been enabled by default only for the x86 class of processors where unaligned accesses are allowed. Technically LTC\_FAST
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5332 is not \textit{portable} since unaligned accesses are not covered by the ISO C specifications.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5333
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5334 In practice however, you can use it on pretty much any platform (even MIPS) with care.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5335
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5336 By design the \textit{fast} mode functions won't get unaligned on their own. For instance, if you call ctr\_encrypt() right after calling
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5337 ctr\_start() and all the inputs you gave are aligned than ctr\_encrypt() will perform aligned memory operations only. However, if you
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5338 call ctr\_encrypt() with an odd amount of plaintext then call it again the CTR pad (the IV) will be partially used. This will
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5339 cause the ctr routine to first use up the remaining pad bytes. Then if there are enough plaintext bytes left it will use
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5340 whole word XOR operations. These operations will be unaligned.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5341
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5342 The simplest precaution is to make sure you process all data in power of two blocks and handle \textit{remainder} at the end. e.g. If you are
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5343 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.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5344
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5345 \index{LTC\_FAST\_TYPE}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5346 If you do plan on using the \textit{LTC\_FAST} mode you have to also define a \textit{LTC\_FAST\_TYPE} macro which resolves to an optimal sized
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5347 data type you can perform integer operations with. Ideally it should be four or eight bytes since it must properly divide the size
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5348 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
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5349 use this mode. So sad.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5350
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5351 \subsection{LTC\_NO\_ASM}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5352 When this has been defined the library will not use any inline assembler. Only a few platforms support assembler inlines but various versions of ICC and GCC
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5353 cannot handle all of the assembler functions.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5354
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5355 \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
5356 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
5357 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
5358 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
5359 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
5360
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5361 Also see technical note number five for more details.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5362
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5363 \subsection{LTC\_EASY}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5364 When defined the library is configured to build fewer algorithms and modes. Mostly it sticks to NIST and ANSI approved algorithms. See
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5365 the header file \textit{tomcrypt\_custom.h} for more details. It is meant to provide literally an easy method of trimming the library
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5366 build to the most minimum of useful functionality.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5367
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5368 \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
5369 Twofish is a 128-bit symmetric block cipher that is provided within the library. The cipher itself is flexible enough
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5370 to allow some trade-offs in the implementation. When TWOFISH\_SMALL is defined the scheduled symmetric key for Twofish
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5371 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
5372 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
5373 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
5374
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5375 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
5376 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
5377 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
5378 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
5379
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5380 \subsection{GCM\_TABLES}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5381 When defined GCM will use a 64KB table (per GCM state) which will greatly speed up the per--packet latency.
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5382 It also increases the initialization time and is not suitable when you are going to use a key a few times only.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5383
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5384 \subsection{GCM\_TABLES\_SSE2}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5385 \index{SSE2}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5386 When defined GCM will use the SSE2 instructions to perform the $GF(2^x)$ multiply using 16 128--bit XOR operations. It shaves a few cycles per byte
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5387 of GCM output on both the AMD64 and Intel Pentium 4 platforms. Requires GCC and an SSE2 equipped platform.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5388
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5389 \subsection{LTC\_SMALL\_CODE}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5390 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
5391 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
5392
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5393 \subsection{LTC\_PTHREAD}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5394 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
5395 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
5396
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5397 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
5398 the tables safer.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5399
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5400 \subsection{LTC\_ECC\_TIMING\_RESISTANT}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5401 When this has been defined the ECC point multiplier (built--in to the library) will use a timing resistant point multiplication
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5402 algorithm which prevents leaking key bits of the private key (scalar). It is a slower algorithm but useful for situations
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5403 where timing side channels pose a significant threat.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5404
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5405 \subsection{Math Descriptors}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5406 The library comes with three math descriptors that allow you to interface the public key cryptography API to freely available math
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5407 libraries. When \textbf{GMP\_DESC}, \textbf{LTM\_DESC}, or \textbf{TFM\_DESC} are defined
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5408 descriptors for the respective library are built and included in the library as \textit{gmp\_desc}, \textit{ltm\_desc}, or \textit{tfm\_desc} respectively.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5409
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5410 In the test demos that use the libraries the additional flags \textbf{USE\_GMP}, \textbf{USE\_LTM}, and \textbf{USE\_TFM} can be defined
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5411 to tell the program which library to use. Only one of the USE flags can be defined at once.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5412
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5413 \index{GMP\_DESC} \index{USE\_GMP} \index{LTM\_DESC} \index{TFM\_DESC} \index{USE\_LTM} \index{USE\_TFM}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5414 \begin{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5415 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5416 CFLAGS="-DGMP_DESC -DLTM_DESC -DTFM_DESC -DUSE_TFM" \
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5417 EXTRALIBS="-lgmp -ltommath -ltfm" make -f makefile.shared install timing
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5418 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5419 \end{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5420
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5421 That will build and install the library with all descriptors (and link against all), but only use TomsFastMath in the timing demo.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5422
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5423 \chapter{Optimizations}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5424 \mysection{Introduction}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5425 The entire API was designed with plug and play in mind at the low level. That is you can swap out any cipher, hash, PRNG or bignum library and the dependent API will not
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5426 require updating. This has the nice benefit that one can add ciphers (etc.) not have to re--write portions of the API. For the most part, LibTomCrypt has also been written
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5427 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
5428 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
5429
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5430 That works well for most cases but there are times where performance is of the essence. This API allows optimized routines to be dropped in--place of the existing
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5431 portable routines. For instance, hand optimized assembler versions of AES could be provided. Any existing function that uses the cipher could automatically use
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5432 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
5433
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5434 At the heart of this flexibility is the \textit{descriptor} system. A descriptor is essentially just a C \textit{struct} which describes the algorithm and provides pointers
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5435 to functions that do the required work. For a given class of operation (e.g. cipher, hash, prng, bignum) the functions of a descriptor have identical prototypes which makes
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5436 development simple. In most dependent routines all an end developer has to do is register\_XXX() the descriptor and they are set.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5437
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5438 \mysection{Ciphers}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5439 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
5440
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5441 \label{sec:cipherdesc}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5442 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5443 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5444 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
5445 /** name of cipher */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5446 char *name;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5447
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5448 /** internal ID */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5449 unsigned char ID;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5450
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5451 /** min keysize (octets) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5452 int min_key_length,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5453
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5454 /** max keysize (octets) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5455 max_key_length,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5456
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5457 /** block size (octets) */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5458 block_length,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5459
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5460 /** 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
5461 default_rounds;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5462
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5463 /** Setup the cipher
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5464 @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
5465 @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
5466 @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
5467 @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
5468 @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
5469 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5470 int (*setup)(const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5471 int keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5472 int num_rounds,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5473 symmetric_key *skey);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5474
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5475 /** Encrypt a block
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5476 @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
5477 @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
5478 @param skey The scheduled key
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5479 @return CRYPT_OK if successful
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5480 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5481 int (*ecb_encrypt)(const unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5482 unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5483 symmetric_key *skey);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5484
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5485 /** Decrypt a block
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5486 @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
5487 @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
5488 @param skey The scheduled key
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5489 @return CRYPT_OK if successful
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5490 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5491 int (*ecb_decrypt)(const unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5492 unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5493 symmetric_key *skey);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5494
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5495 /** Test the block cipher
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5496 @return CRYPT_OK if successful,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5497 CRYPT_NOP if self-testing has been disabled
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5498 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5499 int (*test)(void);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5500
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5501 /** Terminate the context
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5502 @param skey The scheduled key
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5503 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5504 void (*done)(symmetric_key *skey);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5505
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5506 /** Determine a key size
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5507 @param keysize [in/out] The size of the key desired
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5508 The suggested size
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5509 @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
5510 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5511 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
5512
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5513 /** Accelerators **/
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5514 /** Accelerated ECB encryption
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5515 @param pt Plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5516 @param ct Ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5517 @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
5518 @param skey The scheduled key context
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5519 @return CRYPT_OK if successful
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5520 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5521 int (*accel_ecb_encrypt)(const unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5522 unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5523 unsigned long blocks,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5524 symmetric_key *skey);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5525
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5526 /** Accelerated ECB decryption
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5527 @param pt Plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5528 @param ct Ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5529 @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
5530 @param skey The scheduled key context
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5531 @return CRYPT_OK if successful
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5532 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5533 int (*accel_ecb_decrypt)(const unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5534 unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5535 unsigned long blocks,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5536 symmetric_key *skey);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5537
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5538 /** Accelerated CBC encryption
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5539 @param pt Plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5540 @param ct Ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5541 @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
5542 @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
5543 @param skey The scheduled key context
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5544 @return CRYPT_OK if successful
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5545 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5546 int (*accel_cbc_encrypt)(const unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5547 unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5548 unsigned long blocks,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5549 unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5550 symmetric_key *skey);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5551
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5552 /** Accelerated CBC decryption
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5553 @param pt Plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5554 @param ct Ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5555 @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
5556 @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
5557 @param skey The scheduled key context
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5558 @return CRYPT_OK if successful
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5559 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5560 int (*accel_cbc_decrypt)(const unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5561 unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5562 unsigned long blocks,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5563 unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5564 symmetric_key *skey);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5565
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5566 /** Accelerated CTR encryption
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5567 @param pt Plaintext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5568 @param ct Ciphertext
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5569 @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
5570 @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
5571 @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
5572 @param skey The scheduled key context
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5573 @return CRYPT_OK if successful
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5574 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5575 int (*accel_ctr_encrypt)(const unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5576 unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5577 unsigned long blocks,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5578 unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5579 int mode,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5580 symmetric_key *skey);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5581
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5582 /** Accelerated LRW
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5583 @param pt Plaintext
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5584 @param ct Ciphertext
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5585 @param blocks The number of complete blocks to process
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5586 @param IV The initial value (input/output)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5587 @param tweak The LRW tweak
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5588 @param skey The scheduled key context
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5589 @return CRYPT_OK if successful
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5590 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5591 int (*accel_lrw_encrypt)(const unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5592 unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5593 unsigned long blocks,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5594 unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5595 const unsigned char *tweak,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5596 symmetric_key *skey);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5597
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5598 /** Accelerated LRW
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5599 @param ct Ciphertext
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5600 @param pt Plaintext
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5601 @param blocks The number of complete blocks to process
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5602 @param IV The initial value (input/output)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5603 @param tweak The LRW tweak
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5604 @param skey The scheduled key context
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5605 @return CRYPT_OK if successful
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5606 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5607 int (*accel_lrw_decrypt)(const unsigned char *ct,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5608 unsigned char *pt,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5609 unsigned long blocks,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5610 unsigned char *IV,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5611 const unsigned char *tweak,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5612 symmetric_key *skey);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5613
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5614 /** 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
5615 @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
5616 @param keylen The length of the secret key (octets)
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5617 @param uskey A previously scheduled key [can be NULL]
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5618 @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
5619 @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
5620 @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
5621 @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
5622 @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
5623 @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
5624 @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
5625 @param tag [out] The destination tag
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5626 @param taglen [in/out] The max size and resulting size
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5627 of the authentication tag
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5628 @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
5629 @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
5630 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5631 int (*accel_ccm_memory)(
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5632 const unsigned char *key, unsigned long keylen,
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5633 symmetric_key *uskey,
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5634 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
5635 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
5636 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
5637 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5638 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
5639 int direction);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5640
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5641 /** Accelerated GCM packet (one shot)
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5642 @param key The secret key
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5643 @param keylen The length of the secret key
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5644 @param IV The initial vector
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5645 @param IVlen The length of the initial vector
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5646 @param adata The additional authentication data (header)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5647 @param adatalen The length of the adata
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5648 @param pt The plaintext
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5649 @param ptlen The length of the plaintext/ciphertext
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5650 @param ct The ciphertext
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5651 @param tag [out] The MAC tag
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5652 @param taglen [in/out] The MAC tag length
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5653 @param direction Encrypt or Decrypt mode (GCM_ENCRYPT or GCM_DECRYPT)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5654 @return CRYPT_OK on success
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5655 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5656 int (*accel_gcm_memory)(
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5657 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
5658 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
5659 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
5660 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
5661 unsigned char *ct,
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5662 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
5663 int direction);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5664
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5665 /** Accelerated one shot OMAC
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5666 @param key The secret key
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5667 @param keylen The key length (octets)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5668 @param in The message
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5669 @param inlen Length of message (octets)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5670 @param out [out] Destination for tag
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5671 @param outlen [in/out] Initial and final size of out
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5672 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5673 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5674 int (*omac_memory)(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5675 const unsigned char *key, unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5676 const unsigned char *in, unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5677 unsigned char *out, unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5678
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5679 /** Accelerated one shot XCBC
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5680 @param key The secret key
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5681 @param keylen The key length (octets)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5682 @param in The message
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5683 @param inlen Length of message (octets)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5684 @param out [out] Destination for tag
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5685 @param outlen [in/out] Initial and final size of out
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5686 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5687 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5688 int (*xcbc_memory)(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5689 const unsigned char *key, unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5690 const unsigned char *in, unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5691 unsigned char *out, unsigned long *outlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5692
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5693 /** Accelerated one shot F9
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5694 @param key The secret key
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5695 @param keylen The key length (octets)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5696 @param in The message
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5697 @param inlen Length of message (octets)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5698 @param out [out] Destination for tag
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5699 @param outlen [in/out] Initial and final size of out
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5700 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5701 @remark Requires manual padding
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5702 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5703 int (*f9_memory)(
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5704 const unsigned char *key, unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5705 const unsigned char *in, unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5706 unsigned char *out, unsigned long *outlen);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5707 };
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5708 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5709 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5710
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5711 \subsection{Name}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5712 \index{find\_cipher()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5713 The \textit{name} parameter specifies the name of the cipher. This is what a developer would pass to find\_cipher() to find the cipher in the descriptor
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5714 tables.
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5715
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5716 \subsection{Internal ID}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5717 This is a single byte Internal ID you can use to distinguish ciphers from each other.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5718
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5719 \subsection{Key Lengths}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5720 The minimum key length is \textit{min\_key\_length} and is measured in octets. Similarly the maximum key length is \textit{max\_key\_length}. They can be equal
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5721 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
5722
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5723 \subsection{Block Length}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5724 The size of the ciphers plaintext or ciphertext is \textit{block\_length} and is measured in octets.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5725
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5726 \subsection{Rounds}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5727 Some ciphers allow different number of rounds to be used. Usually you just use the default. The default round count is \textit{default\_rounds}.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5728
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5729 \subsection{Setup}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5730 To initialize a cipher (for ECB mode) the function setup() was provided. It accepts an array of key octets \textit{key} of length \textit{keylen} octets. The user
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5731 can specify the number of rounds they want through \textit{num\_rounds} where $num\_rounds = 0$ means use the default. The destination of a scheduled key is stored
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5732 in \textit{skey}.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5733
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5734 Inside the \textit{symmetric\_key} union there is a \textit{void *data} which you can use to allocate data if you need a data structure that does not fit with the existing
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5735 ones provided. Just make sure in your \textit{done()} function that you free the allocated memory.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5736
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5737 \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
5738 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
5739 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
5740
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5741 \subsection{Testing}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5742 The test() function is used to self--test the \textit{device}. It takes no arguments and returns \textbf{CRYPT\_OK} if all is working properly. You may return
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5743 \textbf{CRYPT\_NOP} to indicate that no testing was performed.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5744
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5745 \subsection{Key Sizing}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5746 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
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5747 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
5748 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
5749 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
5750
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5751 \subsection{Acceleration}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5752 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5753 it is not supported. In those cases the software defaults are used (using the single ECB block routines).
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5754
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5755 \subsubsection{Accelerated ECB}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5756 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5757 through the accel\_ecb\_encrypt and accel\_ecb\_decrypt pointers. The \textit{blocks} count is the number of complete blocks to process.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5758
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5759 \subsubsection{Accelerated CBC}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5760 These two functions are meant for accelerated CBC encryption. These functions are accessed through the accel\_cbc\_encrypt and accel\_cbc\_decrypt pointers.
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5761 The \textit{blocks} value is the number of complete blocks to process. The \textit{IV} is the CBC initial vector. It is an input upon calling this function and must be
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5762 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
5763
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5764 \subsubsection{Accelerated CTR}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5765 This function is meant for accelerated CTR encryption. It is accessible through the accel\_ctr\_encrypt pointer.
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5766 The \textit{blocks} value is the number of complete blocks to process. The \textit{IV} is the CTR counter vector. It is an input upon calling this function and must be
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5767 updated by the function before returning. The \textit{mode} value indicates whether the counter is big (mode = CTR\_COUNTER\_BIG\_ENDIAN) or
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5768 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
5769
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5770 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
5771 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
5772
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5773 \begin{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5774 \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
5775 \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
5776 \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
5777 \end{enumerate}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5778
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5779 The \textit{CTR pad} is empty when a multiple (including zero) blocks of text have been processed. That is, if you pass in seven bytes to AES--CTR mode you would have to
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5780 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
5781 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
5782
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5783 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
5784
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5785 \subsubsection{Accelerated LRW}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5786 These functions are meant for accelerated LRW. They process blocks of input in lengths of multiples of 16 octets. They must accept the \textit{IV} and \textit{tweak}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5787 state variables and updated them prior to returning. Note that you may want to disable \textbf{LRW\_TABLES} in \textit{tomcrypt\_custom.h} if you intend
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5788 to use accelerators for LRW.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5789
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5790 While both encrypt and decrypt accelerators are not required it is suggested as it makes lrw\_setiv() more efficient.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5791
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5792 Note that calling lrw\_done() will only invoke the cipher\_descriptor[].done() function on the \textit{symmetric\_key} parameter of the LRW state. That means
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5793 if your device requires any (LRW specific) resources you should free them in your ciphers() done function. The simplest way to think of it is to write
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5794 the plugin solely to do LRW with the cipher. That way cipher\_descriptor[].setup() means to init LRW resources and cipher\_descriptor[].done() means to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5795 free them.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5796
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5797 \subsubsection{Accelerated CCM}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5798 This function is meant for accelerated CCM encryption or decryption. It processes the entire packet in one call. You can optimize the work flow somewhat
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5799 by allowing the caller to call the setup() function first to schedule the key if your accelerator cannot do the key schedule on the fly (for instance). This
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5800 function MUST support both key passing methods.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5801
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5802 \begin{center}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5803 \begin{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5804 \begin{tabular}{|r|r|l|}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5805 \hline \textbf{key} & \textbf{uskey} & \textbf{Source of key} \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5806 \hline NULL & NULL & Error, not supported \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5807 \hline non-NULL & NULL & Use key, do a key schedule \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5808 \hline NULL & non-NULL & Use uskey, key schedule not required \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5809 \hline non-NULL & non-NULL & Use uskey, key schedule not required \\
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5810 \hline
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5811 \end{tabular}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5812 \end{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5813 \end{center}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5814
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5815 \index{ccm\_memory()} This function is called when the user calls ccm\_memory().
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5816
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5817 \subsubsection{Accelerated GCM}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5818 \index{gcm\_memory()}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5819 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
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5820 be called prior to this. This function must handle scheduling the key provided on its own. It is called when the user calls gcm\_memory().
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5821
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5822 \subsubsection{Accelerated OMAC}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5823 \index{omac\_memory()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5824 This function is meant to perform an optimized OMAC1 (CMAC) message authentication code computation when the user calls omac\_memory().
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5825
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5826 \subsubsection{Accelerated XCBC-MAC}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5827 \index{xcbc\_memory()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5828 This function is meant to perform an optimized XCBC-MAC message authentication code computation when the user calls xcbc\_memory().
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5829
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5830 \subsubsection{Accelerated F9}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5831 \index{f9\_memory()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5832 This function is meant to perform an optimized F9 message authentication code computation when the user calls f9\_memory(). Like f9\_memory(), it requires
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5833 the caller to perform any 3GPP related padding before calling in order to ensure proper compliance with F9.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5834
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5835
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5836 \mysection{One--Way Hashes}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5837 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
5838
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5839 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5840 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5841 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
5842 /** name of hash */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5843 char *name;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5844
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5845 /** internal ID */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5846 unsigned char ID;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5847
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5848 /** 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
5849 unsigned long hashsize;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5850
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5851 /** 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
5852 unsigned long blocksize;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5853
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5854 /** ASN.1 OID */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5855 unsigned long OID[16];
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5856
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5857 /** 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
5858 unsigned long OIDlen;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5859
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5860 /** 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
5861 @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
5862 @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
5863 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5864 int (*init)(hash_state *hash);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5865
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5866 /** 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
5867 @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
5868 @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
5869 @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
5870 @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
5871 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5872 int (*process)( hash_state *hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5873 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5874 unsigned long inlen);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5875
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5876 /** 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
5877 @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
5878 @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
5879 @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
5880 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5881 int (*done)( hash_state *hash,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5882 unsigned char *out);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5883
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5884 /** Self-test
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5885 @return CRYPT_OK if successful,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5886 CRYPT_NOP if self-tests have been disabled
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5887 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5888 int (*test)(void);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5889
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5890 /* accelerated hmac callback: if you need to-do
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5891 multiple packets just use the generic hmac_memory
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5892 and provide a hash callback
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5893 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5894 int (*hmac_block)(const unsigned char *key,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5895 unsigned long keylen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5896 const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5897 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5898 unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5899 unsigned long *outlen);
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5900 };
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5901 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5902 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5903
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5904 \subsection{Name}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5905 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
5906
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5907 \subsection{Internal ID}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5908 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
5909
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5910 \subsection{Digest Size}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5911 The \textit{hashsize} variable indicates the length of the output in octets.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5912
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5913 \subsection{Block Size}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5914 The \textit{blocksize} variable indicates the length of input (in octets) that the hash processes in a given
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5915 invocation.
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5916
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5917 \subsection{OID Identifier}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5918 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
5919
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5920 \subsection{Initialization}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5921 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
5922
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5923 \subsection{Process}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5924 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
5925 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
5926
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5927 \subsection{Done}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5928 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
5929
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5930 \subsection{Acceleration}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5931 A compatible accelerator must allow processing data in any granularity which may require internal padding on the driver side.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5932
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5933 \subsection{HMAC Acceleration}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5934 The hmac\_block() callback is meant for single--shot optimized HMAC implementations. It is called directly by hmac\_memory() if present. If you need
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5935 to be able to process multiple blocks per MAC then you will have to simply provide a process() callback and use hmac\_memory() as provided in LibTomCrypt.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5936
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5937 \mysection{Pseudo--Random Number Generators}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5938 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
5939
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5940 \begin{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5941 \begin{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5942 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
5943 /** 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
5944 char *name;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5945
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5946 /** 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
5947 int export_size;
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5948
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5949 /** 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
5950 @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
5951 @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
5952 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5953 int (*start)(prng_state *prng);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5954
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5955 /** 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
5956 @param in The entropy
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5957 @param inlen Length of the entropy (octets)
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5958 @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
5959 @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
5960 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5961 int (*add_entropy)(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5962 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5963 prng_state *prng);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5964
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5965 /** 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
5966 @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
5967 @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
5968 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5969 int (*ready)(prng_state *prng);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5970
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5971 /** 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
5972 @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
5973 @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
5974 @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
5975 @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
5976 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5977 unsigned long (*read)(unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5978 unsigned long outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5979 prng_state *prng);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5980
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5981 /** 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
5982 @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
5983 @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
5984 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5985 int (*done)(prng_state *prng);
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5986
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5987 /** 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
5988 @param out [out] The destination for the state
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5989 @param outlen [in/out] The max size and resulting size
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5990 @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
5991 @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
5992 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5993 int (*pexport)(unsigned char *out,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5994 unsigned long *outlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5995 prng_state *prng);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
5996
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5997 /** 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
5998 @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
5999 @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
6000 @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
6001 @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
6002 */
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6003 int (*pimport)(const unsigned char *in,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6004 unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6005 prng_state *prng);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6006
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6007 /** Self-test the PRNG
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6008 @return CRYPT_OK if successful,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6009 CRYPT_NOP if self-testing has been disabled
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6010 */
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6011 int (*test)(void);
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6012 };
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6013 \end{verbatim}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6014 \end{small}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6015
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6016 \subsection{Name}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6017 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
6018
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6019 \subsection{Export Size}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6020 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
6021
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6022 \subsection{Start}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6023 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
6024
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6025 \subsection{Entropy Addition}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6026 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
6027
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6028 \subsection{Ready}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6029 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
6030 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
6031
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6032 \subsection{Read}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6033 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
6034 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
6035
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6036 \subsection{Done}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6037 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
6038
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6039 \subsection{Exporting and Importing}
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6040 An exported PRNG state is data that the PRNG can later import to resume activity. They're not meant to resume \textit{the same session}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6041 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
6042
382
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6043 \mysection{BigNum Math Descriptors}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6044 The library also makes use of the math descriptors to access math functions. While bignum math libraries usually differ in implementation
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6045 it hasn't proven hard to write \textit{glue} to use math libraries so far. The basic descriptor looks like.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6046
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6047 \begin{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6048 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6049 /** math descriptor */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6050 typedef struct {
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6051 /** Name of the math provider */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6052 char *name;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6053
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6054 /** Bits per digit, amount of bits must fit in an unsigned long */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6055 int bits_per_digit;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6056
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6057 /* ---- init/deinit functions ---- */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6058
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6059 /** initialize a bignum
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6060 @param a The number to initialize
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6061 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6062 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6063 int (*init)(void **a);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6064
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6065 /** init copy
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6066 @param dst The number to initialize and write to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6067 @param src The number to copy from
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6068 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6069 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6070 int (*init_copy)(void **dst, void *src);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6071
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6072 /** deinit
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6073 @param a The number to free
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6074 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6075 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6076 void (*deinit)(void *a);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6077
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6078 /* ---- data movement ---- */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6079
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6080 /** copy
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6081 @param src The number to copy from
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6082 @param dst The number to write to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6083 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6084 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6085 int (*copy)(void *src, void *dst);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6086
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6087 /* ---- trivial low level functions ---- */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6088
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6089 /** set small constant
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6090 @param a Number to write to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6091 @param n Source upto bits_per_digit (meant for small constants)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6092 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6093 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6094 int (*set_int)(void *a, unsigned long n);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6095
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6096 /** get small constant
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6097 @param a Small number to read
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6098 @return The lower bits_per_digit of the integer (unsigned)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6099 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6100 unsigned long (*get_int)(void *a);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6101
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6102 /** get digit n
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6103 @param a The number to read from
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6104 @param n The number of the digit to fetch
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6105 @return The bits_per_digit sized n'th digit of a
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6106 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6107 unsigned long (*get_digit)(void *a, int n);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6108
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6109 /** Get the number of digits that represent the number
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6110 @param a The number to count
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6111 @return The number of digits used to represent the number
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6112 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6113 int (*get_digit_count)(void *a);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6114
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6115 /** compare two integers
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6116 @param a The left side integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6117 @param b The right side integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6118 @return LTC_MP_LT if a < b,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6119 LTC_MP_GT if a > b and
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6120 LTC_MP_EQ otherwise. (signed comparison)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6121 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6122 int (*compare)(void *a, void *b);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6123
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6124 /** compare against int
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6125 @param a The left side integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6126 @param b The right side integer (upto bits_per_digit)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6127 @return LTC_MP_LT if a < b,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6128 LTC_MP_GT if a > b and
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6129 LTC_MP_EQ otherwise. (signed comparison)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6130 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6131 int (*compare_d)(void *a, unsigned long n);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6132
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6133 /** Count the number of bits used to represent the integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6134 @param a The integer to count
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6135 @return The number of bits required to represent the integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6136 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6137 int (*count_bits)(void * a);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6138
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6139 /** Count the number of LSB bits which are zero
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6140 @param a The integer to count
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6141 @return The number of contiguous zero LSB bits
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6142 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6143 int (*count_lsb_bits)(void *a);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6144
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6145 /** Compute a power of two
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6146 @param a The integer to store the power in
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6147 @param n The power of two you want to store (a = 2^n)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6148 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6149 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6150 int (*twoexpt)(void *a , int n);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6151
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6152 /* ---- radix conversions ---- */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6153
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6154 /** read ascii string
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6155 @param a The integer to store into
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6156 @param str The string to read
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6157 @param radix The radix the integer has been represented in (2-64)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6158 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6159 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6160 int (*read_radix)(void *a, const char *str, int radix);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6161
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6162 /** write number to string
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6163 @param a The integer to store
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6164 @param str The destination for the string
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6165 @param radix The radix the integer is to be represented in (2-64)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6166 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6167 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6168 int (*write_radix)(void *a, char *str, int radix);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6169
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6170 /** get size as unsigned char string
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6171 @param a The integer to get the size
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6172 @return The length of the integer in octets
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6173 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6174 unsigned long (*unsigned_size)(void *a);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6175
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6176 /** store an integer as an array of octets
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6177 @param src The integer to store
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6178 @param dst The buffer to store the integer in
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6179 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6180 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6181 int (*unsigned_write)(void *src, unsigned char *dst);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6182
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6183 /** read an array of octets and store as integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6184 @param dst The integer to load
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6185 @param src The array of octets
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6186 @param len The number of octets
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6187 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6188 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6189 int (*unsigned_read)( void *dst,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6190 unsigned char *src,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6191 unsigned long len);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6192
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6193 /* ---- basic math ---- */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6194
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6195 /** add two integers
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6196 @param a The first source integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6197 @param b The second source integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6198 @param c The destination of "a + b"
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6199 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6200 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6201 int (*add)(void *a, void *b, void *c);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6202
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6203 /** add two integers
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6204 @param a The first source integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6205 @param b The second source integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6206 (single digit of upto bits_per_digit in length)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6207 @param c The destination of "a + b"
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6208 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6209 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6210 int (*addi)(void *a, unsigned long b, void *c);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6211
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6212 /** subtract two integers
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6213 @param a The first source integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6214 @param b The second source integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6215 @param c The destination of "a - b"
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6216 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6217 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6218 int (*sub)(void *a, void *b, void *c);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6219
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6220 /** subtract two integers
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6221 @param a The first source integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6222 @param b The second source integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6223 (single digit of upto bits_per_digit in length)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6224 @param c The destination of "a - b"
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6225 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6226 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6227 int (*subi)(void *a, unsigned long b, void *c);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6228
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6229 /** multiply two integers
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6230 @param a The first source integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6231 @param b The second source integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6232 (single digit of upto bits_per_digit in length)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6233 @param c The destination of "a * b"
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6234 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6235 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6236 int (*mul)(void *a, void *b, void *c);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6237
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6238 /** multiply two integers
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6239 @param a The first source integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6240 @param b The second source integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6241 (single digit of upto bits_per_digit in length)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6242 @param c The destination of "a * b"
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6243 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6244 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6245 int (*muli)(void *a, unsigned long b, void *c);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6246
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6247 /** Square an integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6248 @param a The integer to square
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6249 @param b The destination
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6250 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6251 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6252 int (*sqr)(void *a, void *b);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6253
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6254 /** Divide an integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6255 @param a The dividend
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6256 @param b The divisor
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6257 @param c The quotient (can be NULL to signify don't care)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6258 @param d The remainder (can be NULL to signify don't care)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6259 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6260 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6261 int (*div)(void *a, void *b, void *c, void *d);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6262
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6263 /** divide by two
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6264 @param a The integer to divide (shift right)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6265 @param b The destination
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6266 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6267 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6268 int (*div_2)(void *a, void *b);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6269
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6270 /** Get remainder (small value)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6271 @param a The integer to reduce
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6272 @param b The modulus (upto bits_per_digit in length)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6273 @param c The destination for the residue
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6274 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6275 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6276 int (*modi)(void *a, unsigned long b, unsigned long *c);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6277
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6278 /** gcd
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6279 @param a The first integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6280 @param b The second integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6281 @param c The destination for (a, b)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6282 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6283 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6284 int (*gcd)(void *a, void *b, void *c);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6285
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6286 /** lcm
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6287 @param a The first integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6288 @param b The second integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6289 @param c The destination for [a, b]
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6290 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6291 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6292 int (*lcm)(void *a, void *b, void *c);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6293
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6294 /** Modular multiplication
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6295 @param a The first source
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6296 @param b The second source
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6297 @param c The modulus
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6298 @param d The destination (a*b mod c)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6299 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6300 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6301 int (*mulmod)(void *a, void *b, void *c, void *d);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6302
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6303 /** Modular squaring
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6304 @param a The first source
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6305 @param b The modulus
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6306 @param c The destination (a*a mod b)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6307 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6308 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6309 int (*sqrmod)(void *a, void *b, void *c);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6310
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6311 /** Modular inversion
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6312 @param a The value to invert
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6313 @param b The modulus
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6314 @param c The destination (1/a mod b)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6315 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6316 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6317 int (*invmod)(void *, void *, void *);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6318
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6319 /* ---- reduction ---- */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6320
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6321 /** setup Montgomery
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6322 @param a The modulus
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6323 @param b The destination for the reduction digit
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6324 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6325 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6326 int (*montgomery_setup)(void *a, void **b);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6327
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6328 /** get normalization value
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6329 @param a The destination for the normalization value
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6330 @param b The modulus
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6331 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6332 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6333 int (*montgomery_normalization)(void *a, void *b);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6334
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6335 /** reduce a number
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6336 @param a The number [and dest] to reduce
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6337 @param b The modulus
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6338 @param c The value "b" from montgomery_setup()
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6339 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6340 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6341 int (*montgomery_reduce)(void *a, void *b, void *c);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6342
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6343 /** clean up (frees memory)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6344 @param a The value "b" from montgomery_setup()
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6345 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6346 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6347 void (*montgomery_deinit)(void *a);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6348
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6349 /* ---- exponentiation ---- */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6350
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6351 /** Modular exponentiation
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6352 @param a The base integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6353 @param b The power (can be negative) integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6354 @param c The modulus integer
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6355 @param d The destination
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6356 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6357 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6358 int (*exptmod)(void *a, void *b, void *c, void *d);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6359
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6360 /** Primality testing
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6361 @param a The integer to test
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6362 @param b The destination of the result (FP_YES if prime)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6363 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6364 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6365 int (*isprime)(void *a, int *b);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6366
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6367 /* ---- (optional) ecc point math ---- */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6368
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6369 /** ECC GF(p) point multiplication (from the NIST curves)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6370 @param k The integer to multiply the point by
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6371 @param G The point to multiply
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6372 @param R The destination for kG
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6373 @param modulus The modulus for the field
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6374 @param map Boolean indicated whether to map back to affine or not
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6375 (can be ignored if you work in affine only)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6376 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6377 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6378 int (*ecc_ptmul)( void *k,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6379 ecc_point *G,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6380 ecc_point *R,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6381 void *modulus,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6382 int map);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6383
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6384 /** ECC GF(p) point addition
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6385 @param P The first point
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6386 @param Q The second point
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6387 @param R The destination of P + Q
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6388 @param modulus The modulus
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6389 @param mp The "b" value from montgomery_setup()
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6390 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6391 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6392 int (*ecc_ptadd)(ecc_point *P,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6393 ecc_point *Q,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6394 ecc_point *R,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6395 void *modulus,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6396 void *mp);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6397
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6398 /** ECC GF(p) point double
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6399 @param P The first point
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6400 @param R The destination of 2P
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6401 @param modulus The modulus
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6402 @param mp The "b" value from montgomery_setup()
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6403 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6404 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6405 int (*ecc_ptdbl)(ecc_point *P,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6406 ecc_point *R,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6407 void *modulus,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6408 void *mp);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6409
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6410 /** ECC mapping from projective to affine,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6411 currently uses (x,y,z) => (x/z^2, y/z^3, 1)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6412 @param P The point to map
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6413 @param modulus The modulus
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6414 @param mp The "b" value from montgomery_setup()
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6415 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6416 @remark The mapping can be different but keep in mind a
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6417 ecc_point only has three integers (x,y,z) so if
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6418 you use a different mapping you have to make it fit.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6419 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6420 int (*ecc_map)(ecc_point *P, void *modulus, void *mp);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6421
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6422 /** Computes kA*A + kB*B = C using Shamir's Trick
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6423 @param A First point to multiply
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6424 @param kA What to multiple A by
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6425 @param B Second point to multiply
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6426 @param kB What to multiple B by
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6427 @param C [out] Destination point (can overlap with A or B)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6428 @param modulus Modulus for curve
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6429 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6430 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6431 int (*ecc_mul2add)(ecc_point *A, void *kA,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6432 ecc_point *B, void *kB,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6433 ecc_point *C,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6434 void *modulus);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6435
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6436
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6437 /* ---- (optional) rsa optimized math (for internal CRT) ---- */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6438
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6439 /** RSA Key Generation
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6440 @param prng An active PRNG state
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6441 @param wprng The index of the PRNG desired
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6442 @param size The size of the key in octets
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6443 @param e The "e" value (public key).
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6444 e==65537 is a good choice
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6445 @param key [out] Destination of a newly created private key pair
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6446 @return CRYPT_OK if successful, upon error all allocated ram is freed
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6447 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6448 int (*rsa_keygen)(prng_state *prng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6449 int wprng,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6450 int size,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6451 long e,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6452 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6453
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6454 /** RSA exponentiation
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6455 @param in The octet array representing the base
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6456 @param inlen The length of the input
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6457 @param out The destination (to be stored in an octet array format)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6458 @param outlen The length of the output buffer and the resulting size
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6459 (zero padded to the size of the modulus)
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6460 @param which PK_PUBLIC for public RSA and PK_PRIVATE for private RSA
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6461 @param key The RSA key to use
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6462 @return CRYPT_OK on success
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6463 */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6464 int (*rsa_me)(const unsigned char *in, unsigned long inlen,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6465 unsigned char *out, unsigned long *outlen, int which,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6466 rsa_key *key);
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6467 } ltc_math_descriptor;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6468 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6469 \end{small}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6470
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6471 Most of the functions are fairly straightforward and do not need documentation. We'll cover the basic conventions of the API and then explain the accelerated functions.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6472
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6473 \subsection{Conventions}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6474
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6475 All \textit{bignums} are accessed through an opaque \textit{void *} data type. You must internally cast the pointer if you need to access members of your bignum structure. During
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6476 the init calls a \textit{void **} will be passed where you allocate your structure and set the pointer then initialize the number to zero. During the deinit calls you must
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6477 free the bignum as well as the structure you allocated to place it in.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6478
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6479 All functions except the Montgomery reductions work from left to right with the arguments. For example, mul(a, b, c) computes $c \leftarrow ab$.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6480
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6481 All functions (except where noted otherwise) return \textbf{CRYPT\_OK} to signify a successful operation. All error codes must be valid LibTomCrypt error codes.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6482
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6483 The digit routines (including functions with the \textit{i} suffix) use a \textit{unsigned long} to represent the digit. If your internal digit is larger than this you must
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6484 then partition your digits. Normally this does not matter as \textit{unsigned long} will be the same size as your register size. Note that if your digit is smaller
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6485 than an \textit{unsigned long} that is also acceptable as the \textit{bits\_per\_digit} parameter will specify this.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6486
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6487 \subsection{ECC Functions}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6488 The ECC system in LibTomCrypt is based off of the NIST recommended curves over $GF(p)$ and is used to implement EC-DSA and EC-DH. The ECC functions work with
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6489 the \textbf{ecc\_point} structure and assume the points are stored in Jacobian projective format.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6490
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6491 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6492 /** A point on a ECC curve, stored in Jacobian format such
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6493 that (x,y,z) => (x/z^2, y/z^3, 1) when interpreted as affine */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6494 typedef struct {
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6495 /** The x co-ordinate */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6496 void *x;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6497 /** The y co-ordinate */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6498 void *y;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6499 /** The z co-ordinate */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6500 void *z;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6501 } ecc_point;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6502 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6503
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6504 All ECC functions must use this mapping system. The only exception is when you remap all ECC callbacks which will allow you to have more control
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6505 over how the ECC math will be implemented. Out of the box you only have three parameters per point to use $(x, y, z)$ however, these are just void pointers. They
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6506 could point to anything you want. The only further exception is the export functions which expects the values to be in affine format.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6507
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6508 \subsubsection{Point Multiply}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6509 This will multiply the point $G$ by the scalar $k$ and store the result in the point $R$. The value should be mapped to affine only if $map$ is set to one.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6510
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6511 \subsubsection{Point Addition}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6512 This will add the point $P$ to the point $Q$ and store it in the point $R$. The $mp$ parameter is the \textit{b} value from the montgomery\_setup() call. The input points
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6513 may be in either affine (with $z = 1$) or projective format and the output point is always projective.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6514
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6515 \subsubsection{Point Mapping}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6516 This will map the point $P$ back from projective to affine. The output point $P$ must be of the form $(x, y, 1)$.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6517
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6518 \subsubsection{Shamir's Trick}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6519 \index{Shamir's Trick}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6520 \index{ltc\_ecc\_mul2add()}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6521 To accelerate EC--DSA verification the library provides a built--in function called ltc\_ecc\_mul2add(). This performs two point multiplications and an addition in
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6522 roughly the time of one point multiplication. It is called from ecc\_verify\_hash() if an accelerator is not present. The acclerator function must allow the points to
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6523 overlap (e.g., $A \leftarrow k_1A + k_2B$) and must return the final point in affine format.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6524
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6525
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6526 \subsection{RSA Functions}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6527 The RSA Modular Exponentiation (ME) function is used by the RSA API to perform exponentiations for private and public key operations. In particular for
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6528 private key operations it uses the CRT approach to lower the time required. It is passed an RSA key with the following format.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6529
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6530 \begin{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6531 /** RSA PKCS style key */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6532 typedef struct Rsa_key {
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6533 /** Type of key, PK_PRIVATE or PK_PUBLIC */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6534 int type;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6535 /** The public exponent */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6536 void *e;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6537 /** The private exponent */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6538 void *d;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6539 /** The modulus */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6540 void *N;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6541 /** The p factor of N */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6542 void *p;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6543 /** The q factor of N */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6544 void *q;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6545 /** The 1/q mod p CRT param */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6546 void *qP;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6547 /** The d mod (p - 1) CRT param */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6548 void *dP;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6549 /** The d mod (q - 1) CRT param */
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6550 void *dQ;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6551 } rsa_key;
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6552 \end{verbatim}
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6553
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6554 The call reads the \textit{in} buffer as an unsigned char array in big endian format. Then it performs the exponentiation and stores the output in big endian format
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6555 to the \textit{out} buffer. The output must be zero padded (leading bytes) so that the length of the output matches the length of the modulus (in bytes). For example,
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6556 for RSA--1024 the output is always 128 bytes regardless of how small the numerical value of the exponentiation is.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6557
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6558 Since the function is given the entire RSA key (for private keys only) CRT is possible as prescribed in the PKCS \#1 v2.1 specification.
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6559
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6560 \newpage
0cbe8f6dbf9e propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 2af22fb4e878750b88f80f90d439b316d229796f)
Matt Johnston <matt@ucc.asn.au>
parents: 285
diff changeset
6561 \markboth{Index}{Index}
285
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6562 \input{crypt.ind}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6563
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6564 \end{document}
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6565
1b9e69c058d2 propagate from branch 'au.asn.ucc.matt.ltc.dropbear' (head 20dccfc09627970a312d77fb41dc2970b62689c3)
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6566 % $Source: /cvs/libtom/libtomcrypt/crypt.tex,v $
1435
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
6567 % $Revision: 1.128 $
f849a5ca2efc update to libtomcrypt 1.17 (with Dropbear changes)
Matt Johnston <matt@ucc.asn.au>
parents: 382
diff changeset
6568 % $Date: 2007/03/10 23:59:54 $