dropbear: crypt.tex comparison

comparison crypt.tex @ 209:39d5d58461d6 libtomcrypt-orig LTC_1.05

Import of libtomcrypt 1.05

author	Matt Johnston <matt@ucc.asn.au>
date	Wed, 06 Jul 2005 03:53:40 +0000
parents	1c15b283127b
children

comparison

equal deleted inserted replaced

-:1c15b283127b
+:39d5d58461d6
 \def\twiddle{\raisebox{0.3ex}{\mbox{\tiny $\sim$}}}
 \def\gap{\vspace{0.5ex}}
 \makeindex
 \begin{document}
-\title{LibTomCrypt \\ Version 1.02}
+\title{LibTomCrypt \\ Version 1.05}
 \author{Tom St Denis \\
 \\
 [email protected] \\
 http://libtomcrypt.org
 }
 \maketitle
 This text and source code library are both hereby placed in the public domain.  This book has been
 formatted for A4 paper using the \LaTeX{} {\em book} macro package.
-\vspace{10cm}
+\vspace{15cm}
 \begin{flushright}Open Source.  Open Academia.  Open Minds.
 \mbox{ }
 \subsection{Initialization}
 \index{CBC Mode} \index{CTR Mode}
 \index{OFB Mode} \index{CFB Mode}
 The library provides simple support routines for handling CBC, CTR, CFB, OFB and ECB encoded messages.  Assuming the mode
 you want is XXX there is a structure called ``symmetric\_XXX'' that will contain the information required to
-use that mode.  They have identical setup routines (except ECB mode for obvious reasons):
+use that mode.  They have identical setup routines (except CTR and ECB mode):
 \index{ecb\_start()} \index{cfb\_start()} \index{cbc\_start()} \index{ofb\_start()} \index{ctr\_start()}
 \begin{verbatim}
 int XXX_start(int cipher, const unsigned char *IV,
 const unsigned char *key, int keylen,
 int num_rounds, symmetric_XXX *XXX);
+int ctr_start(               int   cipher,
+const unsigned char *IV,
+const unsigned char *key,       int keylen,
+int  num_rounds, int ctr_mode,
+symmetric_CTR *ctr);
 int ecb_start(int cipher, const unsigned char *key, int keylen,
 int num_rounds, symmetric_ECB *ecb);
 \end{verbatim}
 length as the block size\footnote{In otherwords the size of a block of plaintext for the cipher, e.g. 8 for DES, 16 for AES, etc.}
 of the cipher you choose.  It is important that the IV  be random for each unique message you want to encrypt.  The
 parameters ``key'', ``keylen'' and ``num\_rounds'' are the same as in the XXX\_setup() function call.  The final parameter
 is a pointer to the structure you want to hold the information for the mode of operation.
-Both routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise they return an error code.
+In the case of CTR mode there is an additional parameter ``ctr\_mode'' which specifies the mode that the counter is to be used in.
+If \textbf{CTR\_COUNTER\_LITTLE\_ENDIAN} was specified then the counter will be treated as a little endian value.  Otherwise, if
+\textbf{CTR\_COUNTER\_BIG\_ENDIAN} was specified the counter will be treated as a big endian value.
+The routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise they return an error code.
 \subsection{Encryption and Decryption}
 To actually encrypt or decrypt the following routines are provided:
 \index{ecb\_encrypt()} \index{ecb\_decrypt()} \index{cfb\_encrypt()} \index{cfb\_decrypt()}
 \index{cbc\_encrypt()} \index{cbc\_decrypt()} \index{ofb\_encrypt()} \index{ofb\_decrypt()} \index{ctr\_encrypt()} \index{ctr\_decrypt()}
 find_cipher("twofish"), /* index of desired cipher */
 IV, /* the initial vector */
 key, /* the secret key */
 16, /* length of secret key (16 bytes, 128 bits) */
 0, /* 0 == default # of rounds */
+CTR_COUNTER_LITTLE_ENDIAN, /* Little endian counter */
 &ctr)  /* where to store initialized CTR state */
 ) != CRYPT_OK) {
 printf("ctr_start error: %s\n", error_to_string(err));
 return -1;
 }
 if ((err = gcm_add_aad(gcm, aad, aadlen)) != CRYPT_OK) {
 return err;
 }
 /* process the plaintext */
