Lines Matching defs:Key
121 public key cryptography (via PKCS \#1 RSA, DH or ECCDH), and a plethora of support routines.
172 that for the PRNG needs within the library (\textit{e.g. making a RSA key}). All the developer has to do
183 the key setup, ECB decrypt and encrypt and test vector routines. After that all five chaining mode routines
254 related issue is if you use the same symmetric cipher, hash or public key state data in multiple threads. Normally
326 rsa_key key;
331 /* ... Make up the RSA key somehow ... */
333 /* lets export the key, set x to the size of the
336 if ((err = rsa_export(buffer, &x, PK_PUBLIC, &key)) != CRYPT_OK) {
343 printf("RSA exported key takes %d bytes\n", x);
351 In the above example if the size of the RSA public key was more than 1024 bytes this function would return an error code
371 rsa_key key;
377 /* make a 1024-bit RSA key with the system RNG */
378 if ((err = rsa_make_key(NULL, find_prng("sprng"), 1024/8, 65537, &key))
384 /* use the key ... */
392 Most functions require inputs that are arrays of the data type \textit{unsigned char}. Whether it is a symmetric key, IV
393 for a chaining mode or public key packet it is assumed that regardless of the actual size of \textit{unsigned char} only the
394 lower eight bits contain data. For example, if you want to pass a 256 bit key to a symmetric ciphers setup routine, you
408 \subsection{Key Scheduling}
415 int XXX_setup(const unsigned char *key,
421 The XXX\_setup() routine will setup the cipher to be used with a given number of rounds and a given key length (in bytes).
424 If the function returns successfully the variable \textit{skey} will have a scheduled key stored in it. It's important to note
425 that you should only used this scheduled key with the intended cipher. For example, if you call \textit{blowfish\_setup()} do not
426 pass the scheduled key onto \textit{rc5\_ecb\_encrypt()}. All built--in setup functions do not allocate memory off the heap so
427 when you are done with a key you can simply discard it (e.g. they can be on the stack). However, to maintain proper coding
458 \subsection{Key Sizing}
459 For each cipher there is a function which will help find a desired key size. It is specified as follows:
460 \index{Key Sizing}
464 Essentially, it will round the input keysize in \textit{keysize} down to the next appropriate key size. This function
465 will return {\bf CRYPT\_OK} if the key size specified is acceptable. For example:
473 /* now given a 20 byte key what keysize does Twofish want to use? */
476 printf("Error getting key size: %s\n", error_to_string(err));
479 printf("Twofish suggested a key size of %d\n", keysize);
504 unsigned char pt[8], ct[8], key[8];
508 /* ... key is loaded appropriately in key ... */
511 /* schedule the key */
512 if ((err = blowfish_setup(key, /* the key we will use */
513 8, /* key is 8 bytes (64-bits) long */
515 &skey) /* where to put the scheduled key */
524 &skey); /* our previously scheduled key */
531 &skey); /* our previously scheduled key */
543 \mysection{Key Sizes and Number of Rounds}
555 ciphers are configured such that the default number of rounds provide adequate security for the given block and key
589 are the minimum and maximum key sizes in bytes. The \textit{block\_length} member is the block size of the cipher
591 the min and max key lengths but not always everything in between. The \textit{default\_rounds} field is the default number
609 \hline \textbf{Name} & \textbf{Descriptor Name} & \textbf{Block Size} & \textbf{Key Range} & \textbf{Rounds} \\
654 byte string from the real 7/21 byte key.
660 key will require less ram but the resulting cipher will be slower. The second option is \textit{TWOFISH\_TABLES} which when
671 \hline \textbf{TWOFISH\_SMALL} & \textbf{TWOFISH\_TABLES} & \textbf{Speed and Memory (per key)} \\
673 \hline undefined & defined & Faster key setup, larger code. \\
699 unsigned char key[8];
709 /* generic call to function (assuming the key
710 * in key[] was already setup) */
713 setup(key, 8, 0, &skey)) != CRYPT_OK) {
767 size of the cipher. Given a key $k$, a plaintext $P$ and a cipher $E$ we shall denote the encryption of the block
768 $P$ under the key $k$ as $E_k(P)$. In some modes there exists an initial vector denoted as $C_{-1}$.
776 This mode is very weak since it allows people to swap blocks and perform replay attacks if the same key is used more
786 It is important that the initial vector be unique and preferably random for each message encrypted under the same key.
797 encrypted under the same key replay and swap attacks are infeasible. CTR mode may look simple but it is as secure
822 My personal preference is for the CTR mode since it has several key benefits:
855 const unsigned char *key,
862 const unsigned char *key,
869 const unsigned char *key,
879 parameters \textit{key}, \textit{keylen} and \textit{num\_rounds} are the same as in the XXX\_setup() function call. The final parameter
961 unsigned char key[16], IV[16], buffer[512];
971 /* somehow fill out key and IV */
977 key, /* the secret key */
978 16, /* length of secret key (16 bytes) */
1024 zeromem(key, sizeof(key));
1034 security problems of ECB mode while not increasing the storage requirements. It is used much like any other chaining mode except with two key differences.
1036 The key is specified as two strings the first key $K_1$ is the (normally AES) key and can be any length (typically 16, 24 or 32 octets long). The second key
1037 $K_2$ is the \textit{tweak} key and is always 16 octets long. The tweak value is \textbf{NOT} a nonce or IV value it must be random and secret.
1045 const unsigned char *key,
1052 This will initialize the LRW context with the given (16 octet) \textit{IV}, cipher $K_1$ \textit{key} of length \textit{keylen} octets and the (16 octet) $K_2$ \textit{tweak}.
1099 against the plaintext to encrypt. F8 mode comes with the additional twist that the counter value is secret, encrypted by a \textit{salt key}. We
1106 const unsigned char *key,
1113 This will start the F8 mode state using \textit{key} as the secret key, \textit{IV} as the counter. It uses the \textit{salt\_key} as IV encryption key
1114 (\textit{m} in the RFC 3711). The salt\_key can be shorter than the secret key but it should not be longer.
1164 It is initialized with a random \textit{nonce} that can be shared publicly, a \textit{header} which can be fixed and public, and a random secret symmetric key.
1179 const unsigned char *key,
1188 The \textit{key} parameter is the shared secret symmetric key of length \textit{keylen} octets. The \textit{nonce} parameter is the
1251 unsigned char pt[64], ct[64], nonce[16], key[16], tag[16];
1259 /* ... make up random nonce and key ... */
1306 const unsigned char *key, unsigned long keylen,
1315 const unsigned char *key, unsigned long keylen,
1340 const unsigned char *key,
1345 This will initialize the \textit{ocb} context using cipher descriptor \textit{cipher}. It will use a \textit{key} of length \textit{keylen}
1413 const unsigned char *key, unsigned long keylen,
1427 const unsigned char *key, unsigned long keylen,
1447 const unsigned char *key, unsigned long keylen,
1460 The key can be specified in one of two fashions. First, it can be passed as an array of octets in \textit{key} of length \textit{keylen}. Alternatively,
1461 it can be passed in as a previously scheduled key in \textit{uskey}. The latter fashion saves time when the same key is used for multiple packets. If
1462 \textit{uskey} is not \textbf{NULL}, then \textit{key} may be \textbf{NULL} (and vice-versa).
1492 unsigned char key[16], nonce[12], pt[32], ct[32],
1500 /* somehow fill key, nonce, pt */
1506 key, 16, /* 128-bit key */
1523 key, 16, /* 128-bit key */
1550 To initialize the GCM context with a secret key call the following function.
1556 const unsigned char *key,
1559 This initializes the GCM state \textit{gcm} for the given cipher indexed by \textit{cipher}, with a secret key \textit{key} of length \textit{keylen} octets. The cipher
1628 To process a single packet under any given key the following helper function can be used.
1634 const unsigned char *key,
1644 This will initialize the GCM state with the given key, IV and AAD value then proceed to encrypt or decrypt the message text and store the final
1647 If you are processing many packets under the same key you shouldn't use this function as it invokes the pre--computation with each call.
1650 The following is an example usage of how to use GCM over multiple packets with a shared secret key.
1713 unsigned char key[16], IV[12], pt[PACKET_SIZE];
1717 /* somehow fill key/IV with random values */
1724 gcm_init(&gcm, find_cipher("aes"), key, 16)) != CRYPT_OK) {
1900 Note the usage of \textbf{MAXBLOCKSIZE}. In LibTomCrypt, no symmetric block, key or hash digest is larger than \textbf{MAXBLOCKSIZE} in
2034 \item The cipher must allow an input key the size of the block size.
2078 of a message is a keyed authentication code that only the owner of a private symmetric key will be able to verify. The purpose is
2079 to allow an owner of a private symmetric key to produce an HMAC on a message then later verify if it is correct. Any impostor or
2082 The HMAC support works much like the normal hash functions except that the initialization routine requires you to pass a key
2083 and its length. The key is much like a key you would pass to a cipher. That is, it is simply an array of octets stored in
2089 const unsigned char *key,
2093 to use to authenticate the message. The \textit{key} parameter is the pointer to the array of chars that make up the key. The \textit{keylen} parameter is the
2094 length (in octets) of the key you want to use to authenticate the message. To send octets of a message through the HMAC system you must use the following function:
2115 There are two utility functions provided to make using HMACs easier to do. They accept the key and information about the
2123 const unsigned char *key, unsigned long keylen,
2128 table must be provided in \textit{hash}. It uses the key from \textit{key} with a key length of \textit{keylen}.
2136 const unsigned char *key, unsigned long keylen,
2140 \textit{key} is the array of octets to use as the key of length \textit{keylen}. \textit{out} is the array of octets where the
2158 unsigned char key[16], dst[MAXBLOCKSIZE];
2170 /* we would make up our symmetric key in "key[]" here */
2173 if ((err = hmac_init(&hmac, idx, key, 16)) != CRYPT_OK) {
2200 OMAC\footnote{\url{http://crypt.cis.ibaraki.ac.jp/omac/omac.html}}, which stands for \textit{One-Key CBC MAC} is an
2210 const unsigned char *key,
2215 wish to use. The \textit{key} and \textit{keylen} parameters are the keys used to authenticate the data.
2259 const unsigned char *key, unsigned long keylen,
2263 This will compute the OMAC of \textit{inlen} bytes of \textit{in} using the key \textit{key} of length \textit{keylen} bytes and the cipher
2272 const unsigned char *key, unsigned long keylen,
2277 Which will OMAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes
2296 unsigned char key[16], dst[MAXBLOCKSIZE];
2308 /* we would make up our symmetric key in "key[]" here */
2311 if ((err = omac_init(&omac, idx, key, 16)) != CRYPT_OK) {
2338 protocol is another MAC algorithm that relies solely on a symmetric-key block cipher. It uses essentially the same
2347 const unsigned char *key,
2350 Which initializes the \textit{pmac} state with the given \textit{cipher} and \textit{key} of length \textit{keylen} bytes. The chosen cipher
2393 const unsigned char *key, unsigned long keylen,
2397 This will compute the PMAC of \textit{msglen} bytes of \textit{msg} using the key \textit{key} of length \textit{keylen} bytes, and the cipher
2406 const unsigned char *key, unsigned long keylen,
2411 Which will PMAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes,
2430 const unsigned char *key,
2433 This will initialize the Pelican state with the given AES key. Once this has been done you can begin processing data.
2458 unsigned char key[32], tag[16];
2461 /* somehow initialize a key */
2465 key, /* user key */
2466 32 /* key length in octets */
2500 by using a cipher in CBC mode. It also uses a single key which it expands into the requisite three keys for the MAC function. A XCBC--MAC state is
2507 const unsigned char *key,
2511 This will initialize the XCBC--MAC state \textit{xcbc}, with the key specified in \textit{key} of length \textit{keylen} octets. The cipher indicated
2544 const unsigned char *key, unsigned long keylen,
2548 This will compute the XCBC--MAC of \textit{msglen} bytes of \textit{msg}, using the key \textit{key} of length \textit{keylen} bytes, and the cipher
2556 const unsigned char *key, unsigned long keylen,
2561 Which will XCBC--MAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, and the cipher
2593 const unsigned char *key,
2597 This will initialize the F9--MAC state \textit{f9}, with the key specified in \textit{key} of length \textit{keylen} octets. The cipher indicated
2630 const unsigned char *key, unsigned long keylen,
2634 This will compute the F9--MAC of \textit{msglen} bytes of \textit{msg}, using the key \textit{key} of length \textit{keylen} bytes, and the cipher
2642 const unsigned char *key, unsigned long keylen,
2647 Which will F9--MAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, and the cipher
2664 used to expand a shorter bit string into a longer bit string. PRNGs are used wherever random data is required such as Public Key (PK)
2665 key generation. There is a universal structure called \textit{prng\_state}. To initialize a PRNG call:
2876 key, and any hash that produces at least a 256--bit output. However, to make the implementation simpler
2887 RC4 is an old stream cipher that can also double duty as a PRNG in a pinch. You key RC4 by
2888 calling add\_entropy(), and setup the key by calling ready(). You can only add up to 256 bytes via
2899 SOBER--128 is a stream cipher designed by the QUALCOMM Australia team. Like RC4, you key it by
2902 Note: this cipher has several oddities about how it operates. The first call to add\_entropy() sets the cipher's key.
2904 encrypt several messages with the same key, and not re--use the same key material.
2914 key it from the output of Fortuna (or Yarrow), and use it to encrypt messages. It is also ideal for
2932 /* use "key" as the key */
2933 if ((err = rc4_add_entropy("key", 3, &prng)) != CRYPT_OK) {
3012 /* make a 192-bit ECC key */
3015 printf("Error making key: %s\n", error_to_string(err));
3043 /* make a 192-bit ECC key */
3046 printf("Error making key: %s\n", error_to_string(err));
3054 \chapter{RSA Public Key Cryptography}
3057 RSA wrote the PKCS \#1 specifications which detail RSA Public Key Cryptography. In the specifications are
3140 $m - 2h - 2$. For example, with a $1024$--bit RSA key and SHA--1 as the hash the maximum payload is $86$ bytes.
3222 \mysection{RSA Key Operations}
3225 RSA is a public key algorithm that is based on the inability to find the \textit{e-th} root modulo a composite of unknown
3231 $\mbox{lcm}(p - 1, q - 1)$. The public key consists of the composite $N$ and some integer $e$ such that
3232 $\mbox{gcd}(e, \phi(N)) = 1$. The private key consists of the composite $N$ and the inverse of $e$ modulo $\phi(N)$
3235 A person who wants to encrypt with your public key simply forms an integer (the plaintext) $M$ such that
3237 given only $N$ and $e$ appears to be intractable only the owner of the private key can decrypt the ciphertext and compute
3238 $C^d \equiv \left (M^e \right)^d \equiv M^1 \equiv M\mbox{ }(\mbox{mod }N)$. Similarly the owner of the private key
3253 \subsection{RSA Key Generation}
3255 For RSA routines a single \textit{rsa\_key} structure is used. To make a new RSA key call:
3262 rsa_key *key);
3267 trivial math attacks, and not super slow. The \textit{key} parameter is where the constructed key is placed. All keys must be at
3271 Note: the \textit{rsa\_make\_key()} function allocates memory at run--time when you make the key. Make sure to call
3272 \textit{rsa\_free()} (see below) when you are finished with the key. If \textit{rsa\_make\_key()} fails it will automatically
3277 RSA key which includes the CRT parameters\footnote{As of v0.99 the PK\_PRIVATE\_OPTIMIZED type has been deprecated, and has been replaced by the
3278 PK\_PRIVATE type.} in the form of a RSAPrivateKey (PKCS \#1 compliant). The second type, is a public RSA key which only includes the modulus and public exponent.
3290 rsa_key *key);
3298 \mysection{RSA Key Encryption}
3314 rsa_key *key);
3337 rsa_key *key);
3346 \mysection{RSA Key Decryption}
3358 rsa_key *key);
3382 rsa_key *key);
3392 Similar to RSA key encryption RSA is also used to \textit{digitally sign} message digests (hashes). To facilitate this
3405 rsa_key *key);
3432 rsa_key *key);
3453 rsa_key *key);
3477 rsa_key *key);
3498 rsa_key key;
3516 /* make an RSA-1024 key */
3519 1024/8, /* 1024-bit key */
3521 &key) /* where to store the key */
3527 /* fill in pt[] with a key we want to send ... */
3538 &key) /* our RSA key */
3544 /* now let's decrypt the encrypted key */
3554 &key) /* our RSA key */
3564 \mysection{RSA Key Format}
3566 The RSA key format adopted for exporting and importing keys is the PKCS \#1 format defined by the ASN.1 constructs known as
3567 RSAPublicKey and RSAPrivateKey. Additionally, the OpenSSL key format is supported by the import function only.
3569 \subsection{RSA Key Export}
3570 To export a RSA key use the following function.
3577 rsa_key *key);
3579 This will export the RSA key in either a RSAPublicKey or RSAPrivateKey (PKCS \#1 types) depending on the value of \textit{type}. When it is
3582 \subsection{RSA Key Import}
3583 To import a RSA key use the following function.
3589 rsa_key *key);
3592 This will import the key stored in \textit{inlen} and import it to \textit{key}. If the function fails it will automatically free any allocated memory. This
3596 import the key, strip off the additional data (it's the preferred hash) and fill in the rsa\_key structure as if it were a native RSAPublicKey. Note that
3606 192-bit key) then the work factor is $2^{96}$ in order to find the secret key.
3623 range in order from $\approx 2^{112}$ points to $\approx 2^{521}$. According to the source document any key size greater
3662 \mysection{Key Format}
3663 LibTomCrypt uses a unique format for ECC public and private keys. While ANSI X9.63 partially specifies key formats, it does it in a less than ideally simple manner. \
3666 \index{ECC Key Format}
3673 pubkey.x INTEGER, -- The X co-ordinate of the public key point
3674 pubkey.y INTEGER, -- The Y co-ordinate of the public key point
3681 pubkey.x INTEGER, -- The X co-ordinate of the public key point
3682 pubkey.y INTEGER, -- The Y co-ordinate of the public key point
3683 secret.k INTEGER, -- The secret key scalar
3688 The first flags bit denotes whether the key is public (zero) or private (one).
3726 \subsection{ECC Key Generation}
3727 There is a key structure called \textit{ecc\_key} used by the ECC functions. There is a function to make a key:
3733 ecc_key *key);
3737 correspond to key sizes of 112, 128, 160, 192, 224, 256, 384, and 521 bits respectively. If you pass a key size that is between any key size it will round
3742 \subsection{Extended Key Generation}
3743 As of v1.16, the library supports an extended key generation routine which allows the user to specify their own curve. It is specified as follows:
3750 ecc_key *key,
3754 This function generates a random ECC key over the curve specified by the parameters by \textit{dp}. The rest of the parameters are equivalent to
3755 those from the original key generation function.
3757 \subsection{ECC Key Free}
3761 void ecc_free(ecc_key *key);
3764 \subsection{ECC Key Export}
3765 To export an ECC key using the LibTomCrypt format call the following function:
3771 ecc_key *key);
3773 This will export the key with the given \textit{type} (\textbf{PK\_PUBLIC} or \textbf{PK\_PRIVATE}), and store it to \textit{out}.
3775 \subsection{ECC Key Import}
3776 The following function imports a LibTomCrypt format ECC key:
3781 ecc_key *key);
3783 This will import the ECC key from \textit{in}, and store it in the ecc\_key structure pointed to by \textit{key}. If the operation fails it will free
3786 \subsection{Extended Key Import}
3788 The following function imports a LibTomCrypt format ECC key using a specified set of curve parameters:
3793 ecc_key *key,
3796 This will import the key from the array pointed to by \textit{in} of length \textit{inlen} octets. The key is stored in
3797 the ECC structure pointed to by \textit{key}. The curve is specified by the parameters pointed to by \textit{dp}. The function will free
3801 The following function exports an ECC public key in the ANSI X9.63 format:
3805 int ecc_ansi_x963_export( ecc_key *key,
3809 The ECC key pointed to by \textit{key} is exported in public fashion to the array pointed to by \textit{out}. The ANSI X9.63 format used is from
3813 The following function imports an ANSI X9.63 section 4.3.6 format public ECC key:
3819 ecc_key *key);
3821 This will import the key stored in the array pointed to by \textit{in} of length \textit{inlen} octets. The imported key is stored in the ECC key pointed to by
3822 \textit{key}. The function will free any allocated memory upon error.
3825 The following function allows the importing of an ANSI x9.63 section 4.3.6 format public ECC key using user specified domain parameters:
3831 ecc_key *key,
3834 This will import the key stored in the array pointed to by \textit{in} of length \textit{inlen} octets using the domain parameters pointed to by \textit{dp}.
3835 The imported key is stored in the ECC key pointed to by \textit{key}. The function will free any allocated memory upon error.
3838 To construct a Diffie-Hellman shared secret with a private and public ECC key, use the following function:
3846 The \textit{private\_key} is typically the local private key, and \textit{public\_key} is the key the remote party has shared.
3850 ECC--DH Encryption is performed by producing a random key, hashing it, and XOR'ing the digest against the plaintext. It is not strictly ANSI X9.63 compliant
3864 ecc_key *key);
3867 As the name implies this function encrypts a (symmetric) key, and is not intended for encrypting long messages directly. It will encrypt the
3868 plaintext in the array pointed to by \textit{in} of length \textit{inlen} octets. It uses the public ECC key pointed to by \textit{key}, and
3872 The data is encrypted to the public ECC \textit{key} such that only the holder of the private key can decrypt the payload. To have multiple
3873 recipients multiple call to this function for each public ECC key is required.
3882 ecc_key *key);
3885 This function will decrypt an encrypted payload. The \textit{key} provided must be the private key corresponding to the public key
3886 used during encryption. If the wrong key is provided the function will not specifically return an error code. It is important
3917 ecc_key *key);
3922 the ECC \textit{key} provided must be a private key.
3932 ecc_key *key);
3938 The ECC \textit{key} must be the public (or private) ECC key corresponding to the key that performed the signature.
3944 With ECC if you try to 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
3945 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
3946 SHA256 and an ECC-192 key, you in effect have 96--bits of security.
3957 \mysection{Key Format}
3958 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
3970 y INTEGER , -- public key, specifically,
3984 y INTEGER , -- public key, specifically,
3988 x INTEGER -- private key
3995 \mysection{Key Generation}
3996 To make a DSA key you must call the following function
4002 dsa_key *key);
4020 \caption{DSA Key Sizes}
4023 When you are finished with a DSA key you can call the following function to free the memory used.
4026 void dsa_free(dsa_key *key);
4029 \mysection{Key Verification}
4030 Each DSA key is composed of the following variables.
4037 \item $x$ a random secret (the secret key) in the range $1 < x < q$
4038 \item $y = g^x \mbox{ (mod }p\mbox{)}$ the public key.
4041 A DSA key is considered valid if it passes all of the following tests.
4057 ensures that the generator actually generates a prime order group. Tests seven and eight ensure that the public key
4065 int dsa_verify_key(dsa_key *key, int *stat);
4068 This will test \textit{key} and store the result in \textit{stat}. If the result is $stat = 0$ the DSA key failed one of the tests
4069 and should not be used at all. If the result is $stat = 1$ the DSA key is valid (as far as valid mathematics are concerned).
4083 dsa_key *key);
4088 is stored and the function returns an error code. The DSA \textit{key} must be of the \textbf{PK\_PRIVATE} persuasion.
4100 dsa_key *key);
4107 a shared key is computed, and the hash of the shared key XOR'ed against the plaintext forms the ciphertext. The format used is functional port of
4111 This function will encrypt a small payload with a recipients public DSA key.
4122 dsa_key *key);
4126 length of the ciphertext \textit{outlen} must be originally set to the length of the output buffer. The DSA \textit{key} can be
4127 a public key.
4137 dsa_key *key);
4140 The DSA \textit{key} must be a private key.
4142 \mysection{DSA Key Import and Export}
4144 \subsection{DSA Key Export}
4145 To export a DSA key so that it can be transported use the following function:
4151 dsa_key *key);
4153 This will export the DSA \textit{key} to the buffer \textit{out} and set the length in \textit{outlen} (which must have been previously
4155 depending on whether you want to export a private or public copy of the DSA key.
4157 \subsection{DSA Key Import}
4158 To import an exported DSA key use the following function
4164 dsa_key *key);
4167 This will import the DSA key from the buffer \textit{in} of length \textit{inlen} to the \textit{key}. If the process fails the function
4890 When making random primes the trial division step is in fact an optimized implementation of \textit{Implementation of Fast RSA Key Generation on Smart Cards}\footnote{Chenghuai Lu, Andre L. M. dos Santos and Francisco R. Pimentel}.
4951 \mysection{Key Sizes}
4954 For symmetric ciphers, use as large as of a key as possible. For the most part \textit{bits are cheap} so using a 256--bit key
4955 is not a hard thing to do. As a good rule of thumb do not use a key smaller than 128 bits.
4958 The following chart gives the work factor for solving a DH/RSA public key using the NFS. The work factor for a key of order
4964 Note that $n$ is not the bit-length but the magnitude. For example, for a 1024-bit key $n = 2^{1024}$. The work required
4969 \hline RSA/DH Key Size (bits) & Work Factor ($log_2$) \\
4981 \caption{RSA/DH Key Strength}
4984 The work factor for ECC keys is much higher since the best attack is still fully exponential. Given a key of magnitude
4989 \hline ECC Key Size (bits) & Work Factor ($log_2$) \\
5001 \caption{ECC Key Strength}
5004 Using the above tables the following suggestions for key sizes seems appropriate:
5007 \hline Security Goal & RSA/DH Key Size (bits) & ECC Key Size (bits) \\
5167 public key functions.
5235 When this functions is defined the functions that store key material on the stack will clean up afterwards.
5276 \subsection{Symmetric Ciphers, One-way Hashes, PRNGS and Public Key Functions}
5277 There are a plethora of macros for the ciphers, hashes, PRNGs and public key functions which are fairly
5291 to allow some trade-offs in the implementation. When TWOFISH\_SMALL is defined the scheduled symmetric key for Twofish
5303 It also increases the initialization time and is not suitable when you are going to use a key a few times only.
5323 algorithm which prevents leaking key bits of the private key (scalar). It is a slower algorithm but useful for situations
5327 The library comes with three math descriptors that allow you to interface the public key cryptography API to freely available math
5385 @param key The input symmetric key
5386 @param keylen The length of the input key (octets)
5388 @param skey [out] The destination of the scheduled key
5391 int (*setup)(const unsigned char *key,
5399 @param skey The scheduled key
5409 @param skey The scheduled key
5423 @param skey The scheduled key
5427 /** Determine a key size
5428 @param keysize [in/out] The size of the key desired
5439 @param skey The scheduled key context
5451 @param skey The scheduled key context
5464 @param skey The scheduled key context
5478 @param skey The scheduled key context
5493 @param skey The scheduled key context
5509 @param skey The scheduled key context
5525 @param skey The scheduled key context
5536 @param key The secret key to use
5537 @param keylen The length of the secret key (octets)
5538 @param uskey A previously scheduled key [can be NULL]
5553 const unsigned char *key, unsigned long keylen,
5563 @param key The secret key
5564 @param keylen The length of the secret key
5578 const unsigned char *key, unsigned long keylen,
5587 @param key The secret key
5588 @param keylen The key length (octets)
5596 const unsigned char *key, unsigned long keylen,
5601 @param key The secret key
5602 @param keylen The key length (octets)
5610 const unsigned char *key, unsigned long keylen,
5615 @param key The secret key
5616 @param keylen The key length (octets)
5625 const unsigned char *key, unsigned long keylen,
5640 \subsection{Key Lengths}
5641 The minimum key length is \textit{min\_key\_length} and is measured in octets. Similarly the maximum key length is \textit{max\_key\_length}. They can be equal
5642 and both must valid key sizes for the cipher. Values in between are not assumed to be valid though they may be.
5651 To initialize a cipher (for ECB mode) the function setup() was provided. It accepts an array of key octets \textit{key} of length \textit{keylen} octets. The user
5652 can specify the number of rounds they want through \textit{num\_rounds} where $num\_rounds = 0$ means use the default. The destination of a scheduled key is stored
5666 \subsection{Key Sizing}
5667 Occasionally, a function will want to find a suitable key size to use since the input is oddly sized. The keysize() function is for this case. It accepts a
5668 pointer to an integer which represents the desired size. The function then has to match it to the exact or a lower key
5670 cannot be mapped to a valid key size for the cipher.
5720 by allowing the caller to call the setup() function first to schedule the key if your accelerator cannot do the key schedule on the fly (for instance). This
5721 function MUST support both key passing methods.
5726 \hline \textbf{key} & \textbf{uskey} & \textbf{Source of key} \\
5728 \hline non-NULL & NULL & Use key, do a key schedule \\
5729 \hline NULL & non-NULL & Use uskey, key schedule not required \\
5730 \hline non-NULL & non-NULL & Use uskey, key schedule not required \\
5741 be called prior to this. This function must handle scheduling the key provided on its own. It is called when the user calls gcm\_memory().
5815 int (*hmac_block)(const unsigned char *key,
6360 /** RSA Key Generation
6363 @param size The size of the key in octets
6364 @param e The "e" value (public key).
6366 @param key [out] Destination of a newly created private key pair
6373 rsa_key *key);
6382 @param key The RSA key to use
6387 rsa_key *key);
6448 The RSA Modular Exponentiation (ME) function is used by the RSA API to perform exponentiations for private and public key operations. In particular for
6449 private key operations it uses the CRT approach to lower the time required. It is passed an RSA key with the following format.
6452 /** RSA PKCS style key */
6454 /** Type of key, PK_PRIVATE or PK_PUBLIC */
6479 Since the function is given the entire RSA key (for private keys only) CRT is possible as prescribed in the PKCS \#1 v2.1 specification.
