|
47 | 47 | \def\gap{\vspace{0.5ex}} |
48 | 48 | \makeindex |
49 | 49 | \begin{document} |
50 | | -\title{LibTomCrypt \\ Version 1.07} |
| 50 | +\title{LibTomCrypt \\ Version 1.08} |
51 | 51 | \author{Tom St Denis \\ |
52 | 52 | \\ |
53 | 53 | tomstdenis@gmail.com \\ |
@@ -3198,7 +3198,7 @@ \section{ASN.1 Formats} |
3198 | 3198 | 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 |
3199 | 3199 | format and two functions have been dedicated to encoding and decoding the format. |
3200 | 3200 |
|
3201 | | -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 |
| 3201 | +On top of the basic data types are the SEQUENCE and SET data types which are collections of other ASN.1 types. They are provided |
3202 | 3202 | 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 |
3203 | 3203 |
|
3204 | 3204 | \index{ltc\_asn1\_list structure} |
@@ -3262,7 +3262,9 @@ \section{ASN.1 Formats} |
3262 | 3262 | \hline LTC\_ASN1\_IA5\_STRING & IA5 STRING (one octet per char) \\ |
3263 | 3263 | \hline LTC\_ASN1\_PRINTABLE\_STRING & PRINTABLE STIRNG (one octet per char) \\ |
3264 | 3264 | \hline LTC\_ASN1\_UTCTIME & UTCTIME (see ltc\_utctime structure) \\ |
3265 | | -\hline LTC\_ASN1\_SEQUENCE & SEQUENCE OF \\ |
| 3265 | +\hline LTC\_ASN1\_SEQUENCE & SEQUENCE (and SEQUENCE OF) \\ |
| 3266 | +\hline LTC\_ASN1\_SET & SET \\ |
| 3267 | +\hline LTC\_ASN1\_SETOF & SET OF \\ |
3266 | 3268 | \hline LTC\_ASN1\_CHOICE & CHOICE \\ |
3267 | 3269 | \hline |
3268 | 3270 | \end{tabular} |
@@ -3347,6 +3349,68 @@ \subsubsection{SEQUENCE Multiple Argument Lists} |
3347 | 3349 | 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 |
3348 | 3350 | 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. |
3349 | 3351 |
|
| 3352 | +\subsection{SET and SET OF} |
| 3353 | +
|
| 3354 | +\index{SET} \index{SET OF} |
| 3355 | +SET and SET OF are related to the SEQUENCE type in that they can be pretty much be decoded with the same code. However, they are different and they should |
| 3356 | +be carefully noted. The SET type is an unordered array of ASN.1 types sorted by the TAG (type identifier) whereas the SET OF type is an ordered array of |
| 3357 | +a \textbf{single} ASN.1 object sorted in ascending order by the DER their respective encodings. |
| 3358 | +
|
| 3359 | +\subsubsection{SET Encoding} |
| 3360 | +
|
| 3361 | +SETs use the same array structure of ltc\_asn1\_list that the SEQUENCE functions use. They are encoded with the following function. |
| 3362 | +
|
| 3363 | +\index{der\_encode\_set()} |
| 3364 | +\begin{verbatim} |
| 3365 | +int der_encode_set(ltc_asn1_list *list, unsigned long inlen, |
| 3366 | + unsigned char *out, unsigned long *outlen); |
| 3367 | +\end{verbatim} |
| 3368 | +
|
| 3369 | +This will encode the list of ASN.1 objects in ``list'' of length ``inlen'' objects and store the output in ``out'' of length ``outlen'' bytes. The function |
| 3370 | +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 |
| 3371 | +array (to make the process deterministic). |
| 3372 | +
|
| 3373 | +This function will \textbf{NOT} recognize ``DEFAULT'' objects and it is the responsibility of the caller to remove them as required. |
| 3374 | +
|
| 3375 | +\subsubsection{SET Decoding} |
| 3376 | +
|
| 3377 | +The SET type can be decoded with the following function. |
| 3378 | +
|
| 3379 | +\index{der\_decode\_set()} |
| 3380 | +\begin{verbatim} |
| 3381 | +int der_decode_set(const unsigned char *in, unsigned long inlen, |
| 3382 | + ltc_asn1_list *list, unsigned long outlen); |
| 3383 | +\end{verbatim} |
| 3384 | +
|
| 3385 | +This will decode the SET specified by ``list'' of length ``outlen'' objects from the input buffer ``in'' of length ``inlen'' octets. |
| 3386 | +
|
| 3387 | +It handles the fact that SETs are not strictly ordered and will make multiple passes (as required) through the list to decode all the objects. |
| 3388 | +
|
| 3389 | +\subsubsection{SET Length} |
| 3390 | +The length of a SET can be determined by calling der\_length\_sequence() since they have the same encoding length. |
| 3391 | +
|
| 3392 | +\subsubsection{SET OF Encoding} |
| 3393 | +A ``SET OF'' object is an array of identifical objects (e.g. OCTET STRING) sorted in ascending order by the DER encoding of the object. They are |
| 3394 | +used to store objects deterministically based solely on their encoding. It uses the same array structure of ltc\_asn1\_list that the SEQUENCE functions |
| 3395 | +use. They are encoded with the following function. |
| 3396 | +
|
| 3397 | +\index{der\_encode\_setof()} |
| 3398 | +\begin{verbatim} |
| 3399 | +int der_encode_setof(ltc_asn1_list *list, unsigned long inlen, |
| 3400 | + unsigned char *out, unsigned long *outlen); |
| 3401 | +\end{verbatim} |
| 3402 | +
|
| 3403 | +This will encode a ``SET OF'' containing the ``list'' of ``inlen'' ASN.1 objects and store the encoding in the output buffer ``out'' of length ``outlen''. |
| 3404 | +
|
| 3405 | +The routine will first encode the SET OF in an unordered fashion (in a temporary buffer) then sort using the XQSORT macro and copy back to the output buffer. This |
| 3406 | +means you need at least enough memory to keep an additional copy of the output on the heap. |
| 3407 | +
|
| 3408 | +\subsubsection{SET OF Decoding} |
| 3409 | +Since the decoding of a ``SET OF'' object is unambiguous it can be decoded with der\_decode\_sequence(). |
| 3410 | +
|
| 3411 | +\subsubsection{SET OF Length} |
| 3412 | +Like the SET type the der\_length\_sequence() function can be used to determine the length of a ``SET OF'' object. |
| 3413 | +
|
3350 | 3414 | \subsection{ASN.1 INTEGER} |
3351 | 3415 |
|
3352 | 3416 | To encode or decode INTEGER data types use the following functions. |
@@ -3547,8 +3611,8 @@ \subsection{ASN.1 Flexi Decoder} |
3547 | 3611 | and ``child''. The list works as a ``doubly-linked list'' structure where decoded items at the same level are sibblings (using next and prev) and items |
3548 | 3612 | encoded in a SEQUENCE are stored as a child element. |
3549 | 3613 |
|
3550 | | -When a SEQUENCE has been encountered a SEQUENCE item is added as a sibbling (e.g. list.type == LTC\_ASN1\_SEQUENCE) and the child pointer points to a new list |
3551 | | -of items contained within the sequence\footnote{The same will be true for the SET data type when I eventually support it.}. |
| 3614 | +When a SEQUENCE or SET has been encountered a SEQUENCE (or SET resp.) item will be added as a sibbling (e.g. list.type == LTC\_ASN1\_SEQUENCE) and the child |
| 3615 | +pointer points to a new list of items contained within the object. |
3552 | 3616 |
|
3553 | 3617 | \index{der\_decode\_sequence\_flexi()} |
3554 | 3618 | \begin{verbatim} |
@@ -5012,5 +5076,5 @@ \subsection{RSA Functions} |
5012 | 5076 | \end{document} |
5013 | 5077 |
|
5014 | 5078 | % $Source: /cvs/libtom/libtomcrypt/crypt.tex,v $ |
5015 | | -% $Revision: 1.55 $ |
5016 | | -% $Date: 2005/11/18 01:45:03 $ |
| 5079 | +% $Revision: 1.59 $ |
| 5080 | +% $Date: 2005/11/24 01:53:18 $ |
0 commit comments