Add X509_NAME_hash_ex() to be able to check if it failed due to unsupported SHA1

[openssl.git] / doc / man3 / DES_random_key.pod

diff --git a/doc/man3/DES_random_key.pod b/doc/man3/DES_random_key.pod
index 4f0f25a5a4a0a5d785a81b21f5520b486a5c280a..775611a8edb7d6b902a07a3b62c72a8f55fb4d6e 100644 (file)
--- a/doc/man3/DES_random_key.pod
+++ b/doc/man3/DES_random_key.pod
@@ -16,6 +16,10 @@ DES_fcrypt, DES_crypt - DES encryption
 
  #include <openssl/des.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  void DES_random_key(DES_cblock *ret);
 
  int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule);
@@ -94,6 +98,10 @@ DES_fcrypt, DES_crypt - DES encryption
 
 =head1 DESCRIPTION
 
+All of the functions described on this page are deprecated. Applications should
+instead use L<EVP_EncryptInit_ex(3)>, L<EVP_EncryptUpdate(3)> and
+L<EVP_EncryptFinal_ex(3)> or the equivalently named decrypt functions.
+
 This library contains a fast implementation of the DES encryption
 algorithm.
 
@@ -104,9 +112,11 @@ consists of 8 bytes with odd parity.  The least significant bit in
 each byte is the parity bit.  The key schedule is an expanded form of
 the key; it is used to speed the encryption process.
 
-DES_random_key() generates a random key.  The PRNG must be seeded
-prior to using this function (see L<RAND_bytes(3)>).  If the PRNG
-could not generate a secure key, 0 is returned.
+DES_random_key() generates a random key.  The random generator must be
+seeded when calling this function.
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
+If the function fails, 0 is returned.
 
 Before a DES key can be used, it must be converted into the
 architecture dependent I<DES_key_schedule> via the
@@ -117,11 +127,8 @@ and is not a weak or semi-weak key.  If the parity is wrong, then -1
 is returned.  If the key is a weak key, then -2 is returned.  If an
 error is returned, the key schedule is not generated.
 
-DES_set_key() works like
-DES_set_key_checked() if the I<DES_check_key> flag is non-zero,
-otherwise like DES_set_key_unchecked().  These functions are available
-for compatibility; it is recommended to use a function that does not
-depend on a global variable.
+DES_set_key() works like DES_set_key_checked() and remains for
+backward compatibility.
 
 DES_set_odd_parity() sets the parity of the passed I<key> to odd.
 
@@ -135,7 +142,7 @@ DES_ecb_encrypt() is the basic DES encryption routine that encrypts or
 decrypts a single 8-byte I<DES_cblock> in I<electronic code book>
 (ECB) mode.  It always transforms the input data, pointed to by
 I<input>, into the output data, pointed to by the I<output> argument.
-If the I<encrypt> argument is non-zero (DES_ENCRYPT), the I<input>
+If the I<encrypt> argument is nonzero (DES_ENCRYPT), the I<input>
 (cleartext) is encrypted in to the I<output> (ciphertext) using the
 key_schedule specified by the I<schedule> argument, previously set via
 I<DES_set_key>. If I<encrypt> is zero (DES_DECRYPT), the I<input> (now
@@ -154,7 +161,7 @@ The macro DES_ecb2_encrypt() is provided to perform two-key Triple-DES
 encryption by using I<ks1> for the final encryption.
 
 DES_ncbc_encrypt() encrypts/decrypts using the I<cipher-block-chaining>
-(CBC) mode of DES.  If the I<encrypt> argument is non-zero, the
+(CBC) mode of DES.  If the I<encrypt> argument is nonzero, the
 routine cipher-block-chain encrypts the cleartext data pointed to by
 the I<input> argument into the ciphertext pointed to by the I<output>
 argument, using the key schedule provided by the I<schedule> argument,
@@ -303,6 +310,8 @@ L<EVP_EncryptInit(3)>
 
 =head1 HISTORY
 
+All of these functions were deprecated in OpenSSL 3.0.
+
 The requirement that the B<salt> parameter to DES_crypt() and DES_fcrypt()
 be two ASCII characters was first enforced in
 OpenSSL 1.1.0.  Previous versions tried to use the letter uppercase B<A>
@@ -311,7 +320,7 @@ on some platforms.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy