51f03f1227
Signed-off-by: Antoine Salon <asalon@vmware.com> Reviewed-by: Paul Dale <paul.dale@oracle.com> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/7522)
115 lines
3.7 KiB
Text
115 lines
3.7 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
SRP_create_verifier,
|
|
SRP_create_verifier_BN,
|
|
SRP_check_known_gN_param,
|
|
SRP_get_default_gN
|
|
- SRP authentication primitives
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/srp.h>
|
|
|
|
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(const char *user, const char *pass, char **salt,
|
|
char **verifier, const char *N, const char *g);
|
|
|
|
char *SRP_check_known_gN_param(const BIGNUM *g, const BIGNUM *N);
|
|
SRP_gN *SRP_get_default_gN(const char *id);
|
|
|
|
=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 provided salt is used instead.
|
|
The caller is responsible for freeing the allocated B<*salt> and B<*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
|
|
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 *salt and *verifier char*
|
|
(use L<OPENSSL_free(3)>).
|
|
|
|
The SRP_check_known_gN_param() function checks that B<g> and B<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>
|
|
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() 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
|
|
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.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Generate and store a 8192 bit password verifier (error handling
|
|
omitted for clarity):
|
|
|
|
#include <openssl/bn.h>
|
|
#include <openssl/srp.h>
|
|
|
|
const char *username = "username";
|
|
const char *password = "password";
|
|
|
|
SRP_VBASE *srpData = SRP_VBASE_new(NULL);
|
|
|
|
SRP_user_pwd *pwd = (SRP_user_pwd*) OPENSSL_malloc(sizeof(SRP_user_pwd));
|
|
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);
|
|
|
|
// TODO: replace with SRP_user_pwd_new()
|
|
pwd->id = OPENSSL_strdup(username);
|
|
pwd->g = gN->g;
|
|
pwd->N = gN->N;
|
|
pwd->s = salt;
|
|
pwd->v = verifier;
|
|
pwd->info = NULL;
|
|
|
|
SRP_VBASE_add0_user(srpData, pwd);
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<srp(1)>,
|
|
L<BN_new(3)>,
|
|
L<OPENSSL_malloc(3)>,
|
|
L<SRP_VBASE_new(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
These functions were first added to OpenSSL 1.0.1.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2018 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
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|