From 4c106e20ef49b789e4dc53c97e0f9a701162be85 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Wed, 25 Mar 2020 17:43:50 +0000 Subject: [PATCH] Document various SRP related APIs This includes the newly added *_ex() variants that take a libctx/property query string. Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/11410) --- doc/man3/SRP_Calc_B.pod | 88 ++++++++++++++++++++++++++++++++ doc/man3/SRP_create_verifier.pod | 53 +++++++++++++------ util/missingcrypto.txt | 6 --- 3 files changed, 124 insertions(+), 23 deletions(-) create mode 100644 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 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 + + /* 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 +and I 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 and B 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 and +I parameter, and those that don't. Any cryptogrpahic functions that +are fetched and used during the calculation use the provided I and +I. See L for more details. The variants +that do not take a I and I 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 or I 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, +L, +L + +=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. + +=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 + 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 and property query string I. Any cryptographic +algorithms that need to be fetched will use the I and I. See +L. + +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). 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 and an SRP group id as B instead to +It is possible to pass NULL as I and an SRP group id as I instead to load the appropriate gN values (see SRP_get_default_gN()). -If both B and B 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 and I 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). -The SRP_check_known_gN_param() function checks that B and B are valid +The SRP_check_known_gN_param() function checks that I and I 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 +The SRP_get_default_gN() function returns the gN parameters for the RFC 5054 I 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 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 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 is not a valid group size, -or the 8192-bit group parameters if B is NULL. +SRP_get_default_gN() returns NULL if I is not a valid group size, +or the 8192-bit group parameters if I 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); diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt index 229b33b4da..e27adb6da1 100644 --- a/util/missingcrypto.txt +++ b/util/missingcrypto.txt @@ -1117,12 +1117,6 @@ SMIME_crlf_copy(3) SMIME_read_ASN1(3) SMIME_text(3) SMIME_write_ASN1(3) -SRP_Calc_A(3) -SRP_Calc_B(3) -SRP_Calc_client_key(3) -SRP_Calc_server_key(3) -SRP_Calc_u(3) -SRP_Calc_x(3) SRP_Verify_A_mod_N(3) SRP_Verify_B_mod_N(3) SSL_CTX_set0_ctlog_store(3) -- 2.34.1