TeaSpeak/tomcrypt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

moar doc

Browse Source 
[skip ci]
This commit is contained in:
Steffen Jaeckel 2017-08-15 00:07:53 +02:00
parent 8b3af12d70
commit 35d920a688
1 changed files with 59 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
doc/crypt.tex
View File

@ -1252,6 +1252,8 @@ Another useful feature of the stream ciphers API is generation of a random strea
\textit{setup} -- \textit{keystream} -- \textit{keystream} -- ... -- \textit{done}. The random stream generation is
implemented like encryption of a stream of \textit{0x00} bytes.
Note: You shouldn't use the keystream interface as a PRNG, as it doesn't allow to re-seed the internal state.
\mysection{ChaCha}
\textit{ChaCha} is currently the most modern stream cipher included in LibTomCrypt, so use this one unless you
@ -1289,7 +1291,6 @@ bytes via:
\begin{verbatim}
err = chacha_keystream(&st, out_buffer, out_len);
\end{verbatim}
Note that it's probably a better idea to use the PRNG interface for this purpose as that one allows re-seeding.
At the end you have to terminate the state:
\begin{verbatim}
@ -1319,7 +1320,6 @@ After that you can get a stream of pseudo--random bytes via:
\begin{verbatim}
err = rc4_stream_keystream(&st, out_buffer, out_len);
\end{verbatim}
Note that it's probably a better idea to use the PRNG interface for this purpose as that one allows re-seeding.
At the end you have to terminate the state:
\begin{verbatim}
@ -1347,7 +1347,6 @@ and a truly random \textit{nonce}. After that you can get a stream of pseudo--ra
\begin{verbatim}
err = sober128_stream_keystream(&st, out_buffer, out_len);
\end{verbatim}
Note that it's probably a better idea to use the PRNG interface for this purpose as that one allows re-seeding.
At the end you have to terminate the state:
\begin{verbatim}
@ -4306,7 +4305,7 @@ the library can perfrom the optimized CRT calculations on private key operations
\chapter{Diffie-Hellman Key Exchange}
\section{Background}
\mysection{Background}
Diffie-Hellman was the original public key system proposed. The system is based upon the group structure
of finite fields. For Diffie-Hellman a prime $p$ is chosen and a ``base'' $b$ such that $b^x\mbox{ }(\mbox{mod }p)$
@ -4332,7 +4331,7 @@ To thwart such attacks the primes and bases in the library have been designed an
the sub-group generated is a large prime namely ${p - 1} \over 2$. Such primes are known as ``strong primes'' and the
smaller prime (e.g. the order of the base) are known as Sophie-Germaine primes.
\section{Core Functions}
\mysection{Core Functions}
This library also provides core Diffie-Hellman functions so you can negotiate keys over insecure mediums. The routines
provided are relatively easy to use and only take two function calls to negotiate a shared key. There is a structure
@ -4353,7 +4352,7 @@ $p-1$ is equal to $2r$ where $r$ is a large prime. The bases are chosen to gene
leaking a bit of the key. This means the bases generate a very large prime order group which is good to make cryptanalysis
hard.
The next two routines are for exporting/importing Diffie-Hellman keys in a binary format. This is useful for transport
The next two routines are for exporting/importing Diffie-Hellman keys in/from DER encoded ASN.1. This is useful for transport
over communication mediums.
\index{dh\_export()} \index{dh\_import()}
@ -4364,9 +4363,27 @@ int dh_export(unsigned char *out, unsigned long *outlen,
int dh_import(const unsigned char *in, unsigned long inlen, dh_key *key);
\end{verbatim}
The ASN.1 sequence used to represent a DH key is as following:
\begin{verbatim}
DiffieHellmanKey ::= SEQUENCE {
version Version,
flags Flags,
p INTEGER, -- prime
g INTEGER, -- base/group
n INTEGER -- either x when private key or y when public key }
Version ::= INTEGER { v1(0) }
Flags ::= BIT STRING {
privateKey (0) -- this BIT is '1' if it's a private key or '0' if it's a public key
}
\end{verbatim}
These two functions work just like the ``rsa\_export()'' and ``rsa\_import()'' functions except these work with
Diffie-Hellman keys. Its important to note you do not have to free the ram for a ``dh\_key'' if an import fails. You can free a
``dh\_key'' using:
Diffie-Hellman keys. Its important to note you do not have to free the ram for a ``dh\_key'' if an import fails.
You can free a ``dh\_key'' using:
\begin{verbatim}
void dh_free(dh_key *key);
\end{verbatim}
@ -4389,7 +4406,39 @@ int dh_get_groupsize(dh_key *key);
\end{verbatim}
This returns the size in bytes of the modulus chosen for that key.
\subsection{Remarks on Usage}
\mysection{Other Diffie-Hellman Functions}
To be able to import Diffie-Hellman keys LibTomCrypt provides several API functions.
\\
To import the prime and group from binary format:
\index{dh\_set\_pg()}
\begin{verbatim}
int dh_set_pg(const unsigned char *p, unsigned long plen,
const unsigned char *g, unsigned long glen,
dh_key *key);
\end{verbatim}
This sets the prime \textit{p} of length \textit{plen} and the generator/base \textit{g} of length \textit{glen} in the DH key \textit{key}.
\\
To import the prime and group from an ASN.1 encoded DHparam Sequence:
\index{dh\_set\_pg\_dhparam()}
\begin{verbatim}
int dh_set_pg_dhparam(const unsigned char *dhparam, unsigned long dhparamlen, dh_key *key);
\end{verbatim}
This sets the parameters in \textit{dhparam} of \textit{dhparamlen} in the DH key \textit{key}.
\\
To import a private or public key from binary data:
\index{dh\_set\_key()}
\begin{verbatim}
int dh_set_key(const unsigned char *in, unsigned long inlen, int type, dh_key *key);
\end{verbatim}
This will import, depending on \textit{type} which can be either \textit{PK\_PRIVATE} or \textit{PK\_PUBLIC},
the according part of the DH key \textit{key} from \textit{in} of length \textit{inlen}.
After import the key will be verified and in case of an error it will be free'd.
\mysection{Remarks on Usage}
Its important that you hash the shared key before trying to use it as a key for a symmetric cipher or something. An
example program that communicates over sockets, using MD5 and 1024-bit DH keys is\footnote{This function is a small example. It is suggested that proper packaging be used. For example, if the public key sent is truncated these routines will not detect that.}:
\newpage
@ -4474,23 +4523,10 @@ done2:
}
\end{verbatim}
\end{small}
\newpage
\subsection{Remarks on The Snippet}
When the above code snippet is done (assuming all went well) their will be a shared 128-bit key in the ``key'' array
When the above code snippet is done (assuming all went well) there will be a shared 128-bit key in the ``key'' array
passed to ``establish\_secure\_socket()''.
\section{Other Diffie-Hellman Functions}
XXX-TODO
\begin{verbatim}
int dh_set_pg(const unsigned char *p, unsigned long plen,
const unsigned char *g, unsigned long glen,
dh_key *key);
int dh_set_pg_dhparam(const unsigned char *dhparam, unsigned long dhparamlen, dh_key *key);
int dh_set_key(const unsigned char *in, unsigned long inlen, int type, dh_key *key);
\end{verbatim}
\chapter{Elliptic Curve Cryptography}
\mysection{Background}