-if ((err = gcm_add_process(gcm, pt, ptlen, pt, GCM_ENCRYPT)) != CRYPT_OK) {
+if ((err = gcm_process(gcm, pt, ptlen, pt, GCM_ENCRYPT)) != CRYPT_OK) {
 return err;
 }
 /* Finish up and get the MAC tag */
 taglen = sizeof(tag);
 if ((err = gcm_done(gcm, tag, &taglen)) != CRYPT_OK) {
 return err;
 }
+/* ... send a header describing the lengths ... */
 /* depending on the protocol and how IV is generated you may have to send it too... */
 send(socket, iv, ivlen, 0);
 /* send the aad */
 \chapter{RSA Public Key Cryptography}
 \section{Introduction}
 RSA wrote the PKCS \#1 specifications which detail RSA Public Key Cryptography.  In the specifications are
-padding algorithms for encryption and signatures.  The standard includes ``v1.5'' and ``v2.0'' algorithms.
+padding algorithms for encryption and signatures.  The standard includes the ``v2.1'' algorithms.
-To simplify matters a little the v2.0 encryption and signature padding algorithms are called OAEP and PSS
+To simplify matters a little the v2.1 encryption and signature padding algorithms are called OAEP and PSS
 respectively.
 \section{PKCS \#1 Encryption}
 PKCS \#1 RSA Encryption amounts to OAEP padding of the input message followed by the modular exponentiation.  As far as this portion of
 during encoding.
 If the function succeeds it decodes the OAEP encoded message into ``out'' of length ``outlen'' and stores a
 $1$ in ``res''.  If the packet is invalid it stores $0$ in ``res'' and if the function fails for another reason
 it returns an error code.
-\subsection{PKCS \#1 v1.5 Encoding}
-\index{pkcs\_1\_v15\_es\_encode()}
-\begin{verbatim}
-int pkcs_1_v15_es_encode(const unsigned char *msg,    unsigned long msglen,
-unsigned long  modulus_bitlen,
-prng_state    *prng,   int           prng_idx,
-unsigned char *out,    unsigned long *outlen);
-\end{verbatim}
-This will PKCS v1.5 encode the data in ``msg'' of length ``msglen''.  Pass the length (in bits) of your
-RSA modulus in ``modulus\_bitlen''.  The encoded data will be stored in ``out'' of length ``outlen''.
-\subsection{PKCS \#1 v1.5 Decoding}
-\index{pkcs\_1\_v15\_es\_decode()}
-\begin{verbatim}
-int pkcs_1_v15_es_decode(const unsigned char *msg,  unsigned long msglen,
-unsigned long modulus_bitlen,
-unsigned char *out,  unsigned long outlen,
-int           *res);
-\end{verbatim}
-This will PKCS v1.5 decode the message in ``msg'' of length ``msglen''.  It will store the output in ``out''. Note
-that the length of the output ``outlen'' is a constant.  This decoder cannot determine the original message
-length.  If the data in ``msg'' is a valid packet then a $1$ is stored in ``res'', otherwise a $0$ is
-stored.
 \section{PKCS \#1 Digital Signatures}
 \subsection{PSS Encoding}
 PSS encoding is the second half of the PKCS \#1 standard which is padding to be applied to messages that are signed.
 ``msghashlen''.  If the block is a valid PSS block and the decoded hash equals the hash supplied ``res'' is set to non--zero.  Otherwise,
 it is set to zero.  The rest of the parameters are as in the PSS encode call.
 It's important to use the same ``saltlen'' and hash for both encoding and decoding as otherwise the procedure will not work.
-\subsection{PKCS \#1 v1.5 Encoding}
-\index{pkcs\_1\_v15\_sa\_encode()}
-\begin{verbatim}
-int pkcs_1_v15_sa_encode(const unsigned char *msghash,  unsigned long msghashlen,
-int            hash_idx, unsigned long modulus_bitlen,
-unsigned char *out,      unsigned long *outlen);
-\end{verbatim}
-This will PKCS \#1 v1.5 signature encode the message hash ``msghash''  of length ``msghashlen''.  You have
-to tell this routine which hash produced the message hash in ``hash\_idx''.  The encoded hash is stored
-in ``out'' of length ``outlen''.
-\subsection{PKCS \#1 v1.5 Decoding}
-\index{pkcs\_1\_v15\_sa\_decode()}
-\begin{verbatim}
-int pkcs_1_v15_sa_decode(const unsigned char *msghash, unsigned long msghashlen,
-const unsigned char *sig,     unsigned long siglen,
-int           hash_idx, unsigned long modulus_bitlen,
-int          *res);
-\end{verbatim}
-This will PKCS \#1 v1.5 signature decode the data in ``sig'' of length ``siglen'' and compare the extracted
-hash against ``msghash'' of length ``msghashlen''.  You have to tell this routine which hash produced the
-message digest in ``hash\_idx''.  If the packet is valid and the hashes match ``res'' is set to $1$.  Otherwise,
-it is set to $0$.
 \section{RSA Operations}
 \subsection{Background}
 RSA is a public key algorithm that is based on the inability to find the ``e-th'' root modulo a composite of unknown
 factorization.  Normally the difficulty of breaking RSA is associated with the integer factoring problem but they are
 \index{rsa\_decrypt\_key()}
 \begin{verbatim}
 int rsa_decrypt_key(const unsigned char *in,  unsigned long inlen,
 unsigned char *out, unsigned long *outlen,
 const unsigned char *lparam, unsigned long lparamlen,
-prng_state    *prng,   int           prng_idx,
+int            hash_idx, int *stat,
-int            hash_idx, int *res,
 rsa_key       *key);
 \end{verbatim}
 This function will RSA decrypt ``in'' of length ``inlen'' then OAEP depad the resulting data and store it in
 ``out'' of length ``outlen''.  The ``lparam'' and ``lparamlen'' are the same parameters you would pass
 to pkcs\_1\_oaep\_decode().
-If the RSA decrypted data isn't a valid OAEP packet then ``res'' is set to $0$.  Otherwise, it is set to $1$.
+If the RSA decrypted data isn't a valid OAEP packet then ``stat'' is set to $0$.  Otherwise, it is set to $1$.
 \subsection{RSA Hash Signatures}
 Similar to RSA key encryption RSA is also used to ``digitally sign'' message digests (hashes).  To facilitate this
 process the following functions have been provided.
 \index{rsa\_verify\_hash()}
 \begin{verbatim}
 int rsa_verify_hash(const unsigned char *sig,      unsigned long siglen,
 const unsigned char *msghash,  unsigned long msghashlen,
-prng_state    *prng,     int           prng_idx,
 int            hash_idx, unsigned long saltlen,
 int           *stat,     rsa_key      *key);
 \end{verbatim}
 This will RSA ``verify'' the signature in ``sig'' of length ``siglen''.  Next the RSA decoded data is PSS decoded
 l1, /* length of ciphertext */
 pt2, /* where to put plaintext */
 &l2, /* plaintext length */
 "TestApp", /* lparam for this program */
 7, /* lparam is 7 bytes long */
-NULL, /* PRNG state */
-prng_idx, /* prng idx */
 hash_idx, /* hash idx */
 &res, /* validity of data */
 &key) /* our RSA key */
 ) != CRYPT_OK) {
 printf("rsa_decrypt_key %s", error_to_string(err));
 The variable $b$ is chosen such that the number of points is nearly maximal.  In fact the order of the base points $\beta$
 provided are very close to $p$ that is $\vert \vert \phi(\beta) \vert \vert \approx \vert \vert p \vert \vert$.  The curves
 range in order from $\approx 2^{192}$ points to $\approx 2^{521}$.  According to the source document any key size greater
 than or equal to 256-bits is sufficient for long term security.
+\section{Key Format}
+LibTomCrypt uses it's own format for ECC public and private keys.  While ANSI X9.62 partially specifies key formats (it covers public keys) it does it in a less
+than ideally simple manner.  In the case of LibTomCrypt it is meant \textbf{solely} for NIST $GF(p)$ curves.  The format of the keys is as follows:
+\begin{small}
+\begin{verbatim}
+ECCPublicKey ::= SEQUENCE {
+flags       BIT STRING(1), -- public/private flag (always zero),
+keySize     INTEGER,       -- Curve size (in bits) divided by eight
+-- and rounded down, e.g. 521 => 65
+pubkey.x    INTEGER,       -- The X co-ordinate of the public key point
+pubkey.y    INTEGER,       -- The Y co-ordinate of the public key point
+}
+ECCPrivateKey ::= SEQUENCE {
+flags       BIT STRING(1), -- public/private flag (always one),
+keySize     INTEGER,       -- Curve size (in bits) divided by eight
+-- and rounded down, e.g. 521 => 65
+pubkey.x    INTEGER,       -- The X co-ordinate of the public key point
+pubkey.y    INTEGER,       -- The Y co-ordinate of the public key point
+secret.k    INTEGER,       -- The secret key scalar
+}
+\end{verbatim}
+\end{small}
+The first flags bit denotes whether the key is public (zero) or private (one).
 \section{Core Functions}
 Like the DH routines there is a key structure ``ecc\_key'' used by the functions.  There is a function to make a key:
 \index{ecc\_make\_key()}
 \begin{verbatim}
 int ecc_make_key(prng_state *prng, int wprng,
 int keysize, ecc_key *key);
 \end{verbatim}
-The ``keysize'' is the size of the modulus in bytes desired.  Currently directly supported values are 20, 24, 28, 32, 48 and 65 bytes which
+The ``keysize'' is the size of the modulus in bytes desired.  Currently directly supported values are 24, 28, 32, 48 and 65 bytes which
-correspond to key sizes of 160, 192, 224, 256, 384 and 521 bits respectively.  If you pass a key size that is between any key size
+correspond to key sizes of 192, 224, 256, 384 and 521 bits respectively.  If you pass a key size that is between any key size
 it will round the keysize up to the next available one.  The rest of the parameters work like they do in the ``dh\_make\_key()'' function.
 To free the ram allocated by a key call:
 \index{ecc\_free()}
 \begin{verbatim}
 void ecc_free(ecc_key *key);
 int ecc_decrypt_key(const unsigned char *in,  unsigned long  inlen,
 unsigned char *out, unsigned long *outlen,
 ecc_key *key);
 \end{verbatim}
-Where ``in'' is an input symmetric key of no more than 32 bytes.  Essentially these routines created a random public key
+Where ``in'' is an input symmetric key of no more than 64 bytes.  Essentially these routines created a random public key
 and find the hash of the shared secret.  The message digest is than XOR'ed against the symmetric key.  All of the required
 data is placed in ``out'' by ``ecc\_encrypt\_key()''.   The hash chosen must produce a message digest at least as large
 as the symmetric key you are trying to share.
+\subsection{Encrypt Packet Format}
+The packet format for the encrypted keys is the following ASN.1 SEQUENCE:
+\begin{verbatim}
+ECCEncrypt ::= SEQUENCE {
+hashID        OBJECT IDENTIFIER, -- OID of hash used
+pubkey        OCTET STRING     , -- Encapsulated ECCPublicKey (see above)
+skey          OCTET STRING       -- xor of plaintext and "hash of shared secret"
+}
+\end{verbatim}
 There are also functions to sign and verify the hash of a message.
 \index{ecc\_sign\_hash()} \index{ecc\_verify\_hash()}
 \begin{verbatim}
 int ecc_sign_hash(const unsigned char *in,  unsigned long inlen,
 unsigned char *out, unsigned long *outlen,
 The ``ecc\_sign\_hash'' function signs the message hash in ``in'' of length ``inlen'' and forms a ECC packet in ``out''.
 The ``ecc\_verify\_hash'' function verifies the ECC signature in ``sig'' against the hash in ``hash''.  It sets ``stat''
 to non-zero if the signature passes or zero if it fails.
+\subsection{Signature Format}
+The signature code is an implementation of X9.62 EC-DSA and the output is comformant for GF(p) curves.
 \section{ECC Keysizes}
 With ECC if you try and sign a hash that is bigger than your ECC key you can run into problems.  The math will still work
 and in effect the signature will still work.  With ECC keys the strength of the signature is limited by the size of
-the hash or the size of they key, whichever is smaller.  For example, if you sign with SHA256 and a ECC-160 key in effect
+the hash or the size of they key, whichever is smaller.  For example, if you sign with SHA256 and an ECC-192 key in effect
-you have 160-bits of security (e.g. as if you signed with SHA-1).
+you have 192-bits of security.
 The library will not warn you if you make this mistake so it is important to check yourself before using the
 signatures.
 \chapter{Digital Signature Algorithm}
 order at least 1024-bits.  With DSA you need a group of order at least 160-bits.  By comparison the ElGamal signature
 would require at least 256 bytes where as the DSA signature would require only at least 40 bytes.
 The API for the DSA is essentially the same as the other PK algorithms.  Except in the case of DSA no encryption or
 decryption routines are provided.
+\section{Key Format}
+Since no useful public standard for DSA key storage was presented to me during the course of this development I made my own ASN.1 SEQUENCE which I document
+now so that others can interoperate with this library.
+\begin{verbatim}
+DSAPublicKey ::= SEQUENCE {
+publicFlags    BIT STRING(1), -- must be 0
+g              INTEGER      , -- base generator, check that g^q mod p == 1
+-- and that 1 < g < p - 1
+p              INTEGER      , -- prime modulus
+q              INTEGER      , -- order of sub-group (must be prime)
+y              INTEGER      , -- public key, specifically, g^x mod p,
+-- check that y^q mod p == 1
+-- and that 1 < y < p - 1
+}
+DSAPrivateKey ::= SEQUENCE {
+publicFlags    BIT STRING(1), -- must be 1
+g              INTEGER      , -- base generator, check that g^q mod p == 1
+-- and that 1 < g < p - 1
+p              INTEGER      , -- prime modulus
+q              INTEGER      , -- order of sub-group (must be prime)
+y              INTEGER      , -- public key, specifically, g^x mod p,
+-- check that y^q mod p == 1
+-- and that 1 < y < p - 1
+x              INTEGER        -- private key
+}
+\end{verbatim}
+The leading BIT STRING has a single bit in it which is zero for public keys and one for private keys.  This makes the structure uniquely decodable and easy
+to work with.
 \section{Key Generation}
 To make a DSA key you must call the following function
 \begin{verbatim}
 int dsa_make_key(prng_state *prng, int wprng,
 This will import the DSA key from the buffer ``in'' of length ``inlen'' to the ``key''.  If the process fails the function
 will automatically free all of the heap allocated in the process (you don't have to call dsa\_free()).
 \chapter{Standards Support}
-\section{DER Support}
+\section{ASN.1 Formats}
-DER or ``Distinguished Encoding Rules'' is a subset of the ASN.1 encoding rules that is fully deterministic and
+LibTomCrypt supports a variety of ASN.1 data types encoded with the Distinguished Encoding Rules (DER) suitable for various cryptographic protocols.  The data types
-ideal for cryptography.  In particular ASN.1 specifies an INTEGER type for storing arbitrary sized integers.  DER
+are all provided with three basic functions with \textit{similar} prototypes.  One function has been dedicated to calculate the length in octets of a given
-further limits the ASN.1 specifications to a deterministic encoding.
+format and two functions have been dedicated to encoding and decoding the format.
-\subsection{Storing INTEGER types}
+On top of the basic data types are the SEQUENCE and\footnote{Planned for LTC 1.06} SET data types which are collections of other ASN.1 types.  They are provided
+in the same manner as the other data types except they use list of objects known as the \textbf{ltc\_asn1\_list} structure.  It is defined as
+\index{ltc\_asn1\_list structure}
+\begin{verbatim}
+typedef struct {
+int           type;
+void         *data;
+unsigned long size;
+int           used;
+} ltc_asn1_list;
+\end{verbatim}
+The ``type'' field is one of the following ASN.1 field definitions.  The ``data'' pointer is a void pointer to the data to be encoded (or the destination) and the
+``size'' field is specific to what you are encoding (e.g. number of bits in the BIT STRING data type).  The ``used'' field is primarily for the CHOICE decoder
+and reflects if the particular member of a list was the decoded data type.  To help build the lists in an orderly fashion the macro
+``LTC\_SET\_ASN1(list, index, Type, Data, Size)'' has been provided.
+It will assign to the ``index''th position in the ``list'' the tripplet (Type, Data, Size).  An example usage would be:
+\begin{small}
+\begin{verbatim}
+...
+ltc_asn1_list   sequence[3];
+unsigned long   three=3;
+LTC_SET_ASN1(sequence, 0, LTC_ASN1_IA5_STRING,    "hello", 5);
+LTC_SET_ASN1(sequence, 1, LTC_ASN1_SHORT_INTEGER, &three,  1);
+LTC_SET_ASN1(sequence, 2, LTC_ASN1_NULL,           NULL,   0);
+\end{verbatim}
+\end{small}
+The macro is relatively safe with respect to modifying variables, for instance the following code is equivalent.
+\begin{small}
+\begin{verbatim}
+...
+ltc_asn1_list   sequence[3];
+unsigned long   three=3;
+int             x=0;
+LTC_SET_ASN1(sequence, x++, LTC_ASN1_IA5_STRING,    "hello", 5);
+LTC_SET_ASN1(sequence, x++, LTC_ASN1_SHORT_INTEGER, &three,  1);
+LTC_SET_ASN1(sequence, x++, LTC_ASN1_NULL,           NULL,   0);
+\end{verbatim}
+\end{small}
+\begin{figure}[here]
+\begin{center}
+\begin{small}
+\begin{tabular}{|l|l|}
+\hline \textbf{Definition}           & \textbf{ASN.1 Type} \\
+\hline LTC\_ASN1\_EOL                & End of a ASN.1 list structure. \\
+\hline LTC\_ASN1\_INTEGER            & INTEGER (uses mp\_int) \\
+\hline LTC\_ASN1\_SHORT\_INTEGER     & INTEGER (32--bit using unsigned long) \\
+\hline LTC\_ASN1\_BIT\_STRING        & BIT STRING (one bit per char) \\
+\hline LTC\_ASN1\_OCTET\_STRING      & OCTET STRING (one octet per char) \\
+\hline LTC\_ASN1\_NULL               & NULL \\
+\hline LTC\_ASN1\_OBJECT\_IDENTIFIER & OBJECT IDENTIFIER (words are in unsigned long) \\
+\hline LTC\_ASN1\_IA5\_STRING        & IA5 STRING (one octet per char) \\
+\hline LTC\_ASN1\_PRINTABLE\_STRING  & PRINTABLE STIRNG (one octet per char) \\
+\hline LTC\_ASN1\_UTCTIME            & UTCTIME (see ltc\_utctime structure) \\
+\hline LTC\_ASN1\_SEQUENCE           & SEQUENCE OF \\
+\hline LTC\_ASN1\_CHOICE             & CHOICE \\
+\hline
+\end{tabular}
+\caption{List of ASN.1 Supported Types}
+\end{small}
+\end{center}
+\end{figure}
+\subsection{SEQUENCE Type}
+The SEQUENCE data type is a collection of other ASN.1 data types encapsulated with a small header which is a useful way of sending multiple data types in one packet.
+\subsubsection{SEUQNECE Encoding}
+To encode a sequence a \textbf{ltc\_asn1\_list} array must be initialized with the members of the sequence and their respective pointers.  The encoding is performed
+with the following function.
+\index{der\_encode\_sequence()}
+\begin{verbatim}
+int der_encode_sequence(ltc_asn1_list *list, unsigned long inlen,
+unsigned char *out,  unsigned long *outlen);
+\end{verbatim}
+This encodes a sequence of items pointed to by ``list'' where the list has ``inlen'' items in it.  The SEQUENCE will be encoded to ``out'' and of length ``outlen''.  The
+function will terminate when it reads all the items out of the list (upto ``inlen'') or it encounters an item in the list with a type of \textbf{LTC\_ASN1\_EOL}.
+The ``data'' pointer in the list would be the same pointer you would pass to the respective ASN.1 encoder (e.g. der\_encode\_bit\_string()) and it is simply passed on
+verbatim to the dependent encoder.  The list can contain other SEQUENCE or SET types which enables you to have nested SEQUENCE and SET definitions.  In these cases
+the ``data'' pointer is simply a pointer to another \textbf{ltc\_asn1\_list}.
+\subsubsection{SEQUENCE Decoding}
+\index{der\_decode\_sequence()}
+Decoding a SEQUENCE is similar to encoding.  You set up an array of \textbf{ltc\_asn1\_list} where in this case the ``size'' member is the maximum size
+(in certain cases).  For types such as IA5 STRING, BIT STRING, OCTET STRING (etc) the ``size'' field is updated after successful decoding to reflect how many
+units of the respective type has been loaded.
+\begin{verbatim}
+int der_decode_sequence(const unsigned char *in,   unsigned long  inlen,
+ltc_asn1_list *list, unsigned long  outlen);
+\end{verbatim}
+This will decode upto ``outlen'' items from the input buffer ``in'' of length ``inlen'' octets.  The function will stop (gracefully) when it runs out of items to decode.
+It will fail (for among other reasons) when it runs out of input bytes to read, a data type is invalid or a heap failure occured.
+For the following types the ``size'' field will be updated to reflect the number of units read of the given type.
+\begin{enumerate}
+\item BIT STRING
+\item OCTET STRING
+\item OBJECT IDENTIFIER
+\item IA5 STRING
+\item PRINTABLE STRING
+\end{enumerate}
+\subsubsection{SEQUENCE Length}
+The length of a SEQUENCE can be determined with the following function.
+\index{der\_length\_sequence()}
+\begin{verbatim}
+int der_length_sequence(ltc_asn1_list *list, unsigned long inlen,
+unsigned long *outlen);
+\end{verbatim}
+This will get the encoding size for the given ``list'' of length ``inlen'' and store it in ``outlen''.
+\subsubsection{SEQUENCE Multiple Argument Lists}
+For small or simple sequences an encoding or decoding can be performed with one of the following two functions.
+\index{der\_encode\_sequence\_multi()}
+\index{der\_decode\_sequence\_multi()}
+\begin{verbatim}
+int der_encode_sequence_multi(unsigned char *out, unsigned long *outlen, ...);
+int der_decode_sequence_multi(const unsigned char *in, unsigned long inlen, ...);
+\end{verbatim}
+These either encode or decode (respectively) a SEQUENCE data type where the items in the sequence are specified after the length parameter.
+The list of items are specified as a triple of the form ``(type, size, data)''  where ``type'' is an \textbf{int}, ``size'' is a \textbf{unsigned long}
+and ``data'' is \textbf{void} pointer.  The list of items must be terminated with an item with the type \textbf{LTC\_ASN1\_EOL}.
+It's ideal that you cast the ``size'' values to unsigned long to ensure that the proper data type is passed to the function.  Constants such as ``1'' without
+a cast or prototype are of type \textbf{int} by default.  Appending \textit{UL} or prepending \textit{(unsigned long)} is enough to cast it to the correct type.
+\subsection{ASN.1 INTEGER}
+To encode or decode INTEGER data types use the following functions.
 \index{der\_encode\_integer()}
-\begin{alltt}
+\index{der\_decode\_integer()}
+\index{der\_length\_integer()}
+\begin{verbatim}
 int der_encode_integer(mp_int *num, unsigned char *out, unsigned long *outlen);
-\end{alltt}
+int der_decode_integer(const unsigned char *in, unsigned long inlen, mp_int *num);
-This will store the integer in ``num'' to the output buffer ``out'' of length ``outlen''.  It only stores
-non--negative numbers.  It stores the number of octets used back in ``outlen''.
-\subsection{Reading INTEGER types}
-\index{der\_decode\_integer()}
-\begin{alltt}
-int der_decode_integer(const unsigned char *in, unsigned long *inlen, mp_int *num);
-\end{alltt}
-This will decode the DER encoded INTEGER in ``in'' of length ``inlen'' and store the resulting integer
-in ``num''.  It will store the bytes read in ``inlen'' which is handy if you have to parse multiple
-data items out of a binary packet.
-\subsection{INTEGER length}
-\index{der\_length\_integer()}
-\begin{alltt}
 int der_length_integer(mp_int *num, unsigned long *len);
-\end{alltt}
+\end{verbatim}
-This will determine the length of the DER encoding of the integer ``num'' and store it in ``len''.
+These will encode or decode a signed INTEGER data type using the ``mp\_int'' data type to store the large INTEGER.  To encode smaller values without allocating
-\subsection{Multiple INTEGER types}
+an mp\_int to store the value the ``short'' INTEGER functions were made available.
-To simplify the DER encoding/decoding there are two functions two handle multple types at once.
+\index{der\_encode\_short\_integer()}
-\index{der\_put\_multi\_integer()}
+\index{der\_decode\_short\_integer()}
-\index{der\_get\_multi\_integer()}
+\index{der\_length\_short\_integer()}
-\begin{alltt}
+\begin{verbatim}
-int der_put_multi_integer(unsigned char *dst, unsigned long *outlen, mp_int *num, ...);
+int der_encode_short_integer(unsigned long  num,
-int der_get_multi_integer(const unsigned char *src, unsigned long *inlen,  mp_int *num, ...);
+unsigned char *out, unsigned long *outlen);
-\end{alltt}
+int der_decode_short_integer(const unsigned char *in,  unsigned long inlen,
-These will handle multiple encodings/decodings at once.  They work like their single operand counterparts
+unsigned long *num);
-except they handle a \textbf{NULL} terminated list of operands.
+int der_length_short_integer(unsigned long num, unsigned long *outlen);
-\begin{verbatim}
+\end{verbatim}
-#include <tomcrypt.h>
-int main(void)
+These will encode or decode an unsigned \textbf{unsigned long} type (only reads upto 32--bits).  For values in the range $0 \dots 2^{32} - 1$ the integer
-{
+and short integer functions can encode and decode each others outputs.
-mp_int        a, b, c, d;
-unsigned char buffer[1000];
+\subsection{ASN.1 BIT STRING}
-unsigned long len;
-int           err;
+\index{der\_encode\_bit\_string()}
+\index{der\_decode\_bit\_string()}
-/* init a,b,c,d with some values ... */
+\index{der\_length\_bit\_string()}
+\begin{verbatim}
-/* ok we want to store them now... */
+int der_encode_bit_string(const unsigned char *in, unsigned long inlen,
-len = sizeof(buffer);
+unsigned char *out, unsigned long *outlen);
-if ((err = der_put_multi_integer(buffer, &len,
-&a, &b, &c, &d, NULL)) != CRYPT_OK) {
+int der_decode_bit_string(const unsigned char *in, unsigned long inlen,
-// error
+unsigned char *out, unsigned long *outlen);
-}
-printf("I stored %lu bytes in buf\n", len);
+int der_length_bit_string(unsigned long nbits, unsigned long *outlen);
+\end{verbatim}
-/* ok say we want to get them back for fun */
-/* len set previously...otherwise set it to the size of the packet */
+These will encode or decode a BIT STRING data type.  The bits are passed in (or read out) using one \textbf{char} per bit.  A non--zero value will be interpretted
-if ((err = der_get_multi_integer(buffer, &len,
+as a one bit and a zero value a zero bit.
-&a, &b, &c, &d, NULL)) != CRYPT_OK) {
-// error
+\subsection{ASN.1 OCTET STRING}
-}
-printf("I read %lu bytes from buf\n", len);
+\index{der\_encode\_octet\_string()}
-}
+\index{der\_decode\_octet\_string()}
-\end{verbatim}
+\index{der\_length\_octet\_string()}
+\begin{verbatim}
+int der_encode_octet_string(const unsigned char *in, unsigned long inlen,
+unsigned char *out, unsigned long *outlen);
+int der_decode_octet_string(const unsigned char *in, unsigned long inlen,
+unsigned char *out, unsigned long *outlen);
+int der_length_octet_string(unsigned long noctets, unsigned long *outlen);
+\end{verbatim}
+These will encode or decode an OCTET STRING data type.  The octets are stored using one \textbf{char} each.
+\subsection{ASN.1 OBJECT IDENTIFIER}
+\index{der\_encode\_object\_identifier()}
+\index{der\_decode\_object\_identifier()}
+\index{der\_length\_object\_identifier()}
+\begin{verbatim}
+int der_encode_object_identifier(unsigned long *words, unsigned long  nwords,
+unsigned char *out,   unsigned long *outlen);
+int der_decode_object_identifier(const unsigned char *in,    unsigned long  inlen,
+unsigned long *words, unsigned long *outlen);
+int der_length_object_identifier(unsigned long *words, unsigned long nwords,
+unsigned long *outlen);
+\end{verbatim}
+These will encode or decode an OBJECT IDENTIFIER object.  The words of the OID are stored in individual \textbf{unsigned long} elements and must be in the range
+$0 \ldots 2^{32} - 1$.
+\subsection{ASN.1 IA5 STRING}
+\index{der\_encode\_ia5\_string()}
+\index{der\_decode\_ia5\_string()}
+\index{der\_length\_ia5\_string()}
+\begin{verbatim}
+int der_encode_ia5_string(const unsigned char *in, unsigned long inlen,
+unsigned char *out, unsigned long *outlen);
+int der_decode_ia5_string(const unsigned char *in, unsigned long inlen,
+unsigned char *out, unsigned long *outlen);
+int der_length_ia5_string(const unsigned char *octets, unsigned long noctets,
+unsigned long *outlen);
+\end{verbatim}
+These will encode or decode an IA5 STRING.  The characters are read or stored in individual \textbf{char} elements.  This functions performs internal character
+to numerical conversions based on the conventions of the compiler being used.  For instance, on an x86\_32 machine 'A' == 65 but the same may not be true on
+say a SPARC machine.  Internally these functions have a table of literal characters and their numerical ASCII values.  This provides a stable conversion provided
+that the build platform honours the runtime platforms character conventions.
+If you're worried try building the test suite and running it.  It has hard coded test vectors to ensure it is operating properly.
+\subsection{ASN.1 PRINTABLE STRING}
+\index{der\_encode\_printable\_string()}
+\index{der\_decode\_printable\_string()}
+\index{der\_length\_printable\_string()}
+\begin{verbatim}
+int der_encode_printable_string(const unsigned char *in, unsigned long inlen,
+unsigned char *out, unsigned long *outlen);
+int der_decode_printable_string(const unsigned char *in, unsigned long inlen,
+unsigned char *out, unsigned long *outlen);
+int der_length_printable_string(const unsigned char *octets, unsigned long noctets,
+unsigned long *outlen);
+\end{verbatim}
+These will encode or decode an PRINTABLE STRING.  The characters are read or stored in individual \textbf{char} elements.  This functions performs internal character
+to numerical conversions based on the conventions of the compiler being used.  For instance, on an x86\_32 machine 'A' == 65 but the same may not be true on
+say a SPARC machine.  Internally these functions have a table of literal characters and their numerical ASCII values.  This provides a stable conversion provided
+that the build platform honours the runtime platforms character conventions.
+If you're worried try building the test suite and running it.  It has hard coded test vectors to ensure it is operating properly.
+\subsection{ASN.1 UTCTIME}
+The UTCTIME type is to store a date and time in ASN.1 format.  It uses the following structure to organize the time.
+\begin{verbatim}
+typedef struct {
+unsigned YY, /* year    00--99 */
+MM, /* month   01--12 */
+DD, /* day     01--31 */
+hh, /* hour    00--23 */
+mm, /* minute  00--59 */
+ss, /* second  00--59 */
+off_dir, /* timezone offset direction 0 == +, 1 == - */
+off_hh, /* timezone offset hours */
+off_mm; /* timezone offset minutes */
+} ltc_utctime;
+\end{verbatim}
+The time can be offset plus or minus a set amount of hours (off\_hh) and minutes (off\_mm).  When ``off\_dir'' is zero the time will be added otherwise it
+will be subtracted.
+For instance, the array $\lbrace 5, 6, 20, 22, 4, 00, 0, 5, 0 \rbrace$ represents the current time of 2005, June 20th, 22:04:00 with a time offset of +05h00.
+\index{der\_encode\_utctime()}
+\index{der\_decode\_utctime()}
+\index{der\_length\_utctime()}
+\begin{verbatim}
+int der_encode_utctime(ltc_utctime *utctime,
+unsigned char *out,   unsigned long *outlen);
+int der_decode_utctime(const unsigned char *in, unsigned long *inlen,
+ltc_utctime   *out);
+int der_length_utctime(ltc_utctime *utctime, unsigned long *outlen);
+\end{verbatim}
+The encoder will store time in one of the two ASN.1 formats, either ``YYMMDDhhmmssZ'' or ``YYMMDDhhmmss$\pm$hhmm'' and perform minimal error checking on the
+input.  The decoder will read all valid ASN.1 formats and perform range checking on the values (not complete but rational) useful for catching packet errors.
+It is suggested that decoded data be further scrutinized (e.g. days of month in particular).
+\subsection{ASN.1 CHOICE}
+The CHOICE ASN.1 type represents a union of ASN.1 types all of which are stored in a ``ltc\_asn1\_list''.  There is no encoder for the CHOICE type, only a
+decoder.  The decoder will scan through the provided list attempting to use the appropriate decoder on the input packet.  The list can contain any ASN.1 data
+type\footnote{Except it cannot have LTC\_ASN1\_INTEGER and LTC\_ASN1\_SHORT\_INTEGER simultaneously.} except for other CHOICE types.
+There is no encoder for the CHOICE type as the actual DER encoding is the encoding of the chosen type.
+\index{der\_decode\_choice()}
+\begin{verbatim}
+int der_decode_choice(const unsigned char *in,   unsigned long *inlen,
+ltc_asn1_list *list, unsigned long  outlen);
+\end{verbatim}
+This will decode the input in the ``in'' field of length ``inlen''.  It uses the provided ASN.1 list specified in the ``list'' field which has ``outlen'' elements.
+The ``inlen'' field will be updated with the length of the decoded data type as well as the respective entry in the ``list'' field will have the ``used'' flag
+set to non--zero to reflect it was the data type decoded.
 \section{Password Based Cryptography}
 \subsection{PKCS \#5}
+\index{PKCS \#5}
 In order to securely handle user passwords for the purposes of creating session keys and chaining IVs the PKCS \#5 was drafted.   PKCS \#5
 is made up of two algorithms, Algorithm One and Algorithm Two.  Algorithm One is the older fairly limited algorithm which has been implemented
 for completeness.  Algorithm Two is a bit more modern and more flexible to work with.
 \subsection{Algorithm One}
 memcpy(mac_key,    outbuf+32, 16);
 /* use material (recall to store the salt in the output) */
 \}
 \end{alltt}
 \chapter{Miscellaneous}
 \section{Base64 Encoding and Decoding}
 The library provides functions to encode and decode a RFC1521 base64 coding scheme.  This means that it can decode what it
 encodes but the format used does not comply to any known standard.  The characters used in the mappings are:
 The work factor for ECC keys is much higher since the best attack is still fully exponentional.  Given a key of magnitude
 $n$ it requires $\sqrt n$ work.  The following table sumarizes the work required:
 \begin{center}
 \begin{tabular}{|c|c|}
 \hline ECC Key Size (bits) & Work Factor ($log_2$) \\
-\hline 160 & 80  \\
 \hline 192 & 96  \\
 \hline 224 & 112 \\
 \hline 256 & 128 \\
 \hline 384 & 192 \\
 \hline 521 & 260.5 \\
 useful when TWOFISH\_SMALL is defined as the table values are computed on the fly.  When this is defined the code size
 will increase by approximately 500 bytes.  If this is defined but TWOFISH\_SMALL is not the cipher will still work but
 it will not speed up the encryption or decryption functions.
 \subsection{GCM\_TABLES}
-When defined GCM will use a 64KB table (per GCM state) which will greatly lower up the per--packet latency.
+When defined GCM will use a 64KB table (per GCM state) which will greatly speed up the per--packet latency.
-It also increases the initialization time.
+It also increases the initialization time and isn't suitable when you are going to use a key a few times only.
 \subsection{SMALL\_CODE}
 When this is defined some of the code such as the Rijndael and SAFER+ ciphers are replaced with smaller code variants.
 These variants are slower but can save quite a bit of code space.
 If you do plan on using the ``LTC\_FAST'' mode you have to also define a ``LTC\_FAST\_TYPE'' macro which resolves to an optimal sized
 data type you can perform integer operations with.  Ideally it should be four or eight bytes since it must properly divide the size
 of your block cipher (e.g. 16 bytes for AES).  This means sadly if you're on a platform with 57--bit words (or something) you can't
 use this mode.  So sad.
+\subsection{LTC\_PTHREAD}
+When this is activated all of the descriptor table functions will use pthread locking to ensure thread safe updates to the tables.  Note that
+it doesn't prevent a thread that is passively using a table from being messed up by another thread that updates the table.
+Generally the rule of thumb is to setup the tables once at startup and then leave them be.  This added build flag simply makes updating
+the tables safer.
 \section{MPI Tweaks}
 \subsection{RSA Only Tweak}
 If you plan on only using RSA with moduli in the range of 1024 to 2560 bits you can enable a series of tweaks
 to reduce the library size.  Follow these steps
 \subsection{Setup}
 To initialize a cipher (for ECB mode) the function setup() was provided.  It accepts an array of key octets ``key'' of length ``keylen'' octets.  The user
 can specify the number of rounds they want through ``num\_rounds'' where $num\_rounds = 0$ means use the default.  The destination of a scheduled key is stored
 in ``skey''.
-This is where things get tricky.  Currently there is no provision to allocate memory during initialization since there is no ``cipher done'' function.  So you have
+Inside the ``symmetric\_key'' union there is a ``void *data'' which you can use to allocate data if you need a data structure that doesn't fit with the existing
-to either use an existing member of the symmetric\_key union or alias your own structure over top of it provided symmetric\_key is not smaller.
+ones provided.  Just make sure in your ``done()'' function that you free the allocated memory.
 \subsection{Single block ECB}
 To process a single block in ECB mode the ecb\_encrypt() and ecb\_decrypt() functions were provided.  The plaintext and ciphertext buffers are allowed to overlap so you
 must make sure you do not overwrite the output before you are finished with the input.
 updated by the function before returning.
 \subsubsection{Accelerated CTR}
 This function is meant for accelerated CTR encryption.  It is accessible through the accel\_ctr\_encrypt pointer.
 The ``blocks'' value is the number of complete blocks to process.  The ``IV'' is the CTR counter vector.  It is an input upon calling this function and must be
-updated by the function before returning.  The ``mode'' value indicates whether the counter is big ($mode = 1$) or little ($mode = 0$) endian.
+updated by the function before returning.  The ``mode'' value indicates whether the counter is big (mode = CTR\_COUNTER\_BIG\_ENDIAN) or
+little (mode = CTR\_COUNTER\_LITTLE\_ENDIAN) endian.
 This function (and the way it's called) differs from the other two since ctr\_encrypt() allows any size input plaintext.  The accelerator will only be
 called if the following conditions are met.
 \begin{enumerate}
 unsigned char ID;
 /** Size of digest in octets */
 unsigned long hashsize;
 /** Input block size in octets */
 unsigned long blocksize;
-/** ASN.1 DER identifier */
+/** ASN.1 OID */
-unsigned char DER[64];
+unsigned long OID[16];
 /** Length of DER encoding */
-unsigned long DERlen;
+unsigned long OIDlen;
 /** Init a hash state
 @param hash   The hash to initialize
 @return CRYPT_OK if successful
 */
 int (*init)(hash_state *hash);
 \subsection{Block Size}
 The `blocksize'' variable indicates the length of input (in octets) that the hash processes in a given
 invokation.
-\subsection{DER Identifier}
+\subsection{OID Identifier}
-This is the DER identifier (including the SEQUENCE header).  This is used solely for PKCS \#1 style signatures.
+This is the universal ASN.1 Object Identifier for the hash.
 \subsection{Initialization}
 The init function initializes the hash and prepares it to process message bytes.
 \subsection{Process}
 but should at least maintain the same level of state entropy.
 \input{crypt.ind}
 \end{document}
+% $Source: /cvs/libtom/libtomcrypt/crypt.tex,v $
+% $Revision: 1.39 $
+% $Date: 2005/06/27 13:08:28 $

Mercurial > dropbear

comparison crypt.tex @ 209:39d5d58461d6 libtomcrypt-orig LTC_1.05