Less documentation for deprecated API

Deprecated functions are still documented.
Put HISTORY after SEE ALSO; add HISTORY to BN_zero

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/3746)

15 files changed, 103 insertions, 174 deletions

diff --git a/doc/man3/BN_generate_prime.pod b/doc/man3/BN_generate_prime.pod
index 1c40a13..f833d5c 100644
--- a/doc/man3/BN_generate_prime.pod
+++ b/doc/man3/BN_generate_prime.pod
@@ -108,13 +108,13 @@ after the j-th iteration (j = 0, 1, ...). B<ctx> is a
 pre-allocated B<BN_CTX> (to save the overhead of allocating and
 freeing the structure in a loop), or B<NULL>.
 
-BN_GENCB_call calls the callback function held in the B<BN_GENCB> structure
+BN_GENCB_call() calls the callback function held in the B<BN_GENCB> structure
 and passes the ints B<a> and B<b> as arguments. There are two types of
 B<BN_GENCB> structure that are supported: "new" style and "old" style. New
 programs should prefer the "new" style, whilst the "old" style is provided
 for backwards compatibility purposes.
 
-A BN_GENCB structure should be created through a call to BN_GENCB_new(),
+A B<BN_GENCB> structure should be created through a call to BN_GENCB_new(),
 and freed through a call to BN_GENCB_free().
 
 For "new" style callbacks a BN_GENCB structure should be initialised with a
