diff options
Diffstat (limited to 'nettle.texinfo')
| -rw-r--r-- | nettle.texinfo | 192 |
1 files changed, 178 insertions, 14 deletions
diff --git a/nettle.texinfo b/nettle.texinfo index 9cfaf43a..23eed335 100644 --- a/nettle.texinfo +++ b/nettle.texinfo @@ -93,6 +93,7 @@ Cipher modes * CBC:: * CTR:: +* CFB:: * GCM:: * CCM:: @@ -1884,21 +1885,23 @@ a message that is larger than the cipher's block size. As explained in processing them independently with the block cipher (Electronic Code Book mode, @acronym{ECB}), leaks information. -Besides @acronym{ECB}, Nettle provides a two other modes of operation: -Cipher Block Chaining (@acronym{CBC}), Counter mode (@acronym{CTR}), and -a couple of @acronym{AEAD} modes (@pxref{Authenticated encryption}). -@acronym{CBC} is widely used, but there are a few subtle issues of -information leakage, see, e.g., +Besides @acronym{ECB}, Nettle provides several other modes of operation: +Cipher Block Chaining (@acronym{CBC}), Counter mode (@acronym{CTR}), Cipher +Feedback (@acronym{CFB}) and a couple of @acronym{AEAD} modes +(@pxref{Authenticated encryption}). @acronym{CBC} is widely used, but +there are a few subtle issues of information leakage, see, e.g., @uref{http://www.kb.cert.org/vuls/id/958563, @acronym{SSH} @acronym{CBC} vulnerability}. Today, @acronym{CTR} is usually preferred over @acronym{CBC}. -Modes like @acronym{CBC} and @acronym{CTR} provide @emph{no} message -authentication, and should always be used together with a @acronym{MAC} -(@pxref{Keyed hash functions}) or signature to authenticate the message. +Modes like @acronym{CBC}, @acronym{CTR} and @acronym{CFB} provide @emph{no} +message authentication, and should always be used together with a +@acronym{MAC} (@pxref{Keyed hash functions}) or signature to authenticate +the message. @menu * CBC:: * CTR:: +* CFB:: @end menu @node CBC, CTR, Cipher modes, Cipher modes @@ -1994,7 +1997,7 @@ These macros use some tricks to make the compiler display a warning if the types of @var{f} and @var{ctx} don't match, e.g. if you try to use an @code{struct aes_ctx} context with the @code{des_encrypt} function. -@node CTR, , CBC, Cipher modes +@node CTR, CFB, CBC, Cipher modes @comment node-name, next, previous, up @subsection Counter mode @@ -2070,6 +2073,91 @@ last three arguments define the source and destination area for the operation. @end deffn +@node CFB, , CTR, Cipher modes +@comment node-name, next, previous, up +@subsection Cipher Feedback mode + +@cindex Cipher Feedback Mode +@cindex CFB Mode + +Cipher Feedback mode (@acronym{CFB}) being a close relative to both +@acronym{CBC} mode and @acronym{CTR} mode borrows some characteristics +from stream ciphers. + +The message is divided into @code{n} blocks @code{M_1},@dots{} +@code{M_n}, where @code{M_n} is of size @code{m} which may be smaller +than the block size. Except for the last block, all the message blocks +must be of size equal to the cipher's block size. + +If @code{E_k} is the encryption function of a block cipher, @code{IV} is +the initialization vector, then the @code{n} plaintext blocks are +transformed into @code{n} ciphertext blocks @code{C_1},@dots{} +@code{C_n} as follows: + +@example +C_1 = E_k(IV) XOR M_1 +C_2 = E_k(C_1) XOR M_2 + +@dots{} + +C_(n-1) = E_k(C_(n - 2)) XOR M_(n-1) +C_n = E_k(C_(n - 1)) [1..m] XOR M_n +@end example + +Nettle's includes two functions for applying a block cipher in Cipher +Feedback (@acronym{CFB}) mode, one for encryption and one for +decryption. These functions uses @code{void *} to pass cipher contexts +around. + +@deftypefun {void} cfb_encrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) +@deftypefunx {void} cfb_decrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) + +Applies the encryption or decryption function @var{f} in @acronym{CFB} +mode. The final ciphertext block processed is copied into @var{iv} +before returning, so that a large message can be processed by a sequence +of calls to @code{cfb_encrypt}. Note that for @acronym{CFB} mode +internally uses encryption only function and hence @var{f} should always +be the encryption function for the underlying block cipher. + +When a message is encrypted using a sequence of calls to +@code{cfb_encrypt}, all but the last call @emph{must} use a length that +is a multiple of the block size. +@end deftypefun + +Like for @acronym{CBC}, there are also a couple of helper macros. + +@deffn Macro CFB_CTX (@var{context_type}, @var{block_size}) +Expands to +@example +@{ + context_type ctx; + uint8_t iv[block_size]; +@} +@end example +@end deffn + +@deffn Macro CFB_SET_IV(@var{ctx}, @var{iv}) +First argument is a pointer to a context struct as defined by +@code{CFB_CTX}, and the second is a pointer to an initialization vector +that is copied into that context. +@end deffn + +@deffn Macro CFB_ENCRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src}) +A simpler way to invoke @code{cfb_encrypt}. The first argument is a +pointer to a context struct as defined by @code{CFB_CTX}, and the second +argument is an encryption function following Nettle's conventions. The +last three arguments define the source and destination area for the +operation. +@end deffn + +@deffn Macro CFB_DECRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src}) +A simpler way to invoke @code{cfb_decrypt}. The first argument is a +pointer to a context struct as defined by @code{CFB_CTX}, and the second +argument is an encryption function following Nettle's conventions. The +last three arguments define the source and destination area for the +operation. +@end deffn + @node Authenticated encryption, Keyed hash functions, Cipher modes, Reference @comment node-name, next, previous, up @@ -3366,12 +3454,7 @@ processing a new message. @node Key derivation functions, Public-key algorithms, Keyed hash functions, Reference @comment node-name, next, previous, up @section Key derivation Functions - @cindex Key Derivation Function -@cindex Password Based Key Derivation Function -@cindex PKCS #5 -@cindex KDF -@cindex PBKDF A @dfn{key derivation function} (@acronym{KDF}) is a function that from a given symmetric key derives other symmetric keys. A sub-class of KDFs @@ -3380,7 +3463,51 @@ which take as input a password or passphrase, and its purpose is typically to strengthen it and protect against certain pre-computation attacks by using salting and expensive computation. +@subsection HKDF: HMAC-based Extract-and-Expand +@cindex HKDF + +HKDF is a key derivation function used as a building block of +higher-level protocols like TLS 1.3. It is a derivation function +based on HMAC described in @cite{RFC 5869}, +and is split into two logical modules, called 'extract' and 'expand'. +The extract module takes an initial secret and a random +salt to "extract" a fixed-length pseudorandom key (PRK). The second stage +takes as input the previous PRK and some informational data (e.g., +text) and expands them into multiple keys. + +Nettle's @acronym{HKDF} functions are defined in +@file{<nettle/hkdf.h>}. There are two abstract functions for the extract +and expand operations that operate on any HMAC implemented via the @code{nettle_hash_update_func}, +and @code{nettle_hash_digest_func} interfaces. + +@deftypefun void hkdf_extract (void *mac_ctx, nettle_hash_update_func *update, nettle_hash_digest_func *digest, size_t digest_size,size_t secret_size, const uint8_t *secret, uint8_t *dst) +Extract a Pseudorandom Key (PRK) from a secret and a salt according +to HKDF. The HMAC must have been initialized, with its key being the +salt for the Extract operation. This function will call the +@var{update} and @var{digest} functions passing the @var{mac_ctx} +context parameter as an argument in order to compute digest of size +@var{digest_size}. Inputs are the secret @var{secret} of length +@var{secret_length}. The output length is fixed to @var{digest_size} octets, +thus the output buffer @var{dst} must have room for at least @var{digest_size} octets. +@end deftypefun + +@deftypefun void hkdf_expand (void *mac_ctx, nettle_hash_update_func *update, nettle_hash_digest_func *digest, size_t digest_size, size_t info_size, const uint8_t *info, size_t length, uint8_t *dst) +Expand a Pseudorandom Key (PRK) to an arbitrary size according to HKDF. +The HMAC must have been initialized, with its key being the +PRK from the Extract operation. This function will call the +@var{update} and @var{digest} functions passing the @var{mac_ctx} +context parameter as an argument in order to compute digest of size +@var{digest_size}. Inputs are the info @var{info} of length +@var{info_length}, and the desired derived output length @var{length}. +The output buffer is @var{dst} which must have room for at least @var{length} octets. +@end deftypefun + + @subsection @acronym{PBKDF2} +@cindex Password Based Key Derivation Function +@cindex PKCS #5 +@cindex KDF +@cindex PBKDF The most well known PBKDF is the @code{PKCS #5 PBKDF2} described in @cite{RFC 2898} which uses a pseudo-random function such as @acronym{HMAC-SHA1}. @@ -3770,6 +3897,43 @@ of the digest together with an object identifier for the used hash algorithm. @end deftypefun +While the above functions for the RSA signature operations use the +@cite{PKCS#1} padding scheme, Nettle also provides the variants based on +the PSS padding scheme, specified in @cite{RFC 3447}. These variants +take advantage of a randomly choosen salt value, which could enhance the +security by causing output to be different for equivalent inputs. +However, assuming the same security level as inverting the @acronym{RSA} +algorithm, a longer salt value does not always mean a better security +@uref{http://www.iacr.org/archive/eurocrypt2002/23320268/coron.pdf}. +The typical choices of the length are between 0 and the digest size of +the underlying hash function. + +Creating an RSA signature with the PSS padding scheme is done with one +of the following functions: + +@deftypefun int rsa_pss_sha256_sign_digest_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t @var{salt_length}, const uint8_t *@var{salt}, const uint8_t *@var{digest}, mpz_t @var{signature}) +@deftypefunx int rsa_pss_sha384_sign_digest_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t @var{salt_length}, const uint8_t *@var{salt}, const uint8_t *@var{digest}, mpz_t @var{signature}) +@deftypefunx int rsa_pss_sha512_sign_digest_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t @var{salt_length}, const uint8_t *@var{salt}, const uint8_t *@var{digest}, mpz_t @var{signature}) +Creates a signature using the PSS padding scheme. @var{salt} should +point to a salt string of size @var{salt_length}. @var{digest} should +point to a digest of size @code{SHA256_DIGEST_SIZE}, +@code{SHA384_DIGEST_SIZE}, or @code{SHA512_DIGEST_SIZE}respectively. The +signature is stored in @var{signature} (which must have been +@code{mpz_init}:ed earlier). +Returns one on success, or zero on failure. +@end deftypefun + +Verifying an RSA signature with the PSS padding scheme is done with one +of the following functions: + +@deftypefun int rsa_pss_sha256_verify_digest (const struct rsa_public_key *@var{key}, size_t @var{salt_length}, const uint8_t *@var{digest}, const mpz_t @var{signature}) +@deftypefunx int rsa_pss_sha384_verify_digest (const struct rsa_public_key *@var{key}, size_t @var{salt_length}, const uint8_t *@var{digest}, const mpz_t @var{signature}) +@deftypefunx int rsa_pss_sha512_verify_digest (const struct rsa_public_key *@var{key}, size_t @var{salt_length}, const uint8_t *@var{digest}, const mpz_t @var{signature}) +Returns 1 if the signature is valid, or 0 if it isn't. @var{digest} +should point to a digest of size @code{SHA256_DIGEST_SIZE}, +@code{SHA384_DIGEST_SIZE}, or @code{SHA512_DIGEST_SIZE} respectively. +@end deftypefun + The following function is used to encrypt a clear text message using RSA. @deftypefun int rsa_encrypt (const struct rsa_public_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t @var{length}, const uint8_t *@var{cleartext}, mpz_t @var{ciphertext}) Returns 1 on success, 0 on failure. If the message is too long then this |