Document various SRP related APIs

This includes the newly added *_ex() variants that take a libctx/property
query string.

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

2 files changed, 124 insertions, 17 deletions

diff --git a/doc/man3/SRP_Calc_B.pod b/doc/man3/SRP_Calc_B.pod
new file mode 100644
index 0000000000..1353311f50
--- /dev/null
+++ b/doc/man3/SRP_Calc_B.pod
@@ -0,0 +1,88 @@
+=pod
+
+=head1 NAME
+
+SRP_Calc_server_key,
+SRP_Calc_A,
+SRP_Calc_B_ex,
+SRP_Calc_B,
+SRP_Calc_u_ex,
+SRP_Calc_u,
+SRP_Calc_x_ex,
+SRP_Calc_x,
+SRP_Calc_client_key_ex,
+SRP_Calc_client_key
+- SRP authentication primitives
+
+=head1 SYNOPSIS
+
+ #include <openssl/srp.h>
+
+ /* server side .... */
+ BIGNUM *SRP_Calc_server_key(const BIGNUM *A, const BIGNUM *v, const BIGNUM *u,
+                             const BIGNUM *b, const BIGNUM *N);
+ BIGNUM *SRP_Calc_B_ex(const BIGNUM *b, const BIGNUM *N, const BIGNUM *g,
+                       const BIGNUM *v, OPENSSL_CTX *libctx, const char *propq);
+ BIGNUM *SRP_Calc_B(const BIGNUM *b, const BIGNUM *N, const BIGNUM *g,
+                   const BIGNUM *v);
+
+ BIGNUM *SRP_Calc_u_ex(const BIGNUM *A, const BIGNUM *B, const BIGNUM *N,
+                       OPENSSL_CTX *libctx, const char *propq);
+ BIGNUM *SRP_Calc_u(const BIGNUM *A, const BIGNUM *B, const BIGNUM *N);
+
+ /* client side .... */
+ BIGNUM *SRP_Calc_client_key_ex(const BIGNUM *N, const BIGNUM *B, const BIGNUM *g,
+                             const BIGNUM *x, const BIGNUM *a, const BIGNUM *u,
+                             OPENSSL_CTX *libctx, const char *propq);
+ BIGNUM *SRP_Calc_client_key(const BIGNUM *N, const BIGNUM *B, const BIGNUM *g,
+                             const BIGNUM *x, const BIGNUM *a, const BIGNUM *u);
+ BIGNUM *SRP_Calc_x_ex(const BIGNUM *s, const char *user, const char *pass,
+                       OPENSSL_CTX *libctx, const char *propq);
+ BIGNUM *SRP_Calc_x(const BIGNUM *s, const char *user, const char *pass);
+ BIGNUM *SRP_Calc_A(const BIGNUM *a, const BIGNUM *N, const BIGNUM *g);
+
+=head1 DESCRIPTION
+
+The SRP functions described on this page are used to calculate various
+parameters and keys used by SRP as defined in RFC2945. The server key and I<B>
+and I<u> parameters are used on the server side and are calculated via
+SRP_Calc_server_key(), SRP_Calc_B_ex(), SRP_Calc_B(), SRP_Calc_u_ex() and
+SRP_Calc_u(). The client key and B<x> and B<A> parameters are used on the
+client side and are calculated via the functions SRP_Calc_client_key_ex(),
+SRP_Calc_client_key(), SRP_Calc_x_ex(), SRP_Calc_x() and SRP_Calc_A(). See
+RFC2945 for a detailed description of their usage and the meaning of the various
+BIGNUM parameters to these functions.
+
+Most of these functions come in two forms. Those that take a I<libctx> and
+I<propq> parameter, and those that don't. Any cryptogrpahic functions that
+are fetched and used during the calculation use the provided I<libctx> and
+I<propq>. See L<provider(7)/Fetching algorithms> for more details. The variants
+that do not take a I<libctx> and I<propq> parameter use the default library
+context and property query string. The SRP_Calc_server_key() and SRP_Calc_A()
+functions do not have a form that takes I<libctx> or I<propq> parameters because
+they do not need to fetch any cryptographic algorithms.
+
+=head1 RETURN VALUES
+
+All these functions return the calculated key or parameter, or NULL on error.
+
+=head1 SEE ALSO
+
+L<openssl-srp(1)>,
+L<SRP_VBASE_new(3)>,
+L<SRP_user_pwd_new(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 1.0.1.
+
+=head1 COPYRIGHT
+
+Copyright 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
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man3/SRP_create_verifier.pod b/doc/man3/SRP_create_verifier.pod
index fb77bba794..98f31d1430 100644
--- a/doc/man3/SRP_create_verifier.pod
+++ b/doc/man3/SRP_create_verifier.pod
@@ -2,7 +2,9 @@
 
 =head1 NAME
 
+SRP_create_verifier_ex,
 SRP_create_verifier,
+SRP_create_verifier_BN_ex,
 SRP_create_verifier_BN,
 SRP_check_known_gN_param,
 SRP_get_default_gN
@@ -12,8 +14,15 @@ SRP_get_default_gN
 
  #include <openssl/srp.h>
 
+ int SRP_create_verifier_BN_ex(const char *user, const char *pass, BIGNUM **salt,
+                               BIGNUM **verifier, const BIGNUM *N,
+                               const BIGNUM *g, OPENSSL_CTX *libctx,
+                               const char *propq);
  char *SRP_create_verifier_BN(const char *user, const char *pass, BIGNUM **salt,
                               BIGNUM **verifier, const BIGNUM *N, const BIGNUM *g);
+ char *SRP_create_verifier_ex(const char *user, const char *pass, char **salt,
+                              char **verifier, const char *N, const char *g,
+                              OPENSSL_CTX *libctx, const char *propq);
  char *SRP_create_verifier(const char *user, const char *pass, char **salt,
                            char **verifier, const char *N, const char *g);
 
@@ -22,46 +31,55 @@ SRP_get_default_gN
 
 =head1 DESCRIPTION
 
-The SRP_create_verifier_BN() function creates an SRP password verifier from
-the supplied parameters as defined in section 2.4 of RFC 5054.
-On successful exit B<*verifier> will point to a newly allocated BIGNUM containing
-the verifier and (if a salt was not provided) B<*salt> will be populated with a
-newly allocated BIGNUM containing a random salt. If B<*salt> is not NULL then
+The SRP_create_verifier_BN_ex() function creates an SRP password verifier from
+the supplied parameters as defined in section 2.4 of RFC 5054 using the library
+context I<libctx> and property query string I<propq>. Any cryptographic
+algorithms that need to be fetched will use the I<libctx> and I<propq>. See
+L<provider(7)/Fetching algorithms>.
+
+SRP_create_verifier_BN() is the same as SRP_create_verifier_BN_ex() except the
+default library context and property query string is used.
+
+On successful exit I<*verifier> will point to a newly allocated BIGNUM containing
+the verifier and (if a salt was not provided) I<*salt> will be populated with a
+newly allocated BIGNUM containing a random salt. If I<*salt> is not NULL then
 the provided salt is used instead.
-The caller is responsible for freeing the allocated B<*salt> and B<*verifier>
+The caller is responsible for freeing the allocated I<*salt> and I<*verifier>
 BIGNUMS (use L<BN_free(3)>).
 
 The SRP_create_verifier() function is similar to SRP_create_verifier_BN() but
 all numeric parameters are in a non-standard base64 encoding originally designed
 for compatibility with libsrp. This is mainly present for historical compatibility
 and its use is discouraged.
-It is possible to pass NULL as B<N> and an SRP group id as B<g> instead to
+It is possible to pass NULL as I<N> and an SRP group id as I<g> instead to
 load the appropriate gN values (see SRP_get_default_gN()).
-If both B<N> and B<g> are NULL the 8192-bit SRP group parameters are used.
-The caller is responsible for freeing the allocated B<*salt> and B<*verifier>
+If both I<N> and I<g> are NULL the 8192-bit SRP group parameters are used.
+The caller is responsible for freeing the allocated I<*salt> and I<*verifier>
 (use L<OPENSSL_free(3)>).
 
-The SRP_check_known_gN_param() function checks that B<g> and B<N> are valid
+The SRP_check_known_gN_param() function checks that I<g> and I<N> are valid
 SRP group parameters from RFC 5054 appendix A.
 
-The SRP_get_default_gN() function returns the gN parameters for the RFC 5054 B<id>
+The SRP_get_default_gN() function returns the gN parameters for the RFC 5054 I<id>
 SRP group size.
 The known ids are "1024", "1536", "2048", "3072", "4096", "6144" and "8192".
 
 =head1 RETURN VALUES
 
-SRP_create_verifier_BN() returns 1 on success and 0 on failure.
+SRP_create_verifier_BN_ex() and SRP_create_verifier_BN() return 1 on success and
+0 on failure.
 
-SRP_create_verifier() returns NULL on failure and a non-NULL value on success:
-"*" if B<N> is not NULL, the selected group id otherwise. This value should
+SRP_create_verifier_ex() and SRP_create_verifier() return NULL on failure and a
+non-NULL value on success:
+"*" if I<N> is not NULL, the selected group id otherwise. This value should
 not be freed.
 
 SRP_check_known_gN_param() returns the text representation of the group id
 (ie. the prime bit size) or NULL if the arguments are not valid SRP group parameters.
 This value should not be freed.
 
-SRP_get_default_gN() returns NULL if B<id> is not a valid group size,
-or the 8192-bit group parameters if B<id> is NULL.
+SRP_get_default_gN() returns NULL if I<id> is not a valid group size,
+or the 8192-bit group parameters if I<id> is NULL.
 
 =head1 EXAMPLES
 
@@ -79,7 +97,8 @@ omitted for clarity):
  SRP_gN *gN = SRP_get_default_gN("8192");
 
  BIGNUM *salt = NULL, *verifier = NULL;
- SRP_create_verifier_BN(username, password, &salt, &verifier, gN->N, gN->g);
+ SRP_create_verifier_BN_ex(username, password, &salt, &verifier, gN->N, gN->g,
+                           NULL, NULL);
 
  SRP_user_pwd *pwd = SRP_user_pwd_new();
  SRP_user_pwd_set1_ids(pwd, username, NULL);