Commit 9784d367 authored by Niels Möller's avatar Niels Möller

Document new conventions for weak key and des

parity checks. Document des_check_parity.

Rev: nettle/NEWS:1.6
Rev: nettle/nettle.texinfo:1.11
parent d126be37
...@@ -18,8 +18,24 @@ NEWS for the 2.5 release ...@@ -18,8 +18,24 @@ NEWS for the 2.5 release
which callers sould check, and they return failure if the which callers sould check, and they return failure if the
number q is not of the appropriate size. number q is not of the appropriate size.
* The return value from des_set_key, des3_set_key and
blowfish_set_key now indicates whether or not the given key
is weak. But in either case, the key setup is done, and
applications that don't care about weak keys can ignore the
return value.
The incompatible part of this change is that enum des_error
and enum blowfish_error has been deleted, and so has the
status attribute in struct des_ctx, struct des3_ctx, and
struct blowfish_ctx.
Other changes: Other changes:
* des_set_key and des3_set_key no longer check the key parity
bits. Parity bits are silently ignored. A new function
des_check_parity is provided, for applications that care
about the DES parity bits.
* Support for sha224, sha384 and sha512. * Support for sha224, sha384 and sha512.
* Support for digital signatures using rsa-sha512 and * Support for digital signatures using rsa-sha512 and
......
...@@ -709,10 +709,10 @@ functions}, or digital signatures like @acronym{RSA}. ...@@ -709,10 +709,10 @@ functions}, or digital signatures like @acronym{RSA}.
Some ciphers have so called ``weak keys'', keys that results in Some ciphers have so called ``weak keys'', keys that results in
undesirable structure after the key setup processing, and should be undesirable structure after the key setup processing, and should be
avoided. In Nettle, the presence of weak keys for a cipher mean that the avoided. In Nettle, most key setup functions have no return value, but
key setup function can fail, so you have to check its return value. In for ciphers with weak keys, the return value indicates whether or not
addition, the context struct has a field @code{status}, that is set to a the given key is weak. For good keys, key setup returns 1, and for weak
non-zero value if key setup fails. When possible, avoid algorithm that keys, it returns 0. When possible, avoid algorithms that
have weak keys. There are several good ciphers that don't have any weak have weak keys. There are several good ciphers that don't have any weak
keys. keys.
...@@ -957,7 +957,10 @@ Default BLOWFISH key size, 16 ...@@ -957,7 +957,10 @@ Default BLOWFISH key size, 16
@deftypefun int blowfish_set_key (struct blowfish_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{key}) @deftypefun int blowfish_set_key (struct blowfish_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{key})
Initialize the cipher. The same function is used for both encryption and Initialize the cipher. The same function is used for both encryption and
decryption. Returns 1 on success, and 0 if the key was weak. Calling decryption. Checks for weak keys, returning 1
for good keys and 0 for weak keys. Applications that don't care about
weak keys can ignore the return value.
@code{blowfish_encrypt} or @code{blowfish_decrypt} with a weak key will @code{blowfish_encrypt} or @code{blowfish_decrypt} with a weak key will
crash with an assert violation. crash with an assert violation.
@end deftypefun @end deftypefun
...@@ -977,7 +980,7 @@ Analogous to @code{blowfish_encrypt} ...@@ -977,7 +980,7 @@ Analogous to @code{blowfish_encrypt}
DES is the old Data Encryption Standard, specified by NIST. It uses a DES is the old Data Encryption Standard, specified by NIST. It uses a
block size of 64 bits (8 octets), and a key size of 56 bits. However, block size of 64 bits (8 octets), and a key size of 56 bits. However,
the key bits are distributed over 8 octets, where the least significant the key bits are distributed over 8 octets, where the least significant
bit of each octet is used for parity. A common way to use DES is to bit of each octet may be used for parity. A common way to use DES is to
generate 8 random octets in some way, then set the least significant bit generate 8 random octets in some way, then set the least significant bit
of each octet to get odd parity, and initialize DES with the resulting of each octet to get odd parity, and initialize DES with the resulting
key. key.
...@@ -1002,9 +1005,9 @@ DES key size, 8 ...@@ -1002,9 +1005,9 @@ DES key size, 8
@deftypefun int des_set_key (struct des_ctx *@var{ctx}, const uint8_t *@var{key}) @deftypefun int des_set_key (struct des_ctx *@var{ctx}, const uint8_t *@var{key})
Initialize the cipher. The same function is used for both encryption and Initialize the cipher. The same function is used for both encryption and
decryption. Returns 1 on success, and 0 if the key was weak or had bad decryption. Parity bits are ignored. Checks for weak keys, returning 1
parity. Calling @code{des_encrypt} or @code{des_decrypt} with a bad key for good keys and 0 for weak keys. Applications that don't care about
will crash with an assert violation. weak keys can ignore the return value.
@end deftypefun @end deftypefun
@deftypefun void des_encrypt (struct des_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src}) @deftypefun void des_encrypt (struct des_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
...@@ -1018,6 +1021,11 @@ in any other way. ...@@ -1018,6 +1021,11 @@ in any other way.
Analogous to @code{des_encrypt} Analogous to @code{des_encrypt}
@end deftypefun @end deftypefun
@deftypefun int des_check_parity (unsigned @var{length}, const uint8_t *@var{key});
Checks that the given key has correct, odd, parity. Returns 1 for
correct parity, and 0 for bad parity.
@end deftypefun
@deftypefun void des_fix_parity (unsigned @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) @deftypefun void des_fix_parity (unsigned @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
Adjusts the parity bits to match DES's requirements. You need this Adjusts the parity bits to match DES's requirements. You need this
function if you have created a random-looking string by a key agreement function if you have created a random-looking string by a key agreement
...@@ -1072,9 +1080,10 @@ DES key size, 24 ...@@ -1072,9 +1080,10 @@ DES key size, 24
@deftypefun int des3_set_key (struct des3_ctx *@var{ctx}, const uint8_t *@var{key}) @deftypefun int des3_set_key (struct des3_ctx *@var{ctx}, const uint8_t *@var{key})
Initialize the cipher. The same function is used for both encryption and Initialize the cipher. The same function is used for both encryption and
decryption. Returns 1 on success, and 0 if the key was weak or had bad decryption. Parity bits are ignored. Checks for weak keys, returning 1
parity. Calling @code{des_encrypt} or @code{des_decrypt} with a bad key if all three keys are good keys, and 0 if one or more key is weak.
will crash with an assert violation. Applications that don't care about weak keys can ignore the return
value.
@end deftypefun @end deftypefun
For random-looking strings, you can use @code{des_fix_parity} to adjust For random-looking strings, you can use @code{des_fix_parity} to adjust
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment