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
191:1c15b283127b 209:39d5d58461d6
45 \def\twiddle{\raisebox{0.3ex}{\mbox{\tiny $\sim$}}} 45 \def\twiddle{\raisebox{0.3ex}{\mbox{\tiny $\sim$}}}
46 46
47 \def\gap{\vspace{0.5ex}} 47 \def\gap{\vspace{0.5ex}}
48 \makeindex 48 \makeindex
49 \begin{document} 49 \begin{document}
50 \title{LibTomCrypt \\ Version 1.02} 50 \title{LibTomCrypt \\ Version 1.05}
51 \author{Tom St Denis \\ 51 \author{Tom St Denis \\
52 \\ 52 \\
53 [email protected] \\ 53 [email protected] \\
54 http://libtomcrypt.org 54 http://libtomcrypt.org
55 } 55 }
56 \maketitle 56 \maketitle
57 This text and source code library are both hereby placed in the public domain. This book has been 57 This text and source code library are both hereby placed in the public domain. This book has been
58 formatted for A4 paper using the \LaTeX{} {\em book} macro package. 58 formatted for A4 paper using the \LaTeX{} {\em book} macro package.
59 59
60 \vspace{10cm} 60 \vspace{15cm}
61 61
62 \begin{flushright}Open Source. Open Academia. Open Minds. 62 \begin{flushright}Open Source. Open Academia. Open Minds.
63 63
64 \mbox{ } 64 \mbox{ }
65 65
769 \subsection{Initialization} 769 \subsection{Initialization}
770 \index{CBC Mode} \index{CTR Mode} 770 \index{CBC Mode} \index{CTR Mode}
771 \index{OFB Mode} \index{CFB Mode} 771 \index{OFB Mode} \index{CFB Mode}
772 The library provides simple support routines for handling CBC, CTR, CFB, OFB and ECB encoded messages. Assuming the mode 772 The library provides simple support routines for handling CBC, CTR, CFB, OFB and ECB encoded messages. Assuming the mode
773 you want is XXX there is a structure called ``symmetric\_XXX'' that will contain the information required to 773 you want is XXX there is a structure called ``symmetric\_XXX'' that will contain the information required to
774 use that mode. They have identical setup routines (except ECB mode for obvious reasons): 774 use that mode. They have identical setup routines (except CTR and ECB mode):
775 \index{ecb\_start()} \index{cfb\_start()} \index{cbc\_start()} \index{ofb\_start()} \index{ctr\_start()} 775 \index{ecb\_start()} \index{cfb\_start()} \index{cbc\_start()} \index{ofb\_start()} \index{ctr\_start()}
776 \begin{verbatim} 776 \begin{verbatim}
777 int XXX_start(int cipher, const unsigned char *IV, 777 int XXX_start(int cipher, const unsigned char *IV,
778 const unsigned char *key, int keylen, 778 const unsigned char *key, int keylen,
779 int num_rounds, symmetric_XXX *XXX); 779 int num_rounds, symmetric_XXX *XXX);
780
781 int ctr_start( int cipher,
782 const unsigned char *IV,
783 const unsigned char *key, int keylen,
784 int num_rounds, int ctr_mode,
785 symmetric_CTR *ctr);
780 786
781 int ecb_start(int cipher, const unsigned char *key, int keylen, 787 int ecb_start(int cipher, const unsigned char *key, int keylen,
782 int num_rounds, symmetric_ECB *ecb); 788 int num_rounds, symmetric_ECB *ecb);
783 \end{verbatim} 789 \end{verbatim}
784 790
787 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.} 793 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.}
788 of the cipher you choose. It is important that the IV be random for each unique message you want to encrypt. The 794 of the cipher you choose. It is important that the IV be random for each unique message you want to encrypt. The
789 parameters ``key'', ``keylen'' and ``num\_rounds'' are the same as in the XXX\_setup() function call. The final parameter 795 parameters ``key'', ``keylen'' and ``num\_rounds'' are the same as in the XXX\_setup() function call. The final parameter
790 is a pointer to the structure you want to hold the information for the mode of operation. 796 is a pointer to the structure you want to hold the information for the mode of operation.
791 797
792 Both routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise they return an error code. 798
799 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.
800 If \textbf{CTR\_COUNTER\_LITTLE\_ENDIAN} was specified then the counter will be treated as a little endian value. Otherwise, if
801 \textbf{CTR\_COUNTER\_BIG\_ENDIAN} was specified the counter will be treated as a big endian value.
802
803 The routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise they return an error code.
793 804
794 \subsection{Encryption and Decryption} 805 \subsection{Encryption and Decryption}
795 To actually encrypt or decrypt the following routines are provided: 806 To actually encrypt or decrypt the following routines are provided:
796 \index{ecb\_encrypt()} \index{ecb\_decrypt()} \index{cfb\_encrypt()} \index{cfb\_decrypt()} 807 \index{ecb\_encrypt()} \index{ecb\_decrypt()} \index{cfb\_encrypt()} \index{cfb\_decrypt()}
797 \index{cbc\_encrypt()} \index{cbc\_decrypt()} \index{ofb\_encrypt()} \index{ofb\_decrypt()} \index{ctr\_encrypt()} \index{ctr\_decrypt()} 808 \index{cbc\_encrypt()} \index{cbc\_decrypt()} \index{ofb\_encrypt()} \index{ofb\_decrypt()} \index{ctr\_encrypt()} \index{ctr\_decrypt()}
865 find_cipher("twofish"), /* index of desired cipher */ 876 find_cipher("twofish"), /* index of desired cipher */
866 IV, /* the initial vector */ 877 IV, /* the initial vector */
867 key, /* the secret key */ 878 key, /* the secret key */
868 16, /* length of secret key (16 bytes, 128 bits) */ 879 16, /* length of secret key (16 bytes, 128 bits) */
869 0, /* 0 == default # of rounds */ 880 0, /* 0 == default # of rounds */
881 CTR_COUNTER_LITTLE_ENDIAN, /* Little endian counter */
870 &ctr) /* where to store initialized CTR state */ 882 &ctr) /* where to store initialized CTR state */
871 ) != CRYPT_OK) { 883 ) != CRYPT_OK) {
872 printf("ctr_start error: %s\n", error_to_string(err)); 884 printf("ctr_start error: %s\n", error_to_string(err));
873 return -1; 885 return -1;
874 } 886 }
1347 if ((err = gcm_add_aad(gcm, aad, aadlen)) != CRYPT_OK) { 1359 if ((err = gcm_add_aad(gcm, aad, aadlen)) != CRYPT_OK) {
1348 return err; 1360 return err;
1349 } 1361 }
1350 1362
1351 /* process the plaintext */ 1363 /* process the plaintext */
1352 if ((err = gcm_add_process(gcm, pt, ptlen, pt, GCM_ENCRYPT)) != CRYPT_OK) { 1364 if ((err = gcm_process(gcm, pt, ptlen, pt, GCM_ENCRYPT)) != CRYPT_OK) {
1353 return err; 1365 return err;
1354 } 1366 }
1355 1367
1356 /* Finish up and get the MAC tag */ 1368 /* Finish up and get the MAC tag */
1357 taglen = sizeof(tag); 1369 taglen = sizeof(tag);
1358 if ((err = gcm_done(gcm, tag, &taglen)) != CRYPT_OK) { 1370 if ((err = gcm_done(gcm, tag, &taglen)) != CRYPT_OK) {
1359 return err; 1371 return err;
1360 } 1372 }
1373
1374 /* ... send a header describing the lengths ... */
1361 1375
1362 /* depending on the protocol and how IV is generated you may have to send it too... */ 1376 /* depending on the protocol and how IV is generated you may have to send it too... */
1363 send(socket, iv, ivlen, 0); 1377 send(socket, iv, ivlen, 0);
1364 1378
1365 /* send the aad */ 1379 /* send the aad */
2450 2464
2451 \chapter{RSA Public Key Cryptography} 2465 \chapter{RSA Public Key Cryptography}
2452 2466
2453 \section{Introduction} 2467 \section{Introduction}
2454 RSA wrote the PKCS \#1 specifications which detail RSA Public Key Cryptography. In the specifications are 2468 RSA wrote the PKCS \#1 specifications which detail RSA Public Key Cryptography. In the specifications are
2455 padding algorithms for encryption and signatures. The standard includes ``v1.5'' and ``v2.0'' algorithms. 2469 padding algorithms for encryption and signatures. The standard includes the ``v2.1'' algorithms.
2456 To simplify matters a little the v2.0 encryption and signature padding algorithms are called OAEP and PSS 2470 To simplify matters a little the v2.1 encryption and signature padding algorithms are called OAEP and PSS
2457 respectively. 2471 respectively.
2458 2472
2459 \section{PKCS \#1 Encryption} 2473 \section{PKCS \#1 Encryption}
2460 2474
2461 PKCS \#1 RSA Encryption amounts to OAEP padding of the input message followed by the modular exponentiation. As far as this portion of 2475 PKCS \#1 RSA Encryption amounts to OAEP padding of the input message followed by the modular exponentiation. As far as this portion of
2506 during encoding. 2520 during encoding.
2507 2521
2508 If the function succeeds it decodes the OAEP encoded message into ``out'' of length ``outlen'' and stores a 2522 If the function succeeds it decodes the OAEP encoded message into ``out'' of length ``outlen'' and stores a
2509 $1$ in ``res''. If the packet is invalid it stores $0$ in ``res'' and if the function fails for another reason 2523 $1$ in ``res''. If the packet is invalid it stores $0$ in ``res'' and if the function fails for another reason
2510 it returns an error code. 2524 it returns an error code.
2511
2512 \subsection{PKCS \#1 v1.5 Encoding}
2513
2514 \index{pkcs\_1\_v15\_es\_encode()}
2515 \begin{verbatim}
2516 int pkcs_1_v15_es_encode(const unsigned char *msg, unsigned long msglen,
2517 unsigned long modulus_bitlen,
2518 prng_state *prng, int prng_idx,
2519 unsigned char *out, unsigned long *outlen);
2520 \end{verbatim}
2521
2522 This will PKCS v1.5 encode the data in ``msg'' of length ``msglen''. Pass the length (in bits) of your
2523 RSA modulus in ``modulus\_bitlen''. The encoded data will be stored in ``out'' of length ``outlen''.
2524
2525 \subsection{PKCS \#1 v1.5 Decoding}
2526 \index{pkcs\_1\_v15\_es\_decode()}
2527 \begin{verbatim}
2528 int pkcs_1_v15_es_decode(const unsigned char *msg, unsigned long msglen,
2529 unsigned long modulus_bitlen,
2530 unsigned char *out, unsigned long outlen,
2531 int *res);
2532 \end{verbatim}
2533
2534 This will PKCS v1.5 decode the message in ``msg'' of length ``msglen''. It will store the output in ``out''. Note
2535 that the length of the output ``outlen'' is a constant. This decoder cannot determine the original message
2536 length. If the data in ``msg'' is a valid packet then a $1$ is stored in ``res'', otherwise a $0$ is
2537 stored.
2538 2525
2539 \section{PKCS \#1 Digital Signatures} 2526 \section{PKCS \#1 Digital Signatures}
2540 2527
2541 \subsection{PSS Encoding} 2528 \subsection{PSS Encoding}
2542 PSS encoding is the second half of the PKCS \#1 standard which is padding to be applied to messages that are signed. 2529 PSS encoding is the second half of the PKCS \#1 standard which is padding to be applied to messages that are signed.
2575 ``msghashlen''. If the block is a valid PSS block and the decoded hash equals the hash supplied ``res'' is set to non--zero. Otherwise, 2562 ``msghashlen''. If the block is a valid PSS block and the decoded hash equals the hash supplied ``res'' is set to non--zero. Otherwise,
2576 it is set to zero. The rest of the parameters are as in the PSS encode call. 2563 it is set to zero. The rest of the parameters are as in the PSS encode call.
2577 2564
2578 It's important to use the same ``saltlen'' and hash for both encoding and decoding as otherwise the procedure will not work. 2565 It's important to use the same ``saltlen'' and hash for both encoding and decoding as otherwise the procedure will not work.
2579 2566
2580 \subsection{PKCS \#1 v1.5 Encoding}
2581
2582 \index{pkcs\_1\_v15\_sa\_encode()}
2583 \begin{verbatim}
2584 int pkcs_1_v15_sa_encode(const unsigned char *msghash, unsigned long msghashlen,
2585 int hash_idx, unsigned long modulus_bitlen,
2586 unsigned char *out, unsigned long *outlen);
2587 \end{verbatim}
2588
2589 This will PKCS \#1 v1.5 signature encode the message hash ``msghash'' of length ``msghashlen''. You have
2590 to tell this routine which hash produced the message hash in ``hash\_idx''. The encoded hash is stored
2591 in ``out'' of length ``outlen''.
2592
2593 \subsection{PKCS \#1 v1.5 Decoding}
2594
2595 \index{pkcs\_1\_v15\_sa\_decode()}
2596 \begin{verbatim}
2597 int pkcs_1_v15_sa_decode(const unsigned char *msghash, unsigned long msghashlen,
2598 const unsigned char *sig, unsigned long siglen,
2599 int hash_idx, unsigned long modulus_bitlen,
2600 int *res);
2601 \end{verbatim}
2602
2603 This will PKCS \#1 v1.5 signature decode the data in ``sig'' of length ``siglen'' and compare the extracted
2604 hash against ``msghash'' of length ``msghashlen''. You have to tell this routine which hash produced the
2605 message digest in ``hash\_idx''. If the packet is valid and the hashes match ``res'' is set to $1$. Otherwise,
2606 it is set to $0$.
2607
2608 \section{RSA Operations} 2567 \section{RSA Operations}
2609 \subsection{Background} 2568 \subsection{Background}
2610 2569
2611 RSA is a public key algorithm that is based on the inability to find the ``e-th'' root modulo a composite of unknown 2570 RSA is a public key algorithm that is based on the inability to find the ``e-th'' root modulo a composite of unknown
2612 factorization. Normally the difficulty of breaking RSA is associated with the integer factoring problem but they are 2571 factorization. Normally the difficulty of breaking RSA is associated with the integer factoring problem but they are
2696 \index{rsa\_decrypt\_key()} 2655 \index{rsa\_decrypt\_key()}
2697 \begin{verbatim} 2656 \begin{verbatim}
2698 int rsa_decrypt_key(const unsigned char *in, unsigned long inlen, 2657 int rsa_decrypt_key(const unsigned char *in, unsigned long inlen,
2699 unsigned char *out, unsigned long *outlen, 2658 unsigned char *out, unsigned long *outlen,
2700 const unsigned char *lparam, unsigned long lparamlen, 2659 const unsigned char *lparam, unsigned long lparamlen,
2701 prng_state *prng, int prng_idx, 2660 int hash_idx, int *stat,
2702 int hash_idx, int *res,
2703 rsa_key *key); 2661 rsa_key *key);
2704 \end{verbatim} 2662 \end{verbatim}
2705 This function will RSA decrypt ``in'' of length ``inlen'' then OAEP depad the resulting data and store it in 2663 This function will RSA decrypt ``in'' of length ``inlen'' then OAEP depad the resulting data and store it in
2706 ``out'' of length ``outlen''. The ``lparam'' and ``lparamlen'' are the same parameters you would pass 2664 ``out'' of length ``outlen''. The ``lparam'' and ``lparamlen'' are the same parameters you would pass
2707 to pkcs\_1\_oaep\_decode(). 2665 to pkcs\_1\_oaep\_decode().
2708 2666
2709 If the RSA decrypted data isn't a valid OAEP packet then ``res'' is set to $0$. Otherwise, it is set to $1$. 2667 If the RSA decrypted data isn't a valid OAEP packet then ``stat'' is set to $0$. Otherwise, it is set to $1$.
2710 2668
2711 \subsection{RSA Hash Signatures} 2669 \subsection{RSA Hash Signatures}
2712 Similar to RSA key encryption RSA is also used to ``digitally sign'' message digests (hashes). To facilitate this 2670 Similar to RSA key encryption RSA is also used to ``digitally sign'' message digests (hashes). To facilitate this
2713 process the following functions have been provided. 2671 process the following functions have been provided.
2714 2672
2727 2685
2728 \index{rsa\_verify\_hash()} 2686 \index{rsa\_verify\_hash()}
2729 \begin{verbatim} 2687 \begin{verbatim}
2730 int rsa_verify_hash(const unsigned char *sig, unsigned long siglen, 2688 int rsa_verify_hash(const unsigned char *sig, unsigned long siglen,
2731 const unsigned char *msghash, unsigned long msghashlen, 2689 const unsigned char *msghash, unsigned long msghashlen,
2732 prng_state *prng, int prng_idx,
2733 int hash_idx, unsigned long saltlen, 2690 int hash_idx, unsigned long saltlen,
2734 int *stat, rsa_key *key); 2691 int *stat, rsa_key *key);
2735 \end{verbatim} 2692 \end{verbatim}
2736 2693
2737 This will RSA ``verify'' the signature in ``sig'' of length ``siglen''. Next the RSA decoded data is PSS decoded 2694 This will RSA ``verify'' the signature in ``sig'' of length ``siglen''. Next the RSA decoded data is PSS decoded
2797 l1, /* length of ciphertext */ 2754 l1, /* length of ciphertext */
2798 pt2, /* where to put plaintext */ 2755 pt2, /* where to put plaintext */
2799 &l2, /* plaintext length */ 2756 &l2, /* plaintext length */
2800 "TestApp", /* lparam for this program */ 2757 "TestApp", /* lparam for this program */
2801 7, /* lparam is 7 bytes long */ 2758 7, /* lparam is 7 bytes long */
2802 NULL, /* PRNG state */
2803 prng_idx, /* prng idx */
2804 hash_idx, /* hash idx */ 2759 hash_idx, /* hash idx */
2805 &res, /* validity of data */ 2760 &res, /* validity of data */
2806 &key) /* our RSA key */ 2761 &key) /* our RSA key */
2807 ) != CRYPT_OK) { 2762 ) != CRYPT_OK) {
2808 printf("rsa_decrypt_key %s", error_to_string(err)); 2763 printf("rsa_decrypt_key %s", error_to_string(err));
3058 The variable $b$ is chosen such that the number of points is nearly maximal. In fact the order of the base points $\beta$ 3013 The variable $b$ is chosen such that the number of points is nearly maximal. In fact the order of the base points $\beta$
3059 provided are very close to $p$ that is $\vert \vert \phi(\beta) \vert \vert \approx \vert \vert p \vert \vert$. The curves 3014 provided are very close to $p$ that is $\vert \vert \phi(\beta) \vert \vert \approx \vert \vert p \vert \vert$. The curves
3060 range in order from $\approx 2^{192}$ points to $\approx 2^{521}$. According to the source document any key size greater 3015 range in order from $\approx 2^{192}$ points to $\approx 2^{521}$. According to the source document any key size greater
3061 than or equal to 256-bits is sufficient for long term security. 3016 than or equal to 256-bits is sufficient for long term security.
3062 3017
3018 \section{Key Format}
3019 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
3020 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:
3021
3022 \begin{small}
3023 \begin{verbatim}
3024 ECCPublicKey ::= SEQUENCE {
3025 flags BIT STRING(1), -- public/private flag (always zero),
3026 keySize INTEGER, -- Curve size (in bits) divided by eight
3027 -- and rounded down, e.g. 521 => 65
3028 pubkey.x INTEGER, -- The X co-ordinate of the public key point
3029 pubkey.y INTEGER, -- The Y co-ordinate of the public key point
3030 }
3031
3032 ECCPrivateKey ::= SEQUENCE {
3033 flags BIT STRING(1), -- public/private flag (always one),
3034 keySize INTEGER, -- Curve size (in bits) divided by eight
3035 -- and rounded down, e.g. 521 => 65
3036 pubkey.x INTEGER, -- The X co-ordinate of the public key point
3037 pubkey.y INTEGER, -- The Y co-ordinate of the public key point
3038 secret.k INTEGER, -- The secret key scalar
3039 }
3040 \end{verbatim}
3041 \end{small}
3042
3043 The first flags bit denotes whether the key is public (zero) or private (one).
3044
3063 \section{Core Functions} 3045 \section{Core Functions}
3064 3046
3065 Like the DH routines there is a key structure ``ecc\_key'' used by the functions. There is a function to make a key: 3047 Like the DH routines there is a key structure ``ecc\_key'' used by the functions. There is a function to make a key:
3066 \index{ecc\_make\_key()} 3048 \index{ecc\_make\_key()}
3067 \begin{verbatim} 3049 \begin{verbatim}
3068 int ecc_make_key(prng_state *prng, int wprng, 3050 int ecc_make_key(prng_state *prng, int wprng,
3069 int keysize, ecc_key *key); 3051 int keysize, ecc_key *key);
3070 \end{verbatim} 3052 \end{verbatim}
3071 3053
3072 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 3054 The ``keysize'' is the size of the modulus in bytes desired. Currently directly supported values are 24, 28, 32, 48 and 65 bytes which
3073 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 3055 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
3074 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. 3056 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.
3075 To free the ram allocated by a key call: 3057 To free the ram allocated by a key call:
3076 \index{ecc\_free()} 3058 \index{ecc\_free()}
3077 \begin{verbatim} 3059 \begin{verbatim}
3078 void ecc_free(ecc_key *key); 3060 void ecc_free(ecc_key *key);
3127 int ecc_decrypt_key(const unsigned char *in, unsigned long inlen, 3109 int ecc_decrypt_key(const unsigned char *in, unsigned long inlen,
3128 unsigned char *out, unsigned long *outlen, 3110 unsigned char *out, unsigned long *outlen,
3129 ecc_key *key); 3111 ecc_key *key);
3130 \end{verbatim} 3112 \end{verbatim}
3131 3113
3132 Where ``in'' is an input symmetric key of no more than 32 bytes. Essentially these routines created a random public key 3114 Where ``in'' is an input symmetric key of no more than 64 bytes. Essentially these routines created a random public key
3133 and find the hash of the shared secret. The message digest is than XOR'ed against the symmetric key. All of the required 3115 and find the hash of the shared secret. The message digest is than XOR'ed against the symmetric key. All of the required
3134 data is placed in ``out'' by ``ecc\_encrypt\_key()''. The hash chosen must produce a message digest at least as large 3116 data is placed in ``out'' by ``ecc\_encrypt\_key()''. The hash chosen must produce a message digest at least as large
3135 as the symmetric key you are trying to share. 3117 as the symmetric key you are trying to share.
3136 3118
3119 \subsection{Encrypt Packet Format}
3120
3121 The packet format for the encrypted keys is the following ASN.1 SEQUENCE:
3122
3123 \begin{verbatim}
3124 ECCEncrypt ::= SEQUENCE {
3125 hashID OBJECT IDENTIFIER, -- OID of hash used
3126 pubkey OCTET STRING , -- Encapsulated ECCPublicKey (see above)
3127 skey OCTET STRING -- xor of plaintext and "hash of shared secret"
3128 }
3129 \end{verbatim}
3130
3137 There are also functions to sign and verify the hash of a message. 3131 There are also functions to sign and verify the hash of a message.
3138 \index{ecc\_sign\_hash()} \index{ecc\_verify\_hash()} 3132 \index{ecc\_sign\_hash()} \index{ecc\_verify\_hash()}
3139 \begin{verbatim} 3133 \begin{verbatim}
3140 int ecc_sign_hash(const unsigned char *in, unsigned long inlen, 3134 int ecc_sign_hash(const unsigned char *in, unsigned long inlen,
3141 unsigned char *out, unsigned long *outlen, 3135 unsigned char *out, unsigned long *outlen,
3148 3142
3149 The ``ecc\_sign\_hash'' function signs the message hash in ``in'' of length ``inlen'' and forms a ECC packet in ``out''. 3143 The ``ecc\_sign\_hash'' function signs the message hash in ``in'' of length ``inlen'' and forms a ECC packet in ``out''.
3150 The ``ecc\_verify\_hash'' function verifies the ECC signature in ``sig'' against the hash in ``hash''. It sets ``stat'' 3144 The ``ecc\_verify\_hash'' function verifies the ECC signature in ``sig'' against the hash in ``hash''. It sets ``stat''
3151 to non-zero if the signature passes or zero if it fails. 3145 to non-zero if the signature passes or zero if it fails.
3152 3146
3147 \subsection{Signature Format}
3148 The signature code is an implementation of X9.62 EC-DSA and the output is comformant for GF(p) curves.
3153 3149
3154 \section{ECC Keysizes} 3150 \section{ECC Keysizes}
3155 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 3151 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
3156 and in effect the signature will still work. With ECC keys the strength of the signature is limited by the size of 3152 and in effect the signature will still work. With ECC keys the strength of the signature is limited by the size of
3157 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 3153 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
3158 you have 160-bits of security (e.g. as if you signed with SHA-1). 3154 you have 192-bits of security.
3159 3155
3160 The library will not warn you if you make this mistake so it is important to check yourself before using the 3156 The library will not warn you if you make this mistake so it is important to check yourself before using the
3161 signatures. 3157 signatures.
3162 3158
3163 \chapter{Digital Signature Algorithm} 3159 \chapter{Digital Signature Algorithm}
3167 order at least 1024-bits. With DSA you need a group of order at least 160-bits. By comparison the ElGamal signature 3163 order at least 1024-bits. With DSA you need a group of order at least 160-bits. By comparison the ElGamal signature
3168 would require at least 256 bytes where as the DSA signature would require only at least 40 bytes. 3164 would require at least 256 bytes where as the DSA signature would require only at least 40 bytes.
3169 3165
3170 The API for the DSA is essentially the same as the other PK algorithms. Except in the case of DSA no encryption or 3166 The API for the DSA is essentially the same as the other PK algorithms. Except in the case of DSA no encryption or
3171 decryption routines are provided. 3167 decryption routines are provided.
3168
3169 \section{Key Format}
3170 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
3171 now so that others can interoperate with this library.
3172
3173 \begin{verbatim}
3174 DSAPublicKey ::= SEQUENCE {
3175 publicFlags BIT STRING(1), -- must be 0
3176 g INTEGER , -- base generator, check that g^q mod p == 1
3177 -- and that 1 < g < p - 1
3178 p INTEGER , -- prime modulus
3179 q INTEGER , -- order of sub-group (must be prime)
3180 y INTEGER , -- public key, specifically, g^x mod p,
3181 -- check that y^q mod p == 1
3182 -- and that 1 < y < p - 1
3183 }
3184
3185 DSAPrivateKey ::= SEQUENCE {
3186 publicFlags BIT STRING(1), -- must be 1
3187 g INTEGER , -- base generator, check that g^q mod p == 1
3188 -- and that 1 < g < p - 1
3189 p INTEGER , -- prime modulus
3190 q INTEGER , -- order of sub-group (must be prime)
3191 y INTEGER , -- public key, specifically, g^x mod p,
3192 -- check that y^q mod p == 1
3193 -- and that 1 < y < p - 1
3194 x INTEGER -- private key
3195 }
3196 \end{verbatim}
3197
3198 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
3199 to work with.
3172 3200
3173 \section{Key Generation} 3201 \section{Key Generation}
3174 To make a DSA key you must call the following function 3202 To make a DSA key you must call the following function
3175 \begin{verbatim} 3203 \begin{verbatim}
3176 int dsa_make_key(prng_state *prng, int wprng, 3204 int dsa_make_key(prng_state *prng, int wprng,
3289 3317
3290 This will import the DSA key from the buffer ``in'' of length ``inlen'' to the ``key''. If the process fails the function 3318 This will import the DSA key from the buffer ``in'' of length ``inlen'' to the ``key''. If the process fails the function
3291 will automatically free all of the heap allocated in the process (you don't have to call dsa\_free()). 3319 will automatically free all of the heap allocated in the process (you don't have to call dsa\_free()).
3292 3320
3293 \chapter{Standards Support} 3321 \chapter{Standards Support}
3294 \section{DER Support} 3322 \section{ASN.1 Formats}
3295 DER or ``Distinguished Encoding Rules'' is a subset of the ASN.1 encoding rules that is fully deterministic and 3323 LibTomCrypt supports a variety of ASN.1 data types encoded with the Distinguished Encoding Rules (DER) suitable for various cryptographic protocols. The data types
3296 ideal for cryptography. In particular ASN.1 specifies an INTEGER type for storing arbitrary sized integers. DER 3324 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
3297 further limits the ASN.1 specifications to a deterministic encoding. 3325 format and two functions have been dedicated to encoding and decoding the format.
3298 3326
3299 \subsection{Storing INTEGER types} 3327 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
3328 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
3329
3330 \index{ltc\_asn1\_list structure}
3331 \begin{verbatim}
3332 typedef struct {
3333 int type;
3334 void *data;
3335 unsigned long size;
3336 int used;
3337 } ltc_asn1_list;
3338 \end{verbatim}
3339
3340 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
3341 ``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
3342 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
3343 ``LTC\_SET\_ASN1(list, index, Type, Data, Size)'' has been provided.
3344
3345 It will assign to the ``index''th position in the ``list'' the tripplet (Type, Data, Size). An example usage would be:
3346
3347 \begin{small}
3348 \begin{verbatim}
3349 ...
3350 ltc_asn1_list sequence[3];
3351 unsigned long three=3;
3352
3353 LTC_SET_ASN1(sequence, 0, LTC_ASN1_IA5_STRING, "hello", 5);
3354 LTC_SET_ASN1(sequence, 1, LTC_ASN1_SHORT_INTEGER, &three, 1);
3355 LTC_SET_ASN1(sequence, 2, LTC_ASN1_NULL, NULL, 0);
3356 \end{verbatim}
3357 \end{small}
3358
3359 The macro is relatively safe with respect to modifying variables, for instance the following code is equivalent.
3360
3361 \begin{small}
3362 \begin{verbatim}
3363 ...
3364 ltc_asn1_list sequence[3];
3365 unsigned long three=3;
3366 int x=0;
3367 LTC_SET_ASN1(sequence, x++, LTC_ASN1_IA5_STRING, "hello", 5);
3368 LTC_SET_ASN1(sequence, x++, LTC_ASN1_SHORT_INTEGER, &three, 1);
3369 LTC_SET_ASN1(sequence, x++, LTC_ASN1_NULL, NULL, 0);
3370 \end{verbatim}
3371 \end{small}
3372
3373 \begin{figure}[here]
3374 \begin{center}
3375 \begin{small}
3376 \begin{tabular}{|l|l|}
3377 \hline \textbf{Definition} & \textbf{ASN.1 Type} \\
3378 \hline LTC\_ASN1\_EOL & End of a ASN.1 list structure. \\
3379 \hline LTC\_ASN1\_INTEGER & INTEGER (uses mp\_int) \\
3380 \hline LTC\_ASN1\_SHORT\_INTEGER & INTEGER (32--bit using unsigned long) \\
3381 \hline LTC\_ASN1\_BIT\_STRING & BIT STRING (one bit per char) \\
3382 \hline LTC\_ASN1\_OCTET\_STRING & OCTET STRING (one octet per char) \\
3383 \hline LTC\_ASN1\_NULL & NULL \\
3384 \hline LTC\_ASN1\_OBJECT\_IDENTIFIER & OBJECT IDENTIFIER (words are in unsigned long) \\
3385 \hline LTC\_ASN1\_IA5\_STRING & IA5 STRING (one octet per char) \\
3386 \hline LTC\_ASN1\_PRINTABLE\_STRING & PRINTABLE STIRNG (one octet per char) \\
3387 \hline LTC\_ASN1\_UTCTIME & UTCTIME (see ltc\_utctime structure) \\
3388 \hline LTC\_ASN1\_SEQUENCE & SEQUENCE OF \\
3389 \hline LTC\_ASN1\_CHOICE & CHOICE \\
3390 \hline
3391 \end{tabular}
3392 \caption{List of ASN.1 Supported Types}
3393 \end{small}
3394 \end{center}
3395 \end{figure}
3396
3397 \subsection{SEQUENCE Type}
3398 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.
3399
3400 \subsubsection{SEUQNECE Encoding}
3401 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
3402 with the following function.
3403
3404 \index{der\_encode\_sequence()}
3405 \begin{verbatim}
3406 int der_encode_sequence(ltc_asn1_list *list, unsigned long inlen,
3407 unsigned char *out, unsigned long *outlen);
3408 \end{verbatim}
3409 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
3410 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}.
3411
3412 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
3413 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
3414 the ``data'' pointer is simply a pointer to another \textbf{ltc\_asn1\_list}.
3415
3416 \subsubsection{SEQUENCE Decoding}
3417
3418 \index{der\_decode\_sequence()}
3419
3420 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
3421 (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
3422 units of the respective type has been loaded.
3423
3424 \begin{verbatim}
3425 int der_decode_sequence(const unsigned char *in, unsigned long inlen,
3426 ltc_asn1_list *list, unsigned long outlen);
3427 \end{verbatim}
3428
3429 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.
3430 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.
3431
3432 For the following types the ``size'' field will be updated to reflect the number of units read of the given type.
3433 \begin{enumerate}
3434 \item BIT STRING
3435 \item OCTET STRING
3436 \item OBJECT IDENTIFIER
3437 \item IA5 STRING
3438 \item PRINTABLE STRING
3439 \end{enumerate}
3440
3441 \subsubsection{SEQUENCE Length}
3442
3443 The length of a SEQUENCE can be determined with the following function.
3444
3445 \index{der\_length\_sequence()}
3446 \begin{verbatim}
3447 int der_length_sequence(ltc_asn1_list *list, unsigned long inlen,
3448 unsigned long *outlen);
3449 \end{verbatim}
3450
3451 This will get the encoding size for the given ``list'' of length ``inlen'' and store it in ``outlen''.
3452
3453 \subsubsection{SEQUENCE Multiple Argument Lists}
3454
3455 For small or simple sequences an encoding or decoding can be performed with one of the following two functions.
3456
3457 \index{der\_encode\_sequence\_multi()}
3458 \index{der\_decode\_sequence\_multi()}
3459
3460 \begin{verbatim}
3461 int der_encode_sequence_multi(unsigned char *out, unsigned long *outlen, ...);
3462 int der_decode_sequence_multi(const unsigned char *in, unsigned long inlen, ...);
3463 \end{verbatim}
3464
3465 These either encode or decode (respectively) a SEQUENCE data type where the items in the sequence are specified after the length parameter.
3466
3467 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}
3468 and ``data'' is \textbf{void} pointer. The list of items must be terminated with an item with the type \textbf{LTC\_ASN1\_EOL}.
3469
3470 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
3471 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.
3472
3473 \subsection{ASN.1 INTEGER}
3474
3475 To encode or decode INTEGER data types use the following functions.
3476
3300 \index{der\_encode\_integer()} 3477 \index{der\_encode\_integer()}
3301 \begin{alltt} 3478 \index{der\_decode\_integer()}
3479 \index{der\_length\_integer()}
3480 \begin{verbatim}
3302 int der_encode_integer(mp_int *num, unsigned char *out, unsigned long *outlen); 3481 int der_encode_integer(mp_int *num, unsigned char *out, unsigned long *outlen);
3303 \end{alltt} 3482 int der_decode_integer(const unsigned char *in, unsigned long inlen, mp_int *num);
3304
3305 This will store the integer in ``num'' to the output buffer ``out'' of length ``outlen''. It only stores
3306 non--negative numbers. It stores the number of octets used back in ``outlen''.
3307
3308 \subsection{Reading INTEGER types}
3309 \index{der\_decode\_integer()}
3310 \begin{alltt}
3311 int der_decode_integer(const unsigned char *in, unsigned long *inlen, mp_int *num);
3312 \end{alltt}
3313 This will decode the DER encoded INTEGER in ``in'' of length ``inlen'' and store the resulting integer
3314 in ``num''. It will store the bytes read in ``inlen'' which is handy if you have to parse multiple
3315 data items out of a binary packet.
3316
3317 \subsection{INTEGER length}
3318 \index{der\_length\_integer()}
3319 \begin{alltt}
3320 int der_length_integer(mp_int *num, unsigned long *len); 3483 int der_length_integer(mp_int *num, unsigned long *len);
3321 \end{alltt} 3484 \end{verbatim}
3322 This will determine the length of the DER encoding of the integer ``num'' and store it in ``len''. 3485
3323 3486 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
3324 \subsection{Multiple INTEGER types} 3487 an mp\_int to store the value the ``short'' INTEGER functions were made available.
3325 To simplify the DER encoding/decoding there are two functions two handle multple types at once. 3488
3326 3489 \index{der\_encode\_short\_integer()}
3327 \index{der\_put\_multi\_integer()} 3490 \index{der\_decode\_short\_integer()}
3328 \index{der\_get\_multi\_integer()} 3491 \index{der\_length\_short\_integer()}
3329 \begin{alltt} 3492 \begin{verbatim}
3330 int der_put_multi_integer(unsigned char *dst, unsigned long *outlen, mp_int *num, ...); 3493 int der_encode_short_integer(unsigned long num,
3331 int der_get_multi_integer(const unsigned char *src, unsigned long *inlen, mp_int *num, ...); 3494 unsigned char *out, unsigned long *outlen);
3332 \end{alltt} 3495
3333 3496 int der_decode_short_integer(const unsigned char *in, unsigned long inlen,
3334 These will handle multiple encodings/decodings at once. They work like their single operand counterparts 3497 unsigned long *num);
3335 except they handle a \textbf{NULL} terminated list of operands. 3498
3336 3499 int der_length_short_integer(unsigned long num, unsigned long *outlen);
3337 \begin{verbatim} 3500 \end{verbatim}
3338 #include <tomcrypt.h> 3501
3339 int main(void) 3502 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
3340 { 3503 and short integer functions can encode and decode each others outputs.
3341 mp_int a, b, c, d; 3504
3342 unsigned char buffer[1000]; 3505 \subsection{ASN.1 BIT STRING}
3343 unsigned long len; 3506
3344 int err; 3507 \index{der\_encode\_bit\_string()}
3345 3508 \index{der\_decode\_bit\_string()}
3346 /* init a,b,c,d with some values ... */ 3509 \index{der\_length\_bit\_string()}
3347 3510 \begin{verbatim}
3348 /* ok we want to store them now... */ 3511 int der_encode_bit_string(const unsigned char *in, unsigned long inlen,
3349 len = sizeof(buffer); 3512 unsigned char *out, unsigned long *outlen);
3350 if ((err = der_put_multi_integer(buffer, &len, 3513
3351 &a, &b, &c, &d, NULL)) != CRYPT_OK) { 3514 int der_decode_bit_string(const unsigned char *in, unsigned long inlen,
3352 // error 3515 unsigned char *out, unsigned long *outlen);
3353 } 3516
3354 printf("I stored %lu bytes in buf\n", len); 3517 int der_length_bit_string(unsigned long nbits, unsigned long *outlen);
3355 3518 \end{verbatim}
3356 /* ok say we want to get them back for fun */ 3519
3357 /* len set previously...otherwise set it to the size of the packet */ 3520 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
3358 if ((err = der_get_multi_integer(buffer, &len, 3521 as a one bit and a zero value a zero bit.
3359 &a, &b, &c, &d, NULL)) != CRYPT_OK) { 3522
3360 // error 3523 \subsection{ASN.1 OCTET STRING}
3361 } 3524
3362 printf("I read %lu bytes from buf\n", len); 3525 \index{der\_encode\_octet\_string()}
3363 } 3526 \index{der\_decode\_octet\_string()}
3364 \end{verbatim} 3527 \index{der\_length\_octet\_string()}
3528 \begin{verbatim}
3529 int der_encode_octet_string(const unsigned char *in, unsigned long inlen,
3530 unsigned char *out, unsigned long *outlen);
3531
3532 int der_decode_octet_string(const unsigned char *in, unsigned long inlen,
3533 unsigned char *out, unsigned long *outlen);
3534
3535 int der_length_octet_string(unsigned long noctets, unsigned long *outlen);
3536 \end{verbatim}
3537
3538 These will encode or decode an OCTET STRING data type. The octets are stored using one \textbf{char} each.
3539
3540 \subsection{ASN.1 OBJECT IDENTIFIER}
3541
3542 \index{der\_encode\_object\_identifier()}
3543 \index{der\_decode\_object\_identifier()}
3544 \index{der\_length\_object\_identifier()}
3545 \begin{verbatim}
3546 int der_encode_object_identifier(unsigned long *words, unsigned long nwords,
3547 unsigned char *out, unsigned long *outlen);
3548
3549 int der_decode_object_identifier(const unsigned char *in, unsigned long inlen,
3550 unsigned long *words, unsigned long *outlen);
3551
3552 int der_length_object_identifier(unsigned long *words, unsigned long nwords,
3553 unsigned long *outlen);
3554 \end{verbatim}
3555
3556 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
3557 $0 \ldots 2^{32} - 1$.
3558
3559 \subsection{ASN.1 IA5 STRING}
3560
3561 \index{der\_encode\_ia5\_string()}
3562 \index{der\_decode\_ia5\_string()}
3563 \index{der\_length\_ia5\_string()}
3564 \begin{verbatim}
3565 int der_encode_ia5_string(const unsigned char *in, unsigned long inlen,
3566 unsigned char *out, unsigned long *outlen);
3567
3568 int der_decode_ia5_string(const unsigned char *in, unsigned long inlen,
3569 unsigned char *out, unsigned long *outlen);
3570
3571 int der_length_ia5_string(const unsigned char *octets, unsigned long noctets,
3572 unsigned long *outlen);
3573 \end{verbatim}
3574
3575 These will encode or decode an IA5 STRING. The characters are read or stored in individual \textbf{char} elements. This functions performs internal character
3576 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
3577 say a SPARC machine. Internally these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided
3578 that the build platform honours the runtime platforms character conventions.
3579
3580 If you're worried try building the test suite and running it. It has hard coded test vectors to ensure it is operating properly.
3581
3582 \subsection{ASN.1 PRINTABLE STRING}
3583
3584 \index{der\_encode\_printable\_string()}
3585 \index{der\_decode\_printable\_string()}
3586 \index{der\_length\_printable\_string()}
3587 \begin{verbatim}
3588 int der_encode_printable_string(const unsigned char *in, unsigned long inlen,
3589 unsigned char *out, unsigned long *outlen);
3590
3591 int der_decode_printable_string(const unsigned char *in, unsigned long inlen,
3592 unsigned char *out, unsigned long *outlen);
3593
3594 int der_length_printable_string(const unsigned char *octets, unsigned long noctets,
3595 unsigned long *outlen);
3596 \end{verbatim}
3597
3598 These will encode or decode an PRINTABLE STRING. The characters are read or stored in individual \textbf{char} elements. This functions performs internal character
3599 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
3600 say a SPARC machine. Internally these functions have a table of literal characters and their numerical ASCII values. This provides a stable conversion provided
3601 that the build platform honours the runtime platforms character conventions.
3602
3603 If you're worried try building the test suite and running it. It has hard coded test vectors to ensure it is operating properly.
3604
3605 \subsection{ASN.1 UTCTIME}
3606
3607 The UTCTIME type is to store a date and time in ASN.1 format. It uses the following structure to organize the time.
3608
3609 \begin{verbatim}
3610 typedef struct {
3611 unsigned YY, /* year 00--99 */
3612 MM, /* month 01--12 */
3613 DD, /* day 01--31 */
3614 hh, /* hour 00--23 */
3615 mm, /* minute 00--59 */
3616 ss, /* second 00--59 */
3617 off_dir, /* timezone offset direction 0 == +, 1 == - */
3618 off_hh, /* timezone offset hours */
3619 off_mm; /* timezone offset minutes */
3620 } ltc_utctime;
3621 \end{verbatim}
3622
3623 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
3624 will be subtracted.
3625
3626 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.
3627
3628 \index{der\_encode\_utctime()}
3629 \index{der\_decode\_utctime()}
3630 \index{der\_length\_utctime()}
3631 \begin{verbatim}
3632 int der_encode_utctime(ltc_utctime *utctime,
3633 unsigned char *out, unsigned long *outlen);
3634
3635 int der_decode_utctime(const unsigned char *in, unsigned long *inlen,
3636 ltc_utctime *out);
3637
3638 int der_length_utctime(ltc_utctime *utctime, unsigned long *outlen);
3639 \end{verbatim}
3640
3641 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
3642 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.
3643
3644 It is suggested that decoded data be further scrutinized (e.g. days of month in particular).
3645
3646 \subsection{ASN.1 CHOICE}
3647
3648 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
3649 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
3650 type\footnote{Except it cannot have LTC\_ASN1\_INTEGER and LTC\_ASN1\_SHORT\_INTEGER simultaneously.} except for other CHOICE types.
3651
3652 There is no encoder for the CHOICE type as the actual DER encoding is the encoding of the chosen type.
3653
3654 \index{der\_decode\_choice()}
3655 \begin{verbatim}
3656 int der_decode_choice(const unsigned char *in, unsigned long *inlen,
3657 ltc_asn1_list *list, unsigned long outlen);
3658 \end{verbatim}
3659
3660 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.
3661 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
3662 set to non--zero to reflect it was the data type decoded.
3663
3365 \section{Password Based Cryptography} 3664 \section{Password Based Cryptography}
3366 \subsection{PKCS \#5} 3665 \subsection{PKCS \#5}
3666 \index{PKCS \#5}
3367 In order to securely handle user passwords for the purposes of creating session keys and chaining IVs the PKCS \#5 was drafted. PKCS \#5 3667 In order to securely handle user passwords for the purposes of creating session keys and chaining IVs the PKCS \#5 was drafted. PKCS \#5
3368 is made up of two algorithms, Algorithm One and Algorithm Two. Algorithm One is the older fairly limited algorithm which has been implemented 3668 is made up of two algorithms, Algorithm One and Algorithm Two. Algorithm One is the older fairly limited algorithm which has been implemented
3369 for completeness. Algorithm Two is a bit more modern and more flexible to work with. 3669 for completeness. Algorithm Two is a bit more modern and more flexible to work with.
3370 3670
3371 \subsection{Algorithm One} 3671 \subsection{Algorithm One}
3433 memcpy(mac_key, outbuf+32, 16); 3733 memcpy(mac_key, outbuf+32, 16);
3434 3734
3435 /* use material (recall to store the salt in the output) */ 3735 /* use material (recall to store the salt in the output) */
3436 \} 3736 \}
3437 \end{alltt} 3737 \end{alltt}
3438
3439 3738
3440 \chapter{Miscellaneous} 3739 \chapter{Miscellaneous}
3441 \section{Base64 Encoding and Decoding} 3740 \section{Base64 Encoding and Decoding}
3442 The library provides functions to encode and decode a RFC1521 base64 coding scheme. This means that it can decode what it 3741 The library provides functions to encode and decode a RFC1521 base64 coding scheme. This means that it can decode what it
3443 encodes but the format used does not comply to any known standard. The characters used in the mappings are: 3742 encodes but the format used does not comply to any known standard. The characters used in the mappings are:
3632 The work factor for ECC keys is much higher since the best attack is still fully exponentional. Given a key of magnitude 3931 The work factor for ECC keys is much higher since the best attack is still fully exponentional. Given a key of magnitude
3633 $n$ it requires $\sqrt n$ work. The following table sumarizes the work required: 3932 $n$ it requires $\sqrt n$ work. The following table sumarizes the work required:
3634 \begin{center} 3933 \begin{center}
3635 \begin{tabular}{|c|c|} 3934 \begin{tabular}{|c|c|}
3636 \hline ECC Key Size (bits) & Work Factor ($log_2$) \\ 3935 \hline ECC Key Size (bits) & Work Factor ($log_2$) \\
3637 \hline 160 & 80 \\
3638 \hline 192 & 96 \\ 3936 \hline 192 & 96 \\
3639 \hline 224 & 112 \\ 3937 \hline 224 & 112 \\
3640 \hline 256 & 128 \\ 3938 \hline 256 & 128 \\
3641 \hline 384 & 192 \\ 3939 \hline 384 & 192 \\
3642 \hline 521 & 260.5 \\ 3940 \hline 521 & 260.5 \\
3790 useful when TWOFISH\_SMALL is defined as the table values are computed on the fly. When this is defined the code size 4088 useful when TWOFISH\_SMALL is defined as the table values are computed on the fly. When this is defined the code size
3791 will increase by approximately 500 bytes. If this is defined but TWOFISH\_SMALL is not the cipher will still work but 4089 will increase by approximately 500 bytes. If this is defined but TWOFISH\_SMALL is not the cipher will still work but
3792 it will not speed up the encryption or decryption functions. 4090 it will not speed up the encryption or decryption functions.
3793 4091
3794 \subsection{GCM\_TABLES} 4092 \subsection{GCM\_TABLES}
3795 When defined GCM will use a 64KB table (per GCM state) which will greatly lower up the per--packet latency. 4093 When defined GCM will use a 64KB table (per GCM state) which will greatly speed up the per--packet latency.
3796 It also increases the initialization time. 4094 It also increases the initialization time and isn't suitable when you are going to use a key a few times only.
3797 4095
3798 \subsection{SMALL\_CODE} 4096 \subsection{SMALL\_CODE}
3799 When this is defined some of the code such as the Rijndael and SAFER+ ciphers are replaced with smaller code variants. 4097 When this is defined some of the code such as the Rijndael and SAFER+ ciphers are replaced with smaller code variants.
3800 These variants are slower but can save quite a bit of code space. 4098 These variants are slower but can save quite a bit of code space.
3801 4099
3821 4119
3822 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 4120 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
3823 data type you can perform integer operations with. Ideally it should be four or eight bytes since it must properly divide the size 4121 data type you can perform integer operations with. Ideally it should be four or eight bytes since it must properly divide the size
3824 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 4122 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
3825 use this mode. So sad. 4123 use this mode. So sad.
4124
4125 \subsection{LTC\_PTHREAD}
4126 When this is activated all of the descriptor table functions will use pthread locking to ensure thread safe updates to the tables. Note that
4127 it doesn't prevent a thread that is passively using a table from being messed up by another thread that updates the table.
4128
4129 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
4130 the tables safer.
3826 4131
3827 \section{MPI Tweaks} 4132 \section{MPI Tweaks}
3828 \subsection{RSA Only Tweak} 4133 \subsection{RSA Only Tweak}
3829 If you plan on only using RSA with moduli in the range of 1024 to 2560 bits you can enable a series of tweaks 4134 If you plan on only using RSA with moduli in the range of 1024 to 2560 bits you can enable a series of tweaks
3830 to reduce the library size. Follow these steps 4135 to reduce the library size. Follow these steps
4028 \subsection{Setup} 4333 \subsection{Setup}
4029 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 4334 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
4030 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 4335 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
4031 in ``skey''. 4336 in ``skey''.
4032 4337
4033 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 4338 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
4034 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. 4339 ones provided. Just make sure in your ``done()'' function that you free the allocated memory.
4035 4340
4036 \subsection{Single block ECB} 4341 \subsection{Single block ECB}
4037 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 4342 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
4038 must make sure you do not overwrite the output before you are finished with the input. 4343 must make sure you do not overwrite the output before you are finished with the input.
4039 4344
4060 updated by the function before returning. 4365 updated by the function before returning.
4061 4366
4062 \subsubsection{Accelerated CTR} 4367 \subsubsection{Accelerated CTR}
4063 This function is meant for accelerated CTR encryption. It is accessible through the accel\_ctr\_encrypt pointer. 4368 This function is meant for accelerated CTR encryption. It is accessible through the accel\_ctr\_encrypt pointer.
4064 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 4369 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
4065 updated by the function before returning. The ``mode'' value indicates whether the counter is big ($mode = 1$) or little ($mode = 0$) endian. 4370 updated by the function before returning. The ``mode'' value indicates whether the counter is big (mode = CTR\_COUNTER\_BIG\_ENDIAN) or
4371 little (mode = CTR\_COUNTER\_LITTLE\_ENDIAN) endian.
4066 4372
4067 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 4373 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
4068 called if the following conditions are met. 4374 called if the following conditions are met.
4069 4375
4070 \begin{enumerate} 4376 \begin{enumerate}
4099 unsigned char ID; 4405 unsigned char ID;
4100 /** Size of digest in octets */ 4406 /** Size of digest in octets */
4101 unsigned long hashsize; 4407 unsigned long hashsize;
4102 /** Input block size in octets */ 4408 /** Input block size in octets */
4103 unsigned long blocksize; 4409 unsigned long blocksize;
4104 /** ASN.1 DER identifier */ 4410 /** ASN.1 OID */
4105 unsigned char DER[64]; 4411 unsigned long OID[16];
4106 /** Length of DER encoding */ 4412 /** Length of DER encoding */
4107 unsigned long DERlen; 4413 unsigned long OIDlen;
4108 /** Init a hash state 4414 /** Init a hash state
4109 @param hash The hash to initialize 4415 @param hash The hash to initialize
4110 @return CRYPT_OK if successful 4416 @return CRYPT_OK if successful
4111 */ 4417 */
4112 int (*init)(hash_state *hash); 4418 int (*init)(hash_state *hash);
4142 4448
4143 \subsection{Block Size} 4449 \subsection{Block Size}
4144 The `blocksize'' variable indicates the length of input (in octets) that the hash processes in a given 4450 The `blocksize'' variable indicates the length of input (in octets) that the hash processes in a given
4145 invokation. 4451 invokation.
4146 4452
4147 \subsection{DER Identifier} 4453 \subsection{OID Identifier}
4148 This is the DER identifier (including the SEQUENCE header). This is used solely for PKCS \#1 style signatures. 4454 This is the universal ASN.1 Object Identifier for the hash.
4149 4455
4150 \subsection{Initialization} 4456 \subsection{Initialization}
4151 The init function initializes the hash and prepares it to process message bytes. 4457 The init function initializes the hash and prepares it to process message bytes.
4152 4458
4153 \subsection{Process} 4459 \subsection{Process}
4249 but should at least maintain the same level of state entropy. 4555 but should at least maintain the same level of state entropy.
4250 4556
4251 \input{crypt.ind} 4557 \input{crypt.ind}
4252 4558
4253 \end{document} 4559 \end{document}
4560
4561 % $Source: /cvs/libtom/libtomcrypt/crypt.tex,v $
4562 % $Revision: 1.39 $
4563 % $Date: 2005/06/27 13:08:28 $