Document various SRP related APIs

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

diff --git a/doc/man3/SRP_Calc_B.pod b/doc/man3/SRP_Calc_B.pod
new file mode 100644 (file)
index 0000000..1353311
--- /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