434 lines
16 KiB
TeX
434 lines
16 KiB
TeX
\documentclass[b5paper]{book}
|
|
\usepackage{hyperref}
|
|
\usepackage{makeidx}
|
|
\usepackage{amssymb}
|
|
\usepackage{color}
|
|
\usepackage{alltt}
|
|
\usepackage{graphicx}
|
|
\usepackage{layout}
|
|
\def\union{\cup}
|
|
\def\intersect{\cap}
|
|
\def\getsrandom{\stackrel{\rm R}{\gets}}
|
|
\def\cross{\times}
|
|
\def\cat{\hspace{0.5em} \| \hspace{0.5em}}
|
|
\def\catn{$\|$}
|
|
\def\divides{\hspace{0.3em} | \hspace{0.3em}}
|
|
\def\nequiv{\not\equiv}
|
|
\def\approx{\raisebox{0.2ex}{\mbox{\small $\sim$}}}
|
|
\def\lcm{{\rm lcm}}
|
|
\def\gcd{{\rm gcd}}
|
|
\def\log{{\rm log}}
|
|
\def\ord{{\rm ord}}
|
|
\def\abs{{\mathit abs}}
|
|
\def\rep{{\mathit rep}}
|
|
\def\mod{{\mathit\ mod\ }}
|
|
\renewcommand{\pmod}[1]{\ ({\rm mod\ }{#1})}
|
|
\newcommand{\floor}[1]{\left\lfloor{#1}\right\rfloor}
|
|
\newcommand{\ceil}[1]{\left\lceil{#1}\right\rceil}
|
|
\def\Or{{\rm\ or\ }}
|
|
\def\And{{\rm\ and\ }}
|
|
\def\iff{\hspace{1em}\Longleftrightarrow\hspace{1em}}
|
|
\def\implies{\Rightarrow}
|
|
\def\undefined{{\rm ``undefined"}}
|
|
\def\Proof{\vspace{1ex}\noindent {\bf Proof:}\hspace{1em}}
|
|
\let\oldphi\phi
|
|
\def\phi{\varphi}
|
|
\def\Pr{{\rm Pr}}
|
|
\newcommand{\str}[1]{{\mathbf{#1}}}
|
|
\def\F{{\mathbb F}}
|
|
\def\N{{\mathbb N}}
|
|
\def\Z{{\mathbb Z}}
|
|
\def\R{{\mathbb R}}
|
|
\def\C{{\mathbb C}}
|
|
\def\Q{{\mathbb Q}}
|
|
\definecolor{DGray}{gray}{0.5}
|
|
\newcommand{\emailaddr}[1]{\mbox{$<${#1}$>$}}
|
|
\def\twiddle{\raisebox{0.3ex}{\mbox{\tiny $\sim$}}}
|
|
\def\gap{\vspace{0.5ex}}
|
|
\makeindex
|
|
\begin{document}
|
|
\frontmatter
|
|
\pagestyle{empty}
|
|
\title{LibTomPoly User Manual \\ v0.04}
|
|
\author{Tom St Denis \\ tomstdenis@iahu.ca}
|
|
\maketitle
|
|
This text and library are hereby placed in the public domain. This book has been
|
|
formatted for B5 [176x250] paper using the \LaTeX{} {\em book} macro package.
|
|
|
|
\vspace{10cm}
|
|
|
|
\begin{flushright}Open Source. Open Academia. Open Minds.
|
|
|
|
\mbox{ }
|
|
|
|
Tom St Denis,
|
|
|
|
Ontario, Canada
|
|
\end{flushright}
|
|
|
|
\tableofcontents
|
|
\listoffigures
|
|
\mainmatter
|
|
\pagestyle{headings}
|
|
\chapter{Introduction}
|
|
\section{What is LibTomPoly?}
|
|
LibTomPoly is a public domain open source library to provide polynomial basis arithmetic. It uses the public domain
|
|
library LibTomMath (not included) for the integer arithmetic and extends the functonality to provide polynomial arithmetic.
|
|
|
|
Technically speaking the library allows the user to perform arithmetic on elements from the group $GF(p)[x]$ and to
|
|
a lesser extent (this will change in the future) over $\Z[x]$. Essentially the math you can do with integers (including
|
|
forming rings and fields) you can do with with polynomials and now you can do with LibTomPoly.
|
|
|
|
\section{License}
|
|
LibTomPoly is public domain. Enjoy.
|
|
|
|
\section{Terminology}
|
|
Throughout this manual and within the library there will be some terminology that not everyone is familiar with. It is afterall
|
|
weird math.
|
|
|
|
\begin{figure}[here]
|
|
\begin{center}
|
|
\begin{small}
|
|
\begin{tabular}{|l|l|}
|
|
\hline \textbf{Term} & \textbf{Definition} \\
|
|
\hline monic polynomial & A polynomial where the leading coefficient is a one. \\
|
|
\hline irreducible polynomial & A polynomial that has no factors in a given group. \\
|
|
& For instance, $x^2 + 4$ is irreducible in $\Z[x]$ but not \\
|
|
& in $GF(17)[x]$ since $x^2 + 4 = (x+8)(x+9) \mbox{ (mod }17\mbox{)}$. \\
|
|
\hline primitive polynomial & An irreducible polynomial which generates all of \\
|
|
& elements of a given field (e.g. $GF(p)[x]/v(x)$) \\
|
|
\hline characteristic & An integer $k$ such that $k \cdot p(x) \equiv 0$ \\
|
|
\hline deg() & Functon returns degree of polynomial, e.g. deg($x^6 + x^3 + 1$) = 6 \\
|
|
\hline
|
|
\end{tabular}
|
|
\end{small}
|
|
\end{center}
|
|
\caption{Terminology}
|
|
\end{figure}
|
|
|
|
\section{Building the Library}
|
|
The library is not ready for production yet but you can test out the library manually if you want. To build the library
|
|
simply type
|
|
|
|
\begin{alltt}
|
|
make
|
|
\end{alltt}
|
|
|
|
Which will build ``libtompoly.a''. To build a Win32 library with MSVC type
|
|
|
|
\begin{alltt}
|
|
nmake -f makefile.msvc
|
|
\end{alltt}
|
|
|
|
To build against this library include ``tompoly.h'' and link against ``libtompoly.a'' (or tommath.lib as appropriate).
|
|
To build the included demo type
|
|
|
|
\begin{alltt}
|
|
make demo
|
|
\end{alltt}
|
|
|
|
Which will build ``demo'' in the current directory. The demo is not interactive and produces results which must be manually
|
|
inspected.
|
|
|
|
\chapter{Getting Started}
|
|
|
|
\section{The LibTomMath Connection}
|
|
LibTomPoly is really just an extension of LibTomMath\footnote{\url{http://math.libtomcrypt.org}}. As such the library has
|
|
been designed in much the same way as far as argument passing and error handling events are concerned. The reader is
|
|
encouraged to become familiar with LibTomMath before diving into LibTomPoly.
|
|
|
|
\section{The pb\_poly structure}
|
|
A polynomial can characterized by a few variables. Given the C structure as follows
|
|
|
|
\begin{alltt}
|
|
typedef struct \{
|
|
int used, /* number of terms */
|
|
alloc; /* number of terms available (total) */
|
|
mp_int characteristic, /* characteristic, zero if not finite */
|
|
*terms; /* terms of polynomial */
|
|
\} pb_poly;
|
|
\end{alltt}
|
|
|
|
\begin{enumerate}
|
|
\item The \textbf{used} member indicates how many terms of the \textbf{terms} array are used to represent the polynomial.
|
|
\item The \textbf{alloc} member indicates the size of the \textbf{terms} array. Also note that even if \textbf{used}
|
|
is less than \textbf{alloc} the mp\_ints above \textbf{used} in the array must be set to a valid representation
|
|
of zero.
|
|
\item The \textbf{characteristic} member is an mp\_int representing the characteristic of the polynomial. If the desire is to
|
|
have a null characteristic (e.g. $\Z[x]$) this element must still be initialized to a valid representation
|
|
of zero.
|
|
\item The \textbf{terms} member is a dynamically sized array of mp\_int values which represent the coefficients for
|
|
the terms of the polynomial. They start from least to most significant degree. E.g. $p(x) = \sum_{i=0}^{used-1} terms_i \cdot x^i$.
|
|
\end{enumerate}
|
|
|
|
\section{Return Codes}
|
|
The library uses the return codes from LibTomMath. They are
|
|
|
|
\index{MP\_OKAY}\index{MP\_YES}\index{MP\_NO}\index{MP\_VAL}\index{MP\_MEM}
|
|
\begin{figure}[here!]
|
|
\begin{center}
|
|
\begin{small}
|
|
\begin{tabular}{|l|l|}
|
|
\hline \textbf{Code} & \textbf{Meaning} \\
|
|
\hline MP\_OKAY & The function succeeded. \\
|
|
\hline MP\_VAL & The function input was invalid. \\
|
|
\hline MP\_MEM & Heap memory exhausted. \\
|
|
\hline &\\
|
|
\hline MP\_YES & Response is yes. \\
|
|
\hline MP\_NO & Response is no. \\
|
|
\hline
|
|
\end{tabular}
|
|
\end{small}
|
|
\end{center}
|
|
\caption{Return Codes}
|
|
\end{figure}
|
|
|
|
\section{Function Argument Passing}
|
|
Just like LibTomMath the arguments are meant to be read left to right where the destination is on the right. Consider
|
|
the following.
|
|
|
|
\begin{alltt}
|
|
pb_add(a, b, c); /* c = a + b */
|
|
pb_mul(a, b, c); /* c = a * b */
|
|
\end{alltt}
|
|
|
|
Also like LibTomMath input arguments can be specified as output arguments. Consider.
|
|
|
|
\begin{alltt}
|
|
pb_mul(a, b, a); /* a = a * b */
|
|
pb_gcd(a, b, b); /* b = (a, b) */
|
|
\end{alltt}
|
|
|
|
However, polynomial math raises another consideration. The characteristic of the result is taken from the right most
|
|
argument passed to the function. Not all functions will return an error code if the characteristics of the inputs
|
|
do not match so it's important to keep this in mind. In general the results are undefined if not all of the polynomials
|
|
have identical characteristics.
|
|
|
|
\section{Initializing Polynomials}
|
|
In order to use a pb\_poly structure with one of the functions in this library the structure must be initialized.
|
|
There are three functions provided to initialize pb\_poly structures.
|
|
|
|
\subsection{Default Initialization}
|
|
\index{pb\_init}
|
|
\begin{alltt}
|
|
int pb_init(pb_poly *a, mp_int *characteristic);
|
|
\end{alltt}
|
|
This will initialize ``a'' with the given ``characteristic'' such that the polynomial represented is a constant zero.
|
|
The mp\_int characteristic must be a valid initialized mp\_int even if a characteristic of zero is desired. By default,
|
|
the polynomial will be initialized so there are ``PB\_TERMS'' terms available. This will grow automatically as required
|
|
by the other functions.
|
|
|
|
\subsection{Initilization of Given Size}
|
|
\index{pb\_init\_size}
|
|
\begin{alltt}
|
|
int pb_init_size(pb_poly *a, mp_int *characteristic, int size);
|
|
\end{alltt}
|
|
This behaves similar to pb\_init() except it will allocate ``size'' terms to initialize instead of ``PB\_TERMS''. This
|
|
is useful if you happen to know in advance how many terms you want.
|
|
|
|
\subsection{Initilization of a Copy}
|
|
\index{pb\_init\_copy}
|
|
\begin{alltt}
|
|
int pb_init_copy(pb_poly *a, pb_poly *b);
|
|
\end{alltt}
|
|
|
|
This will initialize ``a'' so it is a verbatim copy of ``b''. It will copy the characteristic and all of the terms
|
|
from ``b'' into ``a''.
|
|
|
|
\subsection{Freeing a Polynomial}
|
|
\index{pb\_clear}
|
|
\begin{alltt}
|
|
int pb_clear(pb_poly *a);
|
|
\end{alltt}
|
|
|
|
This will free all the memory required by ``a'' and mark it as been freed. You can repeatedly pb\_clear() the same
|
|
pb\_poly safely.
|
|
|
|
\chapter{Basic Operations}
|
|
\section{Comparison}
|
|
Comparisions with polynomials is a bit less intuitive then with integers. Is $x^2 + 3$ greater than $x^2 + x + 4$? To
|
|
create a rational form of comparison the following comparison codes were designed.
|
|
|
|
\begin{figure}[here]
|
|
\begin{small}
|
|
\begin{center}
|
|
\begin{tabular}{|l|l|}
|
|
\hline \textbf{Code} & \textbf{Meaning} \\
|
|
\hline PB\_EQ & The polynomials are exactly equal \\
|
|
\hline PB\_DEG\_LT & The left polynomial has a lower degree than the right. \\
|
|
\hline PB\_DEG\_EQ & Both have the same degree. \\
|
|
\hline PB\_DEG\_GT & The left polynomial has a higher degree than the right. \\
|
|
\hline
|
|
\end{tabular}
|
|
\end{center}
|
|
\end{small}
|
|
\caption{Compare Codes}
|
|
\end{figure}
|
|
|
|
\index{pb\_cmp}
|
|
\begin{alltt}
|
|
int pb_cmp(pb_poly *a, pb_poly *b);
|
|
\end{alltt}
|
|
|
|
This will compare the polynomial ``a'' to the left of the polynomial ``b''. It will return one of the four
|
|
codes listed above. Note that the function does not compare the characteristics. So if $a \in GF(17)[x]$ and
|
|
$b \in GF(11)[x]$ were both equal to $x^2 + 3$ they would compare to PB\_EQ. Whereas $x^3 + 4$
|
|
would compare to PB\_DEG\_LT, $x^1 + 7$ would compare to $PB\_DEG\_GT$ and $x^2 + 7$ would compare to $PB\_DEG\_EQ$\footnote{If the polynomial $a$ were on the left for all three cases.}.
|
|
|
|
\section{Copying and Swapping}
|
|
\index{pb\_copy}
|
|
\begin{alltt}
|
|
int pb_copy(pb_poly *src, pb_poly *dest);
|
|
\end{alltt}
|
|
This will copy the polynomial from ``src'' to ``dest'' verbatim.
|
|
|
|
\index{pb\_exch}
|
|
\begin{alltt}
|
|
int pb_exch(pb_poly *a, pb_poly *b);
|
|
\end{alltt}
|
|
This will exchange the contents of ``a'' with ``b''.
|
|
|
|
\section{Multiplying and Dividing by $x$}
|
|
\index{pb\_lshd} \index{pb\_rshd}
|
|
\begin{alltt}
|
|
int pb_lshd(pb_poly *a, int i);
|
|
int pb_rshd(pb_poly *a, int i);
|
|
\end{alltt}
|
|
These will multiply (or divide, respectfully) the polynomial ``a'' by $x^i$. If $i \le 0$ the functions return without
|
|
performing any operation. For example,
|
|
|
|
\begin{alltt}
|
|
pb_lshd(a, 2); /* a(x) = a(x) * x^2 */
|
|
pb_rshd(a, 7); /* a(x) = a(x) / x^7 */
|
|
\end{alltt}
|
|
|
|
\chapter{Basic Arithmetic}
|
|
\section{Addition, Subtraction and Multiplication}
|
|
\index{pb\_add} \index{pb\_sub}
|
|
\begin{alltt}
|
|
int pb_add(pb_poly *a, pb_poly *b, pb_poly *c);
|
|
int pb_sub(pb_poly *a, pb_poly *b, pb_poly *c);
|
|
int pb_mul(pb_poly *a, pb_poly *b, pb_poly *c);
|
|
\end{alltt}
|
|
|
|
These will add (subtract or multiply, respectfully) the polynomial ``a'' and polynomial ``b'' and store the result in
|
|
polynomial ``c''. The characteristic from ``c'' is used to calculate the result. Note that the coefficients of ``c''
|
|
will always be positive provided the characteristic of ``c'' is greater than zero.
|
|
|
|
Quick examples of usage.
|
|
|
|
\begin{alltt}
|
|
pb_add(a, b, c); /* c = a + b */
|
|
pb_sub(b, a, c); /* c = b - a */
|
|
pb_mul(c, a, a); /* a = c * a */
|
|
\end{alltt}
|
|
|
|
\section{Division}
|
|
\index{pb\_div}
|
|
\begin{alltt}
|
|
int pb_div(pb_poly *a, pb_poly *b, pb_poly *c, pb_poly *d);
|
|
\end{alltt}
|
|
This will divide the polynomial ``a'' by ``b'' and store the quotient in ``c'' and remainder in ``d''. That is
|
|
|
|
\begin{equation}
|
|
b(x) \cdot c(x) + d(x) = a(x)
|
|
\end{equation}
|
|
|
|
The value of $deg(d(x))$ is always less than $deg(b(x))$. Either of ``c'' and ``d'' can be set to \textbf{NULL} to
|
|
signify their value is not desired. This is useful if you only want the quotient or remainder but not both.
|
|
|
|
Since one of the destinations can be \textbf{NULL} the characteristic of the result is taken from ``b''. The function
|
|
will return an error if the characteristic of ``a'' differs from that of ``b''.
|
|
|
|
This function is defined for polynomials in $GF(p)[x]$ only. A routine pb\_zdiv()\footnote{To be written!} allows the
|
|
division of polynomials in $\Z[x]$.
|
|
|
|
\section{Modular Functions}
|
|
\index{pb\_addmod} \index{pb\_submod} \index{pb\_mulmod}
|
|
\begin{alltt}
|
|
int pb_addmod(pb_poly *a, pb_poly *b, pb_poly *c, pb_poly *d);
|
|
int pb_submod(pb_poly *a, pb_poly *b, pb_poly *c, pb_poly *d);
|
|
int pb_mulmod(pb_poly *a, pb_poly *b, pb_poly *c, pb_poly *d);
|
|
\end{alltt}
|
|
|
|
These add (subtract or multiply respectfully) the polynomial ``a'' and the polynomial ``b'' modulo the polynomial ``c''
|
|
and store the result in the polynomial ``d''.
|
|
|
|
\chapter{Algebraic Functions}
|
|
|
|
\section{Monic Reductions}
|
|
\index{pb\_monic}
|
|
\begin{alltt}
|
|
int pb_monic(pb_poly *a, pb_poly *b)
|
|
\end{alltt}
|
|
Makes ``b'' the monic representation of ``a'' by ensuring the most significant coefficient is one. Only defined
|
|
over $GF(p)[x]$. Note that this is not a straight copy to ``b'' so you must ensure the characteristic of the two
|
|
are equal before you call the function\footnote{Note that $a == b$ is acceptable as well.}. Monic polynomials
|
|
are related to their original polynomial through an integer $k$ as follows
|
|
|
|
\begin{equation}
|
|
a(x) \cdot k^{-1} \equiv b(x)
|
|
\end{equation}
|
|
|
|
\section{Extended Euclidean Algorithm}
|
|
\index{pb\_exteuclid}
|
|
\begin{alltt}
|
|
int pb_exteuclid(pb_poly *a, pb_poly *b,
|
|
pb_poly *U1, pb_poly *U2, pb_poly *U3);
|
|
\end{alltt}
|
|
|
|
This will compute the Euclidean algorithm and find values ``U1'', ``U2'', ``U3'' such that
|
|
|
|
\begin{equation}
|
|
a(x) \cdot U1(x) + b(x) \cdot U2(x) = U3(x)
|
|
\end{equation}
|
|
|
|
The value of ``U3'' is reduced to a monic polynomial. The three destination variables are all optional and can
|
|
be specified as \textbf{NULL} if they are not desired.
|
|
|
|
\section{Greatest Common Divisor}
|
|
\index{pb\_gcd}
|
|
\begin{alltt}
|
|
int pb_gcd(pb_poly *a, pb_poly *b, pb_poly *c);
|
|
\end{alltt}
|
|
This finds the monic greatest common divisor of the two polynomials ``a'' and ``b'' and store the result in ``c''. The
|
|
operation is only defined over $GF(p)[x]$.
|
|
|
|
\section{Modular Inverse}
|
|
\index{pb\_invmod}
|
|
\begin{alltt}
|
|
int pb_invmod(pb_poly *a, pb_poly *b, pb_poly *c);
|
|
\end{alltt}
|
|
This finds the modular inverse of ``a'' modulo ``b'' and stores the result in ``c''. The operation is only defined over
|
|
$GF(p)[x]$. If the operation succeed then the following congruency should hold true.
|
|
|
|
\begin{equation}
|
|
a(x)c(x) \equiv 1 \mbox{ (mod }b(x)\mbox{)}
|
|
\end{equation}
|
|
|
|
\section{Modular Exponentiation}
|
|
\index{pb\_exptmod}
|
|
\begin{alltt}
|
|
int pb_exptmod (pb_poly * G, mp_int * X, pb_poly * P, pb_poly * Y);
|
|
\end{alltt}
|
|
|
|
This raise ``G'' to the power of ``X'' modulo ``P'' and stores the result in ``Y''. Or as a congruence
|
|
|
|
\begin{equation}
|
|
Y(x) \equiv G(x)^X \mbox{ (mod }P(x)\mbox{)}
|
|
\end{equation}
|
|
|
|
Where ``X'' can be negative\footnote{But in that case $G^{-1}(x)$ must exist modulo $P(x)$.} or positive. This function
|
|
is only defined over $GF(p)[x]$.
|
|
|
|
\section{Irreducibility Testing}
|
|
\index{pb\_isirreduc}
|
|
\begin{alltt}
|
|
int pb_isirreduc(pb_poly *a, int *res);
|
|
\end{alltt}
|
|
Sets ``res'' to MP\_YES if ``a'' is irreducible (only for $GF(p)[x]$) otherwise sets ``res'' to MP\_NO.
|
|
|
|
\input{pb.ind}
|
|
|
|
\end{document}
|