@@ -131,12 +131,12 @@ style callbacks or B<callback(a, b, cb_arg)> for old style.
 It is possible to obtained the argument associated with a BN_GENCB structure
 (set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.
 
-BN_generate_prime (deprecated) works in the same way as
-BN_generate_prime_ex but expects an old style callback function
+BN_generate_prime() (deprecated) works in the same way as
+BN_generate_prime_ex() but expects an old-style callback function
 directly in the B<callback> parameter, and an argument to pass to it in
-the B<cb_arg>. Similarly BN_is_prime and BN_is_prime_fasttest are
-deprecated and can be compared to BN_is_prime_ex and
-BN_is_prime_fasttest_ex respectively.
+the B<cb_arg>. BN_is_prime() and BN_is_prime_fasttest()
+can similarly be compared to BN_is_prime_ex() and
+BN_is_prime_fasttest_ex(), respectively.
 
 =head1 RETURN VALUES
 
diff --git a/doc/man3/BN_zero.pod b/doc/man3/BN_zero.pod
index 91d48aa..167a7e4 100644
--- a/doc/man3/BN_zero.pod
+++ b/doc/man3/BN_zero.pod
@@ -17,12 +17,6 @@ operations
  int BN_set_word(BIGNUM *a, unsigned long w);
  unsigned long BN_get_word(BIGNUM *a);
 
-Deprecated:
-
- #if OPENSSL_API_COMPAT < 0x00908000L
- int BN_zero(BIGNUM *a);
- #endif
-
 =head1 DESCRIPTION
 
 BN_zero(), BN_one() and BN_set_word() set B<a> to the values 0, 1 and
@@ -39,15 +33,12 @@ long.
 BN_get_word() returns the value B<a>, and 0xffffffffL if B<a> cannot
 be represented as an unsigned long.
 
-BN_one(), BN_set_word() and the deprecated version of BN_zero()
-return 1 on success, 0 otherwise.
+BN_one() and BN_set_word() return 1 on success, 0 otherwise.
 BN_value_one() returns the constant.
-The preferred version of BN_zero() never fails and returns no value.
+BN_zero() never fails and returns no value.
 
 =head1 BUGS
 
-Someone might change the constant.
-
 If a B<BIGNUM> is equal to 0xffffffffL it can be represented as an
 unsigned long but this value is also returned on error.
 
@@ -55,6 +46,11 @@ unsigned long but this value is also returned on error.
 
 L<BN_bn2bin(3)>
 
+=head1 HISTORY
+
+In OpenSSL 0.9.8, BN_zero() was changed to not return a value; previous
+versions returned an int.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/CONF_modules_free.pod b/doc/man3/CONF_modules_free.pod
index 876cb37..aacbc62 100644
--- a/doc/man3/CONF_modules_free.pod
+++ b/doc/man3/CONF_modules_free.pod
@@ -21,7 +21,9 @@ Deprecated:
 =head1 DESCRIPTION
 
 CONF_modules_free() closes down and frees up all memory allocated by all
-configuration modules.
+configuration modules.  Normally, in versions of OpenSSL prior to 1.1.0,
+applications called
+CONF_modules_free() at exit to tidy up any configuration performed.
 
 CONF_modules_finish() calls each configuration modules B<finish> handler
 to free up any configuration that module may have performed.
@@ -30,13 +32,6 @@ CONF_modules_unload() finishes and unloads configuration modules. If
 B<all> is set to B<0> only modules loaded from DSOs will be unloads. If
 B<all> is B<1> all modules, including builtin modules will be unloaded.
 
-=head1 NOTES
-
-Normally in versions of OpenSSL prior to 1.1.0 applications will only call
-CONF_modules_free() at application exit to tidy up any configuration performed.
-From 1.1.0 CONF_modules_free() is deprecated and no explicit CONF cleanup is
-required at all. For more information see L<OPENSSL_init_crypto(3)>.
-
 =head1 RETURN VALUE
 
 None of the functions return a value.
@@ -48,7 +43,8 @@ L<CONF_modules_load_file(3)>
 
 =head1 HISTORY
 
-CONF_modules_free() was deprecated in OpenSSL 1.1.0.
+CONF_modules_free() was deprecated in OpenSSL 1.1.0; do not use it.
+For more information see L<OPENSSL_init_crypto(3)>.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/DH_generate_parameters.pod b/doc/man3/DH_generate_parameters.pod
index 54e98f5..4143df0 100644
--- a/doc/man3/DH_generate_parameters.pod
+++ b/doc/man3/DH_generate_parameters.pod
@@ -27,7 +27,9 @@ Deprecated:
 DH_generate_parameters_ex() generates Diffie-Hellman parameters that can
 be shared among a group of users, and stores them in the provided B<DH>
 structure. The pseudo-random number generator must be
-seeded prior to calling DH_generate_parameters().
+seeded before calling it.
+The parameters generated by DH_generate_parameters_ex() should not be used in
+signature schemes.
 
 B<prime_len> is the length in bits of the safe prime to be generated.
 B<generator> is a small number E<gt> 1, typically 2 or 5.
@@ -36,9 +38,13 @@ A callback function may be used to provide feedback about the progress
 of the key generation. If B<cb> is not B<NULL>, it will be
 called as described in L<BN_generate_prime(3)> while a random prime
 number is generated, and when a prime has been found, B<BN_GENCB_call(cb, 3, 0)>
-is called. See L<BN_generate_prime(3)> for information on
+is called. See L<BN_generate_prime_ex(3)> for information on
 the BN_GENCB_call() function.
 
+DH_generate_parameters() is similar to DH_generate_prime_ex() but
+expects an old-style callback function; see
+L<BN_generate_prime(3)> for information on the old-style callback.
+
 DH_check_params() confirms that the B<p> and B<g> are likely enough to
 be valid.
 This is a lightweight check, if a more thorough check is needed, use
@@ -104,24 +110,21 @@ The parameter B<j> is invalid.
 DH_generate_parameters_ex(), DH_check() and DH_check_params() return 1
 if the check could be performed, 0 otherwise.
 
-DH_generate_parameters() (deprecated) returns a pointer to the DH structure, or
-NULL if the parameter generation fails.
+DH_generate_parameters() returns a pointer to the DH structure or NULL if
+the parameter generation fails.
 
 The error codes can be obtained by L<ERR_get_error(3)>.
 
-=head1 NOTES
-
-DH_generate_parameters_ex() and DH_generate_parameters() may run for several
-hours before finding a suitable prime.
-
-The parameters generated by DH_generate_parameters_ex() and DH_generate_parameters()
-are not to be used in signature schemes.
-
 =head1 SEE ALSO
 
 L<DH_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>,
 L<DH_free(3)>
 
+=head1 HISTORY
+
+DH_generate_parameters() was deprecated in OpenSSL version 0.9.8; use
+DH_generate_parameters_ex() instead.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/DSA_generate_key.pod b/doc/man3/DSA_generate_key.pod
index 3305c16..65f0531 100644
--- a/doc/man3/DSA_generate_key.pod
+++ b/doc/man3/DSA_generate_key.pod
@@ -25,7 +25,7 @@ The error codes can be obtained by L<ERR_get_error(3)>.
 =head1 SEE ALSO
 
 L<DSA_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>,
-L<DSA_generate_parameters(3)>
+L<DSA_generate_parameters_ex(3)>
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/DSA_generate_parameters.pod b/doc/man3/DSA_generate_parameters.pod
index 4e3d748..e011539 100644
--- a/doc/man3/DSA_generate_parameters.pod
+++ b/doc/man3/DSA_generate_parameters.pod
@@ -43,6 +43,10 @@ called as shown below. For information on the BN_GENCB structure and the
 BN_GENCB_call function discussed below, refer to
 L<BN_generate_prime(3)>.
 
+DSA_generate_prime() is similar to DSA_generate_prime_ex() but
+expects an old-style callback function; see
+L<BN_generate_prime(3)> for information on the old-style callback.
+
 =over 2
 
 =item *
@@ -88,29 +92,28 @@ When the generator has been found, B<BN_GENCB_call(cb, 3, 1)> is called.
 
 =back
 
-DSA_generate_parameters() (deprecated) works in much the same way as for DSA_generate_parameters_ex, except that no B<dsa> parameter is passed and
-instead a newly allocated B<DSA> structure is returned. Additionally "old
-style" callbacks are used instead of the newer BN_GENCB based approach.
-Refer to L<BN_generate_prime(3)> for further information.
-
 =head1 RETURN VALUE
 
 DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise.
+The error codes can be obtained by L<ERR_get_error(3)>.
 
-DSA_generate_parameters() returns a pointer to the DSA structure, or
+DSA_generate_parameters() returns a pointer to the DSA structure or
 B<NULL> if the parameter generation fails.
 
-The error codes can be obtained by L<ERR_get_error(3)>.
-
 =head1 BUGS
 
-Seed lengths E<gt> 20 are not supported.
+Seed lengths greater than 20 are not supported.
 
 =head1 SEE ALSO
 
 L<DSA_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>,
 L<DSA_free(3)>, L<BN_generate_prime(3)>
 
+=head1 HISTORY
+
+DSA_generate_parameters() was deprecated in OpenSSL version 0.9.8; use
+DSA_generate_parameters_ex() instead.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/ENGINE_add.pod b/doc/man3/ENGINE_add.pod
index df3ad33..bac325f 100644
--- a/doc/man3/ENGINE_add.pod
+++ b/doc/man3/ENGINE_add.pod
@@ -321,29 +321,6 @@ consideration is whether any/all available ENGINE implementations should be
 made visible to OpenSSL - this is controlled by calling the various "load"
 functions.
 
-Having called any of these functions, ENGINE objects would have been
-dynamically allocated and populated with these implementations and linked
-into OpenSSL's internal linked list. At this point it is important to
-mention an important API function;
-
- void ENGINE_cleanup(void)
-
-If no ENGINE API functions are called at all in an application, then there
-are no inherent memory leaks to worry about from the ENGINE functionality.
-However, prior to OpenSSL 1.1.0 if any ENGINEs are loaded, even if they are
-never registered or used, it was necessary to use the ENGINE_cleanup() function
-to correspondingly cleanup before program exit, if the caller wishes to avoid
-memory leaks. This mechanism used an internal callback registration table
-so that any ENGINE API functionality that knows it requires cleanup can
-register its cleanup details to be called during ENGINE_cleanup(). This
-approach allowed ENGINE_cleanup() to clean up after any ENGINE functionality
-at all that your program uses, yet doesn't automatically create linker
-dependencies to all possible ENGINE functionality - only the cleanup
-callbacks required by the functionality you do use will be required by the
-linker. From OpenSSL 1.1.0 it is no longer necessary to explicitly call
-ENGINE_cleanup and this function is deprecated. Cleanup automatically takes
-place at program exit.
-
 The fact that ENGINEs are made visible to OpenSSL (and thus are linked into
 the program and loaded into memory at run-time) does not mean they are
 "registered" or called into use by OpenSSL automatically - that behaviour
@@ -358,6 +335,11 @@ things, so we will simply illustrate the consequences as they apply to a
 couple of simple cases and leave developers to consider these and the
 source code to openssl's builtin utilities as guides.
 
+If no ENGINE API functions are called within an application, then OpenSSL
+will not allocate any internal resources.  Prior to OpenSSL 1.1.0, however,
+if any ENGINEs are loaded, even if not registered or used, it was necessary to
+call ENGINE_cleanup() before the program exits.
+
 I<Using a specific ENGINE implementation>
 
 Here we'll assume an application has been configured by its user or admin
@@ -585,9 +567,9 @@ L<OPENSSL_init_crypto(3)>, L<RSA_new_method(3)>, L<DSA_new(3)>, L<DH_new(3)>, L<
 
 =head1 HISTORY
 
-ENGINE_cleanup(), ENGINE_load_openssl(), ENGINE_load_dynamic(), and
-ENGINE_load_cryptodev() were deprecated in OpenSSL 1.1.0 by
-OPENSSL_init_crypto().
+ENGINE_cleanup() was deprecated in OpenSSL 1.1.0 by the automatic cleanup
+done by OPENSSL_cleanup()
+and should not be used.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/ERR_load_crypto_strings.pod b/doc/man3/ERR_load_crypto_strings.pod
index 56d91d5..c503241 100644
--- a/doc/man3/ERR_load_crypto_strings.pod
+++ b/doc/man3/ERR_load_crypto_strings.pod
@@ -24,16 +24,12 @@ Deprecated:
 
 =head1 DESCRIPTION
 
-All of the following functions are deprecated from OpenSSL 1.1.0. No explicit
-initialisation or de-initialisation is necessary. See L<OPENSSL_init_crypto(3)>
-and L<OPENSSL_init_ssl(3)>.
-
 ERR_load_crypto_strings() registers the error strings for all
 B<libcrypto> functions. SSL_load_error_strings() does the same,
 but also registers the B<libssl> error strings.
 
-In versions of OpenSSL prior to 1.1.0 ERR_free_strings() freed all previously
-loaded error strings. However from OpenSSL 1.1.0 it does nothing.
+In versions prior to OpenSSL 1.1.0,
+ERR_free_strings() releases any resources created by the above functions.
 
 =head1 RETURN VALUES
 
@@ -48,7 +44,7 @@ L<ERR_error_string(3)>
 
 The ERR_load_crypto_strings(), SSL_load_error_strings(), and
 ERR_free_strings() functions were deprecated in OpenSSL 1.1.0 by
-OPENSSL_init_crypto() and OPENSSL_init_ssl().
+OPENSSL_init_crypto() and OPENSSL_init_ssl() and should not be used.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/ERR_remove_state.pod b/doc/man3/ERR_remove_state.pod
index 617b4b7..273fb7a 100644
--- a/doc/man3/ERR_remove_state.pod
+++ b/doc/man3/ERR_remove_state.pod
@@ -9,25 +9,23 @@ ERR_remove_thread_state, ERR_remove_state - DEPRECATED
 Deprecated:
 
  #if OPENSSL_API_COMPAT < 0x10000000L
- void ERR_remove_state(unsigned long pid);
+ void ERR_remove_state(unsigned long tid);
  #endif
 
  #if OPENSSL_API_COMPAT < 0x10100000L
- void ERR_remove_thread_state(void *);
+ void ERR_remove_thread_state(void *tid);
  #endif
 
 =head1 DESCRIPTION
 
-The functions described here were used to free the error queue
-associated with the current or specified thread.
-
-They are now deprecated and do nothing, as the OpenSSL libraries now
-normally do all thread initialisation and deinitialisation
-automatically (see L<OPENSSL_init_crypto(3)>).
+ERR_remove_state() frees the error queue associated with the specified
+thread, identified by B<tid>.
+ERR_remove_thread_state() does the same thing, except the identifier is
+an opaque pointer.
 
 =head1 RETURN VALUE
 
-The functions described here return no value.
+ERR_remove_state() and ERR_remove_thread_state() return no value.
 
 =head1 SEE ALSO
 
@@ -35,11 +33,9 @@ LL<OPENSSL_init_crypto(3)>
 
 =head1 HISTORY
 
-ERR_remove_state() was deprecated in OpenSSL 1.0.0 when
-ERR_remove_thread_state() was introduced.
-
-ERR_remove_thread_state() was deprecated in OpenSSL 1.1.0 when the
-thread handling functionality was entirely rewritten.
+ERR_remove_state() was deprecated in OpenSSL 1.0.0 and
+ERR_remove_thread_state() was deprecated in OpenSSL 1.1.0; these functions
+and should not be used.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/HMAC.pod b/doc/man3/HMAC.pod
index 493b933..c480a9c 100644
--- a/doc/man3/HMAC.pod
+++ b/doc/man3/HMAC.pod
@@ -78,23 +78,21 @@ itself.
 The following functions may be used if the message is not completely
 stored in memory:
 
-HMAC_Init() initializes a B<HMAC_CTX> structure to use the hash
-function B<evp_md> and the key B<key> which is B<key_len> bytes
-long. It is deprecated and only included for backward compatibility
-with OpenSSL 0.9.6b.
-
 HMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use the hash
-function B<evp_md> and key B<key>. If both are NULL (or B<evp_md> is the same
-as the previous digest used by B<ctx> and B<key> is NULL) the existing key is
+function B<evp_md> and key B<key>. If both are NULL, or if B<key> is NULL
+and B<evp_md> is the same as the previous call, then the
+existing key is
 reused. B<ctx> must have been created with HMAC_CTX_new() before the first use
-of an B<HMAC_CTX> in this function. B<N.B. HMAC_Init() had this undocumented
-behaviour in previous versions of OpenSSL - failure to switch to HMAC_Init_ex()
-in programs that expect it will cause them to stop working>.
+of an B<HMAC_CTX> in this function.
 
-B<NOTE:> If HMAC_Init_ex() is called with B<key> NULL and B<evp_md> is not the
+If HMAC_Init_ex() is called with B<key> NULL and B<evp_md> is not the
 same as the previous digest used by B<ctx> then an error is returned
 because reuse of an existing key with a different digest is not supported.
 
+HMAC_Init() initializes a B<HMAC_CTX> structure to use the hash
+function B<evp_md> and the key B<key> which is B<key_len> bytes
+long. 
+
 HMAC_Update() can be called repeatedly with chunks of the message to
 be authenticated (B<len> bytes at B<data>).
 
diff --git a/doc/man3/OBJ_nid2obj.pod b/doc/man3/OBJ_nid2obj.pod
index 7b4169b..6c1aa13 100644
--- a/doc/man3/OBJ_nid2obj.pod
+++ b/doc/man3/OBJ_nid2obj.pod
@@ -91,11 +91,7 @@ OBJ_length() returns the size of the content octets of B<obj>.
 OBJ_get0_data() returns a pointer to the content octets of B<obj>.
 The returned pointer is an internal pointer which B<must not> be freed.
 
-In OpenSSL before version 1.1.0, OBJ_cleanup() cleaned up the internal
-object table and was called before an application exits if any new objects were
-added using OBJ_create(). This function is deprecated in OpenSSL 1.1.0 and now
-does nothing if called. No explicit de-initialisation is now required. See
-L<OPENSSL_init_crypto(3)> for further information.
+OBJ_cleanup() releases any resources allocated by creating new objects.
 
 =head1 NOTES
 
@@ -179,7 +175,8 @@ L<ERR_get_error(3)>
 
 =head1 HISTORY
 
-OBJ_cleanup() was deprecated in OpenSSL 1.1.0.
+OBJ_cleanup() was deprecated in OpenSSL 1.1.0 by L<OPENSSL_init_crypto(3)>
+and should not be used.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/OpenSSL_add_all_algorithms.pod b/doc/man3/OpenSSL_add_all_algorithms.pod
index 1593e97..0c086d1 100644
--- a/doc/man3/OpenSSL_add_all_algorithms.pod
+++ b/doc/man3/OpenSSL_add_all_algorithms.pod
@@ -22,11 +22,7 @@ Deprecated:
 =head1 DESCRIPTION
 
 OpenSSL keeps an internal table of digest algorithms and ciphers. It uses
-this table to lookup ciphers via functions such as EVP_get_cipher_byname(). In
-OpenSSL before version 1.1.0, these functions initialised and de-initialised
-this table. Starting with OpenSSL 1.1.0 they are deprecated. No explicit initialisation
-or de-initialisation is required. See L<OPENSSL_init_crypto(3)> for further
-information.
+this table to lookup ciphers via functions such as EVP_get_cipher_byname().
 
 OpenSSL_add_all_digests() adds all digest algorithms to the table.
 
@@ -43,30 +39,6 @@ the table. It no longer has any effect in OpenSSL 1.1.0.
 
 None of the functions return a value.
 
-=head1 NOTES
-
-A typical application will call OpenSSL_add_all_algorithms() initially and
-EVP_cleanup() before exiting.
-
-An application does not need to add algorithms to use them explicitly, for example
-by EVP_sha1(). It just needs to add them if it (or any of the functions it calls)
-needs to lookup algorithms.
-
-The cipher and digest lookup functions are used in many parts of the library. If
-the table is not initialized several functions will misbehave and complain they
-cannot find algorithms. This includes the PEM, PKCS#12, SSL and S/MIME libraries.
-This is a common query in the OpenSSL mailing lists.
-
-Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a
-statically linked executable can be quite large. If this is important it is possible
-to just add the required ciphers and digests.
-
-=head1 BUGS
-
-Although the functions do not return error codes it is possible for them to fail.
-This will only happen as a result of a memory allocation failure so this is not
-too much of a problem in practice.
-
 =head1 SEE ALSO
 
 L<evp(7)>, L<EVP_DigestInit(3)>,
@@ -76,11 +48,12 @@ L<EVP_EncryptInit(3)>
 
 The OpenSSL_add_all_algorithms(), OpenSSL_add_all_ciphers(),
 OpenSSL_add_all_digests(), and EVP_cleanup(), functions
-were deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto().
+were deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto() and should
+not be used.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/RAND_cleanup.pod b/doc/man3/RAND_cleanup.pod
index 34b0ae0..a1f1715 100644
--- a/doc/man3/RAND_cleanup.pod
+++ b/doc/man3/RAND_cleanup.pod
@@ -12,8 +12,6 @@ RAND_cleanup - erase the PRNG state
  void RAND_cleanup(void)
  #endif
 
-=head1 DESCRIPTION
-
 Prior to OpenSSL 1.1.0, RAND_cleanup() released all resources used by
 the PRNG.  As of version 1.1.0, it does nothing and should not be called,
 since no explicit initialisation or de-initialisation is necessary. See
@@ -23,13 +21,10 @@ L<OPENSSL_init_crypto(3)>.
 
 RAND_cleanup() returns no value.
 
-=head1 SEE ALSO
-
-L<RAND_bytes(3)>
-
 =head1 HISTORY
 
-RAND_cleanup() was deprecated in OpenSSL 1.1.0.
+RAND_cleanup() was deprecated in OpenSSL 1.1.0; do not use it.
+See L<OPENSSL_init_crypto(3)>
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/RSA_generate_key.pod b/doc/man3/RSA_generate_key.pod
index 6cda49d..be18ae2 100644
--- a/doc/man3/RSA_generate_key.pod
+++ b/doc/man3/RSA_generate_key.pod
@@ -32,6 +32,10 @@ progress of the key generation. If B<cb> is not B<NULL>, it
 will be called as follows using the BN_GENCB_call() function
 described on the L<BN_generate_prime(3)> page.
 
+RSA_generate_prime() is similar to RSA_generate_prime_ex() but
+expects an old-style callback function; see
+L<BN_generate_prime(3)> for information on the old-style callback.
+
 =over 2
 
 =item *
@@ -53,28 +57,27 @@ it is called as B<BN_GENCB_call(cb, 3, 0)>.
 
 The process is then repeated for prime q with B<BN_GENCB_call(cb, 3, 1)>.
 
-RSA_generate_key() is deprecated (new applications should use
-RSA_generate_key_ex() instead). RSA_generate_key() works in the same way as
-RSA_generate_key_ex() except it uses "old style" call backs. See
-L<BN_generate_prime(3)> for further details.
-
 =head1 RETURN VALUE
 
 RSA_generate_key_ex() returns 1 on success or 0 on error.
-RSA_generate_key() returns the key on success or B<NULL> on error.
-
 The error codes can be obtained by L<ERR_get_error(3)>.
 
+RSA_generate_key() returns a pointer to the RSA structure or
+B<NULL> if the key generation fails.
+
 =head1 BUGS
 
 B<BN_GENCB_call(cb, 2, x)> is used with two different meanings.
 
-RSA_generate_key() goes into an infinite loop for illegal input values.
-
 =head1 SEE ALSO
 
 L<ERR_get_error(3)>, L<RAND_bytes(3)>,
-L<RSA_generate_key(3)>, L<BN_generate_prime(3)>
+L<RSA_generate_key_ex(3)>, L<BN_generate_prime(3)>
+
+=head1 HISTORY
+
+RSA_generate_key() was deprecated in OpenSSL 0.9.8; use
+RSA_generate_key_ex() intsead.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/SSL_COMP_add_compression_method.pod b/doc/man3/SSL_COMP_add_compression_method.pod
index c3d402b..1dc8eb1 100644
--- a/doc/man3/SSL_COMP_add_compression_method.pod
+++ b/doc/man3/SSL_COMP_add_compression_method.pod
@@ -35,12 +35,8 @@ SSL_COMP_get0_name() returns the name of the compression method B<comp>.
 
 SSL_COMP_get_id() returns the id of the compression method B<comp>.
 
-In versions of OpenSSL prior to 1.1.0 SSL_COMP_free_compression_methods() freed
-the internal table of compression methods that were built internally, and
-possibly augmented by adding SSL_COMP_add_compression_method(). However this is
-now unnecessary from version 1.1.0.  No explicit initialisation or
-de-initialisation is necessary. See L<OPENSSL_init_crypto(3)> and
-L<OPENSSL_init_ssl(3)>. From OpenSSL 1.1.0 calling this function does nothing.
+SSL_COMP_free_compression_methods() releases any resources acquired to
+maintain the internal table of compression methods.
 
 =head1 NOTES
 
@@ -66,12 +62,6 @@ of compression methods supported on a per connection basis.
 If enabled during compilation, the OpenSSL library will have the
 COMP_zlib() compression method available.
 
-=head1 WARNINGS
-
-Once the identities of the compression methods for the TLS protocol have
-been standardized, the compression API will most likely be changed. Using
-it in the current state is not recommended.
-
 =head1 RETURN VALUES
 
 SSL_COMP_add_compression_method() may return the following values:
@@ -101,7 +91,8 @@ L<ssl(7)>
 
 =head1 HISTORY
 
-SSL_COMP_free_compression_methods() was deprecated in OpenSSL 1.1.0.
+SSL_COMP_free_compression_methods() was deprecated in OpenSSL 1.1.0;
+do not use it.
 SSL_COMP_get0_name() and SSL_comp_get_id() were added in OpenSSL 1.1.0d.
 
 =head1 COPYRIGHT