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)
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
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
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
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.
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.
=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.
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.
=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
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.
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
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.
=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
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 *
=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.
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
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
=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
=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
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
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
=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
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>).
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
=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
=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.
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)>,
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
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
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
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 *
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
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
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:
=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
projects / oweals / openssl.git / commitdiff