1f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\documentclass[synpaper]{book} 2f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\usepackage[dvips]{geometry} 3f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\usepackage{hyperref} 4f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\usepackage{makeidx} 5f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\usepackage{amssymb} 6f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\usepackage{color} 7f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\usepackage{alltt} 8f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\usepackage{graphicx} 9f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\usepackage{layout} 10f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\usepackage{fancyhdr} 11f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\union{\cup} 12f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\intersect{\cap} 13f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\getsrandom{\stackrel{\rm R}{\gets}} 14f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\cross{\times} 15f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\cat{\hspace{0.5em} \| \hspace{0.5em}} 16f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\catn{$\|$} 17f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\divides{\hspace{0.3em} | \hspace{0.3em}} 18f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\nequiv{\not\equiv} 19f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\approx{\raisebox{0.2ex}{\mbox{\small $\sim$}}} 20f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\lcm{{\rm lcm}} 21f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\gcd{{\rm gcd}} 22f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\log{{\rm log}} 23f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\ord{{\rm ord}} 24f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\abs{{\mathit abs}} 25f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\rep{{\mathit rep}} 26f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\mod{{\mathit\ mod\ }} 27f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\renewcommand{\pmod}[1]{\ ({\rm mod\ }{#1})} 28f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\newcommand{\floor}[1]{\left\lfloor{#1}\right\rfloor} 29f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\newcommand{\ceil}[1]{\left\lceil{#1}\right\rceil} 30f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\Or{{\rm\ or\ }} 31f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\And{{\rm\ and\ }} 32f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\iff{\hspace{1em}\Longleftrightarrow\hspace{1em}} 33f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\implies{\Rightarrow} 34f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\undefined{{\rm \textit{undefined}}} 35f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\Proof{\vspace{1ex}\noindent {\bf Proof:}\hspace{1em}} 36f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\let\oldphi\phi 37f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\phi{\varphi} 38f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\Pr{{\rm Pr}} 39f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\newcommand{\str}[1]{{\mathbf{#1}}} 40f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\F{{\mathbb F}} 41f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\N{{\mathbb N}} 42f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\Z{{\mathbb Z}} 43f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\R{{\mathbb R}} 44f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\C{{\mathbb C}} 45f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\Q{{\mathbb Q}} 46f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\definecolor{DGray}{gray}{0.5} 47f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\newcommand{\emailaddr}[1]{\mbox{$<${#1}$>$}} 48f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\twiddle{\raisebox{0.3ex}{\mbox{\tiny $\sim$}}} 49f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\def\gap{\vspace{0.5ex}} 50f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\makeindex 51f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\newcommand{\mysection}[1] % Re-define the chaptering command to use 52f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project { % THESE headers. 53f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \section{#1} 54f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \markboth{\textsf{www.libtom.org}}{\thesection ~ {#1}} 55f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 56f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 57f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\newcommand{\mystarsection}[1] % Re-define the chaptering command to use 58f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project { % THESE headers. 59f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \section*{#1} 60f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \markboth{\textsf{www.libtom.org}}{{#1}} 61f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 62f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\pagestyle{empty} 63f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{document} 64f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\frontmatter 65f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\pagestyle{empty} 66f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 67f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project~ 68f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 69f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\vspace{2in} 70f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 71f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project~ 72f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 73f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{center} 74f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{Huge}LibTomCrypt\end{Huge} 75f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 76f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project~ 77f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 78f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{large}Developer Manual\end{large} 79f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 80f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project~ 81f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 82f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\vspace{15mm} 83f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 84f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 85f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{tabular}{c} 86f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTom St Denis \\ 87f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLibTom Projects 88f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{tabular} 89f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{center} 90f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\vfil 91f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\newpage 92f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis document is part of the LibTomCrypt package and is hereby released into the public domain. 93f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 94f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project~ 95f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 96f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectOpen Source. Open Academia. Open Minds. 97f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 98f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project~ 99f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 100f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{flushright} 101f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTom St Denis 102f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project~ 103f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 104f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectOttawa, Ontario 105f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project~ 106f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 107f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCanada 108f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project~ 109f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\vfil 110f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{flushright} 111f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\newpage 112f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 113f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\tableofcontents 114f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\listoffigures 115f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\pagestyle{myheadings} 116f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mainmatter 117f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{Introduction} 118f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{What is the LibTomCrypt?} 119f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLibTomCrypt is a portable ISO C cryptographic library meant to be a tool set for cryptographers who are 120f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdesigning cryptosystems. It supports symmetric ciphers, one-way hashes, pseudo-random number generators, 121f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpublic key cryptography (via PKCS \#1 RSA, DH or ECCDH), and a plethora of support routines. 122f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 123f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe library was designed such that new ciphers/hashes/PRNGs can be added at run-time and the existing API 124f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project(and helper API functions) are able to use the new designs automatically. There exists self-check functions for each 125f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectblock cipher and hash function to ensure that they compile and execute to the published design specifications. The library 126f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectalso performs extensive parameter error checking to prevent any number of run-time exploits or errors. 127f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 128f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{What the library IS for?} 129f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 130f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe library serves as a toolkit for developers who have to solve cryptographic problems. Out of the box LibTomCrypt 131f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdoes not process SSL or OpenPGP messages, it doesn't read X.509 certificates, or write PEM encoded data. It does, however, 132f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectprovide all of the tools required to build such functionality. LibTomCrypt was designed to be a flexible library that 133f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwas not tied to any particular cryptographic problem. 134f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 135f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Why did I write it?} 136f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectYou may be wondering, \textit{Tom, why did you write a crypto library. I already have one.} Well the reason falls into 137f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttwo categories: 138f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{enumerate} 139f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item I am too lazy to figure out someone else's API. I'd rather invent my own simpler API and use that. 140f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item It was (still is) good coding practice. 141f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{enumerate} 142f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 143f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe idea is that I am not striving to replace OpenSSL or Crypto++ or Cryptlib or etc. I'm trying to write my 144f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{\bf own} crypto library and hopefully along the way others will appreciate the work. 145f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 146f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWith this library all core functions (ciphers, hashes, prngs, and bignum) have the same prototype definition. They all load 147f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand store data in a format independent of the platform. This means if you encrypt with Blowfish on a PPC it should decrypt 148f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecton an x86 with zero problems. The consistent API also means that if you learn how to use Blowfish with the library you 149f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectknow how to use Safer+, RC6, or Serpent as well. With all of the core functions there are central descriptor tables 150f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthat can be used to make a program automatically pick between ciphers, hashes and PRNGs at run-time. That means your 151f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectapplication can support all ciphers/hashes/prngs/bignum without changing the source code. 152f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 153f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNot only did I strive to make a consistent and simple API to work with but I also attempted to make the library 154f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectconfigurable in terms of its build options. Out of the box the library will build with any modern version of GCC 155f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwithout having to use configure scripts. This means that the library will work with platforms where development 156f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttools may be limited (e.g. no autoconf). 157f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 158f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectOn top of making the build simple and the API approachable I've also attempted for a reasonably high level of 159f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrobustness and efficiency. LibTomCrypt traps and returns a series of errors ranging from invalid 160f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectarguments to buffer overflows/overruns. It is mostly thread safe and has been clocked on various platforms 161f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwith \textit{cycles per byte} timings that are comparable (and often favourable) to other libraries such as OpenSSL and 162f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCrypto++. 163f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 164f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Modular} 165f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe LibTomCrypt package has also been written to be very modular. The block ciphers, one--way hashes, 166f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpseudo--random number generators (PRNG), and bignum math routines are all used within the API through \textit{descriptor} tables which 167f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectare essentially structures with pointers to functions. While you can still call particular functions 168f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdirectly (\textit{e.g. sha256\_process()}) this descriptor interface allows the developer to customize their 169f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectusage of the library. 170f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 171f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectFor example, consider a hardware platform with a specialized RNG device. Obviously one would like to tap 172f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthat for the PRNG needs within the library (\textit{e.g. making a RSA key}). All the developer has to do 173f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectis write a descriptor and the few support routines required for the device. After that the rest of the 174f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAPI can make use of it without change. Similarly imagine a few years down the road when AES2 175f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project(\textit{or whatever they call it}) has been invented. It can be added to the library and used within applications 176f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwith zero modifications to the end applications provided they are written properly. 177f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 178f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis flexibility within the library means it can be used with any combination of primitive algorithms and 179f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectunlike libraries like OpenSSL is not tied to direct routines. For instance, in OpenSSL there are CBC block 180f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmode routines for every single cipher. That means every time you add or remove a cipher from the library 181f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectyou have to update the associated support code as well. In LibTomCrypt the associated code (\textit{chaining modes in this case}) 182f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectare not directly tied to the ciphers. That is a new cipher can be added to the library by simply providing 183f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe key setup, ECB decrypt and encrypt and test vector routines. After that all five chaining mode routines 184f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcan make use of the cipher right away. 185f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 186f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{License} 187f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 188f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe project is hereby released as public domain. 189f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 190f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Patent Disclosure} 191f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 192f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe author (Tom St Denis) is not a patent lawyer so this section is not to be treated as legal advice. To the best 193f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof the authors knowledge the only patent related issues within the library are the RC5 and RC6 symmetric block ciphers. 194f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThey can be removed from a build by simply commenting out the two appropriate lines in \textit{tomcrypt\_custom.h}. The rest 195f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof the ciphers and hashes are patent free or under patents that have since expired. 196f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 197f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe RC2 and RC4 symmetric ciphers are not under patents but are under trademark regulations. This means you can use 198f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe ciphers you just can't advertise that you are doing so. 199f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 200f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Thanks} 201f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectI would like to give thanks to the following people (in no particular order) for helping me develop this project from 202f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectearly on: 203f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{enumerate} 204f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Richard van de Laarschot 205f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Richard Heathfield 206f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Ajay K. Agrawal 207f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Brian Gladman 208f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Svante Seleborg 209f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Clay Culver 210f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Jason Klapste 211f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Dobes Vandermeer 212f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Daniel Richards 213f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Wayne Scott 214f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Andrew Tyler 215f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Sky Schulz 216f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Christopher Imes 217f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{enumerate} 218f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 219f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere have been quite a few other people as well. Please check the change log to see who else has contributed from 220f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttime to time. 221f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 222f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{The Application Programming Interface (API)} 223f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Introduction} 224f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{CRYPT\_ERROR} \index{CRYPT\_OK} 225f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 226f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn general the API is very simple to memorize and use. Most of the functions return either {\bf void} or {\bf int}. Functions 227f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthat return {\bf int} will return {\bf CRYPT\_OK} if the function was successful, or one of the many error codes 228f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectif it failed. Certain functions that return int will return $-1$ to indicate an error. These functions will be explicitly 229f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcommented upon. When a function does return a CRYPT error code it can be translated into a string with 230f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 231f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{error\_to\_string()} 232f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 233f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectconst char *error_to_string(int err); 234f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 235f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 236f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAn example of handling an error is: 237f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 238f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 239f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectvoid somefunc(void) 240f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 241f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 242f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 243f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* call a cryptographic function */ 244f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = some_crypto_function(...)) != CRYPT_OK) { 245f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("A crypto error occurred, %s\n", error_to_string(err)); 246f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* perform error handling */ 247f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 248f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* continue on if no error occurred */ 249f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 250f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 251f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 252f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 253f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere is no initialization routine for the library and for the most part the code is thread safe. The only thread 254f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrelated issue is if you use the same symmetric cipher, hash or public key state data in multiple threads. Normally 255f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthat is not an issue. 256f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 257f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo include the prototypes for \textit{LibTomCrypt.a} into your own program simply include \textit{tomcrypt.h} like so: 258f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 259f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 260f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 261f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) { 262f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 263f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 264f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 265f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 266f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 267f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe header file \textit{tomcrypt.h} also includes \textit{stdio.h}, \textit{string.h}, \textit{stdlib.h}, \textit{time.h} and \textit{ctype.h}. 268f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 269f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Macros} 270f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 271f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere are a few helper macros to make the coding process a bit easier. The first set are related to loading and storing 272f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project32/64-bit words in little/big endian format. The macros are: 273f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 274f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{STORE32L} \index{STORE64L} \index{LOAD32L} \index{LOAD64L} \index{STORE32H} \index{STORE64H} \index{LOAD32H} \index{LOAD64H} \index{BSWAP} 275f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\newpage 276f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{figure}[hpbt] 277f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 278f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{center} 279f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{tabular}{|c|c|c|} 280f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline STORE32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 3]$ \\ 281f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline STORE64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 7]$ \\ 282f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline LOAD32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[0 \ldots 3] \to x$ \\ 283f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline LOAD64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[0 \ldots 7] \to x$ \\ 284f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline STORE32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[3 \ldots 0]$ \\ 285f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline STORE64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[7 \ldots 0]$ \\ 286f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline LOAD32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[3 \ldots 0] \to x$ \\ 287f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline LOAD64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[7 \ldots 0] \to x$ \\ 288f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline BSWAP(x) & {\bf unsigned long} x & Swap bytes \\ 289f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 290f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{tabular} 291f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\caption{Load And Store Macros} 292f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{center} 293f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 294f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{figure} 295f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 296f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere are 32 and 64-bit cyclic rotations as well: 297f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ROL} \index{ROR} \index{ROL64} \index{ROR64} \index{ROLc} \index{RORc} \index{ROL64c} \index{ROR64c} 298f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{figure}[hpbt] 299f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 300f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{center} 301f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{tabular}{|c|c|c|} 302f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline ROL(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x << y, 0 \le y \le 31$ \\ 303f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline ROLc(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x << y, 0 \le y \le 31$ \\ 304f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline ROR(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x >> y, 0 \le y \le 31$ \\ 305f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline RORc(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x >> y, 0 \le y \le 31$ \\ 306f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline && \\ 307f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline ROL64(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x << y, 0 \le y \le 63$ \\ 308f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline ROL64c(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x << y, 0 \le y \le 63$ \\ 309f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline ROR64(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x >> y, 0 \le y \le 63$ \\ 310f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline ROR64c(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x >> y, 0 \le y \le 63$ \\ 311f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 312f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{tabular} 313f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\caption{Rotate Macros} 314f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{center} 315f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 316f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{figure} 317f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 318f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Functions with Variable Length Output} 319f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCertain functions such as (for example) \textit{rsa\_export()} give an output that is variable length. To prevent buffer overflows you 320f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmust pass it the length of the buffer where the output will be stored. For example: 321f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_export()} \index{error\_to\_string()} \index{variable length output} 322f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 323f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 324f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 325f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) { 326f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key key; 327f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char buffer[1024]; 328f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long x; 329f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 330f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 331f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* ... Make up the RSA key somehow ... */ 332f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 333f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* lets export the key, set x to the size of the 334f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project * output buffer */ 335f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project x = sizeof(buffer); 336f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = rsa_export(buffer, &x, PK_PUBLIC, &key)) != CRYPT_OK) { 337f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Export error: %s\n", error_to_string(err)); 338f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 339f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 340f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 341f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* if rsa_export() was successful then x will have 342f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project * the size of the output */ 343f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("RSA exported key takes %d bytes\n", x); 344f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 345f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* ... do something with the buffer */ 346f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 347f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 348f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 349f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 350f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 351f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn the above example if the size of the RSA public key was more than 1024 bytes this function would return an error code 352f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectindicating a buffer overflow would have occurred. If the function succeeds, it stores the length of the output back into 353f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{x} so that the calling application will know how many bytes were used. 354f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 355f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs of v1.13, most functions will update your length on failure to indicate the size required by the function. Not all functions 356f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsupport this so please check the source before you rely on it doing that. 357f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 358f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Functions that need a PRNG} 359f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Pseudo Random Number Generator} \index{PRNG} 360f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCertain functions such as \textit{rsa\_make\_key()} require a Pseudo Random Number Generator (PRNG). These functions do not setup 361f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe PRNG themselves so it is the responsibility of the calling function to initialize the PRNG before calling them. 362f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 363f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCertain PRNG algorithms do not require a \textit{prng\_state} argument (sprng for example). The \textit{prng\_state} argument 364f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmay be passed as \textbf{NULL} in such situations. 365f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 366f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{register\_prng()} \index{rsa\_make\_key()} 367f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 368f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 369f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 370f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) { 371f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key key; 372f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 373f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 374f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register the system RNG */ 375f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project register_prng(&sprng_desc) 376f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 377f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* make a 1024-bit RSA key with the system RNG */ 378f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = rsa_make_key(NULL, find_prng("sprng"), 1024/8, 65537, &key)) 379f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project != CRYPT_OK) { 380f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("make_key error: %s\n", error_to_string(err)); 381f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 382f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 383f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 384f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* use the key ... */ 385f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 386f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 387f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 388f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 389f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 390f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 391f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Functions that use Arrays of Octets} 392f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectMost functions require inputs that are arrays of the data type \textit{unsigned char}. Whether it is a symmetric key, IV 393f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfor a chaining mode or public key packet it is assumed that regardless of the actual size of \textit{unsigned char} only the 394f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectlower eight bits contain data. For example, if you want to pass a 256 bit key to a symmetric ciphers setup routine, you 395f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmust pass in (a pointer to) an array of 32 \textit{unsigned char} variables. Certain routines (such as SAFER+) take 396f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectspecial care to work properly on platforms where an \textit{unsigned char} is not eight bits. 397f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 398f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectFor the purposes of this library, the term \textit{byte} will refer to an octet or eight bit word. Typically an array of 399f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttype \textit{byte} will be synonymous with an array of type \textit{unsigned char.} 400f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 401f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{Symmetric Block Ciphers} 402f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Core Functions} 403f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLibTomCrypt provides several block ciphers with an ECB block mode interface. It is important to first note that you 404f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectshould never use the ECB modes directly to encrypt data. Instead you should use the ECB functions to make a chaining mode, 405f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projector use one of the provided chaining modes. All of the ciphers are written as ECB interfaces since it allows the rest of 406f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe API to grow in a modular fashion. 407f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 408f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Key Scheduling} 409f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAll ciphers store their scheduled keys in a single data type called \textit{symmetric\_key}. This allows all ciphers to 410f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecthave the same prototype and store their keys as naturally as possible. This also removes the need for dynamic memory 411f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectallocation, and allows you to allocate a fixed sized buffer for storing scheduled keys. All ciphers must provide six visible 412f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfunctions which are (given that XXX is the name of the cipher) the following: 413f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Cipher Setup} 414f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 415f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_setup(const unsigned char *key, 416f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int keylen, 417f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int rounds, 418f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *skey); 419f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 420f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 421f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe XXX\_setup() routine will setup the cipher to be used with a given number of rounds and a given key length (in bytes). 422f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe number of rounds can be set to zero to use the default, which is generally a good idea. 423f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 424f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIf the function returns successfully the variable \textit{skey} will have a scheduled key stored in it. It's important to note 425f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthat you should only used this scheduled key with the intended cipher. For example, if you call \textit{blowfish\_setup()} do not 426f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpass the scheduled key onto \textit{rc5\_ecb\_encrypt()}. All built--in setup functions do not allocate memory off the heap so 427f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwhen you are done with a key you can simply discard it (e.g. they can be on the stack). However, to maintain proper coding 428f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpractices you should always call the respective XXX\_done() function. This allows for quicker porting to applications with 429f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectexternally supplied plugins. 430f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 431f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ECB Encryption and Decryption} 432f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo encrypt or decrypt a block in ECB mode there are these two functions per cipher: 433f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Cipher Encrypt} \index{Cipher Decrypt} 434f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 435f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_ecb_encrypt(const unsigned char *pt, 436f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 437f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *skey); 438f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 439f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_ecb_decrypt(const unsigned char *ct, 440f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, 441f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *skey); 442f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 443f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese two functions will encrypt or decrypt (respectively) a single block of text\footnote{The size of which depends on 444f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwhich 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 445f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe same buffer. For the encrypt function \textit{pt}\footnote{pt stands for plaintext.} is the input and 446f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{ct}\footnote{ct stands for ciphertext.} is the output. For the decryption function it's the opposite. They both 447f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectreturn \textbf{CRYPT\_OK} on success. To test a particular cipher against test vectors\footnote{As published in their design papers.} 448f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcall the following self-test function. 449f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 450f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Self--Testing} 451f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Cipher Testing} 452f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 453f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_test(void); 454f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 455f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function will return {\bf CRYPT\_OK} if the cipher matches the test vectors from the design publication it is 456f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbased upon. 457f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 458f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Key Sizing} 459f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectFor each cipher there is a function which will help find a desired key size. It is specified as follows: 460f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Key Sizing} 461f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 462f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_keysize(int *keysize); 463f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 464f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectEssentially, it will round the input keysize in \textit{keysize} down to the next appropriate key size. This function 465f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwill return {\bf CRYPT\_OK} if the key size specified is acceptable. For example: 466f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 467f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 468f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 469f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 470f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 471f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int keysize, err; 472f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 473f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* now given a 20 byte key what keysize does Twofish want to use? */ 474f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project keysize = 20; 475f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = twofish_keysize(&keysize)) != CRYPT_OK) { 476f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error getting key size: %s\n", error_to_string(err)); 477f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 478f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 479f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Twofish suggested a key size of %d\n", keysize); 480f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 481f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 482f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 483f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 484f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis should indicate a keysize of sixteen bytes is suggested by storing 16 in \textit{keysize.} 485f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 486f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Cipher Termination} 487f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen you are finished with a cipher you can de--initialize it with the done function. 488f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 489f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectvoid XXX_done(symmetric_key *skey); 490f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 491f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectFor the software based ciphers within LibTomCrypt, these functions will not do anything. However, user supplied 492f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcipher descriptors may require to be called for resource management purposes. To be compliant, all functions which call a cipher 493f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsetup function must also call the respective cipher done function when finished. 494f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 495f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Simple Encryption Demonstration} 496f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAn example snippet that encodes a block with Blowfish in ECB mode. 497f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 498f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{blowfish\_setup()} \index{blowfish\_ecb\_encrypt()} \index{blowfish\_ecb\_decrypt()} \index{blowfish\_done()} 499f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 500f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 501f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 502f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 503f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 504f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char pt[8], ct[8], key[8]; 505f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key skey; 506f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 507f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 508f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* ... key is loaded appropriately in key ... */ 509f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* ... load a block of plaintext in pt ... */ 510f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 511f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* schedule the key */ 512f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = blowfish_setup(key, /* the key we will use */ 513f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 8, /* key is 8 bytes (64-bits) long */ 514f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 0, /* 0 == use default # of rounds */ 515f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &skey) /* where to put the scheduled key */ 516f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ) != CRYPT_OK) { 517f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Setup error: %s\n", error_to_string(err)); 518f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 519f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 520f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 521f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* encrypt the block */ 522f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project blowfish_ecb_encrypt(pt, /* encrypt this 8-byte array */ 523f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ct, /* store encrypted data here */ 524f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &skey); /* our previously scheduled key */ 525f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 526f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* now ct holds the encrypted version of pt */ 527f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 528f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* decrypt the block */ 529f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project blowfish_ecb_decrypt(ct, /* decrypt this 8-byte array */ 530f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project pt, /* store decrypted data here */ 531f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &skey); /* our previously scheduled key */ 532f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 533f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* now we have decrypted ct to the original plaintext in pt */ 534f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 535f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* Terminate the cipher context */ 536f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project blowfish_done(&skey); 537f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 538f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 539f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 540f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 541f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 542f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 543f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Key Sizes and Number of Rounds} 544f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Symmetric Keys} 545f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs 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 546f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectkeys (mainly for test vectors anyways). Ideally, your application should be making at least 256 bit keys. This is not 547f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbecause you are to be paranoid. It is because if your PRNG has a bias of any sort the more bits the better. For 548f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectexample, if you have $\mbox{Pr}\left[X = 1\right] = {1 \over 2} \pm \gamma$ where $\vert \gamma \vert > 0$ then the 549f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttotal amount of entropy in N bits is $N \cdot -log_2\left ({1 \over 2} + \vert \gamma \vert \right)$. So if $\gamma$ 550f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwere $0.25$ (a severe bias) a 256-bit string would have about 106 bits of entropy whereas a 128-bit string would have 551f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectonly 53 bits of entropy. 552f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 553f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe number of rounds of most ciphers is not an option you can change. Only RC5 allows you to change the number of 554f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrounds. By passing zero as the number of rounds all ciphers will use their default number of rounds. Generally the 555f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectciphers are configured such that the default number of rounds provide adequate security for the given block and key 556f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsize. 557f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 558f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{The Cipher Descriptors} 559f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Cipher Descriptor} 560f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo facilitate automatic routines an array of cipher descriptors is provided in the array \textit{cipher\_descriptor}. An element 561f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof this array has the following (partial) format (See Section \ref{sec:cipherdesc}): 562f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 563f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 564f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 565f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstruct _cipher_descriptor { 566f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** name of cipher */ 567f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project char *name; 568f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 569f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** internal ID */ 570f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char ID; 571f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 572f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** min keysize (octets) */ 573f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int min_key_length, 574f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 575f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** max keysize (octets) */ 576f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project max_key_length, 577f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 578f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** block size (octets) */ 579f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project block_length, 580f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 581f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** default number of rounds */ 582f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project default_rounds; 583f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project...<snip>... 584f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project}; 585f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 586f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 587f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 588f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhere \textit{name} is the lower case ASCII version of the name. The fields \textit{min\_key\_length} and \textit{max\_key\_length} 589f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectare the minimum and maximum key sizes in bytes. The \textit{block\_length} member is the block size of the cipher 590f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectin bytes. As a good rule of thumb it is assumed that the cipher supports 591f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe min and max key lengths but not always everything in between. The \textit{default\_rounds} field is the default number 592f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof rounds that will be used. 593f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 594f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectFor a plugin to be compliant it must provide at least each function listed before the accelerators begin. Accelerators are optional, 595f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand if missing will be emulated in software. 596f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 597f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe remaining fields are all pointers to the core functions for each cipher. The end of the cipher\_descriptor array is 598f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmarked when \textit{name} equals {\bf NULL}. 599f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 600f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs of this release the current cipher\_descriptors elements are the following: 601f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\vfil 602f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Cipher descriptor table} 603f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{blowfish\_desc} \index{xtea\_desc} \index{rc2\_desc} \index{rc5\_desc} \index{rc6\_desc} \index{saferp\_desc} \index{aes\_desc} \index{twofish\_desc} 604f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{des\_desc} \index{des3\_desc} \index{noekeon\_desc} \index{skipjack\_desc} \index{anubis\_desc} \index{khazad\_desc} \index{kseed\_desc} \index{kasumi\_desc} 605f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{figure}[hpbt] 606f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 607f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{center} 608f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{tabular}{|c|c|c|c|c|c|} 609f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline \textbf{Name} & \textbf{Descriptor Name} & \textbf{Block Size} & \textbf{Key Range} & \textbf{Rounds} \\ 610f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline Blowfish & blowfish\_desc & 8 & 8 $\ldots$ 56 & 16 \\ 611f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline X-Tea & xtea\_desc & 8 & 16 & 32 \\ 612f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline RC2 & rc2\_desc & 8 & 8 $\ldots$ 128 & 16 \\ 613f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline RC5-32/12/b & rc5\_desc & 8 & 8 $\ldots$ 128 & 12 $\ldots$ 24 \\ 614f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline RC6-32/20/b & rc6\_desc & 16 & 8 $\ldots$ 128 & 20 \\ 615f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline SAFER+ & saferp\_desc &16 & 16, 24, 32 & 8, 12, 16 \\ 616f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline AES & aes\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\ 617f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project & aes\_enc\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\ 618f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline Twofish & twofish\_desc & 16 & 16, 24, 32 & 16 \\ 619f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline DES & des\_desc & 8 & 7 & 16 \\ 620f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 3DES (EDE mode) & des3\_desc & 8 & 21 & 16 \\ 621f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline CAST5 (CAST-128) & cast5\_desc & 8 & 5 $\ldots$ 16 & 12, 16 \\ 622f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline Noekeon & noekeon\_desc & 16 & 16 & 16 \\ 623f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline Skipjack & skipjack\_desc & 8 & 10 & 32 \\ 624f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline Anubis & anubis\_desc & 16 & 16 $\ldots$ 40 & 12 $\ldots$ 18 \\ 625f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline Khazad & khazad\_desc & 8 & 16 & 8 \\ 626f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline SEED & kseed\_desc & 16 & 16 & 16 \\ 627f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline KASUMI & kasumi\_desc & 8 & 16 & 8 \\ 628f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 629f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{tabular} 630f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{center} 631f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 632f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\caption{Built--In Software Ciphers} 633f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{figure} 634f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 635f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Notes} 636f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 637f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{enumerate} 638f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\item 639f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectFor AES, (also known as Rijndael) there are four descriptors which complicate issues a little. The descriptors 640f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrijndael\_desc and rijndael\_enc\_desc provide the cipher named \textit{rijndael}. The descriptors aes\_desc and 641f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectaes\_enc\_desc provide the cipher name \textit{aes}. Functionally both \textit{rijndael} and \textit{aes} are the same cipher. The 642f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectonly difference is when you call find\_cipher() you have to pass the correct name. The cipher descriptors with \textit{enc} 643f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectin the middle (e.g. rijndael\_enc\_desc) are related to an implementation of Rijndael with only the encryption routine 644f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand tables. The decryption and self--test function pointers of both \textit{encrypt only} descriptors are set to \textbf{NULL} and 645f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectshould not be called. 646f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 647f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \textit{encrypt only} descriptors are useful for applications that only use the encryption function of the cipher. Algorithms such 648f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectas EAX, PMAC and OMAC only require the encryption function. So far this \textit{encrypt only} functionality has only been implemented for 649f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectRijndael as it makes the most sense for this cipher. 650f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 651f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\item 652f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote 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 653f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfact 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 654f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbyte string from the real 7/21 byte key. 655f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 656f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\item 657f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote that \textit{Twofish} has additional configuration options (Figure \ref{fig:twofishopts}) that take place at build time. These options are found in 658f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe file \textit{tomcrypt\_cfg.h}. The first option is \textit{TWOFISH\_SMALL} which when defined will force the Twofish code 659f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto not pre-compute the Twofish \textit{$g(X)$} function as a set of four $8 \times 32$ s-boxes. This means that a scheduled 660f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectkey will require less ram but the resulting cipher will be slower. The second option is \textit{TWOFISH\_TABLES} which when 661f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdefined will force the Twofish code to use pre-computed tables for the two s-boxes $q_0, q_1$ as well as the multiplication 662f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectby the polynomials 5B and EF used in the MDS multiplication. As a result the code is faster and slightly larger. The 663f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectspeed increase is useful when \textit{TWOFISH\_SMALL} is defined since the s-boxes and MDS multiply form the heart of the 664f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTwofish round function. 665f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 666f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{figure}[hpbt] 667f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Twofish build options} \index{TWOFISH\_SMALL} \index{TWOFISH\_TABLES} 668f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 669f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{center} 670f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{tabular}{|l|l|l|} 671f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline \textbf{TWOFISH\_SMALL} & \textbf{TWOFISH\_TABLES} & \textbf{Speed and Memory (per key)} \\ 672f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline undefined & undefined & Very fast, 4.2KB of ram. \\ 673f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline undefined & defined & Faster key setup, larger code. \\ 674f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline defined & undefined & Very slow, 0.2KB of ram. \\ 675f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline defined & defined & Faster, 0.2KB of ram, larger code. \\ 676f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline 677f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{tabular} 678f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{center} 679f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 680f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\caption{Twofish Build Options} 681f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\label{fig:twofishopts} 682f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{figure} 683f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{enumerate} 684f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 685f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 686f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo work with the cipher\_descriptor array there is a function: 687f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{find\_cipher()} 688f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 689f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint find_cipher(char *name) 690f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 691f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich will search for a given name in the array. It returns $-1$ if the cipher is not found, otherwise it returns 692f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe location in the array where the cipher was found. For example, to indirectly setup Blowfish you can also use: 693f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 694f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{register\_cipher()} \index{find\_cipher()} \index{error\_to\_string()} 695f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 696f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 697f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 698f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 699f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char key[8]; 700f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key skey; 701f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 702f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 703f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* you must register a cipher before you use it */ 704f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_cipher(&blowfish_desc)) == -1) { 705f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Unable to register Blowfish cipher."); 706f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 707f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 708f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 709f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* generic call to function (assuming the key 710f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project * in key[] was already setup) */ 711f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = 712f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project cipher_descriptor[find_cipher("blowfish")]. 713f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project setup(key, 8, 0, &skey)) != CRYPT_OK) { 714f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error setting up Blowfish: %s\n", error_to_string(err)); 715f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 716f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 717f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 718f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* ... use cipher ... */ 719f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 720f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 721f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 722f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 723f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectA good safety would be to check the return value of \textit{find\_cipher()} before accessing the desired function. In order 724f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto use a cipher with the descriptor table you must register it first using: 725f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{register\_cipher()} 726f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 727f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint register_cipher(const struct _cipher_descriptor *cipher); 728f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 729f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich accepts a pointer to a descriptor and returns the index into the global descriptor table. If an error occurs such 730f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectas 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 731f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthan once it will just return the index of the first copy. To remove a cipher call: 732f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{unregister\_cipher()} 733f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 734f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint unregister_cipher(const struct _cipher_descriptor *cipher); 735f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 736f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich returns {\bf CRYPT\_OK} if it removes the cipher, otherwise it returns {\bf CRYPT\_ERROR}. 737f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 738f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 739f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 740f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 741f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 742f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 743f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 744f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register the cipher */ 745f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_cipher(&rijndael_desc) == -1) { 746f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error registering Rijndael\n"); 747f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 748f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 749f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 750f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* use Rijndael */ 751f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 752f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* remove it */ 753f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = unregister_cipher(&rijndael_desc)) != CRYPT_OK) { 754f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error removing Rijndael: %s\n", error_to_string(err)); 755f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 756f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 757f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 758f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 759f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 760f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 761f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 762f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis snippet is a small program that registers Rijndael. 763f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 764f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Symmetric Modes of Operations} 765f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Background} 766f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectA typical symmetric block cipher can be used in chaining modes to effectively encrypt messages larger than the block 767f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsize of the cipher. Given a key $k$, a plaintext $P$ and a cipher $E$ we shall denote the encryption of the block 768f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$P$ under the key $k$ as $E_k(P)$. In some modes there exists an initial vector denoted as $C_{-1}$. 769f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 770f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{ECB Mode} 771f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ECB mode} 772f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectECB or Electronic Codebook Mode is the simplest method to use. It is given as: 773f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{equation} 774f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectC_i = E_k(P_i) 775f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{equation} 776f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis mode is very weak since it allows people to swap blocks and perform replay attacks if the same key is used more 777f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthan once. 778f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 779f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{CBC Mode} 780f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{CBC mode} 781f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCBC or Cipher Block Chaining mode is a simple mode designed to prevent trivial forms of replay and swap attacks on ciphers. 782f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt is given as: 783f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{equation} 784f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectC_i = E_k(P_i \oplus C_{i - 1}) 785f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{equation} 786f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt is important that the initial vector be unique and preferably random for each message encrypted under the same key. 787f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 788f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{CTR Mode} 789f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{CTR mode} 790f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCTR or Counter Mode is a mode which only uses the encryption function of the cipher. Given a initial vector which is 791f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttreated as a large binary counter the CTR mode is given as: 792f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{eqnarray} 793f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectC_{-1} = C_{-1} + 1\mbox{ }(\mbox{mod }2^W) \nonumber \\ 794f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectC_i = P_i \oplus E_k(C_{-1}) 795f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{eqnarray} 796f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhere $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 797f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectencrypted under the same key replay and swap attacks are infeasible. CTR mode may look simple but it is as secure 798f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectas the block cipher is under a chosen plaintext attack (provided the initial vector is unique). 799f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 800f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{CFB Mode} 801f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{CFB mode} 802f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCFB or Ciphertext Feedback Mode is a mode akin to CBC. It is given as: 803f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{eqnarray} 804f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectC_i = P_i \oplus C_{-1} \nonumber \\ 805f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectC_{-1} = E_k(C_i) 806f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{eqnarray} 807f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote that in this library the output feedback width is equal to the size of the block cipher. That is this mode is used 808f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto encrypt whole blocks at a time. However, the library will buffer data allowing the user to encrypt or decrypt partial 809f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectblocks without a delay. When this mode is first setup it will initially encrypt the initial vector as required. 810f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 811f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{OFB Mode} 812f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{OFB mode} 813f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectOFB or Output Feedback Mode is a mode akin to CBC as well. It is given as: 814f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{eqnarray} 815f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectC_{-1} = E_k(C_{-1}) \nonumber \\ 816f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectC_i = P_i \oplus C_{-1} 817f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{eqnarray} 818f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLike the CFB mode the output width in CFB mode is the same as the width of the block cipher. OFB mode will also 819f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbuffer the output which will allow you to encrypt or decrypt partial blocks without delay. 820f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 821f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Choice of Mode} 822f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectMy personal preference is for the CTR mode since it has several key benefits: 823f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{enumerate} 824f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item No short cycles which is possible in the OFB and CFB modes. 825f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Provably as secure as the block cipher being used under a chosen plaintext attack. 826f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Technically does not require the decryption routine of the cipher. 827f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Allows random access to the plaintext. 828f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Allows the encryption of block sizes that are not equal to the size of the block cipher. 829f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{enumerate} 830f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe CTR, CFB and OFB routines provided allow you to encrypt block sizes that differ from the ciphers block size. They 831f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectaccomplish this by buffering the data required to complete a block. This allows you to encrypt or decrypt any size 832f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectblock of memory with either of the three modes. 833f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 834f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe ECB and CBC modes process blocks of the same size as the cipher at a time. Therefore, they are less flexible than the 835f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectother modes. 836f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 837f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Ciphertext Stealing} 838f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Ciphertext stealing} 839f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCiphertext stealing is a method of dealing with messages in CBC mode which are not a multiple of the block length. This is accomplished 840f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectby encrypting the last ciphertext block in ECB mode, and XOR'ing the output against the last partial block of plaintext. LibTomCrypt does not 841f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsupport this mode directly but it is fairly easy to emulate with a call to the cipher's ecb\_encrypt() callback function. 842f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 843f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe more sane way to deal with partial blocks is to pad them with zeroes, and then use CBC normally. 844f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 845f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Initialization} 846f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{CBC Mode} \index{CTR Mode} 847f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{OFB Mode} \index{CFB Mode} 848f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe library provides simple support routines for handling CBC, CTR, CFB, OFB and ECB encoded messages. Assuming the mode 849f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectyou want is XXX there is a structure called \textit{symmetric\_XXX} that will contain the information required to 850f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectuse that mode. They have identical setup routines (except CTR and ECB mode): 851f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecb\_start()} \index{cfb\_start()} \index{cbc\_start()} \index{ofb\_start()} \index{ctr\_start()} 852f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 853f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_start( int cipher, 854f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *IV, 855f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 856f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int keylen, 857f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int num_rounds, 858f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_XXX *XXX); 859f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 860f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ctr_start( int cipher, 861f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *IV, 862f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 863f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int keylen, 864f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int num_rounds, 865f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int ctr_mode, 866f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_CTR *ctr); 867f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 868f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecb_start( int cipher, 869f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 870f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int keylen, 871f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int num_rounds, 872f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_ECB *ecb); 873f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 874f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 875f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn each case, \textit{cipher} is the index into the cipher\_descriptor array of the cipher you want to use. The \textit{IV} value is 876f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe initialization vector to be used with the cipher. You must fill the IV yourself and it is assumed they are the same 877f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectlength 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.} 878f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof the cipher you choose. It is important that the IV be random for each unique message you want to encrypt. The 879f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectparameters \textit{key}, \textit{keylen} and \textit{num\_rounds} are the same as in the XXX\_setup() function call. The final parameter 880f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectis a pointer to the structure you want to hold the information for the mode of operation. 881f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 882f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 883f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn 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. 884f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIf \textbf{CTR\_COUNTER\_ LITTLE\_ENDIAN} was specified then the counter will be treated as a little endian value. Otherwise, if 885f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\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 886f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectincrement then encrypt is also supported. By OR'ing \textbf{LTC\_CTR\_RFC3686} with the CTR \textit{mode} value, ctr\_start() will increment 887f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe counter before encrypting it for the first time. 888f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 889f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise, they return an error code. 890f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 891f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Encryption and Decryption} 892f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo actually encrypt or decrypt the following routines are provided: 893f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecb\_encrypt()} \index{ecb\_decrypt()} \index{cfb\_encrypt()} \index{cfb\_decrypt()} 894f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{cbc\_encrypt()} \index{cbc\_decrypt()} \index{ofb\_encrypt()} \index{ofb\_decrypt()} \index{ctr\_encrypt()} \index{ctr\_decrypt()} 895f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 896f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_encrypt(const unsigned char *pt, 897f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 898f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len, 899f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_YYY *YYY); 900f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 901f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_decrypt(const unsigned char *ct, 902f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, 903f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len, 904f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_YYY *YYY); 905f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 906f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhere \textit{XXX} is one of $\lbrace ecb, cbc, ctr, cfb, ofb \rbrace$. 907f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 908f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn 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 909f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectchunk 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} 910f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand end up with the same ciphertext. However, encrypting \textit{ABC} and \textit{DABC} will result in different ciphertexts. All 911f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfive of the modes will return {\bf CRYPT\_OK} on success from the encrypt or decrypt functions. 912f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 913f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn 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 914f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectzeroes or with whatever your protocol requires). 915f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 916f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo 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. 917f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 918f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{IV Manipulation} 919f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo change or read the IV of a previously initialized chaining mode use the following two functions. 920f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{cbc\_setiv()} \index{cbc\_getiv()} \index{ofb\_setiv()} \index{ofb\_getiv()} \index{cfb\_setiv()} \index{cfb\_getiv()} 921f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ctr\_setiv()} \index{ctr\_getiv()} 922f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 923f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_getiv(unsigned char *IV, 924f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *len, 925f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_XXX *XXX); 926f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 927f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_setiv(const unsigned char *IV, 928f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len, 929f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_XXX *XXX); 930f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 931f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 932f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 933f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstored in \textit{len}. The XXX\_setiv will initialize the chaining mode state as if the original IV were the new IV specified. The length 934f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof the IV passed in must be the size of the ciphers block size. 935f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 936f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe XXX\_setiv() functions are handy if you wish to change the IV without re--keying the cipher. 937f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 938f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhat 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 939f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwere 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 940f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfirst 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 941f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe 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 942f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectseeking within the session. In OFB mode, the IV is encrypted and becomes the new pad. 943f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 944f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Stream Termination} 945f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo terminate an open stream call the done function. 946f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 947f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecb\_done()} \index{cbc\_done()}\index{cfb\_done()}\index{ofb\_done()} \index{ctr\_done()} 948f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 949f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_done(symmetric_XXX *XXX); 950f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 951f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 952f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will terminate the stream (by terminating the cipher) and return \textbf{CRYPT\_OK} if successful. 953f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 954f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\newpage 955f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Examples} 956f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 957f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 958f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 959f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 960f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 961f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char key[16], IV[16], buffer[512]; 962f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_CTR ctr; 963f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int x, err; 964f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 965f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register twofish first */ 966f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_cipher(&twofish_desc) == -1) { 967f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error registering cipher.\n"); 968f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 969f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 970f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 971f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* somehow fill out key and IV */ 972f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 973f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* start up CTR mode */ 974f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = ctr_start( 975f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project find_cipher("twofish"), /* index of desired cipher */ 976f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project IV, /* the initial vector */ 977f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project key, /* the secret key */ 978f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 16, /* length of secret key (16 bytes) */ 979f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 0, /* 0 == default # of rounds */ 980f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project CTR_COUNTER_LITTLE_ENDIAN, /* Little endian counter */ 981f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &ctr) /* where to store the CTR state */ 982f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ) != CRYPT_OK) { 983f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("ctr_start error: %s\n", error_to_string(err)); 984f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 985f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 986f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 987f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* somehow fill buffer than encrypt it */ 988f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = ctr_encrypt( buffer, /* plaintext */ 989f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project buffer, /* ciphertext */ 990f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project sizeof(buffer), /* length of plaintext pt */ 991f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &ctr) /* CTR state */ 992f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ) != CRYPT_OK) { 993f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("ctr_encrypt error: %s\n", error_to_string(err)); 994f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 995f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 996f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 997f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* make use of ciphertext... */ 998f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 999f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* now we want to decrypt so let's use ctr_setiv */ 1000f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = ctr_setiv( IV, /* the initial IV we gave to ctr_start */ 1001f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 16, /* the IV is 16 bytes long */ 1002f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &ctr) /* the ctr state we wish to modify */ 1003f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ) != CRYPT_OK) { 1004f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("ctr_setiv error: %s\n", error_to_string(err)); 1005f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 1006f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1007f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1008f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = ctr_decrypt( buffer, /* ciphertext */ 1009f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project buffer, /* plaintext */ 1010f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project sizeof(buffer), /* length of plaintext */ 1011f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &ctr) /* CTR state */ 1012f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ) != CRYPT_OK) { 1013f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("ctr_decrypt error: %s\n", error_to_string(err)); 1014f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 1015f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1016f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1017f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* terminate the stream */ 1018f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = ctr_done(&ctr)) != CRYPT_OK) { 1019f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("ctr_done error: %s\n", error_to_string(err)); 1020f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 1021f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1022f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1023f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* clear up and return */ 1024f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project zeromem(key, sizeof(key)); 1025f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project zeromem(&ctr, sizeof(ctr)); 1026f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1027f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 1028f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 1029f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1030f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 1031f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1032f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{LRW Mode} 1033f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLRW 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 1034f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsecurity problems of ECB mode while not increasing the storage requirements. It is used much like any other chaining mode except with two key differences. 1035f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1036f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 1037f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$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. 1038f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1039f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo initialize LRW mode use: 1040f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1041f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{lrw\_start()} 1042f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1043f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint lrw_start( int cipher, 1044f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *IV, 1045f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 1046f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int keylen, 1047f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *tweak, 1048f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int num_rounds, 1049f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_LRW *lrw); 1050f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1051f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1052f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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}. 1053f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhile 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 1054f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectnumber of rounds for the block cipher \textit{num\_rounds} can be 0 to use the default number of rounds for the given cipher. 1055f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1056f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo process data use the following functions: 1057f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1058f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{lrw\_encrypt()} \index{lrw\_decrypt()} 1059f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1060f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint lrw_encrypt(const unsigned char *pt, 1061f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 1062f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len, 1063f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_LRW *lrw); 1064f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1065f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint lrw_decrypt(const unsigned char *ct, 1066f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, 1067f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len, 1068f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_LRW *lrw); 1069f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1070f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1071f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese 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 1072f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof 16. The LRW code uses a fast tweak update such that consecutive blocks are encrypted faster than if random seeking where used. 1073f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1074f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo manipulate the IV use the following functions: 1075f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1076f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{lrw\_getiv()} \index{lrw\_setiv()} 1077f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1078f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint lrw_getiv(unsigned char *IV, 1079f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *len, 1080f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_LRW *lrw); 1081f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1082f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint lrw_setiv(const unsigned char *IV, 1083f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len, 1084f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_LRW *lrw); 1085f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1086f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese 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 1087f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectupdating the entire tweak which is slower than sequential use. Avoid seeking excessively in performance constrained code. 1088f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1089f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo terminate the LRW state use the following: 1090f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1091f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{lrw\_done()} 1092f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1093f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint lrw_done(symmetric_LRW *lrw); 1094f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1095f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1096f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{F8 Mode} 1097f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{F8 Mode} 1098f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 1099f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectagainst the plaintext to encrypt. F8 mode comes with the additional twist that the counter value is secret, encrypted by a \textit{salt key}. We 1100f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectinitialize F8 mode with the following function call: 1101f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1102f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{f8\_start()} 1103f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1104f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint f8_start( int cipher, 1105f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *IV, 1106f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 1107f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int keylen, 1108f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *salt_key, 1109f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int skeylen, 1110f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int num_rounds, 1111f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_F8 *f8); 1112f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1113f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 1114f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project(\textit{m} in the RFC 3711). The salt\_key can be shorter than the secret key but it should not be longer. 1115f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1116f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo encrypt or decrypt data we use the following two functions: 1117f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1118f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{f8\_encrypt()} \index{f8\_decrypt()} 1119f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1120f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint f8_encrypt(const unsigned char *pt, 1121f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 1122f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len, 1123f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_F8 *f8); 1124f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1125f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint f8_decrypt(const unsigned char *ct, 1126f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, 1127f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len, 1128f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_F8 *f8); 1129f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1130f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese 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 1131f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof the ciphers block size. 1132f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1133f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo change or retrieve the current counter IV value use the following functions: 1134f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{f8\_getiv()} \index{f8\_setiv()} 1135f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1136f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint f8_getiv(unsigned char *IV, 1137f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *len, 1138f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_F8 *f8); 1139f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1140f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint f8_setiv(const unsigned char *IV, 1141f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len, 1142f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_F8 *f8); 1143f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1144f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese 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 1145f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectable 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 1146f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectf8\_start(). 1147f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1148f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo terminate an F8 state call the following function: 1149f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1150f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{f8\_done()} 1151f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1152f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint f8_done(symmetric_F8 *f8); 1153f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1154f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1155f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\vfil 1156f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Encrypt and Authenticate Modes} 1157f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1158f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{EAX Mode} 1159f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLibTomCrypt provides support for a mode called EAX\footnote{See 1160f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectM. Bellare, P. Rogaway, D. Wagner, A Conventional Authenticated-Encryption Mode.} in a manner similar to the way it was intended to be used 1161f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectby 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, 1162f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCTR and OMAC support and provides encryption and 1163f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectauthentication\footnote{Note that since EAX only requires OMAC and CTR you may use \textit{encrypt only} cipher descriptors with this mode.}. 1164f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt 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. 1165f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1166f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \textit{header} data is meant to be meta--data associated with a stream that isn't private (e.g., protocol messages). It can 1167f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbe 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. 1168f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1169f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe mode can then process plaintext producing ciphertext as well as compute a partial checksum. The actual checksum 1170f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcalled a \textit{tag} is only emitted when the message is finished. In the interim, the user can process any arbitrary 1171f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsized message block to send to the recipient as ciphertext. This makes the EAX mode especially suited for streaming modes 1172f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof operation. 1173f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1174f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe mode is initialized with the following function. 1175f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{eax\_init()} 1176f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1177f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint eax_init( eax_state *eax, 1178f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 1179f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 1180f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long keylen, 1181f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *nonce, 1182f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long noncelen, 1183f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *header, 1184f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long headerlen); 1185f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1186f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1187f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhere \textit{eax} is the EAX state. The \textit{cipher} parameter is the index of the desired cipher in the descriptor table. 1188f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \textit{key} parameter is the shared secret symmetric key of length \textit{keylen} octets. The \textit{nonce} parameter is the 1189f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrandom public string of length \textit{noncelen} octets. The \textit{header} parameter is the random (or fixed or \textbf{NULL}) header for the 1190f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmessage of length \textit{headerlen} octets. 1191f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1192f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen this function completes, the \textit{eax} state will be initialized such that you can now either have data decrypted or 1193f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectencrypted 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. 1194f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1195f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo encrypt or decrypt data in a streaming mode use the following. 1196f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{eax\_encrypt()} \index{eax\_decrypt()} 1197f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1198f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint eax_encrypt( eax_state *eax, 1199f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *pt, 1200f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 1201f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long length); 1202f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1203f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint eax_decrypt( eax_state *eax, 1204f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *ct, 1205f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, 1206f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long length); 1207f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1208f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe function \textit{eax\_encrypt} will encrypt the bytes in \textit{pt} of \textit{length} octets, and store the ciphertext in 1209f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{ct}. Note: \textit{ct} and \textit{pt} may be the same region in memory. This function will also send the ciphertext 1210f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthrough the OMAC function. The function \textit{eax\_decrypt} decrypts \textit{ct}, and stores it in \textit{pt}. This also allows 1211f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{pt} and \textit{ct} to be the same region in memory. 1212f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1213f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectYou cannot both encrypt or decrypt with the same \textit{eax} context. For bi--directional communication you will need to initialize 1214f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttwo EAX contexts (preferably with different headers and nonces). 1215f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1216f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote: both of these functions allow you to send the data in any granularity but the order is important. While 1217f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe eax\_init() function allows you to add initial header data to the stream you can also add header data during the 1218f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectEAX stream with the following. 1219f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1220f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{eax\_addheader()} 1221f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1222f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint eax_addheader( eax_state *eax, 1223f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *header, 1224f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long length); 1225f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1226f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will add the \textit{length} octet from \textit{header} to the given \textit{eax} header. Once the message is finished, the 1227f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{tag} (checksum) may be computed with the following function: 1228f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1229f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{eax\_done()} 1230f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1231f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint eax_done( eax_state *eax, 1232f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *tag, 1233f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *taglen); 1234f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1235f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will terminate the EAX state \textit{eax}, and store up to \textit{taglen} bytes of the message tag in \textit{tag}. The function 1236f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthen stores how many bytes of the tag were written out back in to \textit{taglen}. 1237f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1238f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe EAX mode code can be tested to ensure it matches the test vectors by calling the following function: 1239f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{eax\_test()} 1240f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1241f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint eax_test(void); 1242f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1243f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis requires that the AES (or Rijndael) block cipher be registered with the cipher\_descriptor table first. 1244f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1245f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1246f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 1247f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 1248f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 1249f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 1250f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project eax_state eax; 1251f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char pt[64], ct[64], nonce[16], key[16], tag[16]; 1252f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long taglen; 1253f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1254f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_cipher(&rijndael_desc) == -1) { 1255f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error registering Rijndael"); 1256f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 1257f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1258f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1259f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* ... make up random nonce and key ... */ 1260f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1261f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* initialize context */ 1262f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = eax_init( &eax, /* context */ 1263f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project find_cipher("rijndael"), /* cipher id */ 1264f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project nonce, /* the nonce */ 1265f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 16, /* nonce is 16 bytes */ 1266f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project "TestApp", /* example header */ 1267f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 7) /* header length */ 1268f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ) != CRYPT_OK) { 1269f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error eax_init: %s", error_to_string(err)); 1270f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 1271f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1272f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1273f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* now encrypt data, say in a loop or whatever */ 1274f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = eax_encrypt( &eax, /* eax context */ 1275f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project pt, /* plaintext (source) */ 1276f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ct, /* ciphertext (destination) */ 1277f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project sizeof(pt) /* size of plaintext */ 1278f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ) != CRYPT_OK) { 1279f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error eax_encrypt: %s", error_to_string(err)); 1280f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 1281f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1282f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1283f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* finish message and get authentication tag */ 1284f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project taglen = sizeof(tag); 1285f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = eax_done( &eax, /* eax context */ 1286f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project tag, /* where to put tag */ 1287f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &taglen /* length of tag space */ 1288f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ) != CRYPT_OK) { 1289f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error eax_done: %s", error_to_string(err)); 1290f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 1291f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1292f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1293f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* now we have the authentication tag in "tag" and 1294f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project * it's taglen bytes long */ 1295f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 1296f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1297f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1298f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectYou can also perform an entire EAX state on a block of memory in a single function call with the 1299f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfollowing functions. 1300f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1301f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1302f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{eax\_encrypt\_authenticate\_memory} \index{eax\_decrypt\_verify\_memory} 1303f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1304f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint eax_encrypt_authenticate_memory( 1305f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 1306f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 1307f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *nonce, unsigned long noncelen, 1308f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *header, unsigned long headerlen, 1309f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *pt, unsigned long ptlen, 1310f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 1311f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *tag, unsigned long *taglen); 1312f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1313f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint eax_decrypt_verify_memory( 1314f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 1315f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 1316f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *nonce, unsigned long noncelen, 1317f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *header, unsigned long headerlen, 1318f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *ct, unsigned long ctlen, 1319f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, 1320f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *tag, unsigned long taglen, 1321f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int *res); 1322f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1323f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1324f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectBoth essentially just call eax\_init() followed by eax\_encrypt() (or eax\_decrypt() respectively) and eax\_done(). The parameters 1325f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecthave the same meaning as with those respective functions. 1326f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1327f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 1328f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe tag it computed while decrypting the message. If the tags match then it stores a $1$ in \textit{res}, otherwise it stores a $0$. 1329f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1330f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{OCB Mode} 1331f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLibTomCrypt provides support for a mode called OCB\footnote{See 1332f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectP. Rogaway, M. Bellare, J. Black, T. Krovetz, \textit{OCB: A Block Cipher Mode of Operation for Efficient Authenticated Encryption}.} 1333f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project. OCB is an encryption protocol that simultaneously provides authentication. It is slightly faster to use than EAX mode 1334f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbut is less flexible. Let's review how to initialize an OCB context. 1335f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1336f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ocb\_init()} 1337f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1338f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ocb_init( ocb_state *ocb, 1339f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 1340f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 1341f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long keylen, 1342f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *nonce); 1343f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1344f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1345f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will initialize the \textit{ocb} context using cipher descriptor \textit{cipher}. It will use a \textit{key} of length \textit{keylen} 1346f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand the random \textit{nonce}. Note that \textit{nonce} must be a random (public) string the same length as the block ciphers 1347f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectblock size (e.g. 16 bytes for AES). 1348f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1349f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis mode has no \textit{Associated Data} like EAX mode does which means you cannot authenticate metadata along with the stream. 1350f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo encrypt or decrypt data use the following. 1351f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1352f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ocb\_encrypt()} \index{ocb\_decrypt()} 1353f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1354f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ocb_encrypt( ocb_state *ocb, 1355f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *pt, 1356f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct); 1357f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1358f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ocb_decrypt( ocb_state *ocb, 1359f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *ct, 1360f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt); 1361f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1362f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1363f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will encrypt (or decrypt for the latter) a fixed length of data from \textit{pt} to \textit{ct} (vice versa for the latter). 1364f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThey assume that \textit{pt} and \textit{ct} are the same size as the block cipher's block size. Note that you cannot call 1365f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectboth functions given a single \textit{ocb} state. For bi-directional communication you will have to initialize two \textit{ocb} 1366f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstates (with different nonces). Also \textit{pt} and \textit{ct} may point to the same location in memory. 1367f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1368f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{State Termination} 1369f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1370f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen you are finished encrypting the message you call the following function to compute the tag. 1371f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1372f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ocb\_done\_encrypt()} 1373f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1374f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ocb_done_encrypt( ocb_state *ocb, 1375f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *pt, 1376f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long ptlen, 1377f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 1378f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *tag, 1379f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *taglen); 1380f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1381f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1382f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will terminate an encrypt stream \textit{ocb}. If you have trailing bytes of plaintext that will not complete a block 1383f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectyou can pass them here. This will also encrypt the \textit{ptlen} bytes in \textit{pt} and store them in \textit{ct}. It will also 1384f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstore up to \textit{taglen} bytes of the tag into \textit{tag}. 1385f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1386f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote that \textit{ptlen} must be less than or equal to the block size of block cipher chosen. Also note that if you have 1387f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectan input message equal to the length of the block size then you pass the data here (not to ocb\_encrypt()) only. 1388f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1389f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo terminate a decrypt stream and compared the tag you call the following. 1390f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1391f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ocb\_done\_decrypt()} 1392f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1393f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ocb_done_decrypt( ocb_state *ocb, 1394f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *ct, 1395f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long ctlen, 1396f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, 1397f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *tag, 1398f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long taglen, 1399f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int *res); 1400f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1401f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSimilarly to the previous function you can pass trailing message bytes into this function. This will compute the 1402f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttag of the message (internally) and then compare it against the \textit{taglen} bytes of \textit{tag} provided. By default 1403f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\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 1404f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmessage). 1405f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1406f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Packet Functions} 1407f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo make life simpler the following two functions are provided for memory bound OCB. 1408f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1409f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project%\index{ocb\_encrypt\_authenticate\_memory()} 1410f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1411f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ocb_encrypt_authenticate_memory( 1412f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 1413f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 1414f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *nonce, 1415f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *pt, unsigned long ptlen, 1416f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 1417f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *tag, unsigned long *taglen); 1418f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1419f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1420f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will OCB encrypt the message \textit{pt} of length \textit{ptlen}, and store the ciphertext in \textit{ct}. The length \textit{ptlen} 1421f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcan be any arbitrary length. 1422f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1423f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ocb\_decrypt\_verify\_memory()} 1424f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1425f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ocb_decrypt_verify_memory( 1426f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 1427f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 1428f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *nonce, 1429f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *ct, unsigned long ctlen, 1430f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, 1431f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *tag, unsigned long taglen, 1432f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int *res); 1433f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1434f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1435f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSimilarly, this will OCB decrypt, and compare the internally computed tag against the tag provided. \textit{res} is set 1436f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectappropriately. 1437f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1438f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{CCM Mode} 1439f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCCM 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, 1440f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectit 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 1441f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfunction that performs the protocol. 1442f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1443f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ccm\_memory()} 1444f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1445f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ccm_memory( 1446f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 1447f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 1448f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *uskey, 1449f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *nonce, unsigned long noncelen, 1450f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *header, unsigned long headerlen, 1451f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, unsigned long ptlen, 1452f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 1453f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *tag, unsigned long *taglen, 1454f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int direction); 1455f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1456f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1457f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 1458f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project16--byte block size for CCM. 1459f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1460f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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, 1461f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectit 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 1462f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{uskey} is not \textbf{NULL}, then \textit{key} may be \textbf{NULL} (and vice-versa). 1463f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1464f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 1465f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectencrypted, it is stored in \textit{header} of length \textit{headerlen} octets. The header can be zero octets long (if $headerlen = 0$ then 1466f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectyou can pass \textit{header} as \textbf{NULL}). 1467f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1468f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 1469f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectallowable that $pt = ct$. The \textit{direction} variable indicates whether encryption (direction $=$ \textbf{CCM\_ENCRYPT}) or 1470f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdecryption (direction $=$ \textbf{CCM\_DECRYPT}) is to be performed. 1471f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1472f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs implemented, this version of CCM cannot handle header or plaintext data longer than $2^{32} - 1$ octets long. 1473f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1474f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectYou can test the implementation of CCM with the following function. 1475f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1476f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ccm\_test()} 1477f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1478f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ccm_test(void); 1479f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1480f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1481f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 1482f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectreturn \textbf{CRYPT\_NOP}. 1483f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1484f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{CCM Example} 1485f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe following is a sample of how to call CCM. 1486f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1487f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 1488f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1489f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 1490f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 1491f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 1492f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char key[16], nonce[12], pt[32], ct[32], 1493f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project tag[16], tagcp[16]; 1494f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long taglen; 1495f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 1496f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1497f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register cipher */ 1498f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project register_cipher(&aes_desc); 1499f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1500f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* somehow fill key, nonce, pt */ 1501f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1502f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* encrypt it */ 1503f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project taglen = sizeof(tag); 1504f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = 1505f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ccm_memory(find_cipher("aes"), 1506f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project key, 16, /* 128-bit key */ 1507f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project NULL, /* not prescheduled */ 1508f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project nonce, 12, /* 96-bit nonce */ 1509f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project NULL, 0, /* no header */ 1510f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project pt, 32, /* 32-byte plaintext */ 1511f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ct, /* ciphertext */ 1512f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project tag, &taglen, 1513f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project CCM_ENCRYPT)) != CRYPT_OK) { 1514f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("ccm_memory error %s\n", error_to_string(err)); 1515f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 1516f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1517f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* ct[0..31] and tag[0..15] now hold the output */ 1518f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1519f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* decrypt it */ 1520f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project taglen = sizeof(tagcp); 1521f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = 1522f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ccm_memory(find_cipher("aes"), 1523f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project key, 16, /* 128-bit key */ 1524f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project NULL, /* not prescheduled */ 1525f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project nonce, 12, /* 96-bit nonce */ 1526f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project NULL, 0, /* no header */ 1527f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ct, 32, /* 32-byte ciphertext */ 1528f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project pt, /* plaintext */ 1529f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project tagcp, &taglen, 1530f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project CCM_DECRYPT)) != CRYPT_OK) { 1531f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("ccm_memory error %s\n", error_to_string(err)); 1532f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 1533f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1534f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1535f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* now pt[0..31] should hold the original plaintext, 1536f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project tagcp[0..15] and tag[0..15] should have the same contents */ 1537f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 1538f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1539f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 1540f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1541f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{GCM Mode} 1542f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectGalois 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 1543f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecthowever, unlike EAX it cannot accept \textit{additional authentication data} (meta--data) after plaintext has been processed. This mode also only works with 1544f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectblock ciphers with a 16--byte block. 1545f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1546f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectA 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 1547f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectunique to every session. Next, the the optional additional authentication data is processed, and finally the plaintext (or ciphertext depending on the direction). 1548f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1549f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Initialization} 1550f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo initialize the GCM context with a secret key call the following function. 1551f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1552f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{gcm\_init()} 1553f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1554f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint gcm_init( gcm_state *gcm, 1555f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 1556f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 1557f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int keylen); 1558f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1559f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 1560f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectchosen must have a 16--byte block size (e.g., AES). 1561f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1562f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Initial Vector} 1563f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAfter 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. 1564f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1565f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{gcm\_add\_iv()} 1566f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1567f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint gcm_add_iv( gcm_state *gcm, 1568f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *IV, 1569f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long IVlen); 1570f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1571f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 1572f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto process the entire IV. 1573f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1574f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote: 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 1575f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto only use 12--byte IVs. You can just increment it like a counter for each packet. 1576f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1577f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Additional Authentication Data} 1578f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAfter the entire IV has been processed, the additional authentication data can be processed. Unlike the IV, a packet/session does not require additional 1579f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectauthentication 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 1580f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectyou begin adding AAD to the GCM state you cannot return to adding IV data until the state has been reset. 1581f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1582f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{gcm\_add\_aad()} 1583f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1584f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint gcm_add_aad( gcm_state *gcm, 1585f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *adata, 1586f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long adatalen); 1587f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1588f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis adds the additional authentication data \textit{adata} of length \textit{adatalen} to the GCM state \textit{gcm}. 1589f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1590f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Plaintext Processing} 1591f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAfter the AAD has been processed, the plaintext (or ciphertext depending on the direction) can be processed. 1592f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1593f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{gcm\_process()} 1594f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1595f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint gcm_process( gcm_state *gcm, 1596f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, 1597f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long ptlen, 1598f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 1599f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int direction); 1600f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1601f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 1602f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe 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, 1603f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectencrypted and stored in the ciphertext buffer. When \textit{direction} equals \textbf{GCM\_DECRYPT} the opposite occurs. 1604f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1605f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{State Termination} 1606f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo terminate a GCM state and retrieve the message authentication tag call the following function. 1607f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1608f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{gcm\_done()} 1609f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1610f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint gcm_done( gcm_state *gcm, 1611f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *tag, 1612f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *taglen); 1613f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1614f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis terminates the GCM state \textit{gcm} and stores the tag in \textit{tag} of length \textit{taglen} octets. 1615f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1616f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{State Reset} 1617f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 1618f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectit is very costly to have to call it repeatedly. To aid in this endeavour, the reset function has been provided. 1619f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1620f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{gcm\_reset()} 1621f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1622f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint gcm_reset(gcm_state *gcm); 1623f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1624f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1625f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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. 1626f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1627f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{One--Shot Packet} 1628f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo process a single packet under any given key the following helper function can be used. 1629f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1630f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{gcm\_memory()} 1631f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1632f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint gcm_memory( 1633f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 1634f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 1635f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long keylen, 1636f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *IV, unsigned long IVlen, 1637f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *adata, unsigned long adatalen, 1638f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, unsigned long ptlen, 1639f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 1640f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *tag, unsigned long *taglen, 1641f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int direction); 1642f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1643f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1644f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 1645f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmessage tag. The definition of the variables is the same as it is for all the manual functions. 1646f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1647f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIf you are processing many packets under the same key you shouldn't use this function as it invokes the pre--computation with each call. 1648f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1649f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Example Usage} 1650f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe following is an example usage of how to use GCM over multiple packets with a shared secret key. 1651f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1652f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 1653f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1654f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 1655f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1656f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint send_packet(const unsigned char *pt, unsigned long ptlen, 1657f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *iv, unsigned long ivlen, 1658f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *aad, unsigned long aadlen, 1659f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project gcm_state *gcm) 1660f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 1661f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 1662f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long taglen; 1663f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char tag[16]; 1664f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1665f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* reset the state */ 1666f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = gcm_reset(gcm)) != CRYPT_OK) { 1667f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return err; 1668f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1669f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1670f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* Add the IV */ 1671f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = gcm_add_iv(gcm, iv, ivlen)) != CRYPT_OK) { 1672f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return err; 1673f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1674f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1675f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* Add the AAD (note: aad can be NULL if aadlen == 0) */ 1676f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = gcm_add_aad(gcm, aad, aadlen)) != CRYPT_OK) { 1677f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return err; 1678f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1679f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1680f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* process the plaintext */ 1681f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = 1682f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project gcm_process(gcm, pt, ptlen, pt, GCM_ENCRYPT)) != CRYPT_OK) { 1683f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return err; 1684f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1685f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1686f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* Finish up and get the MAC tag */ 1687f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project taglen = sizeof(tag); 1688f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = gcm_done(gcm, tag, &taglen)) != CRYPT_OK) { 1689f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return err; 1690f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1691f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1692f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* ... send a header describing the lengths ... */ 1693f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1694f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* depending on the protocol and how IV is 1695f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project * generated you may have to send it too... */ 1696f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project send(socket, iv, ivlen, 0); 1697f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1698f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* send the aad */ 1699f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project send(socket, aad, aadlen, 0); 1700f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1701f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* send the ciphertext */ 1702f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project send(socket, pt, ptlen, 0); 1703f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1704f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* send the tag */ 1705f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project send(socket, tag, taglen, 0); 1706f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1707f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return CRYPT_OK; 1708f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 1709f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1710f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 1711f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 1712f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project gcm_state gcm; 1713f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char key[16], IV[12], pt[PACKET_SIZE]; 1714f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err, x; 1715f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long ptlen; 1716f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1717f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* somehow fill key/IV with random values */ 1718f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1719f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register AES */ 1720f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project register_cipher(&aes_desc); 1721f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1722f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* init the GCM state */ 1723f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = 1724f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project gcm_init(&gcm, find_cipher("aes"), key, 16)) != CRYPT_OK) { 1725f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project whine_and_pout(err); 1726f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1727f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1728f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* handle us some packets */ 1729f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project for (;;) { 1730f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ptlen = make_packet_we_want_to_send(pt); 1731f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1732f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* use IV as counter (12 byte counter) */ 1733f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project for (x = 11; x >= 0; x--) { 1734f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (++IV[x]) { 1735f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project break; 1736f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1737f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1738f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1739f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = send_packet(pt, ptlen, iv, 12, NULL, 0, &gcm)) 1740f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project != CRYPT_OK) { 1741f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project whine_and_pout(err); 1742f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1743f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1744f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_SUCCESS; 1745f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 1746f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1747f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 1748f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1749f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{One-Way Cryptographic Hash Functions} 1750f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Core Functions} 1751f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLike the ciphers, there are hash core functions and a universal data type to hold the hash state called \textit{hash\_state}. To initialize hash 1752f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectXXX (where XXX is the name) call: 1753f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Hash Functions} 1754f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1755f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectvoid XXX_init(hash_state *md); 1756f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1757f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1758f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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: 1759f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1760f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_process( hash_state *md, 1761f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 1762f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen); 1763f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1764f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectEssentially 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 1765f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectare 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, 1766f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthis means that: 1767f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1768f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmd5_process(&md, "hello ", 6); 1769f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmd5_process(&md, "world", 5); 1770f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1771f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWill produce the same message digest as the single call: 1772f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Message Digest} 1773f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1774f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmd5_process(&md, "hello world", 11); 1775f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1776f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1777f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo finally get the message digest (the hash) call: 1778f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1779f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_done( hash_state *md, 1780f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out); 1781f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1782f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1783f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function will finish up the hash and store the result in the \textit{out} array. You must ensure that \textit{out} is long 1784f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectenough for the hash in question. Often hashes are used to get keys for symmetric ciphers so the \textit{XXX\_done()} functions 1785f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwill wipe the \textit{md} variable before returning automatically. 1786f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1787f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo test a hash function call: 1788f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1789f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_test(void); 1790f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1791f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1792f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will return {\bf CRYPT\_OK} if the hash matches the test vectors, otherwise it returns an error code. An 1793f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectexample snippet that hashes a message with md5 is given below. 1794f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 1795f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1796f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 1797f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 1798f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 1799f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project hash_state md; 1800f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *in = "hello world", out[16]; 1801f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1802f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* setup the hash */ 1803f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project md5_init(&md); 1804f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1805f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* add the message */ 1806f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project md5_process(&md, in, strlen(in)); 1807f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1808f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* get the hash in out[0..15] */ 1809f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project md5_done(&md, out); 1810f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1811f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 1812f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 1813f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1814f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 1815f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1816f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Hash Descriptors} 1817f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLike the set of ciphers, the set of hashes have descriptors as well. They are stored in an array called \textit{hash\_descriptor} and 1818f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectare defined by: 1819f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1820f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstruct _hash_descriptor { 1821f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project char *name; 1822f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1823f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long hashsize; /* digest output size in bytes */ 1824f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long blocksize; /* the block size the hash uses */ 1825f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1826f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void (*init) (hash_state *hash); 1827f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1828f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*process)( hash_state *hash, 1829f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 1830f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen); 1831f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1832f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*done) (hash_state *hash, unsigned char *out); 1833f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1834f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*test) (void); 1835f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project}; 1836f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1837f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1838f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{find\_hash()} 1839f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \textit{name} member is the name of the hash function (all lowercase). The \textit{hashsize} member is the size of the digest output 1840f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectin bytes, while \textit{blocksize} is the size of blocks the hash expects to the compression function. Technically, this detail is not important 1841f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfor high level developers but is useful to know for performance reasons. 1842f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1843f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \textit{init} member initializes the hash, \textit{process} passes data through the hash, \textit{done} terminates the hash and retrieves the 1844f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdigest. The \textit{test} member tests the hash against the specified test vectors. 1845f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1846f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere 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 1847f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectposition in the descriptor table of the hash. 1848f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1849f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn addition, there is also find\_hash\_oid() which finds a hash by the ASN.1 OBJECT IDENTIFIER string. 1850f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{find\_hash\_oid()} 1851f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1852f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint find_hash_oid(const unsigned long *ID, unsigned long IDlen); 1853f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1854f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1855f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectYou can use the table to indirectly call a hash function that is chosen at run-time. For example: 1856f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 1857f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1858f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 1859f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 1860f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 1861f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char buffer[100], hash[MAXBLOCKSIZE]; 1862f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int idx, x; 1863f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project hash_state md; 1864f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1865f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register hashes .... */ 1866f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_hash(&md5_desc) == -1) { 1867f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error registering MD5.\n"); 1868f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 1869f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1870f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1871f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register other hashes ... */ 1872f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1873f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* prompt for name and strip newline */ 1874f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Enter hash name: \n"); 1875f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project fgets(buffer, sizeof(buffer), stdin); 1876f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project buffer[strlen(buffer) - 1] = 0; 1877f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1878f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* get hash index */ 1879f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project idx = find_hash(buffer); 1880f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (idx == -1) { 1881f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Invalid hash name!\n"); 1882f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 1883f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1884f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1885f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* hash input until blank line */ 1886f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project hash_descriptor[idx].init(&md); 1887f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project while (fgets(buffer, sizeof(buffer), stdin) != NULL) 1888f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project hash_descriptor[idx].process(&md, buffer, strlen(buffer)); 1889f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project hash_descriptor[idx].done(&md, hash); 1890f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1891f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* dump to screen */ 1892f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project for (x = 0; x < hash_descriptor[idx].hashsize; x++) 1893f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("%02x ", hash[x]); 1894f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("\n"); 1895f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 1896f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 1897f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1898f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 1899f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1900f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote the usage of \textbf{MAXBLOCKSIZE}. In LibTomCrypt, no symmetric block, key or hash digest is larger than \textbf{MAXBLOCKSIZE} in 1901f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectlength. This provides a simple size you can set your automatic arrays to that will not get overrun. 1902f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1903f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere 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 1904f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfunction call. 1905f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1906f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{hash\_memory()} 1907f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1908f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint hash_memory( int hash, 1909f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 1910f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 1911f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 1912f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 1913f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1914f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1915f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 1916f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdigest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size. 1917f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1918f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe next helper function allows for the hashing of a file based on a file name. 1919f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{hash\_file()} 1920f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1921f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint hash_file( int hash, 1922f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const char *fname, 1923f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 1924f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 1925f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1926f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1927f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 1928f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectuser 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} 1929f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwhen it is called. The message digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size. 1930f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1931f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{hash\_filehandle()} 1932f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1933f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint hash_filehandle( int hash, 1934f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project FILE *in, 1935f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 1936f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 1937f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1938f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1939f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 1940f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwill 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} 1941f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwhen it is called. The message digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size. 1942f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1943f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo perform the above hash with md5 the following code could be used: 1944f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 1945f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1946f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 1947f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 1948f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 1949f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int idx, err; 1950f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len; 1951f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char out[MAXBLOCKSIZE]; 1952f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1953f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register the hash */ 1954f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_hash(&md5_desc) == -1) { 1955f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error registering MD5.\n"); 1956f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 1957f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1958f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1959f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* get the index of the hash */ 1960f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project idx = find_hash("md5"); 1961f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1962f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* call the hash */ 1963f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project len = sizeof(out); 1964f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = 1965f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project hash_memory(idx, "hello world", 11, out, &len)) != CRYPT_OK) { 1966f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error hashing data: %s\n", error_to_string(err)); 1967f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 1968f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 1969f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 1970f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 1971f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1972f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 1973f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1974f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Hash Registration} 1975f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSimilar to the cipher descriptor table you must register your hash algorithms before you can use them. These functions 1976f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwork exactly like those of the cipher registration code. The functions are: 1977f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{register\_hash()} \index{unregister\_hash()} 1978f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 1979f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint register_hash(const struct _hash_descriptor *hash); 1980f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1981f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint unregister_hash(const struct _hash_descriptor *hash); 1982f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 1983f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1984f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe following hashes are provided as of this release within the LibTomCrypt library: 1985f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Hash descriptor table} 1986f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1987f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{figure}[here] 1988f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{center} 1989f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{tabular}{|c|c|c|} 1990f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline \textbf{Name} & \textbf{Descriptor Name} & \textbf{Size of Message Digest (bytes)} \\ 1991f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline WHIRLPOOL & whirlpool\_desc & 64 \\ 1992f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline SHA-512 & sha512\_desc & 64 \\ 1993f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline SHA-384 & sha384\_desc & 48 \\ 1994f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline RIPEMD-320 & rmd160\_desc & 40 \\ 1995f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline SHA-256 & sha256\_desc & 32 \\ 1996f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline RIPEMD-256 & rmd160\_desc & 32 \\ 1997f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline SHA-224 & sha224\_desc & 28 \\ 1998f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline TIGER-192 & tiger\_desc & 24 \\ 1999f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline SHA-1 & sha1\_desc & 20 \\ 2000f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline RIPEMD-160 & rmd160\_desc & 20 \\ 2001f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline RIPEMD-128 & rmd128\_desc & 16 \\ 2002f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline MD5 & md5\_desc & 16 \\ 2003f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline MD4 & md4\_desc & 16 \\ 2004f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline MD2 & md2\_desc & 16 \\ 2005f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 2006f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{tabular} 2007f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{center} 2008f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\caption{Built--In Software Hashes} 2009f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{figure} 2010f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\vfil 2011f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2012f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Cipher Hash Construction} 2013f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Cipher Hash Construction} 2014f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAn addition to the suite of hash functions is the \textit{Cipher Hash Construction} or \textit{CHC} mode. In this mode 2015f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectapplicable block ciphers (such as AES) can be turned into hash functions that other LTC functions can use. In 2016f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectparticular this allows a cryptosystem to be designed using very few moving parts. 2017f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2018f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn order to use the CHC system the developer will have to take a few extra steps. First the \textit{chc\_desc} hash 2019f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdescriptor must be registered with register\_hash(). At this point the CHC hash cannot be used to hash 2020f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdata. While it is in the hash system you still have to tell the CHC code which cipher to use. This is accomplished 2021f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectvia the chc\_register() function. 2022f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2023f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{chc\_register()} 2024f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2025f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint chc_register(int cipher); 2026f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2027f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2028f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectA cipher has to be registered with CHC (and also in the cipher descriptor tables with 2029f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectregister\_cipher()). The chc\_register() function will bind a cipher to the CHC system. Only one cipher can 2030f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbe bound to the CHC hash at a time. There are additional requirements for the system to work. 2031f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2032f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{enumerate} 2033f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item The cipher must have a block size greater than 64--bits. 2034f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item The cipher must allow an input key the size of the block size. 2035f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{enumerate} 2036f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2037f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectExample of using CHC with the AES block cipher. 2038f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2039f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2040f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 2041f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 2042f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 2043f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 2044f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2045f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register cipher and hash */ 2046f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_cipher(&aes_enc_desc) == -1) { 2047f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Could not register cipher\n"); 2048f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 2049f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2050f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_hash(&chc_desc) == -1) { 2051f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Could not register hash\n"); 2052f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 2053f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2054f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2055f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* start chc with AES */ 2056f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = chc_register(find_cipher("aes"))) != CRYPT_OK) { 2057f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error binding AES to CHC: %s\n", 2058f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project error_to_string(err)); 2059f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2060f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2061f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* now you can use chc_hash in any LTC function 2062f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project * [aside from pkcs...] */ 2063f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 2064f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2065f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2066f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2067f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Notice} 2068f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt is highly recommended that you \textbf{not} use the MD4 or MD5 hashes for the purposes of digital signatures or authentication codes. 2069f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese hashes are provided for completeness and they still can be used for the purposes of password hashing or one-way accumulators 2070f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project(e.g. Yarrow). 2071f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2072f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 2073f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfor all purposes you would normally use a hash for. 2074f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2075f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{Message Authentication Codes} 2076f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{HMAC Protocol} 2077f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThanks to Dobes Vandermeer, the library now includes support for hash based message authentication codes, or HMAC for short. An HMAC 2078f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof a message is a keyed authentication code that only the owner of a private symmetric key will be able to verify. The purpose is 2079f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto 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 2080f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecteavesdropper will not be able to verify the authenticity of a message. 2081f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2082f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe HMAC support works much like the normal hash functions except that the initialization routine requires you to pass a key 2083f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand 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 2084f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectunsigned characters. The initialization routine is: 2085f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{hmac\_init()} 2086f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2087f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint hmac_init( hmac_state *hmac, 2088f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash, 2089f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 2090f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long keylen); 2091f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2092f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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 2093f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto 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 2094f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectlength (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: 2095f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{hmac\_process()} 2096f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2097f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint hmac_process( hmac_state *hmac, 2098f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 2099f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen); 2100f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2101f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{hmac} is the HMAC state you are working with. \textit{buf} is the array of octets to send into the HMAC process. \textit{len} is the 2102f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectnumber of octets to process. Like the hash process routines you can send the data in arbitrarily sized chunks. When you 2103f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectare finished with the HMAC process you must call the following function to get the HMAC code: 2104f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{hmac\_done()} 2105f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2106f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint hmac_done( hmac_state *hmac, 2107f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 2108f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 2109f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2110f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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. 2111f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectYou 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 2112f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectproduced (depending on which hash was picked). If \textit{outlen} is less than the size of the message digest (and ultimately 2113f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe HMAC code) then the HMAC code is truncated as per FIPS-198 specifications (e.g. take the first \textit{outlen} bytes). 2114f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2115f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere are two utility functions provided to make using HMACs easier to do. They accept the key and information about the 2116f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmessage (file pointer, address in memory), and produce the HMAC result in one shot. These are useful if you want to avoid 2117f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcalling the three step process yourself. 2118f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2119f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{hmac\_memory()} 2120f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2121f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint hmac_memory( 2122f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash, 2123f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 2124f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, unsigned long inlen, 2125f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen); 2126f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2127f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will produce an HMAC code for the array of octets in \textit{in} of length \textit{inlen}. The index into the hash descriptor 2128f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttable must be provided in \textit{hash}. It uses the key from \textit{key} with a key length of \textit{keylen}. 2129f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe result is stored in the array of octets \textit{out} and the length in \textit{outlen}. The value of \textit{outlen} must be set 2130f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto the size of the destination buffer before calling this function. Similarly for files there is the following function: 2131f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{hmac\_file()} 2132f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2133f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint hmac_file( 2134f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash, 2135f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const char *fname, 2136f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 2137f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen); 2138f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2139f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{hash} is the index into the hash descriptor table of the hash you want to use. \textit{fname} is the filename to process. 2140f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\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 2141f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectresult should be stored. 2142f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2143f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo test if the HMAC code is working there is the following function: 2144f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{hmac\_test()} 2145f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2146f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint hmac_test(void); 2147f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2148f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. Some example code for using the 2149f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectHMAC system is given below. 2150f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2151f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 2152f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2153f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 2154f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 2155f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 2156f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int idx, err; 2157f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project hmac_state hmac; 2158f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char key[16], dst[MAXBLOCKSIZE]; 2159f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long dstlen; 2160f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2161f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register SHA-1 */ 2162f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_hash(&sha1_desc) == -1) { 2163f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error registering SHA1\n"); 2164f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 2165f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2166f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2167f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* get index of SHA1 in hash descriptor table */ 2168f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project idx = find_hash("sha1"); 2169f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2170f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* we would make up our symmetric key in "key[]" here */ 2171f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2172f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* start the HMAC */ 2173f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = hmac_init(&hmac, idx, key, 16)) != CRYPT_OK) { 2174f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error setting up hmac: %s\n", error_to_string(err)); 2175f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 2176f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2177f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2178f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* process a few octets */ 2179f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if((err = hmac_process(&hmac, "hello", 5) != CRYPT_OK) { 2180f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error processing hmac: %s\n", error_to_string(err)); 2181f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 2182f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2183f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2184f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* get result (presumably to use it somehow...) */ 2185f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project dstlen = sizeof(dst); 2186f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = hmac_done(&hmac, dst, &dstlen)) != CRYPT_OK) { 2187f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error finishing hmac: %s\n", error_to_string(err)); 2188f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 2189f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2190f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("The hmac is %lu bytes long\n", dstlen); 2191f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2192f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* return */ 2193f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 2194f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 2195f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2196f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 2197f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2198f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{OMAC Support} 2199f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{OMAC} \index{CMAC} 2200f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectOMAC\footnote{\url{http://crypt.cis.ibaraki.ac.jp/omac/omac.html}}, which stands for \textit{One-Key CBC MAC} is an 2201f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectalgorithm which produces a Message Authentication Code (MAC) using only a block cipher such as AES. Note: OMAC has been standardized as 2202f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCMAC within NIST, for the purposes of this library OMAC and CMAC are synonymous. From an API standpoint, the OMAC routines work much like the 2203f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectHMAC routines. Instead, in this case a cipher is used instead of a hash. 2204f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2205f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo start an OMAC state you call 2206f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{omac\_init()} 2207f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2208f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint omac_init( omac_state *omac, 2209f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 2210f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 2211f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long keylen); 2212f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2213f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \textit{omac} parameter is the state for the OMAC algorithm. The \textit{cipher} parameter is the index into the cipher\_descriptor table 2214f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof the cipher\footnote{The cipher must have a 64 or 128 bit block size. Such as CAST5, Blowfish, DES, AES, Twofish, etc.} you 2215f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwish to use. The \textit{key} and \textit{keylen} parameters are the keys used to authenticate the data. 2216f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2217f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo send data through the algorithm call 2218f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{omac\_process()} 2219f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2220f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint omac_process( omac_state *state, 2221f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 2222f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen); 2223f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2224f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will send \textit{inlen} bytes from \textit{in} through the active OMAC state \textit{state}. Returns \textbf{CRYPT\_OK} if the 2225f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfunction succeeds. The function is not sensitive to the granularity of the data. For example, 2226f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2227f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2228f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectomac_process(&mystate, "hello", 5); 2229f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectomac_process(&mystate, " world", 6); 2230f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2231f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2232f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWould produce the same result as, 2233f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2234f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2235f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectomac_process(&mystate, "hello world", 11); 2236f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2237f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2238f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen you are done processing the message you can call the following to compute the message tag. 2239f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2240f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{omac\_done()} 2241f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2242f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint omac_done( omac_state *state, 2243f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 2244f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 2245f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2246f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich will terminate the OMAC and output the \textit{tag} (MAC) to \textit{out}. Note that unlike the HMAC and other code 2247f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{outlen} can be smaller than the default MAC size (for instance AES would make a 16-byte tag). Part of the OMAC 2248f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectspecification states that the output may be truncated. So if you pass in $outlen = 5$ and use AES as your cipher than 2249f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe output MAC code will only be five bytes long. If \textit{outlen} is larger than the default size it is set to the default 2250f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsize to show how many bytes were actually used. 2251f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2252f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSimilar to the HMAC code the file and memory functions are also provided. To OMAC a buffer of memory in one shot use the 2253f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfollowing function. 2254f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2255f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{omac\_memory()} 2256f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2257f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint omac_memory( 2258f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 2259f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 2260f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, unsigned long inlen, 2261f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen); 2262f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2263f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will compute the OMAC of \textit{inlen} bytes of \textit{in} using the key \textit{key} of length \textit{keylen} bytes and the cipher 2264f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectspecified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same 2265f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrules as omac\_done. 2266f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2267f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo OMAC a file use 2268f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{omac\_file()} 2269f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2270f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint omac_file( 2271f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 2272f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 2273f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const char *filename, 2274f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen); 2275f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2276f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2277f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich will OMAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes 2278f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with 2279f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe same rules as omac\_done. 2280f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2281f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo test if the OMAC code is working there is the following function: 2282f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{omac\_test()} 2283f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2284f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint omac_test(void); 2285f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2286f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. Some example code for using the 2287f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectOMAC system is given below. 2288f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2289f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 2290f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2291f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 2292f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 2293f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 2294f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int idx, err; 2295f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project omac_state omac; 2296f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char key[16], dst[MAXBLOCKSIZE]; 2297f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long dstlen; 2298f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2299f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register Rijndael */ 2300f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_cipher(&rijndael_desc) == -1) { 2301f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error registering Rijndael\n"); 2302f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 2303f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2304f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2305f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* get index of Rijndael in cipher descriptor table */ 2306f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project idx = find_cipher("rijndael"); 2307f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2308f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* we would make up our symmetric key in "key[]" here */ 2309f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2310f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* start the OMAC */ 2311f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = omac_init(&omac, idx, key, 16)) != CRYPT_OK) { 2312f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error setting up omac: %s\n", error_to_string(err)); 2313f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 2314f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2315f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2316f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* process a few octets */ 2317f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if((err = omac_process(&omac, "hello", 5) != CRYPT_OK) { 2318f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error processing omac: %s\n", error_to_string(err)); 2319f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 2320f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2321f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2322f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* get result (presumably to use it somehow...) */ 2323f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project dstlen = sizeof(dst); 2324f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = omac_done(&omac, dst, &dstlen)) != CRYPT_OK) { 2325f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error finishing omac: %s\n", error_to_string(err)); 2326f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 2327f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2328f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("The omac is %lu bytes long\n", dstlen); 2329f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2330f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* return */ 2331f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 2332f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 2333f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2334f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 2335f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2336f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{PMAC Support} 2337f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe PMAC\footnote{J.Black, P.Rogaway, \textit{A Block--Cipher Mode of Operation for Parallelizable Message Authentication}} 2338f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectprotocol is another MAC algorithm that relies solely on a symmetric-key block cipher. It uses essentially the same 2339f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAPI as the provided OMAC code. 2340f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2341f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectA PMAC state is initialized with the following. 2342f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2343f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pmac\_init()} 2344f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2345f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pmac_init( pmac_state *pmac, 2346f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 2347f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 2348f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long keylen); 2349f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2350f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich initializes the \textit{pmac} state with the given \textit{cipher} and \textit{key} of length \textit{keylen} bytes. The chosen cipher 2351f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmust have a 64 or 128 bit block size (e.x. AES). 2352f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2353f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo MAC data simply send it through the process function. 2354f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2355f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pmac\_process()} 2356f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2357f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pmac_process( pmac_state *state, 2358f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 2359f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen); 2360f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2361f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will process \textit{inlen} bytes of \textit{in} in the given \textit{state}. The function is not sensitive to the granularity of the 2362f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdata. For example, 2363f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2364f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2365f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpmac_process(&mystate, "hello", 5); 2366f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpmac_process(&mystate, " world", 6); 2367f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2368f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2369f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWould produce the same result as, 2370f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2371f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2372f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpmac_process(&mystate, "hello world", 11); 2373f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2374f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2375f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen a complete message has been processed the following function can be called to compute the message tag. 2376f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2377f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pmac\_done()} 2378f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2379f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pmac_done( pmac_state *state, 2380f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 2381f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 2382f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2383f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 2384f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthan the size of the tag it is set to the amount of bytes stored in \textit{out}. 2385f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2386f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSimilar to the OMAC code the file and memory functions are also provided. To PMAC a buffer of memory in one shot use the 2387f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfollowing function. 2388f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2389f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pmac\_memory()} 2390f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2391f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pmac_memory( 2392f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 2393f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 2394f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, unsigned long inlen, 2395f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen); 2396f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2397f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will compute the PMAC of \textit{msglen} bytes of \textit{msg} using the key \textit{key} of length \textit{keylen} bytes, and the cipher 2398f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectspecified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with the same 2399f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrules as pmac\_done(). 2400f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2401f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo PMAC a file use 2402f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pmac\_file()} 2403f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2404f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pmac_file( 2405f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 2406f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 2407f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const char *filename, 2408f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen); 2409f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2410f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2411f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich will PMAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, 2412f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table. It will store the MAC in \textit{out} with 2413f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe same rules as pmac\_done(). 2414f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2415f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo test if the PMAC code is working there is the following function: 2416f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pmac\_test()} 2417f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2418f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pmac_test(void); 2419f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2420f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. 2421f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2422f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Pelican MAC} 2423f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectPelican 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 2424f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrate 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 2425f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectas it calls AES directly. 2426f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2427f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pelican\_init()} 2428f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2429f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pelican_init( pelican_state *pelmac, 2430f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 2431f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long keylen); 2432f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2433f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will initialize the Pelican state with the given AES key. Once this has been done you can begin processing data. 2434f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2435f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pelican\_process()} 2436f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2437f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pelican_process( pelican_state *pelmac, 2438f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 2439f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen); 2440f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2441f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 2442f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectroutine more efficient but you may pass in any length of text. You can call this function as many times as required to process 2443f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectan entire message. 2444f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2445f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pelican\_done()} 2446f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2447f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pelican_done(pelican_state *pelmac, unsigned char *out); 2448f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2449f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis terminates a Pelican MAC and writes the 16--octet tag to \textit{out}. 2450f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2451f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Example} 2452f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2453f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2454f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 2455f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 2456f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 2457f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project pelican_state pelstate; 2458f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char key[32], tag[16]; 2459f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 2460f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2461f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* somehow initialize a key */ 2462f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2463f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* initialize pelican mac */ 2464f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = pelican_init(&pelstate, /* the state */ 2465f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project key, /* user key */ 2466f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 32 /* key length in octets */ 2467f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project )) != CRYPT_OK) { 2468f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error initializing Pelican: %s", 2469f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project error_to_string(err)); 2470f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 2471f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2472f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2473f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* MAC some data */ 2474f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = pelican_process(&pelstate, /* the state */ 2475f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project "hello world", /* data to mac */ 2476f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 11 /* length of data */ 2477f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project )) != CRYPT_OK) { 2478f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error processing Pelican: %s", 2479f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project error_to_string(err)); 2480f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 2481f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2482f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2483f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* Terminate the MAC */ 2484f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = pelican_done(&pelstate,/* the state */ 2485f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project tag /* where to store the tag */ 2486f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project )) != CRYPT_OK) { 2487f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error terminating Pelican: %s", 2488f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project error_to_string(err)); 2489f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 2490f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2491f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2492f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* tag[0..15] has the MAC output now */ 2493f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2494f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_SUCCESS; 2495f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 2496f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2497f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2498f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{XCBC-MAC} 2499f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs of LibTomCrypt v1.15, XCBC-MAC (RFC 3566) has been provided to support TLS encryption suites. Like OMAC, it computes a message authentication code 2500f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectby 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 2501f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectinitialized with the following function: 2502f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2503f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{xcbc\_init()} 2504f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2505f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint xcbc_init( xcbc_state *xcbc, 2506f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 2507f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 2508f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long keylen); 2509f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2510f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2511f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will initialize the XCBC--MAC state \textit{xcbc}, with the key specified in \textit{key} of length \textit{keylen} octets. The cipher indicated 2512f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectby the \textit{cipher} index can be either a 64 or 128--bit block cipher. This will return \textbf{CRYPT\_OK} on success. 2513f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2514f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo process data through XCBC--MAC use the following function: 2515f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2516f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{xcbc\_process()} 2517f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2518f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint xcbc_process( xcbc_state *state, 2519f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 2520f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen); 2521f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2522f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2523f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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, 2524f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe granularity of the input is not important but the order is. This will return \textbf{CRYPT\_OK} on success. 2525f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2526f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo compute the MAC tag value use the following function: 2527f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2528f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{xcbc\_done()} 2529f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2530f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint xcbc_done( xcbc_state *state, 2531f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 2532f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 2533f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2534f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2535f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 2536f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectspecifies 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. 2537f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2538f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectHelper functions are provided to make parsing memory buffers and files easier. The following functions are provided: 2539f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2540f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{xcbc\_memory()} 2541f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2542f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint xcbc_memory( 2543f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 2544f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 2545f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, unsigned long inlen, 2546f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen); 2547f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2548f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 2549f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectspecified 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(). 2550f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2551f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo xcbc a file use 2552f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{xcbc\_file()} 2553f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2554f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint xcbc_file( 2555f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 2556f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 2557f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const char *filename, 2558f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen); 2559f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2560f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2561f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich 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 2562f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectspecified 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(). 2563f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2564f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2565f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo test XCBC--MAC for RFC 3566 compliance use the following function: 2566f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2567f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{xcbc\_test()} 2568f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2569f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint xcbc_test(void); 2570f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2571f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2572f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will return \textbf{CRYPT\_OK} on success. This requires the AES or Rijndael descriptor be previously registered, otherwise, it will return 2573f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textbf{CRYPT\_NOP}. 2574f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2575f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{F9--MAC} 2576f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 2577f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwith other ciphers. For LibTomCrypt, the F9--MAC code can use any cipher. 2578f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2579f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Usage Notice} 2580f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectF9--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 2581f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbit 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 2582f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecta single 0x40 or 0xC0 byte followed by enough 0x00 bytes to make the message proper multiple. 2583f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2584f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIf 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 2585f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwith F9--MAC. 2586f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2587f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{F9--MAC Functions} 2588f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectA F9--MAC state is initialized with the following function: 2589f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{f9\_init()} 2590f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2591f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint f9_init( f9_state *f9, 2592f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 2593f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, 2594f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long keylen); 2595f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2596f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2597f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will initialize the F9--MAC state \textit{f9}, with the key specified in \textit{key} of length \textit{keylen} octets. The cipher indicated 2598f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectby the \textit{cipher} index can be either a 64 or 128--bit block cipher. This will return \textbf{CRYPT\_OK} on success. 2599f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2600f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo process data through F9--MAC use the following function: 2601f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{f9\_process()} 2602f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2603f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint f9_process( f9_state *state, 2604f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 2605f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen); 2606f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2607f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2608f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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, 2609f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe granularity of the input is not important but the order is. This will return \textbf{CRYPT\_OK} on success. 2610f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2611f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo compute the MAC tag value use the following function: 2612f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2613f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{f9\_done()} 2614f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2615f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint f9_done( f9_state *state, 2616f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 2617f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 2618f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2619f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2620f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 2621f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectspecifies 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 2622f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textbf{CRYPT\_OK} on success. 2623f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2624f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectHelper functions are provided to make parsing memory buffers and files easier. The following functions are provided: 2625f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2626f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{f9\_memory()} 2627f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2628f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint f9_memory( 2629f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 2630f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 2631f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, unsigned long inlen, 2632f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen); 2633f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2634f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 2635f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectspecified 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(). 2636f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2637f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo F9--MAC a file use 2638f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{f9\_file()} 2639f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2640f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint f9_file( 2641f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int cipher, 2642f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 2643f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const char *filename, 2644f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen); 2645f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2646f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2647f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich 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 2648f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectspecified 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(). 2649f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2650f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2651f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo test f9--MAC for RFC 3566 compliance use the following function: 2652f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2653f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{f9\_test()} 2654f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2655f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint f9_test(void); 2656f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2657f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2658f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will return \textbf{CRYPT\_OK} on success. This requires the AES or Rijndael descriptor be previously registered, otherwise, it will return 2659f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textbf{CRYPT\_NOP}. 2660f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2661f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{Pseudo-Random Number Generators} 2662f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Core Functions} 2663f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe library provides an array of core functions for Pseudo-Random Number Generators (PRNGs) as well. A cryptographic PRNG is 2664f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectused to expand a shorter bit string into a longer bit string. PRNGs are used wherever random data is required such as Public Key (PK) 2665f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectkey generation. There is a universal structure called \textit{prng\_state}. To initialize a PRNG call: 2666f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{PRNG start} 2667f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2668f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_start(prng_state *prng); 2669f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2670f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2671f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will setup the PRNG for future use and not seed it. In order for the PRNG to be cryptographically useful you must give it 2672f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectentropy. Ideally you'd have some OS level source to tap like in UNIX. To add entropy to the PRNG call: 2673f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{PRNG add\_entropy} 2674f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2675f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_add_entropy(const unsigned char *in, 2676f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 2677f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng); 2678f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2679f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich returns {\bf CRYPT\_OK} if the entropy was accepted. Once you think you have enough entropy you call another 2680f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfunction to put the entropy into action. 2681f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{PRNG ready} 2682f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2683f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_ready(prng_state *prng); 2684f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2685f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2686f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich returns {\bf CRYPT\_OK} if it is ready. Finally to actually read bytes call: 2687f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{PRNG read} 2688f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2689f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectunsigned long XXX_read(unsigned char *out, 2690f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long outlen, 2691f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng); 2692f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2693f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2694f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich returns the number of bytes read from the PRNG. When you are finished with a PRNG state you call 2695f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe following. 2696f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2697f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{PRNG done} 2698f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2699f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectvoid XXX_done(prng_state *prng); 2700f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2701f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2702f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will terminate a PRNG state and free any memory (if any) allocated. To export a PRNG state 2703f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectso that you can later resume the PRNG call the following. 2704f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2705f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{PRNG export} 2706f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2707f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_export(unsigned char *out, 2708f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 2709f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng); 2710f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2711f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2712f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will write a \textit{PRNG state} to the buffer \textit{out} of length \textit{outlen} bytes. The idea of 2713f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe export is meant to be used as a \textit{seed file}. That is, when the program starts up there will not likely 2714f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbe that much entropy available. To import a state to seed a PRNG call the following function. 2715f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2716f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{PRNG import} 2717f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2718f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_import(const unsigned char *in, 2719f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 2720f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng); 2721f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2722f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2723f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will call the start and add\_entropy functions of the given PRNG. It will use the state in 2724f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{in} of length \textit{inlen} as the initial seed. You must pass the same seed length as was exported 2725f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectby the corresponding export function. 2726f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2727f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote that importing a state will not \textit{resume} the PRNG from where it left off. That is, if you export 2728f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecta state, emit (say) 8 bytes and then import the previously exported state the next 8 bytes will not 2729f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectspecifically equal the 8 bytes you generated previously. 2730f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2731f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen a program is first executed the normal course of operation is: 2732f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2733f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{enumerate} 2734f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Gather entropy from your sources for a given period of time or number of events. 2735f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item Start, use your entropy via add\_entropy and ready the PRNG yourself. 2736f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{enumerate} 2737f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2738f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen your program is finished you simply call the export function and save the state to a medium (disk, 2739f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectflash memory, etc). The next time your application starts up you can detect the state, feed it to the 2740f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectimport function and go on your way. It is ideal that (as soon as possible) after start up you export a 2741f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfresh state. This helps in the case that the program aborts or the machine is powered down without 2742f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbeing given a chance to exit properly. 2743f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2744f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote that even if you have a state to import it is important to add new entropy to the state. However, 2745f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthere is less pressure to do so. 2746f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2747f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo test a PRNG for operational conformity call the following functions. 2748f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2749f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{PRNG test} 2750f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2751f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint XXX_test(void); 2752f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2753f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2754f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will return \textbf{CRYPT\_OK} if PRNG is operating properly. 2755f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2756f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Remarks} 2757f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2758f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt is possible to be adding entropy and reading from a PRNG at the same time. For example, if you first seed the PRNG 2759f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand call ready() you can now read from it. You can also keep adding new entropy to it. The new entropy will not be used 2760f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectin the PRNG until ready() is called again. This allows the PRNG to be used and re-seeded at the same time. No real error 2761f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectchecking is guaranteed to see if the entropy is sufficient, or if the PRNG is even in a ready state before reading. 2762f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2763f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Example} 2764f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectBelow is a simple snippet to read 10 bytes from Yarrow. It is important to note that this snippet is {\bf NOT} secure since 2765f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe entropy added is not random. 2766f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2767f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2768f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 2769f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 2770f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 2771f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state prng; 2772f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char buf[10]; 2773f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 2774f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2775f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* start it */ 2776f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = yarrow_start(&prng)) != CRYPT_OK) { 2777f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Start error: %s\n", error_to_string(err)); 2778f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2779f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* add entropy */ 2780f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = yarrow_add_entropy("hello world", 11, &prng)) 2781f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project != CRYPT_OK) { 2782f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Add_entropy error: %s\n", error_to_string(err)); 2783f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2784f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* ready and read */ 2785f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = yarrow_ready(&prng)) != CRYPT_OK) { 2786f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Ready error: %s\n", error_to_string(err)); 2787f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2788f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Read %lu bytes from yarrow\n", 2789f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project yarrow_read(buf, sizeof(buf), &prng)); 2790f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 2791f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 2792f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2793f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2794f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{PRNG Descriptors} 2795f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{PRNG Descriptor} 2796f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectPRNGs have descriptors that allow plugin driven functions to be created using PRNGs. The plugin descriptors are stored in the structure \textit{prng\_descriptor}. The 2797f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectformat of an element is: 2798f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2799f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstruct _prng_descriptor { 2800f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project char *name; 2801f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int export_size; /* size in bytes of exported state */ 2802f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2803f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*start) (prng_state *); 2804f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2805f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*add_entropy)(const unsigned char *, unsigned long, 2806f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *); 2807f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2808f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*ready) (prng_state *); 2809f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2810f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long (*read)(unsigned char *, unsigned long len, 2811f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *); 2812f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2813f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void (*done)(prng_state *); 2814f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2815f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*export)(unsigned char *, unsigned long *, prng_state *); 2816f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2817f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*import)(const unsigned char *, unsigned long, prng_state *); 2818f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2819f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*test)(void); 2820f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project}; 2821f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2822f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2823f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo find a PRNG in the descriptor table the following function can be used: 2824f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{find\_prng()} 2825f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2826f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint find_prng(const char *name); 2827f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2828f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 2829f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe index into the descriptor table. 2830f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2831f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectJust 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. 2832f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThey are the following: 2833f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{register\_prng()} \index{unregister\_prng()} 2834f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2835f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint register_prng(const struct _prng_descriptor *prng); 2836f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint unregister_prng(const struct _prng_descriptor *prng); 2837f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2838f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2839f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 2840f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdescriptor 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 2841f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwill return \textbf{CRYPT\_OK} if the PRNG was found and removed. Otherwise, it returns \textbf{CRYPT\_ERROR}. 2842f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2843f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{PRNGs Provided} 2844f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{figure}[here] 2845f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{center} 2846f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 2847f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{tabular}{|c|c|l|} 2848f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline \textbf{Name} & \textbf{Descriptor} & \textbf{Usage} \\ 2849f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline Yarrow & yarrow\_desc & Fast short-term PRNG \\ 2850f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline Fortuna & fortuna\_desc & Fast long-term PRNG (recommended) \\ 2851f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline RC4 & rc4\_desc & Stream Cipher \\ 2852f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline SOBER-128 & sober128\_desc & Stream Cipher (also very fast PRNG) \\ 2853f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline 2854f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{tabular} 2855f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 2856f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{center} 2857f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\caption{List of Provided PRNGs} 2858f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{figure} 2859f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2860f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Yarrow} 2861f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectYarrow is fast PRNG meant to collect an unspecified amount of entropy from sources 2862f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project(keyboard, mouse, interrupts, etc), and produce an unbounded string of random bytes. 2863f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2864f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{Note:} This PRNG is still secure for most tasks but is no longer recommended. Users 2865f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectshould use Fortuna instead. 2866f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2867f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Fortuna} 2868f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2869f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectFortuna is a fast attack tolerant and more thoroughly designed PRNG suitable for long term 2870f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectusage. It is faster than the default implementation of Yarrow\footnote{Yarrow has been implemented 2871f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto work with most cipher and hash combos based on which you have chosen to build into the library.} while 2872f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectproviding more security. 2873f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2874f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectFortuna is slightly less flexible than Yarrow in the sense that it only works with the AES block cipher 2875f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand SHA--256 hash function. Technically, Fortuna will work with any block cipher that accepts a 256--bit 2876f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectkey, and any hash that produces at least a 256--bit output. However, to make the implementation simpler 2877f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectit has been fixed to those choices. 2878f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2879f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectFortuna is more secure than Yarrow in the sense that attackers who learn parts of the entropy being 2880f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectadded to the PRNG learn far less about the state than that of Yarrow. Without getting into to many 2881f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdetails Fortuna has the ability to recover from state determination attacks where the attacker starts 2882f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto learn information from the PRNGs output about the internal state. Yarrow on the other hand, cannot 2883f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrecover from that problem until new entropy is added to the pool and put to use through the ready() function. 2884f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2885f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{RC4} 2886f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2887f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectRC4 is an old stream cipher that can also double duty as a PRNG in a pinch. You key RC4 by 2888f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcalling add\_entropy(), and setup the key by calling ready(). You can only add up to 256 bytes via 2889f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectadd\_entropy(). 2890f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2891f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen you read from RC4, the output is XOR'ed against your buffer you provide. In this manner, you can use rc4\_read() 2892f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectas an encrypt (and decrypt) function. 2893f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2894f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectYou really should not use RC4. This is not because RC4 is weak, (though biases are known to exist) but simply due to 2895f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe fact that faster alternatives exist. 2896f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2897f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{SOBER-128} 2898f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2899f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSOBER--128 is a stream cipher designed by the QUALCOMM Australia team. Like RC4, you key it by 2900f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcalling add\_entropy(). There is no need to call ready() for this PRNG as it does not do anything. 2901f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2902f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote: this cipher has several oddities about how it operates. The first call to add\_entropy() sets the cipher's key. 2903f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectEvery other time call to the add\_entropy() function sets the cipher's IV variable. The IV mechanism allows you to 2904f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectencrypt several messages with the same key, and not re--use the same key material. 2905f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2906f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectUnlike Yarrow and Fortuna, all of the entropy (and hence security) of this algorithm rests in the data 2907f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectyou pass it on the \textbf{first} call to add\_entropy(). All buffers sent to add\_entropy() must have a length 2908f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthat is a multiple of four bytes. 2909f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2910f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLike RC4, the output of SOBER--128 is XOR'ed against the buffer you provide it. In this manner, you can use 2911f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsober128\_read() as an encrypt (and decrypt) function. 2912f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2913f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSince SOBER-128 has a fixed keying scheme, and is very fast (faster than RC4) the ideal usage of SOBER-128 is to 2914f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectkey it from the output of Fortuna (or Yarrow), and use it to encrypt messages. It is also ideal for 2915f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsimulations which need a high quality (and fast) stream of bytes. 2916f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2917f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Example Usage} 2918f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 2919f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2920f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 2921f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 2922f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 2923f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state prng; 2924f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char buf[32]; 2925f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 2926f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2927f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = rc4_start(&prng)) != CRYPT_OK) { 2928f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("RC4 init error: %s\n", error_to_string(err)); 2929f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project exit(-1); 2930f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2931f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2932f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* use "key" as the key */ 2933f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = rc4_add_entropy("key", 3, &prng)) != CRYPT_OK) { 2934f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("RC4 add entropy error: %s\n", error_to_string(err)); 2935f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project exit(-1); 2936f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2937f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2938f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* setup RC4 for use */ 2939f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = rc4_ready(&prng)) != CRYPT_OK) { 2940f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("RC4 ready error: %s\n", error_to_string(err)); 2941f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project exit(-1); 2942f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2943f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2944f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* encrypt buffer */ 2945f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project strcpy(buf,"hello world"); 2946f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (rc4_read(buf, 11, &prng) != 11) { 2947f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("RC4 read error\n"); 2948f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project exit(-1); 2949f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 2950f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 2951f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 2952f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2953f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 2954f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo decrypt you have to do the exact same steps. 2955f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2956f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{The Secure RNG} 2957f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Secure RNG} 2958f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAn 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 2959f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectby performing some computation on fresh input bits. Possibly the hardest thing to get correctly in a cryptosystem is the 2960f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectPRNG. Computers are deterministic that try hard not to stray from pre--determined paths. This makes gathering entropy needed to seed a PRNG 2961f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecta hard task. 2962f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2963f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere is one small function that may help on certain platforms: 2964f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rng\_get\_bytes()} 2965f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2966f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectunsigned long rng_get_bytes( 2967f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *buf, 2968f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len, 2969f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void (*callback)(void)); 2970f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2971f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2972f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich will try one of three methods of getting random data. The first is to open the popular \textit{/dev/random} device which 2973f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecton 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.}. 2974f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe second method is to try the Microsoft Cryptographic Service Provider, and read the RNG. The third method is an ANSI C 2975f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectclock 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 2976f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectused 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 2977f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbytes 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 2978f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectany RNG source. There is a function to help setup a PRNG as well: 2979f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rng\_make\_prng()} 2980f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2981f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rng_make_prng( int bits, 2982f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int wprng, 2983f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 2984f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void (*callback)(void)); 2985f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 2986f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will try to initialize the prng with a state of at least \textit{bits} of entropy. The \textit{callback} parameter works much like 2987f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe callback in \textit{rng\_get\_bytes()}. It is highly recommended that you use this function to setup your PRNGs unless you have a 2988f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectplatform where the RNG does not work well. Example usage of this function is given below: 2989f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2990f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 2991f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 2992f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 2993f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 2994f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 2995f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key mykey; 2996f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state prng; 2997f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 2998f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 2999f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register yarrow */ 3000f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_prng(&yarrow_desc) == -1) { 3001f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error registering Yarrow\n"); 3002f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 3003f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 3004f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3005f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* setup the PRNG */ 3006f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = rng_make_prng(128, find_prng("yarrow"), &prng, NULL)) 3007f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project != CRYPT_OK) { 3008f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error setting up PRNG, %s\n", error_to_string(err)); 3009f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 3010f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 3011f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3012f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* make a 192-bit ECC key */ 3013f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = ecc_make_key(&prng, find_prng("yarrow"), 24, &mykey)) 3014f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project != CRYPT_OK) { 3015f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error making key: %s\n", error_to_string(err)); 3016f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 3017f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 3018f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 3019f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 3020f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3021f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 3022f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3023f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{The Secure PRNG Interface} 3024f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt is possible to access the secure RNG through the PRNG interface, and in turn use it within dependent functions such 3025f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectas the PK API. This simplifies the cryptosystem on platforms where the secure RNG is fast. The secure PRNG never 3026f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrequires to be started, that is you need not call the start, add\_entropy, or ready functions. For example, consider 3027f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe previous example using this PRNG. 3028f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3029f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 3030f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3031f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 3032f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 3033f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 3034f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key mykey; 3035f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err; 3036f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3037f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register SPRNG */ 3038f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_prng(&sprng_desc) == -1) { 3039f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error registering SPRNG\n"); 3040f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 3041f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 3042f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3043f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* make a 192-bit ECC key */ 3044f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = ecc_make_key(NULL, find_prng("sprng"), 24, &mykey)) 3045f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project != CRYPT_OK) { 3046f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error making key: %s\n", error_to_string(err)); 3047f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return -1; 3048f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 3049f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return 0; 3050f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 3051f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3052f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 3053f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3054f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{RSA Public Key Cryptography} 3055f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3056f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Introduction} 3057f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectRSA wrote the PKCS \#1 specifications which detail RSA Public Key Cryptography. In the specifications are 3058f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpadding algorithms for encryption and signatures. The standard includes the \textit{v1.5} and \textit{v2.1} algorithms. 3059f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo simplify matters a little the v2.1 encryption and signature padding algorithms are called OAEP and PSS respectively. 3060f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3061f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{PKCS \#1 Padding} 3062f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectPKCS \#1 v1.5 padding is so simple that both signature and encryption padding are performed by the same function. Note: the 3063f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsignature padding does \textbf{not} include the ASN.1 padding required. That is performed by the rsa\_sign\_hash\_ex() function 3064f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdocumented later on in this chapter. 3065f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3066f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{PKCS \#1 v1.5 Encoding} 3067f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe following function performs PKCS \#1 v1.5 padding: 3068f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pkcs\_1\_v1\_5\_encode()} 3069f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3070f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pkcs_1_v1_5_encode( 3071f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *msg, 3072f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long msglen, 3073f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int block_type, 3074f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long modulus_bitlen, 3075f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 3076f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int prng_idx, 3077f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3078f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 3079f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3080f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3081f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will encode the message pointed to by \textit{msg} of length \textit{msglen} octets. The \textit{block\_type} parameter must be set to 3082f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\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} 3083f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectparameter 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 3084f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectlonger than the modulus which helps allocate the correct output buffer size. 3085f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3086f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectOnly 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. 3087f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3088f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{PKCS \#1 v1.5 Decoding} 3089f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe following function performs PKCS \#1 v1.5 de--padding: 3090f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pkcs\_1\_v1\_5\_decode()} 3091f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3092f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pkcs_1_v1_5_decode( 3093f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *msg, 3094f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long msglen, 3095f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int block_type, 3096f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long modulus_bitlen, 3097f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3098f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3099f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int *is_valid); 3100f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3101f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{LTC\_PKCS\_1\_EME} \index{LTC\_PKCS\_1\_EMSA} 3102f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 3103f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\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 3104f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textbf{LTC\_PKCS\_1\_EME} or \textbf{LTC\_PKCS\_1\_EMSA} depending on whether encryption or signature padding is being removed. 3105f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3106f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{PKCS \#1 v2.1 Encryption} 3107f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectPKCS \#1 RSA Encryption amounts to OAEP padding of the input message followed by the modular exponentiation. As far as this portion of 3108f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe library is concerned we are only dealing with th OAEP padding of the message. 3109f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3110f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{OAEP Encoding} 3111f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3112f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe following function performs PKCS \#1 v2.1 encryption padding: 3113f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3114f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pkcs\_1\_oaep\_encode()} 3115f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{alltt} 3116f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pkcs_1_oaep_encode( 3117f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *msg, 3118f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long msglen, 3119f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *lparam, 3120f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long lparamlen, 3121f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long modulus_bitlen, 3122f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 3123f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int prng_idx, 3124f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 3125f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3126f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 3127f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{alltt} 3128f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3129f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis accepts \textit{msg} as input of length \textit{msglen} which will be OAEP padded. The \textit{lparam} variable is an additional system specific 3130f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttag that can be applied to the encoding. This is useful to identify which system encoded the message. If no variance is desired then 3131f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{lparam} can be set to \textbf{NULL}. 3132f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3133f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectOAEP encoding requires the length of the modulus in bits in order to calculate the size of the output. This is passed as the parameter 3134f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\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 3135f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectused 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 3136f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project sized input message. \textit{prng\_idx} and \textit{prng} are the random number generator arguments required to randomize the padding process. 3137f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe padded message is stored in \textit{out} along with the length in \textit{outlen}. 3138f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3139f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIf $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 3140f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$m - 2h - 2$. For example, with a $1024$--bit RSA key and SHA--1 as the hash the maximum payload is $86$ bytes. 3141f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3142f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote that when the message is padded it still has not been RSA encrypted. You must pass the output of this function to 3143f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrsa\_exptmod() to encrypt it. 3144f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3145f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{OAEP Decoding} 3146f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3147f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pkcs\_1\_oaep\_decode()} 3148f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{alltt} 3149f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pkcs_1_oaep_decode( 3150f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *msg, 3151f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long msglen, 3152f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *lparam, 3153f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long lparamlen, 3154f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long modulus_bitlen, 3155f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 3156f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3157f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3158f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int *res); 3159f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{alltt} 3160f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3161f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function decodes an OAEP encoded message and outputs the original message that was passed to the OAEP encoder. \textit{msg} is the 3162f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectoutput 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 3163f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmatch what was used during encoding this function will not decode the packet. \textit{modulus\_bitlen} is the size of the RSA modulus in bits 3164f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand must match what was used during encoding. Similarly the \textit{hash\_idx} index into the hash descriptor table must match what was used 3165f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectduring encoding. 3166f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3167f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIf the function succeeds it decodes the OAEP encoded message into \textit{out} of length \textit{outlen} and stores a 3168f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$1$ in \textit{res}. If the packet is invalid it stores $0$ in \textit{res} and if the function fails for another reason 3169f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectit returns an error code. 3170f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3171f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{PKCS \#1 Digital Signatures} 3172f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3173f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{PSS Encoding} 3174f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectPSS encoding is the second half of the PKCS \#1 standard which is padding to be applied to messages that are signed. 3175f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3176f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pkcs\_1\_pss\_encode()} 3177f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{alltt} 3178f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pkcs_1_pss_encode( 3179f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *msghash, 3180f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long msghashlen, 3181f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long saltlen, 3182f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 3183f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int prng_idx, 3184f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 3185f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long modulus_bitlen, 3186f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3187f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 3188f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{alltt} 3189f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3190f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function assumes the message to be PSS encoded has previously been hashed. The input hash \textit{msghash} is of length 3191f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{msghashlen}. PSS allows a variable length random salt (it can be zero length) to be introduced in the signature process. 3192f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\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 3193f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectnumber generator information required for the salt. 3194f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3195f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSimilar 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 3196f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof the modulus $h$ the length of the hash output (in octets) then there can be $m - h - 2$ bytes of salt. 3197f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3198f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function does not actually sign the data it merely pads the hash of a message so that it can be processed by rsa\_exptmod(). 3199f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3200f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{PSS Decoding} 3201f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3202f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo decode a PSS encoded signature block you have to use the following. 3203f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3204f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pkcs\_1\_pss\_decode()} 3205f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{alltt} 3206f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pkcs_1_pss_decode( 3207f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *msghash, 3208f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long msghashlen, 3209f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *sig, 3210f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long siglen, 3211f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long saltlen, 3212f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 3213f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long modulus_bitlen, 3214f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int *res); 3215f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{alltt} 3216f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will decode the PSS encoded message in \textit{sig} of length \textit{siglen} and compare it to values in \textit{msghash} of length 3217f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\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, 3218f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectit is set to zero. The rest of the parameters are as in the PSS encode call. 3219f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3220f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt's important to use the same \textit{saltlen} and hash for both encoding and decoding as otherwise the procedure will not work. 3221f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3222f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{RSA Key Operations} 3223f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Background} 3224f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3225f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectRSA is a public key algorithm that is based on the inability to find the \textit{e-th} root modulo a composite of unknown 3226f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfactorization. Normally the difficulty of breaking RSA is associated with the integer factoring problem but they are 3227f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectnot strictly equivalent. 3228f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3229f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe system begins with with two primes $p$ and $q$ and their product $N = pq$. The order or \textit{Euler totient} of the 3230f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmultiplicative sub-group formed modulo $N$ is given as $\phi(N) = (p - 1)(q - 1)$ which can be reduced to 3231f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$\mbox{lcm}(p - 1, q - 1)$. The public key consists of the composite $N$ and some integer $e$ such that 3232f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$\mbox{gcd}(e, \phi(N)) = 1$. The private key consists of the composite $N$ and the inverse of $e$ modulo $\phi(N)$ 3233f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectoften simply denoted as $de \equiv 1\mbox{ }(\mbox{mod }\phi(N))$. 3234f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3235f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectA person who wants to encrypt with your public key simply forms an integer (the plaintext) $M$ such that 3236f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$1 < M < N-2$ and computes the ciphertext $C = M^e\mbox{ }(\mbox{mod }N)$. Since finding the inverse exponent $d$ 3237f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectgiven only $N$ and $e$ appears to be intractable only the owner of the private key can decrypt the ciphertext and compute 3238f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$C^d \equiv \left (M^e \right)^d \equiv M^1 \equiv M\mbox{ }(\mbox{mod }N)$. Similarly the owner of the private key 3239f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcan sign a message by \textit{decrypting} it. Others can verify it by \textit{encrypting} it. 3240f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3241f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCurrently RSA is a difficult system to cryptanalyze provided that both primes are large and not close to each other. 3242f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIdeally $e$ should be larger than $100$ to prevent direct analysis. For example, if $e$ is three and you do not pad 3243f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe plaintext to be encrypted than it is possible that $M^3 < N$ in which case finding the cube-root would be trivial. 3244f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe most often suggested value for $e$ is $65537$ since it is large enough to make such attacks impossible and also well 3245f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdesigned for fast exponentiation (requires 16 squarings and one multiplication). 3246f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3247f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt is important to pad the input to RSA since it has particular mathematical structure. For instance 3248f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$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 3249f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto have a forged signature for. Simply get the signatures for $M_1$ and $M_2$ on their own and multiply the result 3250f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttogether. Similar tricks can be used to deduce plaintexts from ciphertexts. It is important not only to sign 3251f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe hash of documents only but also to pad the inputs with data to remove such structure. 3252f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3253f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{RSA Key Generation} 3254f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3255f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectFor RSA routines a single \textit{rsa\_key} structure is used. To make a new RSA key call: 3256f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_make\_key()} 3257f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3258f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rsa_make_key(prng_state *prng, 3259f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int wprng, 3260f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int size, 3261f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project long e, 3262f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 3263f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3264f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3265f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhere \textit{wprng} is the index into the PRNG descriptor array. The \textit{size} parameter is the size in bytes of the RSA modulus desired. 3266f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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 3267f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttrivial math attacks, and not super slow. The \textit{key} parameter is where the constructed key is placed. All keys must be at 3268f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectleast 128 bytes, and no more than 512 bytes in size (\textit{that is from 1024 to 4096 bits}). 3269f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3270f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_free()} 3271f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote: the \textit{rsa\_make\_key()} function allocates memory at run--time when you make the key. Make sure to call 3272f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{rsa\_free()} (see below) when you are finished with the key. If \textit{rsa\_make\_key()} fails it will automatically 3273f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfree the memory allocated. 3274f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3275f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{PK\_PRIVATE} \index{PK\_PUBLIC} 3276f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere are two types of RSA keys. The types are {\bf PK\_PRIVATE} and {\bf PK\_PUBLIC}. The first type is a private 3277f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectRSA 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 3278f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectPK\_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. 3279f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt takes the form of a RSAPublicKey (PKCS \#1 compliant). 3280f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3281f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{RSA Exponentiation} 3282f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo do raw work with the RSA function, that is without padding, use the following function: 3283f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_exptmod()} 3284f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3285f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rsa_exptmod(const unsigned char *in, 3286f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3287f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3288f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3289f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int which, 3290f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 3291f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3292f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 3293f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectin \textit{out} and the size of the result in \textit{outlen}. \textit{which} is set to {\bf PK\_PUBLIC} to use \textit{e} 3294f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project(i.e. for encryption/verifying) and set to {\bf PK\_PRIVATE} to use \textit{d} as the exponent (i.e. for decrypting/signing). 3295f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3296f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote: 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. 3297f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3298f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{RSA Key Encryption} 3299f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNormally RSA is used to encrypt short symmetric keys which are then used in block ciphers to encrypt a message. 3300f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo facilitate encrypting short keys the following functions have been provided. 3301f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3302f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_encrypt\_key()} 3303f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3304f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rsa_encrypt_key( 3305f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 3306f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3307f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3308f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3309f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *lparam, 3310f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long lparamlen, 3311f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 3312f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int prng_idx, 3313f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 3314f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 3315f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3316f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function will OAEP pad \textit{in} of length \textit{inlen} bytes, RSA encrypt it, and store the ciphertext 3317f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectin \textit{out} of length \textit{outlen} octets. The \textit{lparam} and \textit{lparamlen} are the same parameters you would pass 3318f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto \index{pkcs\_1\_oaep\_encode()} pkcs\_1\_oaep\_encode(). 3319f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3320f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Extended Encryption} 3321f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs 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 3322f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectencryption function: 3323f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3324f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_encrypt\_key\_ex()} 3325f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3326f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rsa_encrypt_key_ex( 3327f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 3328f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3329f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3330f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3331f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *lparam, 3332f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long lparamlen, 3333f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 3334f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int prng_idx, 3335f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 3336f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int padding, 3337f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 3338f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3339f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3340f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{LTC\_PKCS\_1\_OAEP} \index{LTC\_PKCS\_1\_V1\_5} 3341f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe parameters are all the same as for rsa\_encrypt\_key() except for the addition of the \textit{padding} parameter. It must be set to 3342f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textbf{LTC\_PKCS\_1\_V1\_5} to perform v1.5 encryption, or set to \textbf{LTC\_PKCS\_1\_OAEP} to perform v2.1 encryption. 3343f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3344f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen performing v1.5 encryption, the hash and lparam parameters are totally ignored and can be set to \textbf{NULL} or zero (respectively). 3345f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3346f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{RSA Key Decryption} 3347f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_decrypt\_key()} 3348f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3349f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rsa_decrypt_key( 3350f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 3351f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3352f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3353f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3354f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *lparam, 3355f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long lparamlen, 3356f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 3357f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int *stat, 3358f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 3359f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3360f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function will RSA decrypt \textit{in} of length \textit{inlen} then OAEP de-pad the resulting data and store it in 3361f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{out} of length \textit{outlen}. The \textit{lparam} and \textit{lparamlen} are the same parameters you would pass 3362f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto pkcs\_1\_oaep\_decode(). 3363f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3364f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIf the RSA decrypted data is not a valid OAEP packet then \textit{stat} is set to $0$. Otherwise, it is set to $1$. 3365f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3366f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Extended Decryption} 3367f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs 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 3368f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdecryption function: 3369f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3370f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_decrypt\_key\_ex()} 3371f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3372f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rsa_decrypt_key_ex( 3373f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 3374f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3375f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3376f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3377f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *lparam, 3378f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long lparamlen, 3379f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 3380f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int padding, 3381f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int *stat, 3382f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 3383f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3384f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3385f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSimilar to the extended encryption, the new parameter \textit{padding} indicates which version of the PKCS \#1 standard to use. 3386f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt 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. 3387f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3388f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen performing v1.5 decryption, the hash and lparam parameters are totally ignored and can be set to \textbf{NULL} or zero (respectively). 3389f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3390f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3391f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{RSA Signature Generation} 3392f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSimilar to RSA key encryption RSA is also used to \textit{digitally sign} message digests (hashes). To facilitate this 3393f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectprocess the following functions have been provided. 3394f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3395f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_sign\_hash()} 3396f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3397f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rsa_sign_hash(const unsigned char *in, 3398f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3399f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3400f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3401f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 3402f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int prng_idx, 3403f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 3404f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long saltlen, 3405f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 3406f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3407f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3408f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will PSS encode the message digest pointed to by \textit{in} of length \textit{inlen} octets. Next, the PSS encoded hash will be RSA 3409f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{signed} and the output stored in the buffer pointed to by \textit{out} of length \textit{outlen} octets. 3410f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3411f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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 3412f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecthash the message being signed. The \textit{saltlen} parameter indicates the length of the desired salt, and should typically be small. A good 3413f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdefault 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 3414f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe RSA modulus (in octets), and \textit{hLen} is the length of the message digest produced by the chosen hash. 3415f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3416f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Extended Signatures} 3417f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3418f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs of v1.15, the library supports both v1.5 and v2.1 signatures. The extended signature generation function has the following prototype: 3419f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3420f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_sign\_hash\_ex()} 3421f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3422f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rsa_sign_hash_ex( 3423f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 3424f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3425f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3426f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3427f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int padding, 3428f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 3429f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int prng_idx, 3430f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 3431f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long saltlen, 3432f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 3433f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3434f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3435f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will PKCS encode the message digest pointed to by \textit{in} of length \textit{inlen} octets. Next, the PKCS encoded hash will be RSA 3436f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{signed} and the output stored in the buffer pointed to by \textit{out} of length \textit{outlen} octets. The \textit{padding} parameter 3437f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmust 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 3438f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectv2.1 signature. 3439f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3440f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen 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 3441f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectvalues such as $\lbrace$\textbf{NULL}, 0, 0$\rbrace$. 3442f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3443f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{RSA Signature Verification} 3444f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_verify\_hash()} 3445f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3446f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rsa_verify_hash(const unsigned char *sig, 3447f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long siglen, 3448f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *msghash, 3449f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long msghashlen, 3450f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 3451f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long saltlen, 3452f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int *stat, 3453f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 3454f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3455f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3456f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will RSA \textit{verify} the signature pointed to by \textit{sig} of length \textit{siglen} octets. Next, the RSA decoded data is PSS decoded 3457f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand the extracted hash is compared against the message digest pointed to by \textit{msghash} of length \textit{msghashlen} octets. 3458f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3459f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIf the RSA decoded data is not a valid PSS message, or if the PSS decoded hash does not match the \textit{msghash} 3460f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectvalue, \textit{res} is set to $0$. Otherwise, if the function succeeds, and signature is valid \textit{res} is set to $1$. 3461f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3462f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Extended Verification} 3463f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3464f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs of v1.15, the library supports both v1.5 and v2.1 signature verification. The extended signature verification function has the following prototype: 3465f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3466f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_verify\_hash\_ex()} 3467f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3468f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rsa_verify_hash_ex( 3469f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *sig, 3470f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long siglen, 3471f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *hash, 3472f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long hashlen, 3473f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int padding, 3474f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 3475f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long saltlen, 3476f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int *stat, 3477f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 3478f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3479f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3480f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will RSA \textit{verify} the signature pointed to by \textit{sig} of length \textit{siglen} octets. Next, the RSA decoded data is PKCS decoded 3481f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand the extracted hash is compared against the message digest pointed to by \textit{msghash} of length \textit{msghashlen} octets. 3482f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3483f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIf the RSA decoded data is not a valid PSS message, or if the PKCS decoded hash does not match the \textit{msghash} 3484f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectvalue, \textit{res} is set to $0$. Otherwise, if the function succeeds, and signature is valid \textit{res} is set to $1$. 3485f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3486f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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 3487f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textbf{LTC\_PKCS\_1\_PSS} to perform a v2.1 verification. When performing a v1.5 verification the \textit{hash\_idx} parameter is ignored. 3488f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3489f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{RSA Encryption Example} 3490f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 3491f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3492f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 3493f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 3494f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 3495f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err, hash_idx, prng_idx, res; 3496f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long l1, l2; 3497f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char pt[16], pt2[16], out[1024]; 3498f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key key; 3499f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3500f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register prng/hash */ 3501f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_prng(&sprng_desc) == -1) { 3502f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error registering sprng"); 3503f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 3504f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 3505f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3506f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register a math library (in this case TomsFastMath) 3507f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ltc_mp = tfm_desc; 3508f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3509f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if (register_hash(&sha1_desc) == -1) { 3510f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error registering sha1"); 3511f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 3512f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 3513f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project hash_idx = find_hash("sha1"); 3514f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_idx = find_prng("sprng"); 3515f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3516f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* make an RSA-1024 key */ 3517f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = rsa_make_key(NULL, /* PRNG state */ 3518f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_idx, /* PRNG idx */ 3519f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 1024/8, /* 1024-bit key */ 3520f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 65537, /* we like e=65537 */ 3521f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &key) /* where to store the key */ 3522f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ) != CRYPT_OK) { 3523f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("rsa_make_key %s", error_to_string(err)); 3524f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 3525f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 3526f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3527f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* fill in pt[] with a key we want to send ... */ 3528f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project l1 = sizeof(out); 3529f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = rsa_encrypt_key(pt, /* data we wish to encrypt */ 3530f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 16, /* data is 16 bytes long */ 3531f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project out, /* where to store ciphertext */ 3532f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &l1, /* length of ciphertext */ 3533f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project "TestApp", /* our lparam for this program */ 3534f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 7, /* lparam is 7 bytes long */ 3535f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project NULL, /* PRNG state */ 3536f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_idx, /* prng idx */ 3537f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project hash_idx, /* hash idx */ 3538f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &key) /* our RSA key */ 3539f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ) != CRYPT_OK) { 3540f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("rsa_encrypt_key %s", error_to_string(err)); 3541f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 3542f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 3543f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3544f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* now let's decrypt the encrypted key */ 3545f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project l2 = sizeof(pt2); 3546f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = rsa_decrypt_key(out, /* encrypted data */ 3547f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project l1, /* length of ciphertext */ 3548f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project pt2, /* where to put plaintext */ 3549f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &l2, /* plaintext length */ 3550f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project "TestApp", /* lparam for this program */ 3551f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 7, /* lparam is 7 bytes long */ 3552f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project hash_idx, /* hash idx */ 3553f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &res, /* validity of data */ 3554f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &key) /* our RSA key */ 3555f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ) != CRYPT_OK) { 3556f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("rsa_decrypt_key %s", error_to_string(err)); 3557f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project return EXIT_FAILURE; 3558f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 3559f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* if all went well pt == pt2, l2 == 16, res == 1 */ 3560f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 3561f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3562f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 3563f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3564f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{RSA Key Format} 3565f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3566f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe RSA key format adopted for exporting and importing keys is the PKCS \#1 format defined by the ASN.1 constructs known as 3567f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectRSAPublicKey and RSAPrivateKey. Additionally, the OpenSSL key format is supported by the import function only. 3568f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3569f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{RSA Key Export} 3570f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo export a RSA key use the following function. 3571f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3572f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_export()} 3573f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3574f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rsa_export(unsigned char *out, 3575f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3576f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int type, 3577f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 3578f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3579f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will export the RSA key in either a RSAPublicKey or RSAPrivateKey (PKCS \#1 types) depending on the value of \textit{type}. When it is 3580f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectset to \textbf{PK\_PRIVATE} the export format will be RSAPrivateKey and otherwise it will be RSAPublicKey. 3581f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3582f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{RSA Key Import} 3583f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo import a RSA key use the following function. 3584f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3585f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{rsa\_import()} 3586f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3587f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rsa_import(const unsigned char *in, 3588f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3589f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 3590f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3591f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3592f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 3593f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfunction can import both RSAPublicKey and RSAPrivateKey formats. 3594f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3595f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs of v1.06 this function can also import OpenSSL DER formatted public RSA keys. They are essentially encapsulated RSAPublicKeys. LibTomCrypt will 3596f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectimport 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 3597f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthere is no function provided to export in this format. 3598f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3599f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{Elliptic Curve Cryptography} 3600f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3601f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Background} 3602f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe library provides a set of core ECC functions as well that are designed to be the Elliptic Curve analogy of all of the 3603f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectDiffie-Hellman routines in the previous chapter. Elliptic curves (of certain forms) have the benefit that they are harder 3604f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto attack (no sub-exponential attacks exist unlike normal DH crypto) in fact the fastest attack requires the square root 3605f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof the order of the base point in time. That means if you use a base point of order $2^{192}$ (which would represent a 3606f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project192-bit key) then the work factor is $2^{96}$ in order to find the secret key. 3607f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3608f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe curves in this library are taken from the following website: 3609f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3610f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecthttp://csrc.nist.gov/cryptval/dss.htm 3611f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3612f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3613f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs 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 3614f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsupport smaller devices which do not need as large keys for security. 3615f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3616f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThey are all curves over the integers modulo a prime. The curves have the basic equation that is: 3617f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{equation} 3618f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecty^2 = x^3 - 3x + b\mbox{ }(\mbox{mod }p) 3619f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{equation} 3620f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3621f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe variable $b$ is chosen such that the number of points is nearly maximal. In fact the order of the base points $\beta$ 3622f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectprovided are very close to $p$ that is $\vert \vert \phi(\beta) \vert \vert \approx \vert \vert p \vert \vert$. The curves 3623f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrange in order from $\approx 2^{112}$ points to $\approx 2^{521}$. According to the source document any key size greater 3624f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthan or equal to 256-bits is sufficient for long term security. 3625f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3626f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Fixed Point Optimizations} 3627f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Fixed Point ECC} 3628f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{MECC\_FP} 3629f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs of v1.12 of LibTomCrypt, support for Fixed Point ECC point multiplication has been added. It is a generic optimization that is 3630f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsupported by any conforming math plugin. It is enabled by defining \textbf{MECC\_FP} during the build, such as 3631f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3632f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3633f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCFLAGS="-DTFM_DESC -DMECC_FP" make 3634f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3635f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3636f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwhich 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 3637f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsafe (by default). It supports the LTC locking macros (such as by enabling LTC\_PTHREAD), but by default is not locked. 3638f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3639f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{FP\_ENTRIES} 3640f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 3641f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcache (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 3642f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpre--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 3643f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectall subsequent point multiplications with that point will use the faster algorithm. 3644f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3645f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{FP\_LUT} 3646f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 3647f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectvalue 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 3648f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwith 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 3649f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectif it is active. Both FP\_ENTRIES and FP\_LUT are definable on the command line if you wish to override them. For instance, 3650f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3651f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3652f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCFLAGS="-DTFM_DESC -DMECC_FP -DFP_ENTRIES=8 -DFP_LUT=6" make 3653f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3654f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3655f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{flushleft} 3656f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{FP\_SIZE} \index{TFM} \index{tfm.h} 3657f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwould 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 3658f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto 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) 3659f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectECC--256 you will only need 576 bits, which would reduce the memory usage by 700\%. 3660f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{flushleft} 3661f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3662f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Key Format} 3663f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLibTomCrypt 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. \ 3664f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn the case of LibTomCrypt, it is meant \textbf{solely} for NIST and SECG $GF(p)$ curves. The format of the keys is as follows: 3665f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3666f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ECC Key Format} 3667f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 3668f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3669f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectECCPublicKey ::= SEQUENCE { 3670f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project flags BIT STRING(0), -- public/private flag (always zero), 3671f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project keySize INTEGER, -- Curve size (in bits) divided by eight 3672f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- and rounded down, e.g. 521 => 65 3673f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project pubkey.x INTEGER, -- The X co-ordinate of the public key point 3674f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project pubkey.y INTEGER, -- The Y co-ordinate of the public key point 3675f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 3676f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3677f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectECCPrivateKey ::= SEQUENCE { 3678f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project flags BIT STRING(1), -- public/private flag (always one), 3679f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project keySize INTEGER, -- Curve size (in bits) divided by eight 3680f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- and rounded down, e.g. 521 => 65 3681f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project pubkey.x INTEGER, -- The X co-ordinate of the public key point 3682f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project pubkey.y INTEGER, -- The Y co-ordinate of the public key point 3683f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project secret.k INTEGER, -- The secret key scalar 3684f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 3685f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3686f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 3687f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3688f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe first flags bit denotes whether the key is public (zero) or private (one). 3689f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3690f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\vfil 3691f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3692f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{ECC Curve Parameters} 3693f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe library uses the following structure to describe an elliptic curve. This is used internally, as well as by the new 3694f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectextended ECC functions which allow the user to specify their own curves. 3695f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3696f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ltc\_ecc\_set\_type} 3697f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3698f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/** Structure defines a NIST GF(p) curve */ 3699f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttypedef struct { 3700f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The size of the curve in octets */ 3701f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int size; 3702f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3703f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** name of curve */ 3704f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project char *name; 3705f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3706f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The prime that defines the field (encoded in hex) */ 3707f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project char *prime; 3708f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3709f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The fields B param (hex) */ 3710f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project char *B; 3711f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3712f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The order of the curve (hex) */ 3713f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project char *order; 3714f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3715f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The x co-ordinate of the base point on the curve (hex) */ 3716f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project char *Gx; 3717f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3718f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The y co-ordinate of the base point on the curve (hex) */ 3719f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project char *Gy; 3720f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} ltc_ecc_set_type; 3721f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3722f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3723f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe curve must be of the form $y^2 = x^3 - 3x + b$, and all of the integer parameters are encoded in hexadecimal format. 3724f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3725f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Core Functions} 3726f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ECC Key Generation} 3727f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere is a key structure called \textit{ecc\_key} used by the ECC functions. There is a function to make a key: 3728f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_make\_key()} 3729f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3730f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecc_make_key(prng_state *prng, 3731f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int wprng, 3732f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int keysize, 3733f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key *key); 3734f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3735f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3736f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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 3737f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcorrespond 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 3738f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe keysize up to the next available one. 3739f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3740f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe function will free any internally allocated resources if there is an error. 3741f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3742f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Extended Key Generation} 3743f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs 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: 3744f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3745f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_make\_key\_ex()} 3746f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3747f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecc_make_key_ex( 3748f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 3749f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int wprng, 3750f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key *key, 3751f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const ltc_ecc_set_type *dp); 3752f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3753f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3754f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function generates a random ECC key over the curve specified by the parameters by \textit{dp}. The rest of the parameters are equivalent to 3755f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthose from the original key generation function. 3756f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3757f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ECC Key Free} 3758f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo free the memory allocated by a ecc\_make\_key(), ecc\_make\_key\_ex(), ecc\_import(), or ecc\_import\_ex() call use the following function: 3759f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_free()} 3760f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3761f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectvoid ecc_free(ecc_key *key); 3762f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3763f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3764f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ECC Key Export} 3765f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo export an ECC key using the LibTomCrypt format call the following function: 3766f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_export()} 3767f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3768f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecc_export(unsigned char *out, 3769f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3770f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int type, 3771f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key *key); 3772f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3773f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will export the key with the given \textit{type} (\textbf{PK\_PUBLIC} or \textbf{PK\_PRIVATE}), and store it to \textit{out}. 3774f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3775f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ECC Key Import} 3776f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe following function imports a LibTomCrypt format ECC key: 3777f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_import()} 3778f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3779f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecc_import(const unsigned char *in, 3780f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3781f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key *key); 3782f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3783f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 3784f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectany allocated memory automatically. 3785f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3786f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Extended Key Import} 3787f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3788f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe following function imports a LibTomCrypt format ECC key using a specified set of curve parameters: 3789f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_import\_ex()} 3790f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3791f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecc_import_ex(const unsigned char *in, 3792f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3793f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key *key, 3794f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const ltc_ecc_set_type *dp); 3795f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3796f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will import the key from the array pointed to by \textit{in} of length \textit{inlen} octets. The key is stored in 3797f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe ECC structure pointed to by \textit{key}. The curve is specified by the parameters pointed to by \textit{dp}. The function will free 3798f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectall internally allocated memory upon error. 3799f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3800f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ANSI X9.63 Export} 3801f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe following function exports an ECC public key in the ANSI X9.63 format: 3802f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3803f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_ansi\_x963\_export()} 3804f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3805f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecc_ansi_x963_export( ecc_key *key, 3806f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3807f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 3808f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3809f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 3810f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsection 4.3.6 of the standard. It does not allow for the export of private keys. 3811f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3812f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ANSI X9.63 Import} 3813f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe following function imports an ANSI X9.63 section 4.3.6 format public ECC key: 3814f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3815f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_ansi\_x963\_import()} 3816f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3817f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecc_ansi_x963_import(const unsigned char *in, 3818f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3819f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key *key); 3820f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3821f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 3822f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{key}. The function will free any allocated memory upon error. 3823f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3824f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Extended ANSI X9.63 Import} 3825f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe following function allows the importing of an ANSI x9.63 section 4.3.6 format public ECC key using user specified domain parameters: 3826f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3827f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_ansi\_x963\_import\_ex()} 3828f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3829f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecc_ansi_x963_import_ex(const unsigned char *in, 3830f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3831f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key *key, 3832f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ltc_ecc_set_type *dp); 3833f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3834f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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}. 3835f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe imported key is stored in the ECC key pointed to by \textit{key}. The function will free any allocated memory upon error. 3836f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3837f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ECC Shared Secret} 3838f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo construct a Diffie-Hellman shared secret with a private and public ECC key, use the following function: 3839f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_shared\_secret()} 3840f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3841f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecc_shared_secret( ecc_key *private_key, 3842f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key *public_key, 3843f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3844f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 3845f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3846f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \textit{private\_key} is typically the local private key, and \textit{public\_key} is the key the remote party has shared. 3847f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote: this function stores only the $x$ co-ordinate of the shared elliptic point as described in ANSI X9.63 ECC--DH. 3848f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3849f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{ECC Diffie-Hellman Encryption} 3850f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectECC--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 3851f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbut 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 3852f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectencrypts a short string (no longer than the message digest) using this technique: 3853f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3854f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ECC-DH Encryption} 3855f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_encrypt\_key()} 3856f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3857f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecc_encrypt_key(const unsigned char *in, 3858f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3859f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3860f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3861f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 3862f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int wprng, 3863f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash, 3864f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key *key); 3865f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3866f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3867f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs the name implies this function encrypts a (symmetric) key, and is not intended for encrypting long messages directly. It will encrypt the 3868f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectplaintext 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 3869f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecthash algorithm indexed by \textit{hash} to construct a shared secret which may be XOR'ed against the plaintext. The ciphertext is stored in 3870f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe output buffer pointed to by \textit{out} of length \textit{outlen} octets. 3871f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3872f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 3873f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrecipients multiple call to this function for each public ECC key is required. 3874f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3875f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ECC-DH Decryption} 3876f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_decrypt\_key()} 3877f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3878f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecc_decrypt_key(const unsigned char *in, 3879f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3880f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3881f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3882f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key *key); 3883f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3884f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3885f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function will decrypt an encrypted payload. The \textit{key} provided must be the private key corresponding to the public key 3886f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectused during encryption. If the wrong key is provided the function will not specifically return an error code. It is important 3887f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto use some form of challenge response in that case (e.g. compute a MAC of a known string). 3888f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3889f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ECC Encryption Format} 3890f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe packet format for the encrypted keys is the following ASN.1 SEQUENCE: 3891f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3892f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3893f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectECCEncrypt ::= SEQUENCE { 3894f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project hashID OBJECT IDENTIFIER, -- OID of hash used 3895f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project pubkey OCTET STRING , -- Encapsulated ECCPublicKey 3896f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project skey OCTET STRING -- xor of plaintext and 3897f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project --"hash of shared secret" 3898f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 3899f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3900f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3901f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{EC DSA Signatures} 3902f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3903f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere are also functions to sign and verify messages. They use the ANSI X9.62 EC-DSA algorithm to generate and verify signatures in the 3904f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectANSI X9.62 format. 3905f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3906f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{EC-DSA Signature Generation} 3907f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo sign a message digest (hash) use the following function: 3908f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3909f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_sign\_hash()} 3910f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3911f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecc_sign_hash(const unsigned char *in, 3912f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 3913f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 3914f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 3915f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 3916f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int wprng, 3917f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key *key); 3918f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3919f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3920f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function will EC--DSA sign the message digest stored in the array pointed to by \textit{in} of length \textit{inlen} octets. The signature 3921f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwill be stored in the array pointed to by \textit{out} of length \textit{outlen} octets. The function requires a properly seeded PRNG, and 3922f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe ECC \textit{key} provided must be a private key. 3923f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3924f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{EC-DSA Signature Verification} 3925f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ecc\_verify\_hash()} 3926f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3927f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint ecc_verify_hash(const unsigned char *sig, 3928f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long siglen, 3929f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *hash, 3930f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long hashlen, 3931f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int *stat, 3932f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_key *key); 3933f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3934f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3935f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function will verify the EC-DSA signature in the array pointed to by \textit{sig} of length \textit{siglen} octets, against the message digest 3936f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpointed 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: 3937f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe 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. 3938f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe ECC \textit{key} must be the public (or private) ECC key corresponding to the key that performed the signature. 3939f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3940f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Signature Format} 3941f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe signature code is an implementation of X9.62 EC--DSA, and the output is compliant for GF(p) curves. 3942f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3943f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{ECC Keysizes} 3944f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWith 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 3945f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwork. 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 3946f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSHA256 and an ECC-192 key, you in effect have 96--bits of security. 3947f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3948f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe library will not warn you if you make this mistake, so it is important to check yourself before using the signatures. 3949f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3950f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{Digital Signature Algorithm} 3951f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Introduction} 3952f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe Digital Signature Algorithm (or DSA) is a variant of the ElGamal Signature scheme which has been modified to 3953f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectreduce 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. 3954f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWith 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 3955f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwould require only at least 40 bytes. 3956f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3957f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Key Format} 3958f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSince 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 3959f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectnow so that others can interoperate with this library. 3960f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3961f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3962f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectDSAPublicKey ::= SEQUENCE { 3963f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project publicFlags BIT STRING(0), -- must be 0 3964f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project g INTEGER , -- base generator 3965f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- check that g^q mod p == 1 3966f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- and that 1 < g < p - 1 3967f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project p INTEGER , -- prime modulus 3968f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project q INTEGER , -- order of sub-group 3969f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- (must be prime) 3970f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project y INTEGER , -- public key, specifically, 3971f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- g^x mod p, 3972f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- check that y^q mod p == 1 3973f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- and that 1 < y < p - 1 3974f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 3975f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3976f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectDSAPrivateKey ::= SEQUENCE { 3977f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project publicFlags BIT STRING(1), -- must be 1 3978f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project g INTEGER , -- base generator 3979f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- check that g^q mod p == 1 3980f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- and that 1 < g < p - 1 3981f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project p INTEGER , -- prime modulus 3982f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project q INTEGER , -- order of sub-group 3983f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- (must be prime) 3984f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project y INTEGER , -- public key, specifically, 3985f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- g^x mod p, 3986f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- check that y^q mod p == 1 3987f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project -- and that 1 < y < p - 1 3988f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project x INTEGER -- private key 3989f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 3990f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 3991f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3992f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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, 3993f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand easy to work with. 3994f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 3995f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Key Generation} 3996f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo make a DSA key you must call the following function 3997f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 3998f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint dsa_make_key(prng_state *prng, 3999f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int wprng, 4000f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int group_size, 4001f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int modulus_size, 4002f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project dsa_key *key); 4003f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4004f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe variable \textit{prng} is an active PRNG state and \textit{wprng} the index to the descriptor. \textit{group\_size} and 4005f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{modulus\_size} control the difficulty of forging a signature. Both parameters are in bytes. The larger the 4006f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{group\_size} the more difficult a forgery becomes upto a limit. The value of $group\_size$ is limited by 4007f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$15 < group\_size < 1024$ and $modulus\_size - group\_size < 512$. Suggested values for the pairs are as follows. 4008f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4009f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{figure}[here] 4010f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{center} 4011f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{tabular}{|c|c|c|} 4012f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline \textbf{Bits of Security} & \textbf{group\_size} & \textbf{modulus\_size} \\ 4013f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline 80 & 20 & 128 \\ 4014f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline 120 & 30 & 256 \\ 4015f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline 140 & 35 & 384 \\ 4016f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline 160 & 40 & 512 \\ 4017f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline 4018f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{tabular} 4019f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{center} 4020f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\caption{DSA Key Sizes} 4021f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{figure} 4022f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4023f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen you are finished with a DSA key you can call the following function to free the memory used. 4024f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{dsa\_free()} 4025f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4026f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectvoid dsa_free(dsa_key *key); 4027f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4028f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4029f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Key Verification} 4030f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectEach DSA key is composed of the following variables. 4031f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4032f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{enumerate} 4033f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item $q$ a small prime of magnitude $256^{group\_size}$. 4034f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item $p = qr + 1$ a large prime of magnitude $256^{modulus\_size}$ where $r$ is a random even integer. 4035f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item $g = h^r \mbox{ (mod }p\mbox{)}$ a generator of order $q$ modulo $p$. $h$ can be any non-trivial random 4036f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project value. For this library they start at $h = 2$ and step until $g$ is not $1$. 4037f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item $x$ a random secret (the secret key) in the range $1 < x < q$ 4038f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item $y = g^x \mbox{ (mod }p\mbox{)}$ the public key. 4039f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{enumerate} 4040f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4041f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectA DSA key is considered valid if it passes all of the following tests. 4042f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4043f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{enumerate} 4044f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item $q$ must be prime. 4045f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item $p$ must be prime. 4046f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item $g$ cannot be one of $\lbrace -1, 0, 1 \rbrace$ (modulo $p$). 4047f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item $g$ must be less than $p$. 4048f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item $(p-1) \equiv 0 \mbox{ (mod }q\mbox{)}$. 4049f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item $g^q \equiv 1 \mbox{ (mod }p\mbox{)}$. 4050f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item $1 < y < p - 1$ 4051f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item $y^q \equiv 1 \mbox{ (mod }p\mbox{)}$. 4052f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{enumerate} 4053f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4054f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTests one and two ensure that the values will at least form a field which is required for the signatures to 4055f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfunction. Tests three and four ensure that the generator $g$ is not set to a trivial value which would make signature 4056f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectforgery easier. Test five ensures that $q$ divides the order of multiplicative sub-group of $\Z/p\Z$. Test six 4057f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectensures that the generator actually generates a prime order group. Tests seven and eight ensure that the public key 4058f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectis within range and belongs to a group of prime order. Note that test eight does not prove that $g$ generated $y$ only 4059f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthat $y$ belongs to a multiplicative sub-group of order $q$. 4060f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4061f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe following function will perform these tests. 4062f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4063f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{dsa\_verify\_key()} 4064f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4065f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint dsa_verify_key(dsa_key *key, int *stat); 4066f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4067f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4068f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 4069f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand should not be used at all. If the result is $stat = 1$ the DSA key is valid (as far as valid mathematics are concerned). 4070f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4071f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Signatures} 4072f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Signature Generation} 4073f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo generate a DSA signature call the following function: 4074f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4075f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{dsa\_sign\_hash()} 4076f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4077f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint dsa_sign_hash(const unsigned char *in, 4078f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4079f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4080f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 4081f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 4082f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int wprng, 4083f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project dsa_key *key); 4084f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4085f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4086f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich will sign the data in \textit{in} of length \textit{inlen} bytes. The signature is stored in \textit{out} and the size 4087f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof the signature in \textit{outlen}. If the signature is longer than the size you initially specify in \textit{outlen} nothing 4088f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectis stored and the function returns an error code. The DSA \textit{key} must be of the \textbf{PK\_PRIVATE} persuasion. 4089f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4090f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Signature Verification} 4091f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo verify a hash created with that function use the following function: 4092f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4093f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{dsa\_verify\_hash()} 4094f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4095f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint dsa_verify_hash(const unsigned char *sig, 4096f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long siglen, 4097f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *hash, 4098f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4099f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int *stat, 4100f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project dsa_key *key); 4101f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4102f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhich will verify the data in \textit{hash} of length \textit{inlen} against the signature stored in \textit{sig} of length \textit{siglen}. 4103f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt will set \textit{stat} to $1$ if the signature is valid, otherwise it sets \textit{stat} to $0$. 4104f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4105f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{DSA Encrypt and Decrypt} 4106f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs of version 1.07, the DSA keys can be used to encrypt and decrypt small payloads. It works similar to the ECC encryption where 4107f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecta 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 4108f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe ECC encryption format to the DSA algorithm. 4109f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4110f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{DSA Encryption} 4111f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function will encrypt a small payload with a recipients public DSA key. 4112f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4113f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{dsa\_encrypt\_key()} 4114f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4115f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint dsa_encrypt_key(const unsigned char *in, 4116f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4117f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4118f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 4119f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 4120f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int wprng, 4121f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash, 4122f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project dsa_key *key); 4123f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4124f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4125f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will encrypt the payload in \textit{in} of length \textit{inlen} and store the ciphertext in the output buffer \textit{out}. The 4126f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectlength of the ciphertext \textit{outlen} must be originally set to the length of the output buffer. The DSA \textit{key} can be 4127f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecta public key. 4128f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4129f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{DSA Decryption} 4130f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4131f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{dsa\_decrypt\_key()} 4132f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4133f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint dsa_decrypt_key(const unsigned char *in, 4134f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4135f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4136f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 4137f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project dsa_key *key); 4138f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4139f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will decrypt the ciphertext \textit{in} of length \textit{inlen}, and store the original payload in \textit{out} of length \textit{outlen}. 4140f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe DSA \textit{key} must be a private key. 4141f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4142f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{DSA Key Import and Export} 4143f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4144f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{DSA Key Export} 4145f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo export a DSA key so that it can be transported use the following function: 4146f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{dsa\_export()} 4147f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4148f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint dsa_export(unsigned char *out, 4149f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 4150f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int type, 4151f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project dsa_key *key); 4152f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4153f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will export the DSA \textit{key} to the buffer \textit{out} and set the length in \textit{outlen} (which must have been previously 4154f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectinitialized to the maximum buffer size). The \textit{type} variable may be either \textbf{PK\_PRIVATE} or \textbf{PK\_PUBLIC} 4155f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdepending on whether you want to export a private or public copy of the DSA key. 4156f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4157f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{DSA Key Import} 4158f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo import an exported DSA key use the following function 4159f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project: 4160f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{dsa\_import()} 4161f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4162f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint dsa_import(const unsigned char *in, 4163f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4164f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project dsa_key *key); 4165f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4166f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4167f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will import the DSA key from the buffer \textit{in} of length \textit{inlen} to the \textit{key}. If the process fails the function 4168f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwill automatically free all of the heap allocated in the process (you don't have to call dsa\_free()). 4169f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4170f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{Standards Support} 4171f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{ASN.1 Formats} 4172f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLibTomCrypt supports a variety of ASN.1 data types encoded with the Distinguished Encoding Rules (DER) suitable for various cryptographic protocols. The data types 4173f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectare all provided with three basic functions with \textit{similar} prototypes. One function has been dedicated to calculate the length in octets of a given 4174f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectformat, and two functions have been dedicated to encoding and decoding the format. 4175f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4176f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectOn top of the basic data types are the SEQUENCE and SET data types which are collections of other ASN.1 types. They are provided 4177f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectin 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: 4178f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4179f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ltc\_asn1\_list structure} 4180f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4181f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttypedef struct { 4182f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int type; 4183f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *data; 4184f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long size; 4185f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int used; 4186f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project struct ltc_asn1_list_ *prev, *next, 4187f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project *child, *parent; 4188f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} ltc_asn1_list; 4189f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4190f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4191f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{LTC\_SET\_ASN1 macro} 4192f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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 4193f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\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 4194f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand reflects if the particular member of a list was the decoded data type. To help build the lists in an orderly fashion the macro 4195f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{LTC\_SET\_ASN1(list, index, Type, Data, Size)} has been provided. 4196f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4197f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt will assign to the \textit{index}th position in the \textit{list} the triplet (Type, Data, Size). An example usage would be: 4198f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4199f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 4200f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4201f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project... 4202f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectltc_asn1_list sequence[3]; 4203f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectunsigned long three=3; 4204f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4205f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLTC_SET_ASN1(sequence, 0, LTC_ASN1_IA5_STRING, "hello", 5); 4206f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLTC_SET_ASN1(sequence, 1, LTC_ASN1_SHORT_INTEGER, &three, 1); 4207f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLTC_SET_ASN1(sequence, 2, LTC_ASN1_NULL, NULL, 0); 4208f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4209f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 4210f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4211f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe macro is relatively safe with respect to modifying variables, for instance the following code is equivalent. 4212f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4213f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 4214f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4215f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project... 4216f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectltc_asn1_list sequence[3]; 4217f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectunsigned long three=3; 4218f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint x=0; 4219f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLTC_SET_ASN1(sequence, x++, LTC_ASN1_IA5_STRING, "hello", 5); 4220f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLTC_SET_ASN1(sequence, x++, LTC_ASN1_SHORT_INTEGER, &three, 1); 4221f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLTC_SET_ASN1(sequence, x++, LTC_ASN1_NULL, NULL, 0); 4222f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4223f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 4224f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4225f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{figure}[here] 4226f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{center} 4227f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 4228f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{tabular}{|l|l|} 4229f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline \textbf{Definition} & \textbf{ASN.1 Type} \\ 4230f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_EOL & End of a ASN.1 list structure. \\ 4231f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_BOOLEAN & BOOLEAN type \\ 4232f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_INTEGER & INTEGER (uses mp\_int) \\ 4233f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_SHORT\_INTEGER & INTEGER (32--bit using unsigned long) \\ 4234f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_BIT\_STRING & BIT STRING (one bit per char) \\ 4235f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_OCTET\_STRING & OCTET STRING (one octet per char) \\ 4236f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_NULL & NULL \\ 4237f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_OBJECT\_IDENTIFIER & OBJECT IDENTIFIER \\ 4238f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_IA5\_STRING & IA5 STRING (one octet per char) \\ 4239f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_UTF8\_STRING & UTF8 STRING (one wchar\_t per char) \\ 4240f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_PRINTABLE\_STRING & PRINTABLE STRING (one octet per char) \\ 4241f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_UTCTIME & UTCTIME (see ltc\_utctime structure) \\ 4242f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_SEQUENCE & SEQUENCE (and SEQUENCE OF) \\ 4243f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_SET & SET \\ 4244f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_SETOF & SET OF \\ 4245f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline LTC\_ASN1\_CHOICE & CHOICE \\ 4246f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline 4247f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{tabular} 4248f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\caption{List of ASN.1 Supported Types} 4249f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 4250f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{center} 4251f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{figure} 4252f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4253f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{SEQUENCE Type} 4254f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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. 4255f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4256f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{SEQUENCE Encoding} 4257f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo 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 4258f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwith the following function. 4259f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4260f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_encode\_sequence()} 4261f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4262f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_encode_sequence(ltc_asn1_list *list, 4263f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4264f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4265f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4266f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4267f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 4268f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfunction 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}. 4269f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4270f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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 4271f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectverbatim 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 4272f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe \textit{data} pointer is simply a pointer to another \textbf{ltc\_asn1\_list}. 4273f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4274f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{SEQUENCE Decoding} 4275f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4276f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_decode\_sequence()} 4277f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4278f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectDecoding 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 4279f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project(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 4280f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectunits of the respective type has been loaded. 4281f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4282f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4283f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_sequence(const unsigned char *in, 4284f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4285f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ltc_asn1_list *list, 4286f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long outlen); 4287f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4288f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4289f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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. 4290f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt 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. 4291f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4292f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectFor the following types the \textit{size} field will be updated to reflect the number of units read of the given type. 4293f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{enumerate} 4294f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item BIT STRING 4295f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item OCTET STRING 4296f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item OBJECT IDENTIFIER 4297f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item IA5 STRING 4298f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item PRINTABLE STRING 4299f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{enumerate} 4300f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4301f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{SEQUENCE Length} 4302f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4303f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe length of a SEQUENCE can be determined with the following function. 4304f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4305f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_length\_sequence()} 4306f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4307f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_length_sequence(ltc_asn1_list *list, 4308f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4309f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4310f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4311f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4312f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will get the encoding size for the given \textit{list} of length \textit{inlen} and store it in \textit{outlen}. 4313f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4314f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{SEQUENCE Multiple Argument Lists} 4315f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4316f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectFor small or simple sequences an encoding or decoding can be performed with one of the following two functions. 4317f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4318f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_encode\_sequence\_multi()} 4319f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_decode\_sequence\_multi()} 4320f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4321f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4322f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_encode_sequence_multi(unsigned char *out, 4323f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, ...); 4324f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4325f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_sequence_multi(const unsigned char *in, 4326f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, ...); 4327f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4328f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4329f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese either encode or decode (respectively) a SEQUENCE data type where the items in the sequence are specified after the length parameter. 4330f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4331f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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} 4332f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand \textit{data} is \textbf{void} pointer. The list of items must be terminated with an item with the type \textbf{LTC\_ASN1\_EOL}. 4333f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4334f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt 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 4335f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecta 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. 4336f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4337f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 4338f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4339f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectunsigned char buf[MAXBUFSIZE]; 4340f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectunsigned long buflen; 4341f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint err; 4342f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4343f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project buflen = sizeof(buf); 4344f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = 4345f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project der_encode_sequence_multi(buf, &buflen, 4346f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project LTC_ASN1_IA5_STRING, 5UL, "Hello", 4347f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project LTC_ASN1_IA5_STRING, 7UL, " World!", 4348f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project LTC_ASN1_EOL, 0UL, NULL)) != CRYPT_OK) { 4349f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project // error handling 4350f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 4351f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4352f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 4353f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4354f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis example encodes a SEQUENCE with two IA5 STRING types containing ``Hello'' and `` World!'' respectively. Note the usage of the \textbf{UL} modifier 4355f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecton the size parameters. This forces the compiler to pass the numbers as the required \textbf{unsigned long} type that the function expects. 4356f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4357f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{SET and SET OF} 4358f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4359f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{SET} \index{SET OF} 4360f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSET 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 4361f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbe 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 4362f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecta \textbf{single} ASN.1 object sorted in ascending order by the DER their respective encodings. 4363f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4364f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{SET Encoding} 4365f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4366f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSETs use the same array structure of ltc\_asn1\_list that the SEQUENCE functions use. They are encoded with the following function: 4367f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4368f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_encode\_set()} 4369f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4370f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_encode_set(ltc_asn1_list *list, 4371f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4372f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4373f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4374f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4375f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4376f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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. 4377f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 4378f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectarray (to make the process deterministic). 4379f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4380f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function will \textbf{NOT} recognize \textit{DEFAULT} objects, and it is the responsibility of the caller to remove them as required. 4381f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4382f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{SET Decoding} 4383f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4384f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe SET type can be decoded with the following function. 4385f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4386f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_decode\_set()} 4387f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4388f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_set(const unsigned char *in, 4389f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4390f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ltc_asn1_list *list, 4391f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long outlen); 4392f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4393f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4394f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will decode the SET specified by \textit{list} of length \textit{outlen} objects from the input buffer \textit{in} of length \textit{inlen} octets. 4395f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4396f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt handles the fact that SETs are not strictly ordered and will make multiple passes (as required) through the list to decode all the objects. 4397f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4398f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{SET Length} 4399f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe length of a SET can be determined by calling der\_length\_sequence() since they have the same encoding length. 4400f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4401f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{SET OF Encoding} 4402f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectA \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 4403f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectused to store objects deterministically based solely on their encoding. It uses the same array structure of ltc\_asn1\_list that the SEQUENCE functions 4404f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectuse. They are encoded with the following function. 4405f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4406f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_encode\_setof()} 4407f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4408f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_encode_setof(ltc_asn1_list *list, 4409f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4410f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4411f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4412f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4413f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4414f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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}. 4415f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4416f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 4417f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmeans you need at least enough memory to keep an additional copy of the output on the heap. 4418f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4419f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{SET OF Decoding} 4420f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSince the decoding of a \textit{SET OF} object is unambiguous it can be decoded with der\_decode\_sequence(). 4421f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4422f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{SET OF Length} 4423f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLike the SET type the der\_length\_sequence() function can be used to determine the length of a \textit{SET OF} object. 4424f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4425f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ASN.1 INTEGER} 4426f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4427f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo encode or decode INTEGER data types use the following functions. 4428f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4429f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_encode\_integer()}\index{der\_decode\_integer()}\index{der\_length\_integer()} 4430f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4431f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_encode_integer( void *num, 4432f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4433f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4434f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4435f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_integer(const unsigned char *in, 4436f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4437f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *num); 4438f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4439f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_length_integer( void *num, 4440f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *len); 4441f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4442f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4443f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese 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 4444f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecta bignum to store the value, the \textit{short} INTEGER functions were made available. 4445f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4446f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_encode\_short\_integer()}\index{der\_decode\_short\_integer()}\index{der\_length\_short\_integer()} 4447f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4448f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_encode_short_integer(unsigned long num, 4449f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4450f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4451f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4452f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_short_integer(const unsigned char *in, 4453f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4454f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *num); 4455f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4456f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_length_short_integer(unsigned long num, 4457f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4458f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4459f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4460f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese 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 4461f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand short integer functions can encode and decode each others outputs. 4462f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4463f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ASN.1 BIT STRING} 4464f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4465f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_encode\_bit\_string()}\index{der\_decode\_bit\_string()}\index{der\_length\_bit\_string()} 4466f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4467f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_encode_bit_string(const unsigned char *in, 4468f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4469f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4470f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4471f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4472f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_bit_string(const unsigned char *in, 4473f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4474f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4475f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4476f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4477f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_length_bit_string(unsigned long nbits, 4478f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4479f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4480f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4481f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese 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 4482f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectas a one bit, and a zero value a zero bit. 4483f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4484f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ASN.1 OCTET STRING} 4485f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4486f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_encode\_octet\_string()}\index{der\_decode\_octet\_string()}\index{der\_length\_octet\_string()} 4487f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4488f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_encode_octet_string(const unsigned char *in, 4489f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4490f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4491f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4492f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4493f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_octet_string(const unsigned char *in, 4494f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4495f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4496f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4497f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4498f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_length_octet_string(unsigned long noctets, 4499f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4500f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4501f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4502f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese will encode or decode an OCTET STRING data type. The octets are stored using one \textbf{unsigned char} each. 4503f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4504f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ASN.1 OBJECT IDENTIFIER} 4505f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4506f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_encode\_object\_identifier()}\index{der\_decode\_object\_identifier()}\index{der\_length\_object\_identifier()} 4507f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4508f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_encode_object_identifier(unsigned long *words, 4509f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long nwords, 4510f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4511f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4512f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4513f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_object_identifier(const unsigned char *in, 4514f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4515f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *words, 4516f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4517f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4518f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_length_object_identifier(unsigned long *words, 4519f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long nwords, 4520f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4521f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4522f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4523f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese 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 4524f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$0 \ldots 2^{32} - 1$. 4525f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4526f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ASN.1 IA5 STRING} 4527f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4528f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_encode\_ia5\_string()}\index{der\_decode\_ia5\_string()}\index{der\_length\_ia5\_string()} 4529f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4530f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_encode_ia5_string(const unsigned char *in, 4531f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4532f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4533f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4534f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4535f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_ia5_string(const unsigned char *in, 4536f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4537f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4538f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4539f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4540f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_length_ia5_string(const unsigned char *octets, 4541f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long noctets, 4542f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4543f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4544f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4545f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese will encode or decode an IA5 STRING. The characters are read or stored in individual \textbf{char} elements. These functions performs internal character 4546f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto 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 4547f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsay a SPARC machine. Internally, these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided 4548f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthat the build platform honours the run--time platforms character conventions. 4549f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4550f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ASN.1 PRINTABLE STRING} 4551f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4552f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_encode\_printable\_string()}\index{der\_decode\_printable\_string()}\index{der\_length\_printable\_string()} 4553f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4554f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_encode_printable_string(const unsigned char *in, 4555f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4556f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4557f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4558f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4559f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_printable_string(const unsigned char *in, 4560f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4561f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4562f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4563f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4564f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_length_printable_string(const unsigned char *octets, 4565f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long noctets, 4566f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4567f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4568f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4569f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese will encode or decode an PRINTABLE STRING. The characters are read or stored in individual \textbf{char} elements. These functions performs internal character 4570f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto 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 4571f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsay a SPARC machine. Internally, these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided 4572f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthat the build platform honours the run-time platforms character conventions. 4573f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4574f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ASN.1 UTF8 STRING} 4575f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4576f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_encode\_utf8\_string()}\index{der\_decode\_utf8\_string()}\index{der\_length\_utf8\_string()} 4577f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4578f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_encode_utf8_string(const wchar_t *in, 4579f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4580f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4581f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4582f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4583f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_utf8_string(const unsigned char *in, 4584f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 4585f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project wchar_t *out, 4586f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4587f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4588f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_length_utf8_string(const wchar_t *octets, 4589f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long noctets, 4590f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4591f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4592f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4593f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese will encode or decode an UTF8 STRING. The characters are read or stored in individual \textbf{wchar\_t} elements. These function performs no internal 4594f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmapping and treat the characters as literals. 4595f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4596f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese 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 4597f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectintend to use the ISO C functions for working with wide--char arrays, you should make sure that wchar\_t has been defined previously. 4598f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4599f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ASN.1 UTCTIME} 4600f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4601f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe UTCTIME type is to store a date and time in ASN.1 format. It uses the following structure to organize the time. 4602f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4603f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ltc\_utctime structure} 4604f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4605f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttypedef struct { 4606f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned YY, /* year 00--99 */ 4607f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project MM, /* month 01--12 */ 4608f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project DD, /* day 01--31 */ 4609f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project hh, /* hour 00--23 */ 4610f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project mm, /* minute 00--59 */ 4611f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ss, /* second 00--59 */ 4612f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project off_dir, /* timezone offset direction 0 == +, 1 == - */ 4613f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project off_hh, /* timezone offset hours */ 4614f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project off_mm; /* timezone offset minutes */ 4615f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} ltc_utctime; 4616f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4617f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4618f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 4619f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwill be subtracted. For instance, the array $\lbrace 5, 6, 20, 22, 4, 00, 0, 5, 0 \rbrace$ represents the current time of 4620f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{2005, June 20th, 22:04:00} with a time offset of +05h00. 4621f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4622f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_encode\_utctime()}\index{der\_decode\_utctime()}\index{der\_length\_utctime()} 4623f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4624f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_encode_utctime( ltc_utctime *utctime, 4625f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4626f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4627f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4628f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_utctime(const unsigned char *in, 4629f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *inlen, 4630f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ltc_utctime *out); 4631f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4632f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_length_utctime( ltc_utctime *utctime, 4633f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4634f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4635f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4636f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 4637f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectinput. 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. 4638f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4639f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt is suggested that decoded data be further scrutinized (e.g. days of month in particular). 4640f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4641f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ASN.1 CHOICE} 4642f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4643f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 4644f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdecoder. 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 4645f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttype\footnote{Except it cannot have LTC\_ASN1\_INTEGER and LTC\_ASN1\_SHORT\_INTEGER simultaneously.} except for other CHOICE types. 4646f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4647f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere is no encoder for the CHOICE type as the actual DER encoding is the encoding of the chosen type. 4648f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4649f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_decode\_choice()} 4650f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4651f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_choice(const unsigned char *in, 4652f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *inlen, 4653f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ltc_asn1_list *list, 4654f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long outlen); 4655f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4656f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4657f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 4658f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\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 4659f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwill have the \textit{used} flag set to non--zero to reflect it was the data type decoded. 4660f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4661f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ASN.1 Flexi Decoder} 4662f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 4663f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe 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 4664f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfree form. 4665f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4666f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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} 4667f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand \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 4668f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectencoded in a SEQUENCE are stored as a child element. 4669f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4670f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen 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 4671f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpointer points to a new list of items contained within the object. 4672f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4673f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_decode\_sequence\_flexi()} 4674f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4675f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint der_decode_sequence_flexi(const unsigned char *in, 4676f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *inlen, 4677f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ltc_asn1_list **out); 4678f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4679f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4680f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 4681f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectall required memory for the decoding. It stores the number of octets read back into \textit{inlen}. 4682f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4683f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 4684f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectnormally. 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}). 4685f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4686f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAn invalid decoding will terminate the process, and free the allocated memory automatically. 4687f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4688f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\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 4689f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecthave 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} 4690f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpointer. Currently no function in LibTomCrypt provides this ability. 4691f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4692f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Sample Decoding} 4693f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSuppose we decode the following structure: 4694f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 4695f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4696f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectUser ::= SEQUENCE { 4697f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project Name IA5 STRING 4698f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project LoginToken SEQUENCE { 4699f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project passwdHash OCTET STRING 4700f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project pubkey ECCPublicKey 4701f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 4702f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project LastOn UTCTIME 4703f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 4704f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4705f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 4706f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{flushleft}and we decoded it with the following code:\end{flushleft} 4707f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4708f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 4709f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4710f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectunsigned char inbuf[MAXSIZE]; 4711f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectunsigned long inbuflen; 4712f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectltc_asn1_list *list; 4713f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint err; 4714f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4715f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/* somehow fill inbuf/inbuflen */ 4716f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectif ((err = der_decode_sequence_flexi(inbuf, inbuflen, &list)) != CRYPT_OK) { 4717f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project printf("Error decoding: %s\n", error_to_string(err)); 4718f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project exit(EXIT_FAILURE); 4719f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 4720f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4721f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 4722f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4723f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAt 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 4724f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectnode with the following code will bring us to the \textit{Name} portion of the SEQUENCE: 4725f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 4726f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4727f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectlist = list->child; 4728f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4729f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 4730f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNow \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 4731f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthat 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. 4732f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWe can walk to this node with the following code: 4733f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 4734f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4735f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/* list already pointing to 'Name' */ 4736f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectlist = list->next->child; 4737f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4738f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 4739f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAt 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. 4740f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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: 4741f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 4742f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4743f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectlist = list->parent->next; 4744f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4745f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 4746f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAt 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 4747f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcan walk up and down the nodes without keeping pointers lying around. 4748f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4749f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4750f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4751f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4752f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4753f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Free'ing a Flexi List} 4754f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo free the list use the following function. 4755f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4756f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{der\_sequence\_free()} 4757f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4758f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectvoid der_sequence_free(ltc_asn1_list *in); 4759f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4760f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4761f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will free all of the memory allocated by der\_decode\_sequence\_flexi(). 4762f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4763f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Password Based Cryptography} 4764f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{PKCS \#5} 4765f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{PKCS \#5} 4766f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn order to securely handle user passwords for the purposes of creating session keys and chaining IVs the PKCS \#5 was drafted. PKCS \#5 4767f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectis made up of two algorithms, Algorithm One and Algorithm Two. Algorithm One is the older fairly limited algorithm which has been implemented 4768f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfor completeness. Algorithm Two is a bit more modern and more flexible to work with. 4769f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4770f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Algorithm One} 4771f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAlgorithm One accepts as input a password, an 8--byte salt, and an iteration counter. The iteration counter is meant to act as delay for 4772f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpeople trying to brute force guess the password. The higher the iteration counter the longer the delay. This algorithm also requires a hash 4773f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectalgorithm and produces an output no longer than the output of the hash. 4774f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4775f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pkcs\_5\_alg1()} 4776f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{alltt} 4777f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pkcs_5_alg1(const unsigned char *password, 4778f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long password_len, 4779f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *salt, 4780f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int iteration_count, 4781f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 4782f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4783f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen) 4784f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{alltt} 4785f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhere \textit{password} is the user's password. Since the algorithm allows binary passwords you must also specify the length in \textit{password\_len}. 4786f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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 4787f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecton the password. The \textit{hash\_idx} is the index of the hash you wish to use in the descriptor table. 4788f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4789f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 4790f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectit is set to the number of bytes stored. If it is smaller than not all of the hash output is stored in \textit{out}. 4791f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4792f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Algorithm Two} 4793f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4794f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAlgorithm Two is the recommended algorithm for this task. It allows variable length salts, and can produce outputs larger than the 4795f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecthash functions output. As such, it can easily be used to derive session keys for ciphers and MACs as well initial vectors as required 4796f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfrom a single password and invocation of this algorithm. 4797f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4798f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{pkcs\_5\_alg2()} 4799f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{alltt} 4800f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint pkcs_5_alg2(const unsigned char *password, 4801f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long password_len, 4802f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *salt, 4803f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long salt_len, 4804f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int iteration_count, 4805f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int hash_idx, 4806f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4807f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen) 4808f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{alltt} 4809f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhere \textit{password} is the users password. Since the algorithm allows binary passwords you must also specify the length in \textit{password\_len}. 4810f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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 4811f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecton 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 4812f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{outlen} is stored in \textit{out}. 4813f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4814f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4815f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/* demo to show how to make session state material 4816f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project * from a password */ 4817f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project#include <tomcrypt.h> 4818f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint main(void) 4819f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project{ 4820f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char password[100], salt[100], 4821f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project cipher_key[16], cipher_iv[16], 4822f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project mac_key[16], outbuf[48]; 4823f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int err, hash_idx; 4824f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long outlen, password_len, salt_len; 4825f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4826f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* register hash and get it's idx .... */ 4827f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4828f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* get users password and make up a salt ... */ 4829f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4830f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* create the material (100 iterations in algorithm) */ 4831f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project outlen = sizeof(outbuf); 4832f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project if ((err = pkcs_5_alg2(password, password_len, salt, 4833f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project salt_len, 100, hash_idx, outbuf, 4834f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project &outlen)) 4835f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project != CRYPT_OK) { 4836f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* error handle */ 4837f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project } 4838f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4839f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* now extract it */ 4840f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project memcpy(cipher_key, outbuf, 16); 4841f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project memcpy(cipher_iv, outbuf+16, 16); 4842f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project memcpy(mac_key, outbuf+32, 16); 4843f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4844f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* use material (recall to store the salt in the output) */ 4845f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} 4846f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4847f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4848f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{Miscellaneous} 4849f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Base64 Encoding and Decoding} 4850f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe library provides functions to encode and decode a RFC 1521 base--64 coding scheme. The characters used in the mappings are: 4851f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4852f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/ 4853f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4854f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThose characters are supported in the 7-bit ASCII map, which means they can be used for transport over 4855f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcommon e-mail, usenet and HTTP mediums. The format of an encoded stream is just a literal sequence of ASCII characters 4856f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwhere a group of four represent 24-bits of input. The first four chars of the encoders output is the length of the 4857f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectoriginal input. After the first four characters is the rest of the message. 4858f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4859f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectOften, it is desirable to line wrap the output to fit nicely in an e-mail or usenet posting. The decoder allows you to 4860f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectput any character (that is not in the above sequence) in between any character of the encoders output. You may not however, 4861f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbreak up the first four characters. 4862f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4863f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo encode a binary string in base64 call: 4864f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{base64\_encode()} \index{base64\_decode()} 4865f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4866f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint base64_encode(const unsigned char *in, 4867f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len, 4868f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4869f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4870f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4871f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhere \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 4872f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto calling this function and it sets the length of the base64 output in \textit{outlen} when it is done. To decode a base64 4873f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstring call: 4874f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4875f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint base64_decode(const unsigned char *in, 4876f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len, 4877f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 4878f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 4879f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4880f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4881f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Primality Testing} 4882f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Primality Testing} 4883f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe library includes primality testing and random prime functions as well. The primality tester will perform the test in 4884f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttwo phases. First it will perform trial division by the first few primes. Second it will perform eight rounds of the 4885f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectRabin-Miller primality testing algorithm. If the candidate passes both phases it is declared prime otherwise it is declared 4886f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcomposite. No prime number will fail the two phases but composites can. Each round of the Rabin-Miller algorithm reduces 4887f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe probability of a pseudo-prime by $1 \over 4$ therefore after sixteen rounds the probability is no more than 4888f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$\left ( { 1 \over 4 } \right )^{8} = 2^{-16}$. In practice the probability of error is in fact much lower than that. 4889f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4890f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen 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}. 4891f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn essence a table of machine-word sized residues are kept of a candidate modulo a set of primes. When the candidate 4892f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectis rejected and ultimately incremented to test the next number the residues are updated without using multi-word precision 4893f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmath operations. As a result the routine can scan ahead to the next number required for testing with very little work 4894f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectinvolved. 4895f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4896f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn the event that a composite did make it through it would most likely cause the the algorithm trying to use it to fail. For 4897f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectinstance, in RSA two primes $p$ and $q$ are required. The order of the multiplicative sub-group (modulo $pq$) is given 4898f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectas $\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 4899f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwill not be able to sign or decrypt messages at all. Suppose $p$ was prime and $q$ was composite this is just a variation of 4900f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe multi-prime RSA. Suppose $q = rs$ for two primes $r$ and $s$ then $\phi(pq) = (p - 1)(r - 1)(s - 1)$ which clearly is 4901f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectnot equal to $(p - 1)(rs - 1)$. 4902f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4903f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese are not technically part of the LibTomMath library but this is the best place to document them. 4904f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo test if a \textit{mp\_int} is prime call: 4905f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4906f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint is_prime(mp_int *N, int *result); 4907f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4908f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis puts a one in \textit{result} if the number is probably prime, otherwise it places a zero in it. It is assumed that if 4909f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectit returns an error that the value in \textit{result} is undefined. To make 4910f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecta random prime call: 4911f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 4912f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectint rand_prime( mp_int *N, 4913f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len, 4914f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng, 4915f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int wprng); 4916f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 4917f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhere \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 4918f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto 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 4919f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textit{len = -128} to the function. Upon success it will return {\bf CRYPT\_OK} and \textit{N} will contain an integer which 4920f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectis very likely prime. 4921f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4922f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{Programming Guidelines} 4923f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4924f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Secure Pseudo Random Number Generators} 4925f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectProbably the single most vulnerable point of any cryptosystem is the PRNG. Without one, generating and protecting secrets 4926f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwould be impossible. The requirement that one be setup correctly is vitally important, and to address this point the library 4927f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdoes provide two RNG sources that will address the largest amount of end users as possible. The \textit{sprng} PRNG provides an easy to 4928f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectaccess source of entropy for any application on a UNIX (and the like) or Windows computer. 4929f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4930f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectHowever, when the end user is not on one of these platforms, the application developer must address the issue of finding 4931f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectentropy. This manual is not designed to be a text on cryptography. I would just like to highlight that when you design 4932f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecta cryptosystem make sure the first problem you solve is getting a fresh source of entropy. 4933f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4934f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Preventing Trivial Errors} 4935f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTwo simple ways to prevent trivial errors is to prevent overflows, and to check the return values. All of the functions 4936f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwhich output variable length strings will require you to pass the length of the destination. If the size of your output 4937f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbuffer is smaller than the output it will report an error. Therefore, make sure the size you pass is correct! 4938f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4939f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAlso, virtually all of the functions return an error code or {\bf CRYPT\_OK}. You should detect all errors, as simple 4940f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttypos can cause algorithms to fail to work as desired. 4941f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4942f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Registering Your Algorithms} 4943f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo avoid linking and other run--time errors it is important to register the ciphers, hashes and PRNGs you intend to use 4944f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbefore you try to use them. This includes any function which would use an algorithm indirectly through a descriptor table. 4945f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4946f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectA neat bonus to the registry system is that you can add external algorithms that are not part of the library without 4947f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecthaving to hack the library. For example, suppose you have a hardware specific PRNG on your system. You could easily 4948f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwrite the few functions required plus a descriptor. After registering your PRNG, all of the library functions that 4949f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectneed a PRNG can instantly take advantage of it. The same applies for ciphers, hashes, and bignum math routines. 4950f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4951f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Key Sizes} 4952f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4953f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Symmetric Ciphers} 4954f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectFor 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 4955f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectis not a hard thing to do. As a good rule of thumb do not use a key smaller than 128 bits. 4956f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4957f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Asymmetric Ciphers} 4958f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe following chart gives the work factor for solving a DH/RSA public key using the NFS. The work factor for a key of order 4959f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$n$ is estimated to be 4960f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{equation} 4961f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecte^{1.923 \cdot ln(n)^{1 \over 3} \cdot ln(ln(n))^{2 \over 3}} 4962f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{equation} 4963f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4964f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote that $n$ is not the bit-length but the magnitude. For example, for a 1024-bit key $n = 2^{1024}$. The work required 4965f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectis: 4966f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{figure}[here] 4967f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{center} 4968f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{tabular}{|c|c|} 4969f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline RSA/DH Key Size (bits) & Work Factor ($log_2$) \\ 4970f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 512 & 63.92 \\ 4971f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 768 & 76.50 \\ 4972f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 1024 & 86.76 \\ 4973f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 1536 & 103.37 \\ 4974f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 2048 & 116.88 \\ 4975f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 2560 & 128.47 \\ 4976f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 3072 & 138.73 \\ 4977f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 4096 & 156.49 \\ 4978f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 4979f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{tabular} 4980f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{center} 4981f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\caption{RSA/DH Key Strength} 4982f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{figure} 4983f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 4984f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe work factor for ECC keys is much higher since the best attack is still fully exponential. Given a key of magnitude 4985f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project$n$ it requires $\sqrt n$ work. The following table summarizes the work required: 4986f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{figure}[here] 4987f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{center} 4988f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{tabular}{|c|c|} 4989f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline ECC Key Size (bits) & Work Factor ($log_2$) \\ 4990f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 112 & 56 \\ 4991f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 128 & 64 \\ 4992f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 160 & 80 \\ 4993f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 192 & 96 \\ 4994f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 224 & 112 \\ 4995f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 256 & 128 \\ 4996f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 384 & 192 \\ 4997f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 521 & 260.5 \\ 4998f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 4999f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{tabular} 5000f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{center} 5001f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\caption{ECC Key Strength} 5002f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{figure} 5003f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5004f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectUsing the above tables the following suggestions for key sizes seems appropriate: 5005f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{center} 5006f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{tabular}{|c|c|c|} 5007f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline Security Goal & RSA/DH Key Size (bits) & ECC Key Size (bits) \\ 5008f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline Near term & 1024 & 160 \\ 5009f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline Short term & 1536 & 192 \\ 5010f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline Long Term & 2560 & 384 \\ 5011f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \hline 5012f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{tabular} 5013f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{center} 5014f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5015f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Thread Safety} 5016f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe library is not fully thread safe but several simple precautions can be taken to avoid any problems. The registry functions 5017f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsuch as register\_cipher() are not thread safe no matter what you do. It is best to call them from your programs initialization 5018f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcode before threads are initiated. 5019f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5020f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe rest of the code uses state variables you must pass it such as hash\_state, hmac\_state, etc. This means that if each 5021f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthread has its own state variables then they will not affect each other, and are fully thread safe. This is fairly simple with symmetric ciphers 5022f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand hashes. 5023f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5024f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{LTC\_PTHREAD} 5025f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe only sticky issue is a shared PRNG which can be alleviated with the careful use of mutex devices. Defining LTC\_PTHREAD for instance, enables 5026f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpthreads based mutex locking in various routines such as the Yarrow and Fortuna PRNGs, the fixed point ECC multiplier, and other routines. 5027f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5028f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{Configuring and Building the Library} 5029f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Introduction} 5030f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe library is fairly flexible about how it can be built, used, and generally distributed. Additions are being made with 5031f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecteach new release that will make the library even more flexible. Each of the classes of functions can be disabled during 5032f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe build process to make a smaller library. This is particularly useful for shared libraries. 5033f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5034f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAs of v1.06 of the library, the build process has been moved to two steps for the typical LibTomCrypt application. This is because 5035f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLibTomCrypt no longer provides a math API on its own and relies on third party libraries (such as LibTomMath, GnuMP, or TomsFastMath). 5036f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5037f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe build process now consists of installing a math library first, and then building and installing LibTomCrypt with a math library 5038f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectconfigured. Note that LibTomCrypt can be built with no internal math descriptors. This means that one must be provided at either 5039f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbuild, or run time for the application. LibTomCrypt comes with three math descriptors that provide a standard interface to math 5040f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectlibraries. 5041f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5042f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Makefile variables} 5043f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5044f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAll GNU driven makefiles (including the makefile for ICC) use a set of common variables to control the build and install process. Most of the 5045f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsettings can be overwritten from the command line which makes custom installation a breeze. 5046f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5047f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{MAKE}\index{CC}\index{AR} 5048f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{MAKE, CC and AR} 5049f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe MAKE, CC and AR flags can all be overwritten. They default to \textit{make}, \textit{\$CC} and \textit{\$AR} respectively. 5050f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectChanging MAKE allows you to change what program will be invoked to handle sub--directories. For example, this 5051f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5052f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5053f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectMAKE=gmake gmake install 5054f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5055f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5056f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{flushleft} will build and install the libraries with the \textit{gmake} tool. Similarly, \end{flushleft} 5057f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5058f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5059f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCC=arm-gcc AR=arm-ar make 5060f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5061f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5062f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{flushleft} will build the library using \textit{arm--gcc} as the compiler and \textit{arm--ar} as the archiver. \end{flushleft} 5063f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5064f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{IGNORE\_SPEED} 5065f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{IGNORE\_SPEED} 5066f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen \textbf{IGNORE\_SPEED} has been defined the default optimization flags for CFLAGS will be disabled which allows the developer to specify new 5067f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCFLAGS on the command line. E.g. to add debugging 5068f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5069f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5070f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCFLAGS="-g3" make IGNORE_SPEED=1 5071f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5072f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5073f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will turn off optimizations and add \textit{-g3} to the CFLAGS which enables debugging. 5074f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5075f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{LIBNAME and LIBNAME\_S} 5076f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{LIBNAME} \index{LIBNAME\_S} 5077f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\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 5078f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectshared. 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. 5079f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5080f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{LIBTEST} \index{LIBTEST\_S} 5081f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSimilarly \textbf{LIBTEST} and \textbf{LIBTEST\_S} are the names for the profiling and testing library. The default is \textit{libtomcrypt\_prof.a} for 5082f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstatic and \textit{libtomcrypt\_prof.la} for shared. 5083f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5084f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Installation Directories} 5085f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{DESTDIR} \index{LIBPATH} \index{INCPATH} \index{DATADIR} 5086f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textbf{DESTDIR} is the prefix for the installation directories. It defaults to an empty string. \textbf{LIBPATH} is the prefix for the library 5087f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdirectory which defaults to \textit{/usr/lib}. \textbf{INCPATH} is the prefix for the header file directory which defaults to \textit{/usr/include}. 5088f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textbf{DATADIR} is the prefix for the data (documentation) directory which defaults to \textit{/usr/share/doc/libtomcrypt/pdf}. 5089f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5090f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAll four can be used to create custom install locations depending on the nature of the OS and file system in use. 5091f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5092f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5093f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmake LIBPATH=/home/tom/project/lib INCPATH=/home/tom/project/include \ 5094f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project DATAPATH=/home/tom/project/docs install 5095f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5096f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5097f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will build the library and install it to the directories under \textit{/home/tom/project/}. e.g. 5098f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5099f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 5100f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5101f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/home/tom/project/: 5102f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttotal 1 5103f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdrwxr-xr-x 2 tom users 80 Jul 30 16:02 docs 5104f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdrwxr-xr-x 2 tom users 528 Jul 30 16:02 include 5105f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdrwxr-xr-x 2 tom users 80 Jul 30 16:02 lib 5106f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5107f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/home/tom/project/docs: 5108f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttotal 452 5109f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 459009 Jul 30 16:02 crypt.pdf 5110f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5111f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/home/tom/project/include: 5112f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttotal 132 5113f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 2482 Jul 30 16:02 tomcrypt.h 5114f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 702 Jul 30 16:02 tomcrypt_argchk.h 5115f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 2945 Jul 30 16:02 tomcrypt_cfg.h 5116f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 22763 Jul 30 16:02 tomcrypt_cipher.h 5117f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 5174 Jul 30 16:02 tomcrypt_custom.h 5118f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 11314 Jul 30 16:02 tomcrypt_hash.h 5119f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 11571 Jul 30 16:02 tomcrypt_mac.h 5120f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 13614 Jul 30 16:02 tomcrypt_macros.h 5121f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 14714 Jul 30 16:02 tomcrypt_math.h 5122f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 632 Jul 30 16:02 tomcrypt_misc.h 5123f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 10934 Jul 30 16:02 tomcrypt_pk.h 5124f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 2634 Jul 30 16:02 tomcrypt_pkcs.h 5125f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 7067 Jul 30 16:02 tomcrypt_prng.h 5126f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 1467 Jul 30 16:02 tomcrypt_test.h 5127f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5128f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/home/tom/project/lib: 5129f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttotal 1073 5130f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project-rwxr-xr-x 1 tom users 1096284 Jul 30 16:02 libtomcrypt.a 5131f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5132f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 5133f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5134f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Extra libraries} 5135f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{EXTRALIBS} 5136f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textbf{EXTRALIBS} specifies any extra libraries required to link the test programs and shared libraries. They are specified in the notation 5137f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthat GCC expects for global archives. 5138f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5139f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5140f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCFLAGS="-DTFM_DESC -DUSE_TFM" EXTRALIBS=-ltfm make install \ 5141f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project test timing 5142f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5143f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5144f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will install the library using the TomsFastMath library and link the \textit{libtfm.a} library out of the default library search path. The two 5145f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdefines are explained below. You can specify multiple archives (say if you want to support two math libraries, or add on additional code) to 5146f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe \textbf{EXTRALIBS} variable by separating them by a space. 5147f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5148f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote that \textbf{EXTRALIBS} is not required if you are only making and installing the static library but none of the test programs. 5149f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5150f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Building a Static Library} 5151f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5152f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectBuilding a static library is fairly trivial as it only requires one invocation of the GNU make command. 5153f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5154f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5155f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCFLAGS="-DTFM_DESC" make install 5156f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5157f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5158f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThat will build LibTomCrypt (including the TomsFastMath descriptor), and install it in the default locations indicated previously. You can enable 5159f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe built--in LibTomMath descriptor as well (or in place of the TomsFastMath descriptor). Similarly, you can build the library with no built--in 5160f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmath descriptors. 5161f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5162f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5163f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmake install 5164f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5165f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5166f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn 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 5167f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpublic key functions. 5168f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5169f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote that even if you include the built--in descriptors you must link against the source library as well. 5170f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5171f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5172f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectgcc -DTFM_DESC myprogram.c -ltomcrypt -ltfm -o myprogram 5173f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5174f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5175f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will compile \textit{myprogram} and link it against the LibTomCrypt library as well as TomsFastMath (which must have been previously installed). Note that 5176f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwe 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 5177f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectgiving warnings. 5178f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5179f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Building a Shared Library} 5180f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5181f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectLibTomCrypt 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 5182f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthat you \textbf{must} specify the \textbf{EXTRALIBS} variable at install time. 5183f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5184f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5185f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCFLAGS="-DTFM_DESC" EXTRALIBS=-ltfm make -f makefile.shared install 5186f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5187f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5188f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 5189f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectshared build process requires libtool to be installed. 5190f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5191f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Header Configuration} 5192f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 5193f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstored in \textit{tomcrypt\_custom.h} which allow the enabling and disabling of various algorithms. 5194f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5195f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{ARGTYPE} 5196f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis lets you control how the LTC\_ARGCHK macro will behave. The macro is used to check pointers inside the functions against 5197f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNULL. There are four settings for ARGTYPE. When set to 0, it will have the default behaviour of printing a message to 5198f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstderr and raising a SIGABRT signal. This is provided so all platforms that use LibTomCrypt can have an error that functions 5199f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectsimilarly. When set to 1, it will simply pass on to the assert() macro. When set to 2, the macro will display the error to 5200f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstderr then return execution to the caller. This could lead to a segmentation fault (e.g. when a pointer is \textbf{NULL}) but is useful 5201f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectif 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 5202f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto 4, it will return CRYPT\_INVALID\_ARG to the caller. 5203f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5204f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Endianess} 5205f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere are five macros related to endianess issues. For little endian platforms define, \textbf{ENDIAN\_LITTLE}. For big endian 5206f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectplatforms define \textbf{ENDIAN\_BIG}. Similarly when the default word size of an \textit{unsigned long} is 32-bits define \textbf{ENDIAN\_32BITWORD} 5207f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projector define \textbf{ENDIAN\_64BITWORD} when its 64-bits. If you do not define any of them the library will automatically use \textbf{ENDIAN\_NEUTRAL} 5208f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwhich will work on all platforms. 5209f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5210f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCurrently LibTomCrypt will detect x86-32, x86-64, MIPS R5900, SPARC and SPARC64 running GCC as well as x86-32 running MSVC. 5211f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5212f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{The Configure Script} 5213f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere are also options you can specify from the \textit{tomcrypt\_custom.h} header file. 5214f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5215f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{X memory routines} 5216f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{XMALLOC}\index{XCALLOC}\index{XREALLOC}\index{XFREE} 5217f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAt the top of tomcrypt\_custom.h are a series of macros denoted as XMALLOC, XCALLOC, XREALLOC, XFREE, and so on. They resolve to 5218f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe name of the respective functions from the standard C library by default. This lets you substitute in your own memory routines. 5219f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIf you substitute in your own functions they must behave like the standard C library functions in terms of what they expect as input and 5220f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectoutput. 5221f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5222f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese 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} 5223f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbios code uses these macros to redirect to very compact heap and string operations. 5224f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5225f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{X clock routines} 5226f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe rng\_get\_bytes() function can call a function that requires the clock() function. These macros let you override 5227f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe default clock() used with a replacement. By default the standard C library clock() function is used. 5228f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5229f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{LTC\_NO\_FILE} 5230f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectDuring 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 5231f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfunctions and instead simply return CRYPT\_NOP. This should help resolve any linker errors stemming from a lack of 5232f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfile I/O on embedded platforms. 5233f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5234f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{LTC\_CLEAN\_STACK} 5235f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen this functions is defined the functions that store key material on the stack will clean up afterwards. 5236f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAssumes that you have no memory paging with the stack. 5237f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5238f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{LTC\_TEST} 5239f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen this has been defined the various self--test functions (for ciphers, hashes, prngs, etc) are included in the build. This is the default configuration. 5240f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIf LTC\_NO\_TEST has been defined, the testing routines will be compacted and only return CRYPT\_NOP. 5241f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5242f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{LTC\_NO\_FAST} 5243f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen this has been defined the library will not use faster word oriented operations. By default, they are only enabled for platforms 5244f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwhich can be auto-detected. This macro ensures that they are never enabled. 5245f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5246f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{LTC\_FAST} 5247f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis mode (auto-detected with x86\_32,x86\_64 platforms with GCC or MSVC) configures various routines such as ctr\_encrypt() or 5248f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcbc\_encrypt() that it can safely XOR multiple octets in one step by using a larger data type. This has the benefit of 5249f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcutting down the overhead of the respective functions. 5250f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5251f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis mode does have one downside. It can cause unaligned reads from memory if you are not careful with the functions. This is why 5252f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectit has been enabled by default only for the x86 class of processors where unaligned accesses are allowed. Technically LTC\_FAST 5253f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectis not \textit{portable} since unaligned accesses are not covered by the ISO C specifications. 5254f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5255f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn practice however, you can use it on pretty much any platform (even MIPS) with care. 5256f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5257f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectBy design the \textit{fast} mode functions won't get unaligned on their own. For instance, if you call ctr\_encrypt() right after calling 5258f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectctr\_start() and all the inputs you gave are aligned than ctr\_encrypt() will perform aligned memory operations only. However, if you 5259f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcall ctr\_encrypt() with an odd amount of plaintext then call it again the CTR pad (the IV) will be partially used. This will 5260f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcause the ctr routine to first use up the remaining pad bytes. Then if there are enough plaintext bytes left it will use 5261f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwhole word XOR operations. These operations will be unaligned. 5262f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5263f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 5264f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCTR'ing a long stream process it in blocks of (say) four kilobytes and handle any remaining incomplete blocks at the end of the stream. 5265f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5266f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{LTC\_FAST\_TYPE} 5267f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIf 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 5268f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdata type you can perform integer operations with. Ideally it should be four or eight bytes since it must properly divide the size 5269f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof 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 5270f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectuse this mode. So sad. 5271f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5272f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{LTC\_NO\_ASM} 5273f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen 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 5274f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcannot handle all of the assembler functions. 5275f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5276f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Symmetric Ciphers, One-way Hashes, PRNGS and Public Key Functions} 5277f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThere are a plethora of macros for the ciphers, hashes, PRNGs and public key functions which are fairly 5278f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectself-explanatory. When they are defined the functionality is included otherwise it is not. There are some 5279f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdependency issues which are noted in the file. For instance, Yarrow requires CTR chaining mode, a block 5280f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcipher and a hash function. 5281f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5282f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAlso see technical note number five for more details. 5283f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5284f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{LTC\_EASY} 5285f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen defined the library is configured to build fewer algorithms and modes. Mostly it sticks to NIST and ANSI approved algorithms. See 5286f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe header file \textit{tomcrypt\_custom.h} for more details. It is meant to provide literally an easy method of trimming the library 5287f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbuild to the most minimum of useful functionality. 5288f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5289f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{TWOFISH\_SMALL and TWOFISH\_TABLES} 5290f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTwofish is a 128-bit symmetric block cipher that is provided within the library. The cipher itself is flexible enough 5291f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto allow some trade-offs in the implementation. When TWOFISH\_SMALL is defined the scheduled symmetric key for Twofish 5292f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrequires only 200 bytes of memory. This is achieved by not pre-computing the substitution boxes. Having this 5293f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdefined will also greatly slow down the cipher. When this macro is not defined Twofish will pre-compute the 5294f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttables at a cost of 4KB of memory. The cipher will be much faster as a result. 5295f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5296f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen TWOFISH\_TABLES is defined the cipher will use pre-computed (and fixed in code) tables required to work. This is 5297f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectuseful when TWOFISH\_SMALL is defined as the table values are computed on the fly. When this is defined the code size 5298f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwill increase by approximately 500 bytes. If this is defined but TWOFISH\_SMALL is not the cipher will still work but 5299f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectit will not speed up the encryption or decryption functions. 5300f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5301f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{GCM\_TABLES} 5302f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen defined GCM will use a 64KB table (per GCM state) which will greatly speed up the per--packet latency. 5303f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIt also increases the initialization time and is not suitable when you are going to use a key a few times only. 5304f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5305f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{GCM\_TABLES\_SSE2} 5306f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{SSE2} 5307f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen 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 5308f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectof GCM output on both the AMD64 and Intel Pentium 4 platforms. Requires GCC and an SSE2 equipped platform. 5309f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5310f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{LTC\_SMALL\_CODE} 5311f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen this is defined some of the code such as the Rijndael and SAFER+ ciphers are replaced with smaller code variants. 5312f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese variants are slower but can save quite a bit of code space. 5313f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5314f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{LTC\_PTHREAD} 5315f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen this is activated all of the descriptor table functions will use pthread locking to ensure thread safe updates to the tables. Note that 5316f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectit doesn't prevent a thread that is passively using a table from being messed up by another thread that updates the table. 5317f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5318f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectGenerally the rule of thumb is to setup the tables once at startup and then leave them be. This added build flag simply makes updating 5319f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe tables safer. 5320f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5321f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{LTC\_ECC\_TIMING\_RESISTANT} 5322f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen this has been defined the ECC point multiplier (built--in to the library) will use a timing resistant point multiplication 5323f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectalgorithm which prevents leaking key bits of the private key (scalar). It is a slower algorithm but useful for situations 5324f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectwhere timing side channels pose a significant threat. 5325f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5326f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Math Descriptors} 5327f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe library comes with three math descriptors that allow you to interface the public key cryptography API to freely available math 5328f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectlibraries. When \textbf{GMP\_DESC}, \textbf{LTM\_DESC}, or \textbf{TFM\_DESC} are defined 5329f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdescriptors for the respective library are built and included in the library as \textit{gmp\_desc}, \textit{ltm\_desc}, or \textit{tfm\_desc} respectively. 5330f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5331f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectIn the test demos that use the libraries the additional flags \textbf{USE\_GMP}, \textbf{USE\_LTM}, and \textbf{USE\_TFM} can be defined 5332f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto tell the program which library to use. Only one of the USE flags can be defined at once. 5333f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5334f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{GMP\_DESC} \index{USE\_GMP} \index{LTM\_DESC} \index{TFM\_DESC} \index{USE\_LTM} \index{USE\_TFM} 5335f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 5336f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5337f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectCFLAGS="-DGMP_DESC -DLTM_DESC -DTFM_DESC -DUSE_TFM" \ 5338f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectEXTRALIBS="-lgmp -ltommath -ltfm" make -f makefile.shared install timing 5339f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5340f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 5341f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5342f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThat will build and install the library with all descriptors (and link against all), but only use TomsFastMath in the timing demo. 5343f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5344f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\chapter{Optimizations} 5345f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Introduction} 5346f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 5347f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectrequire 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 5348f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto 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 5349f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectabout the platform, etc... 5350f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5351f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThat 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 5352f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectportable routines. For instance, hand optimized assembler versions of AES could be provided. Any existing function that uses the cipher could automatically use 5353f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe optimized code without re--writing. This also paves the way for hardware drivers that can access hardware accelerated cryptographic devices. 5354f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5355f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAt 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 5356f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto 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 5357f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectdevelopment simple. In most dependent routines all an end developer has to do is register\_XXX() the descriptor and they are set. 5358f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5359f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Ciphers} 5360f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe ciphers in LibTomCrypt are accessed through the ltc\_cipher\_descriptor structure. 5361f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5362f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\label{sec:cipherdesc} 5363f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 5364f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5365f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstruct ltc_cipher_descriptor { 5366f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** name of cipher */ 5367f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project char *name; 5368f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5369f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** internal ID */ 5370f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char ID; 5371f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5372f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** min keysize (octets) */ 5373f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int min_key_length, 5374f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5375f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** max keysize (octets) */ 5376f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project max_key_length, 5377f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5378f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** block size (octets) */ 5379f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project block_length, 5380f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5381f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** default number of rounds */ 5382f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project default_rounds; 5383f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5384f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Setup the cipher 5385f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param key The input symmetric key 5386f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param keylen The length of the input key (octets) 5387f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param num_rounds The requested number of rounds (0==default) 5388f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param skey [out] The destination of the scheduled key 5389f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5390f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5391f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*setup)(const unsigned char *key, 5392f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int keylen, 5393f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int num_rounds, 5394f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *skey); 5395f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5396f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Encrypt a block 5397f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param pt The plaintext 5398f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param ct [out] The ciphertext 5399f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param skey The scheduled key 5400f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5401f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5402f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*ecb_encrypt)(const unsigned char *pt, 5403f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 5404f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *skey); 5405f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5406f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Decrypt a block 5407f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param ct The ciphertext 5408f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param pt [out] The plaintext 5409f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param skey The scheduled key 5410f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5411f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5412f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*ecb_decrypt)(const unsigned char *ct, 5413f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, 5414f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *skey); 5415f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5416f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Test the block cipher 5417f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful, 5418f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project CRYPT_NOP if self-testing has been disabled 5419f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5420f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*test)(void); 5421f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5422f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Terminate the context 5423f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param skey The scheduled key 5424f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5425f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void (*done)(symmetric_key *skey); 5426f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5427f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Determine a key size 5428f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param keysize [in/out] The size of the key desired 5429f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project The suggested size 5430f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5431f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5432f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*keysize)(int *keysize); 5433f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5434f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/** Accelerators **/ 5435f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Accelerated ECB encryption 5436f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param pt Plaintext 5437f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param ct Ciphertext 5438f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param blocks The number of complete blocks to process 5439f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param skey The scheduled key context 5440f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5441f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5442f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*accel_ecb_encrypt)(const unsigned char *pt, 5443f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 5444f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long blocks, 5445f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *skey); 5446f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5447f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Accelerated ECB decryption 5448f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param pt Plaintext 5449f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param ct Ciphertext 5450f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param blocks The number of complete blocks to process 5451f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param skey The scheduled key context 5452f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5453f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5454f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*accel_ecb_decrypt)(const unsigned char *ct, 5455f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, 5456f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long blocks, 5457f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *skey); 5458f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5459f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Accelerated CBC encryption 5460f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param pt Plaintext 5461f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param ct Ciphertext 5462f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param blocks The number of complete blocks to process 5463f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param IV The initial value (input/output) 5464f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param skey The scheduled key context 5465f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5466f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5467f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*accel_cbc_encrypt)(const unsigned char *pt, 5468f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 5469f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long blocks, 5470f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *IV, 5471f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *skey); 5472f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5473f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Accelerated CBC decryption 5474f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param pt Plaintext 5475f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param ct Ciphertext 5476f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param blocks The number of complete blocks to process 5477f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param IV The initial value (input/output) 5478f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param skey The scheduled key context 5479f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5480f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5481f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*accel_cbc_decrypt)(const unsigned char *ct, 5482f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, 5483f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long blocks, 5484f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *IV, 5485f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *skey); 5486f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5487f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Accelerated CTR encryption 5488f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param pt Plaintext 5489f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param ct Ciphertext 5490f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param blocks The number of complete blocks to process 5491f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param IV The initial value (input/output) 5492f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param mode little or big endian counter (mode=0 or mode=1) 5493f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param skey The scheduled key context 5494f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5495f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5496f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*accel_ctr_encrypt)(const unsigned char *pt, 5497f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 5498f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long blocks, 5499f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *IV, 5500f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int mode, 5501f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *skey); 5502f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5503f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Accelerated LRW 5504f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param pt Plaintext 5505f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param ct Ciphertext 5506f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param blocks The number of complete blocks to process 5507f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param IV The initial value (input/output) 5508f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param tweak The LRW tweak 5509f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param skey The scheduled key context 5510f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5511f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5512f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*accel_lrw_encrypt)(const unsigned char *pt, 5513f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 5514f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long blocks, 5515f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *IV, 5516f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *tweak, 5517f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *skey); 5518f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5519f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Accelerated LRW 5520f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param ct Ciphertext 5521f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param pt Plaintext 5522f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param blocks The number of complete blocks to process 5523f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param IV The initial value (input/output) 5524f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param tweak The LRW tweak 5525f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param skey The scheduled key context 5526f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5527f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5528f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*accel_lrw_decrypt)(const unsigned char *ct, 5529f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, 5530f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long blocks, 5531f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *IV, 5532f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *tweak, 5533f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *skey); 5534f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5535f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Accelerated CCM packet (one-shot) 5536f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param key The secret key to use 5537f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param keylen The length of the secret key (octets) 5538f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param uskey A previously scheduled key [can be NULL] 5539f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param nonce The session nonce [use once] 5540f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param noncelen The length of the nonce 5541f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param header The header for the session 5542f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param headerlen The length of the header (octets) 5543f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param pt [out] The plaintext 5544f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param ptlen The length of the plaintext (octets) 5545f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param ct [out] The ciphertext 5546f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param tag [out] The destination tag 5547f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param taglen [in/out] The max size and resulting size 5548f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project of the authentication tag 5549f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param direction Encrypt or Decrypt direction (0 or 1) 5550f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5551f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5552f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*accel_ccm_memory)( 5553f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 5554f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project symmetric_key *uskey, 5555f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *nonce, unsigned long noncelen, 5556f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *header, unsigned long headerlen, 5557f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, unsigned long ptlen, 5558f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 5559f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *tag, unsigned long *taglen, 5560f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int direction); 5561f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5562f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Accelerated GCM packet (one shot) 5563f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param key The secret key 5564f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param keylen The length of the secret key 5565f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param IV The initial vector 5566f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param IVlen The length of the initial vector 5567f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param adata The additional authentication data (header) 5568f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param adatalen The length of the adata 5569f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param pt The plaintext 5570f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param ptlen The length of the plaintext/ciphertext 5571f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param ct The ciphertext 5572f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param tag [out] The MAC tag 5573f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param taglen [in/out] The MAC tag length 5574f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param direction Encrypt or Decrypt mode (GCM_ENCRYPT or GCM_DECRYPT) 5575f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 5576f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5577f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*accel_gcm_memory)( 5578f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 5579f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *IV, unsigned long IVlen, 5580f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *adata, unsigned long adatalen, 5581f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *pt, unsigned long ptlen, 5582f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *ct, 5583f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *tag, unsigned long *taglen, 5584f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int direction); 5585f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5586f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Accelerated one shot OMAC 5587f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param key The secret key 5588f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param keylen The key length (octets) 5589f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param in The message 5590f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param inlen Length of message (octets) 5591f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param out [out] Destination for tag 5592f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param outlen [in/out] Initial and final size of out 5593f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 5594f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5595f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*omac_memory)( 5596f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 5597f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, unsigned long inlen, 5598f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen); 5599f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5600f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Accelerated one shot XCBC 5601f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param key The secret key 5602f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param keylen The key length (octets) 5603f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param in The message 5604f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param inlen Length of message (octets) 5605f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param out [out] Destination for tag 5606f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param outlen [in/out] Initial and final size of out 5607f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 5608f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5609f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*xcbc_memory)( 5610f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 5611f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, unsigned long inlen, 5612f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen); 5613f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5614f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Accelerated one shot F9 5615f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param key The secret key 5616f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param keylen The key length (octets) 5617f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param in The message 5618f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param inlen Length of message (octets) 5619f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param out [out] Destination for tag 5620f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param outlen [in/out] Initial and final size of out 5621f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 5622f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @remark Requires manual padding 5623f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5624f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*f9_memory)( 5625f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *key, unsigned long keylen, 5626f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, unsigned long inlen, 5627f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen); 5628f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project}; 5629f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5630f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 5631f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5632f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Name} 5633f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{find\_cipher()} 5634f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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 5635f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttables. 5636f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5637f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Internal ID} 5638f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis is a single byte Internal ID you can use to distinguish ciphers from each other. 5639f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5640f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Key Lengths} 5641f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 5642f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectand both must valid key sizes for the cipher. Values in between are not assumed to be valid though they may be. 5643f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5644f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Block Length} 5645f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe size of the ciphers plaintext or ciphertext is \textit{block\_length} and is measured in octets. 5646f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5647f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Rounds} 5648f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSome ciphers allow different number of rounds to be used. Usually you just use the default. The default round count is \textit{default\_rounds}. 5649f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5650f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Setup} 5651f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo 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 5652f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcan 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 5653f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectin \textit{skey}. 5654f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5655f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectInside 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 5656f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectones provided. Just make sure in your \textit{done()} function that you free the allocated memory. 5657f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5658f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Single block ECB} 5659f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo 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 5660f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmust make sure you do not overwrite the output before you are finished with the input. 5661f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5662f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Testing} 5663f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 5664f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\textbf{CRYPT\_NOP} to indicate that no testing was performed. 5665f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5666f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Key Sizing} 5667f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectOccasionally, 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 5668f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpointer 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 5669f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectexample, 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 5670f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project cannot be mapped to a valid key size for the cipher. 5671f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5672f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Acceleration} 5673f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 5674f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectit is not supported. In those cases the software defaults are used (using the single ECB block routines). 5675f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5676f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Accelerated ECB} 5677f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese 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 5678f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthrough the accel\_ecb\_encrypt and accel\_ecb\_decrypt pointers. The \textit{blocks} count is the number of complete blocks to process. 5679f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5680f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Accelerated CBC} 5681f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese two functions are meant for accelerated CBC encryption. These functions are accessed through the accel\_cbc\_encrypt and accel\_cbc\_decrypt pointers. 5682f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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 5683f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectupdated by the function before returning. 5684f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5685f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Accelerated CTR} 5686f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function is meant for accelerated CTR encryption. It is accessible through the accel\_ctr\_encrypt pointer. 5687f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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 5688f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectupdated by the function before returning. The \textit{mode} value indicates whether the counter is big (mode = CTR\_COUNTER\_BIG\_ENDIAN) or 5689f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectlittle (mode = CTR\_COUNTER\_LITTLE\_ENDIAN) endian. 5690f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5691f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 5692f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcalled if the following conditions are met. 5693f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5694f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{enumerate} 5695f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item The accelerator is present 5696f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item The CTR pad is empty 5697f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project \item The remaining length of the input to process is greater than or equal to the block size. 5698f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{enumerate} 5699f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5700f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \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 5701f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectpass 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 5702f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbuffer provided) before encrypting it to create the pad. 5703f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5704f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe accelerator will only be used to encrypt whole blocks. Partial blocks are always handled in software. 5705f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5706f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Accelerated LRW} 5707f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThese 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} 5708f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstate 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 5709f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto use accelerators for LRW. 5710f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5711f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhile both encrypt and decrypt accelerators are not required it is suggested as it makes lrw\_setiv() more efficient. 5712f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5713f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectNote that calling lrw\_done() will only invoke the cipher\_descriptor[].done() function on the \textit{symmetric\_key} parameter of the LRW state. That means 5714f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectif 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 5715f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe plugin solely to do LRW with the cipher. That way cipher\_descriptor[].setup() means to init LRW resources and cipher\_descriptor[].done() means to 5716f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfree them. 5717f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5718f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Accelerated CCM} 5719f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function is meant for accelerated CCM encryption or decryption. It processes the entire packet in one call. You can optimize the work flow somewhat 5720f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectby 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 5721f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfunction MUST support both key passing methods. 5722f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5723f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{center} 5724f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 5725f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{tabular}{|r|r|l|} 5726f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline \textbf{key} & \textbf{uskey} & \textbf{Source of key} \\ 5727f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline NULL & NULL & Error, not supported \\ 5728f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline non-NULL & NULL & Use key, do a key schedule \\ 5729f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline NULL & non-NULL & Use uskey, key schedule not required \\ 5730f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline non-NULL & non-NULL & Use uskey, key schedule not required \\ 5731f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\hline 5732f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{tabular} 5733f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 5734f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{center} 5735f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5736f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ccm\_memory()} This function is called when the user calls ccm\_memory(). 5737f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5738f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Accelerated GCM} 5739f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{gcm\_memory()} 5740f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function is meant for accelerated GCM encryption or decryption. It processes the entire packet in one call. Note that the setup() function will not 5741f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbe called prior to this. This function must handle scheduling the key provided on its own. It is called when the user calls gcm\_memory(). 5742f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5743f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Accelerated OMAC} 5744f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{omac\_memory()} 5745f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function is meant to perform an optimized OMAC1 (CMAC) message authentication code computation when the user calls omac\_memory(). 5746f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5747f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Accelerated XCBC-MAC} 5748f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{xcbc\_memory()} 5749f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function is meant to perform an optimized XCBC-MAC message authentication code computation when the user calls xcbc\_memory(). 5750f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5751f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Accelerated F9} 5752f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{f9\_memory()} 5753f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function is meant to perform an optimized F9 message authentication code computation when the user calls f9\_memory(). Like f9\_memory(), it requires 5754f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe caller to perform any 3GPP related padding before calling in order to ensure proper compliance with F9. 5755f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5756f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5757f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{One--Way Hashes} 5758f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe hash functions are accessed through the ltc\_hash\_descriptor structure. 5759f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5760f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 5761f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5762f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstruct ltc_hash_descriptor { 5763f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** name of hash */ 5764f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project char *name; 5765f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5766f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** internal ID */ 5767f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char ID; 5768f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5769f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Size of digest in octets */ 5770f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long hashsize; 5771f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5772f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Input block size in octets */ 5773f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long blocksize; 5774f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5775f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** ASN.1 OID */ 5776f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long OID[16]; 5777f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5778f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Length of DER encoding */ 5779f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long OIDlen; 5780f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5781f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Init a hash state 5782f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param hash The hash to initialize 5783f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5784f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5785f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*init)(hash_state *hash); 5786f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5787f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Process a block of data 5788f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param hash The hash state 5789f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param in The data to hash 5790f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param inlen The length of the data (octets) 5791f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5792f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5793f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*process)( hash_state *hash, 5794f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 5795f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen); 5796f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5797f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Produce the digest and store it 5798f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param hash The hash state 5799f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param out [out] The destination of the digest 5800f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5801f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5802f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*done)( hash_state *hash, 5803f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out); 5804f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5805f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Self-test 5806f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful, 5807f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project CRYPT_NOP if self-tests have been disabled 5808f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5809f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*test)(void); 5810f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5811f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /* accelerated hmac callback: if you need to-do 5812f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project multiple packets just use the generic hmac_memory 5813f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project and provide a hash callback 5814f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5815f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*hmac_block)(const unsigned char *key, 5816f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long keylen, 5817f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project const unsigned char *in, 5818f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 5819f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, 5820f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen); 5821f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project}; 5822f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5823f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 5824f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5825f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Name} 5826f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis is the name the hash is known by and what find\_hash() will look for. 5827f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5828f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Internal ID} 5829f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis is the internal ID byte used to distinguish the hash from other hashes. 5830f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5831f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Digest Size} 5832f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \textit{hashsize} variable indicates the length of the output in octets. 5833f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5834f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Block Size} 5835f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe \textit{blocksize} variable indicates the length of input (in octets) that the hash processes in a given 5836f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectinvocation. 5837f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5838f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{OID Identifier} 5839f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis is the universal ASN.1 Object Identifier for the hash. 5840f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5841f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Initialization} 5842f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe init function initializes the hash and prepares it to process message bytes. 5843f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5844f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Process} 5845f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis processes message bytes. The algorithm must accept any length of input that the hash would allow. The input is not 5846f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectguaranteed to be a multiple of the block size in length. 5847f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5848f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Done} 5849f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe done function terminates the hash and returns the message digest. 5850f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5851f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Acceleration} 5852f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectA compatible accelerator must allow processing data in any granularity which may require internal padding on the driver side. 5853f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5854f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{HMAC Acceleration} 5855f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe hmac\_block() callback is meant for single--shot optimized HMAC implementations. It is called directly by hmac\_memory() if present. If you need 5856f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto 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. 5857f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5858f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{Pseudo--Random Number Generators} 5859f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe pseudo--random number generators are accessible through the ltc\_prng\_descriptor structure. 5860f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5861f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 5862f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5863f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectstruct ltc_prng_descriptor { 5864f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Name of the PRNG */ 5865f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project char *name; 5866f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5867f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** size in bytes of exported state */ 5868f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int export_size; 5869f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5870f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Start a PRNG state 5871f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param prng [out] The state to initialize 5872f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5873f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5874f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*start)(prng_state *prng); 5875f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5876f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Add entropy to the PRNG 5877f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param in The entropy 5878f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param inlen Length of the entropy (octets) 5879f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param prng The PRNG state 5880f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5881f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5882f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*add_entropy)(const unsigned char *in, 5883f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 5884f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng); 5885f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5886f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Ready a PRNG state to read from 5887f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param prng The PRNG state to ready 5888f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5889f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5890f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*ready)(prng_state *prng); 5891f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5892f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Read from the PRNG 5893f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param out [out] Where to store the data 5894f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param outlen Length of data desired (octets) 5895f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param prng The PRNG state to read from 5896f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return Number of octets read 5897f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5898f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long (*read)(unsigned char *out, 5899f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long outlen, 5900f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng); 5901f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5902f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Terminate a PRNG state 5903f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param prng The PRNG state to terminate 5904f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5905f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5906f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*done)(prng_state *prng); 5907f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5908f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Export a PRNG state 5909f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param out [out] The destination for the state 5910f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param outlen [in/out] The max size and resulting size 5911f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param prng The PRNG to export 5912f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5913f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5914f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*pexport)(unsigned char *out, 5915f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long *outlen, 5916f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng); 5917f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5918f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Import a PRNG state 5919f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param in The data to import 5920f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param inlen The length of the data to import (octets) 5921f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param prng The PRNG to initialize/import 5922f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful 5923f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5924f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*pimport)(const unsigned char *in, 5925f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long inlen, 5926f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project prng_state *prng); 5927f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5928f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Self-test the PRNG 5929f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful, 5930f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project CRYPT_NOP if self-testing has been disabled 5931f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5932f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*test)(void); 5933f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project}; 5934f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 5935f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 5936f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5937f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Name} 5938f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe name by which find\_prng() will find the PRNG. 5939f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5940f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Export Size} 5941f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectWhen an PRNG state is to be exported for future use you specify the space required in this variable. 5942f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5943f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Start} 5944f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectInitialize the PRNG and make it ready to accept entropy. 5945f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5946f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Entropy Addition} 5947f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAdd entropy to the PRNG state. The exact behaviour of this function depends on the particulars of the PRNG. 5948f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5949f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Ready} 5950f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis function makes the PRNG ready to read from by processing the entropy added. The behaviour of this function depends 5951f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecton the specific PRNG used. 5952f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5953f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Read} 5954f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectRead from the PRNG and return the number of bytes read. This function does not have to fill the buffer but it is best 5955f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectif it does as many protocols do not retry reads and will fail on the first try. 5956f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5957f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Done} 5958f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTerminate a PRNG state. The behaviour of this function depends on the particular PRNG used. 5959f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5960f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Exporting and Importing} 5961f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAn exported PRNG state is data that the PRNG can later import to resume activity. They're not meant to resume \textit{the same session} 5962f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectbut should at least maintain the same level of state entropy. 5963f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5964f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\mysection{BigNum Math Descriptors} 5965f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe library also makes use of the math descriptors to access math functions. While bignum math libraries usually differ in implementation 5966f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectit hasn't proven hard to write \textit{glue} to use math libraries so far. The basic descriptor looks like. 5967f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5968f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{small} 5969f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 5970f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/** math descriptor */ 5971f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttypedef struct { 5972f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Name of the math provider */ 5973f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project char *name; 5974f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5975f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Bits per digit, amount of bits must fit in an unsigned long */ 5976f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int bits_per_digit; 5977f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5978f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/* ---- init/deinit functions ---- */ 5979f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5980f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** initialize a bignum 5981f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The number to initialize 5982f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 5983f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5984f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*init)(void **a); 5985f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5986f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** init copy 5987f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param dst The number to initialize and write to 5988f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param src The number to copy from 5989f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 5990f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5991f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*init_copy)(void **dst, void *src); 5992f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5993f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** deinit 5994f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The number to free 5995f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 5996f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 5997f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void (*deinit)(void *a); 5998f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 5999f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/* ---- data movement ---- */ 6000f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6001f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** copy 6002f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param src The number to copy from 6003f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param dst The number to write to 6004f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6005f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6006f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*copy)(void *src, void *dst); 6007f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6008f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/* ---- trivial low level functions ---- */ 6009f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6010f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** set small constant 6011f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a Number to write to 6012f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param n Source upto bits_per_digit (meant for small constants) 6013f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6014f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6015f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*set_int)(void *a, unsigned long n); 6016f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6017f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** get small constant 6018f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a Small number to read 6019f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return The lower bits_per_digit of the integer (unsigned) 6020f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6021f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long (*get_int)(void *a); 6022f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6023f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** get digit n 6024f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The number to read from 6025f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param n The number of the digit to fetch 6026f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return The bits_per_digit sized n'th digit of a 6027f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6028f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long (*get_digit)(void *a, int n); 6029f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6030f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Get the number of digits that represent the number 6031f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The number to count 6032f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return The number of digits used to represent the number 6033f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6034f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*get_digit_count)(void *a); 6035f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6036f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** compare two integers 6037f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The left side integer 6038f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The right side integer 6039f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return LTC_MP_LT if a < b, 6040f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project LTC_MP_GT if a > b and 6041f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project LTC_MP_EQ otherwise. (signed comparison) 6042f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6043f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*compare)(void *a, void *b); 6044f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6045f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** compare against int 6046f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The left side integer 6047f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The right side integer (upto bits_per_digit) 6048f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return LTC_MP_LT if a < b, 6049f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project LTC_MP_GT if a > b and 6050f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project LTC_MP_EQ otherwise. (signed comparison) 6051f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6052f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*compare_d)(void *a, unsigned long n); 6053f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6054f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Count the number of bits used to represent the integer 6055f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The integer to count 6056f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return The number of bits required to represent the integer 6057f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6058f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*count_bits)(void * a); 6059f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6060f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Count the number of LSB bits which are zero 6061f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The integer to count 6062f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return The number of contiguous zero LSB bits 6063f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6064f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*count_lsb_bits)(void *a); 6065f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6066f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Compute a power of two 6067f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The integer to store the power in 6068f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param n The power of two you want to store (a = 2^n) 6069f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6070f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6071f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*twoexpt)(void *a , int n); 6072f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6073f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/* ---- radix conversions ---- */ 6074f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6075f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** read ascii string 6076f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The integer to store into 6077f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param str The string to read 6078f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param radix The radix the integer has been represented in (2-64) 6079f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6080f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6081f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*read_radix)(void *a, const char *str, int radix); 6082f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6083f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** write number to string 6084f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The integer to store 6085f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param str The destination for the string 6086f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param radix The radix the integer is to be represented in (2-64) 6087f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6088f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6089f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*write_radix)(void *a, char *str, int radix); 6090f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6091f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** get size as unsigned char string 6092f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The integer to get the size 6093f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return The length of the integer in octets 6094f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6095f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long (*unsigned_size)(void *a); 6096f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6097f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** store an integer as an array of octets 6098f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param src The integer to store 6099f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param dst The buffer to store the integer in 6100f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6101f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6102f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*unsigned_write)(void *src, unsigned char *dst); 6103f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6104f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** read an array of octets and store as integer 6105f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param dst The integer to load 6106f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param src The array of octets 6107f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param len The number of octets 6108f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6109f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6110f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*unsigned_read)( void *dst, 6111f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *src, 6112f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned long len); 6113f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6114f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/* ---- basic math ---- */ 6115f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6116f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** add two integers 6117f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The first source integer 6118f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The second source integer 6119f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The destination of "a + b" 6120f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6121f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6122f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*add)(void *a, void *b, void *c); 6123f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6124f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** add two integers 6125f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The first source integer 6126f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The second source integer 6127f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project (single digit of upto bits_per_digit in length) 6128f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The destination of "a + b" 6129f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6130f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6131f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*addi)(void *a, unsigned long b, void *c); 6132f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6133f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** subtract two integers 6134f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The first source integer 6135f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The second source integer 6136f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The destination of "a - b" 6137f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6138f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6139f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*sub)(void *a, void *b, void *c); 6140f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6141f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** subtract two integers 6142f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The first source integer 6143f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The second source integer 6144f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project (single digit of upto bits_per_digit in length) 6145f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The destination of "a - b" 6146f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6147f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6148f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*subi)(void *a, unsigned long b, void *c); 6149f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6150f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** multiply two integers 6151f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The first source integer 6152f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The second source integer 6153f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project (single digit of upto bits_per_digit in length) 6154f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The destination of "a * b" 6155f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6156f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6157f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*mul)(void *a, void *b, void *c); 6158f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6159f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** multiply two integers 6160f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The first source integer 6161f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The second source integer 6162f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project (single digit of upto bits_per_digit in length) 6163f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The destination of "a * b" 6164f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6165f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6166f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*muli)(void *a, unsigned long b, void *c); 6167f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6168f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Square an integer 6169f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The integer to square 6170f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The destination 6171f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6172f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6173f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*sqr)(void *a, void *b); 6174f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6175f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Divide an integer 6176f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The dividend 6177f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The divisor 6178f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The quotient (can be NULL to signify don't care) 6179f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param d The remainder (can be NULL to signify don't care) 6180f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6181f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6182f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*div)(void *a, void *b, void *c, void *d); 6183f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6184f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** divide by two 6185f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The integer to divide (shift right) 6186f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The destination 6187f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6188f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6189f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*div_2)(void *a, void *b); 6190f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6191f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Get remainder (small value) 6192f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The integer to reduce 6193f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The modulus (upto bits_per_digit in length) 6194f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The destination for the residue 6195f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6196f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6197f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*modi)(void *a, unsigned long b, unsigned long *c); 6198f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6199f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** gcd 6200f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The first integer 6201f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The second integer 6202f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The destination for (a, b) 6203f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6204f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6205f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*gcd)(void *a, void *b, void *c); 6206f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6207f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** lcm 6208f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The first integer 6209f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The second integer 6210f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The destination for [a, b] 6211f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6212f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6213f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*lcm)(void *a, void *b, void *c); 6214f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6215f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Modular multiplication 6216f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The first source 6217f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The second source 6218f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The modulus 6219f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param d The destination (a*b mod c) 6220f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6221f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6222f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*mulmod)(void *a, void *b, void *c, void *d); 6223f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6224f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Modular squaring 6225f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The first source 6226f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The modulus 6227f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The destination (a*a mod b) 6228f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6229f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6230f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*sqrmod)(void *a, void *b, void *c); 6231f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6232f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Modular inversion 6233f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The value to invert 6234f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The modulus 6235f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The destination (1/a mod b) 6236f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6237f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6238f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*invmod)(void *, void *, void *); 6239f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6240f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/* ---- reduction ---- */ 6241f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6242f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** setup Montgomery 6243f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The modulus 6244f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The destination for the reduction digit 6245f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6246f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6247f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*montgomery_setup)(void *a, void **b); 6248f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6249f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** get normalization value 6250f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The destination for the normalization value 6251f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The modulus 6252f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6253f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6254f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*montgomery_normalization)(void *a, void *b); 6255f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6256f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** reduce a number 6257f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The number [and dest] to reduce 6258f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The modulus 6259f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The value "b" from montgomery_setup() 6260f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6261f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6262f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*montgomery_reduce)(void *a, void *b, void *c); 6263f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6264f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** clean up (frees memory) 6265f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The value "b" from montgomery_setup() 6266f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6267f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6268f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void (*montgomery_deinit)(void *a); 6269f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6270f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/* ---- exponentiation ---- */ 6271f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6272f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Modular exponentiation 6273f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The base integer 6274f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The power (can be negative) integer 6275f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param c The modulus integer 6276f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param d The destination 6277f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6278f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6279f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*exptmod)(void *a, void *b, void *c, void *d); 6280f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6281f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Primality testing 6282f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param a The integer to test 6283f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param b The destination of the result (FP_YES if prime) 6284f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6285f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6286f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*isprime)(void *a, int *b); 6287f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6288f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/* ---- (optional) ecc point math ---- */ 6289f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6290f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** ECC GF(p) point multiplication (from the NIST curves) 6291f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param k The integer to multiply the point by 6292f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param G The point to multiply 6293f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param R The destination for kG 6294f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param modulus The modulus for the field 6295f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param map Boolean indicated whether to map back to affine or not 6296f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project (can be ignored if you work in affine only) 6297f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6298f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6299f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*ecc_ptmul)( void *k, 6300f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_point *G, 6301f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_point *R, 6302f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *modulus, 6303f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int map); 6304f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6305f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** ECC GF(p) point addition 6306f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param P The first point 6307f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param Q The second point 6308f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param R The destination of P + Q 6309f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param modulus The modulus 6310f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param mp The "b" value from montgomery_setup() 6311f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6312f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6313f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*ecc_ptadd)(ecc_point *P, 6314f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_point *Q, 6315f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_point *R, 6316f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *modulus, 6317f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *mp); 6318f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6319f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** ECC GF(p) point double 6320f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param P The first point 6321f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param R The destination of 2P 6322f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param modulus The modulus 6323f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param mp The "b" value from montgomery_setup() 6324f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6325f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6326f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*ecc_ptdbl)(ecc_point *P, 6327f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_point *R, 6328f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *modulus, 6329f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *mp); 6330f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6331f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** ECC mapping from projective to affine, 6332f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project currently uses (x,y,z) => (x/z^2, y/z^3, 1) 6333f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param P The point to map 6334f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param modulus The modulus 6335f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param mp The "b" value from montgomery_setup() 6336f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6337f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @remark The mapping can be different but keep in mind a 6338f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_point only has three integers (x,y,z) so if 6339f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project you use a different mapping you have to make it fit. 6340f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6341f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*ecc_map)(ecc_point *P, void *modulus, void *mp); 6342f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6343f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Computes kA*A + kB*B = C using Shamir's Trick 6344f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param A First point to multiply 6345f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param kA What to multiple A by 6346f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param B Second point to multiply 6347f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param kB What to multiple B by 6348f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param C [out] Destination point (can overlap with A or B) 6349f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param modulus Modulus for curve 6350f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6351f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6352f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*ecc_mul2add)(ecc_point *A, void *kA, 6353f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_point *B, void *kB, 6354f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project ecc_point *C, 6355f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *modulus); 6356f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6357f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6358f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/* ---- (optional) rsa optimized math (for internal CRT) ---- */ 6359f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6360f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** RSA Key Generation 6361f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param prng An active PRNG state 6362f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param wprng The index of the PRNG desired 6363f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param size The size of the key in octets 6364f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param e The "e" value (public key). 6365f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project e==65537 is a good choice 6366f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param key [out] Destination of a newly created private key pair 6367f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK if successful, upon error all allocated ram is freed 6368f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6369f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*rsa_keygen)(prng_state *prng, 6370f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int wprng, 6371f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int size, 6372f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project long e, 6373f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 6374f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6375f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** RSA exponentiation 6376f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param in The octet array representing the base 6377f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param inlen The length of the input 6378f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param out The destination (to be stored in an octet array format) 6379f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param outlen The length of the output buffer and the resulting size 6380f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project (zero padded to the size of the modulus) 6381f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param which PK_PUBLIC for public RSA and PK_PRIVATE for private RSA 6382f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @param key The RSA key to use 6383f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project @return CRYPT_OK on success 6384f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project */ 6385f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int (*rsa_me)(const unsigned char *in, unsigned long inlen, 6386f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project unsigned char *out, unsigned long *outlen, int which, 6387f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project rsa_key *key); 6388f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} ltc_math_descriptor; 6389f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 6390f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{small} 6391f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6392f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectMost 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. 6393f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6394f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{Conventions} 6395f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6396f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAll \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 6397f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe 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 6398f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfree the bignum as well as the structure you allocated to place it in. 6399f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6400f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAll functions except the Montgomery reductions work from left to right with the arguments. For example, mul(a, b, c) computes $c \leftarrow ab$. 6401f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6402f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAll functions (except where noted otherwise) return \textbf{CRYPT\_OK} to signify a successful operation. All error codes must be valid LibTomCrypt error codes. 6403f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6404f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 6405f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthen 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 6406f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthan an \textit{unsigned long} that is also acceptable as the \textit{bits\_per\_digit} parameter will specify this. 6407f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6408f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{ECC Functions} 6409f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 6410f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectthe \textbf{ecc\_point} structure and assume the points are stored in Jacobian projective format. 6411f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6412f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 6413f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/** A point on a ECC curve, stored in Jacobian format such 6414f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project that (x,y,z) => (x/z^2, y/z^3, 1) when interpreted as affine */ 6415f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttypedef struct { 6416f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The x co-ordinate */ 6417f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *x; 6418f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The y co-ordinate */ 6419f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *y; 6420f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The z co-ordinate */ 6421f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *z; 6422f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} ecc_point; 6423f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 6424f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6425f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectAll 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 6426f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectover 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 6427f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectcould point to anything you want. The only further exception is the export functions which expects the values to be in affine format. 6428f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6429f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Point Multiply} 6430f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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. 6431f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6432f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Point Addition} 6433f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis 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 6434f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectmay be in either affine (with $z = 1$) or projective format and the output point is always projective. 6435f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6436f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Point Mapping} 6437f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThis will map the point $P$ back from projective to affine. The output point $P$ must be of the form $(x, y, 1)$. 6438f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6439f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsubsection{Shamir's Trick} 6440f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{Shamir's Trick} 6441f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\index{ltc\_ecc\_mul2add()} 6442f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectTo accelerate EC--DSA verification the library provides a built--in function called ltc\_ecc\_mul2add(). This performs two point multiplications and an addition in 6443f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectroughly 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 6444f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectoverlap (e.g., $A \leftarrow k_1A + k_2B$) and must return the final point in affine format. 6445f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6446f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6447f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\subsection{RSA Functions} 6448f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe RSA Modular Exponentiation (ME) function is used by the RSA API to perform exponentiations for private and public key operations. In particular for 6449f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectprivate key operations it uses the CRT approach to lower the time required. It is passed an RSA key with the following format. 6450f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6451f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\begin{verbatim} 6452f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project/** RSA PKCS style key */ 6453f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projecttypedef struct Rsa_key { 6454f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** Type of key, PK_PRIVATE or PK_PUBLIC */ 6455f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project int type; 6456f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The public exponent */ 6457f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *e; 6458f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The private exponent */ 6459f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *d; 6460f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The modulus */ 6461f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *N; 6462f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The p factor of N */ 6463f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *p; 6464f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The q factor of N */ 6465f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *q; 6466f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The 1/q mod p CRT param */ 6467f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *qP; 6468f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The d mod (p - 1) CRT param */ 6469f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *dP; 6470f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project /** The d mod (q - 1) CRT param */ 6471f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project void *dQ; 6472f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project} rsa_key; 6473f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{verbatim} 6474f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6475f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectThe 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 6476f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectto 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, 6477f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Projectfor RSA--1024 the output is always 128 bytes regardless of how small the numerical value of the exponentiation is. 6478f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6479f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source ProjectSince the function is given the entire RSA key (for private keys only) CRT is possible as prescribed in the PKCS \#1 v2.1 specification. 6480f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6481f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\newpage 6482f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\markboth{Index}{Index} 6483f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\input{crypt.ind} 6484f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6485f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project\end{document} 6486f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project 6487f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project% $Source: /cvs/libtom/libtomcrypt/crypt.tex,v $ 6488f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project% $Revision: 1.123 $ 6489f7fc46c63fdc8f39234fea409b8dbe116d73ebf8The Android Open Source Project% $Date: 2006/12/16 19:08:17 $ 6490