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

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

diff --git a/doc/man3/EC_POINT_add.pod b/doc/man3/EC_POINT_add.pod
index 9b71d71f55cf5a88f40dcee236f6395e04db0451..b276be46ed943408b58090c724eb3c01cd331251 100644 (file)
--- a/doc/man3/EC_POINT_add.pod
+++ b/doc/man3/EC_POINT_add.pod
@@ -15,17 +15,19 @@ EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_i
  int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p);
  int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx);
  int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
+ int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n,
+                  const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx);
+
+Deprecated since OpenSSL 3.0:
+
  int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx);
  int EC_POINTs_make_affine(const EC_GROUP *group, size_t num,
                            EC_POINT *points[], BN_CTX *ctx);
  int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num,
                    const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx);
- int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n,
-                  const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx);
  int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx);
  int EC_GROUP_have_precompute_mult(const EC_GROUP *group);
 
-
 =head1 DESCRIPTION
 
 EC_POINT_add adds the two points B<a> and B<b> and places the result in B<r>. Similarly EC_POINT_dbl doubles the point B<a> and places the
@@ -41,19 +43,23 @@ EC_POINT_cmp compares the two supplied points and tests whether or not they are
 
 The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine
 co-ordinate system. In the case of EC_POINTs_make_affine the value B<num> provides the number of points in the array B<points> to be
-forced.
+forced. These functions were deprecated in OpenSSL 3.0 and should no longer be used.
+Modern versions automatically perform this conversion when needed.
 
-EC_POINT_mul is a convenient interface to EC_POINTs_mul: it calculates the value generator * B<n> + B<q> * B<m> and stores the result in B<r>.
+EC_POINT_mul calculates the value generator * B<n> + B<q> * B<m> and stores the result in B<r>.
 The value B<n> may be NULL in which case the result is just B<q> * B<m> (variable point multiplication). Alternatively, both B<q> and B<m> may be NULL, and B<n> non-NULL, in which case the result is just generator * B<n> (fixed point multiplication).
 When performing a single fixed or variable point multiplication, the underlying implementation uses a constant time algorithm, when the input scalar (either B<n> or B<m>) is in the range [0, ec_group_order).
 
+Although deprecated in OpenSSL 3.0 and should no longer be used,
 EC_POINTs_mul calculates the value generator * B<n> + B<q[0]> * B<m[0]> + ... + B<q[num-1]> * B<m[num-1]>. As for EC_POINT_mul the value B<n> may be NULL or B<num> may be zero.
 When performing a fixed point multiplication (B<n> is non-NULL and B<num> is 0) or a variable point multiplication (B<n> is NULL and B<num> is 1), the underlying implementation uses a constant time algorithm, when the input scalar (either B<n> or B<m[0]>) is in the range [0, ec_group_order).
+Modern versions should instead use EC_POINT_mul(), combined (if needed) with EC_POINT_add() in such rare circumstances.
 
 The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst
 EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L<EC_GROUP_copy(3)> for information
-about the generator.
-
+about the generator. Precomputation functionality was deprecated in OpenSSL 3.0.
+Users of EC_GROUP_precompute_mult() and EC_GROUP_have_precompute_mult() should
+switch to named curves which OpenSSL has hardcoded lookup tables for.
 
 =head1 RETURN VALUES
 
@@ -74,9 +80,15 @@ L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
 L<EC_POINT_new(3)>, L<EC_KEY_new(3)>,
 L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
 
+=head1 HISTORY
+
+EC_POINT_make_affine(), EC_POINTs_make_affine(), EC_POINTs_mul(),
+EC_GROUP_precompute_mult(), and EC_GROUP_have_precompute_mult()
+were deprecated in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
-Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2013-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