]>
Commit | Line | Data |
---|---|---|
495a1e5c AS |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SRP_create_verifier, | |
6 | SRP_create_verifier_BN, | |
7 | SRP_check_known_gN_param, | |
8 | SRP_get_default_gN | |
9 | - SRP authentication primitives | |
10 | ||
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/srp.h> | |
14 | ||
15 | char *SRP_create_verifier_BN(const char *user, const char *pass, BIGNUM **salt, | |
16 | BIGNUM **verifier, const BIGNUM *N, const BIGNUM *g); | |
17 | char *SRP_create_verifier(const char *user, const char *pass, char **salt, | |
18 | char **verifier, const char *N, const char *g); | |
19 | ||
20 | char *SRP_check_known_gN_param(const BIGNUM *g, const BIGNUM *N); | |
21 | SRP_gN *SRP_get_default_gN(const char *id); | |
22 | ||
23 | =head1 DESCRIPTION | |
24 | ||
25 | The SRP_create_verifier_BN() function creates an SRP password verifier from | |
26 | the supplied parameters as defined in section 2.4 of RFC 5054. | |
27 | On successful exit B<*verifier> will point to a newly allocated BIGNUM containing | |
28 | the verifier and (if a salt was not provided) B<*salt> will be populated with a | |
29 | newly allocated BIGNUM containing a random salt. If B<*salt> is not NULL then | |
30 | the provided salt is used instead. | |
31 | The caller is responsible for freeing the allocated B<*salt> and B<*verifier> | |
32 | BIGNUMS (use L<BN_free(3)>). | |
33 | ||
34 | The SRP_create_verifier() function is similar to SRP_create_verifier_BN() but | |
35 | all numeric parameters are in a non-standard base64 encoding originally designed | |
36 | for compatibility with libsrp. This is mainly present for historical compatibility | |
37 | and its use is discouraged. | |
38 | It is possible to pass NULL as B<N> and an SRP group id as B<g> instead to | |
39 | load the appropriate gN values (see SRP_get_default_gN()). | |
40 | If both B<N> and B<g> are NULL the 8192-bit SRP group parameters are used. | |
41 | The caller is responsible for freeing the allocated *salt and *verifier char* | |
42 | (use L<OPENSSL_free(3)>). | |
43 | ||
44 | The SRP_check_known_gN_param() function checks that B<g> and B<N> are valid | |
45 | SRP group parameters from RFC 5054 appendix A. | |
46 | ||
47 | The SRP_get_default_gN() function returns the gN parameters for the RFC 5054 B<id> | |
48 | SRP group size. | |
49 | The known ids are "1024", "1536", "2048", "3072", "4096", "6144" and "8192". | |
50 | ||
51 | =head1 RETURN VALUES | |
52 | ||
53 | SRP_create_verifier_BN() returns 1 on success and 0 on failure. | |
54 | ||
55 | SRP_create_verifier() returns NULL on failure and a non-NULL value on success: | |
56 | "*" if B<N> is not NULL, the selected group id otherwise. This value should | |
57 | not be freed. | |
58 | ||
59 | SRP_check_known_gN_param() returns the text representation of the group id | |
60 | (ie. the prime bit size) or NULL if the arguments are not valid SRP group parameters. | |
61 | This value should not be freed. | |
62 | ||
63 | SRP_get_default_gN() returns NULL if B<id> is not a valid group size, | |
64 | or the 8192-bit group parameters if B<id> is NULL. | |
65 | ||
66 | =head1 EXAMPLES | |
67 | ||
68 | Generate and store a 8192 bit password verifier (error handling | |
69 | omitted for clarity): | |
70 | ||
71 | #include <openssl/bn.h> | |
72 | #include <openssl/srp.h> | |
73 | ||
74 | const char *username = "username"; | |
75 | const char *password = "password"; | |
76 | ||
77 | SRP_VBASE *srpData = SRP_VBASE_new(NULL); | |
78 | ||
79 | SRP_user_pwd *pwd = (SRP_user_pwd*) OPENSSL_malloc(sizeof(SRP_user_pwd)); | |
80 | SRP_gN *gN = SRP_get_default_gN("8192"); | |
81 | ||
82 | BIGNUM *salt = NULL, *verifier = NULL; | |
83 | SRP_create_verifier_BN(username, password, &salt, &verifier, gN->N, gN->g); | |
84 | ||
85 | // TODO: replace with SRP_user_pwd_new() | |
86 | pwd->id = OPENSSL_strdup(username); | |
87 | pwd->g = gN->g; | |
88 | pwd->N = gN->N; | |
89 | pwd->s = salt; | |
90 | pwd->v = verifier; | |
91 | pwd->info = NULL; | |
92 | ||
51f03f12 | 93 | SRP_VBASE_add0_user(srpData, pwd); |
495a1e5c AS |
94 | |
95 | =head1 SEE ALSO | |
96 | ||
97 | L<srp(1)>, | |
98 | L<BN_new(3)>, | |
99 | L<OPENSSL_malloc(3)>, | |
100 | L<SRP_VBASE_new(3)> | |
101 | ||
102 | =head1 HISTORY | |
103 | ||
104 | These functions were first added to OpenSSL 1.0.1. | |
105 | ||
106 | =head1 COPYRIGHT | |
107 | ||
108 | Copyright 2018 The OpenSSL Project Authors. All Rights Reserved. | |
109 | ||
110 | Licensed under the OpenSSL license (the "License"). You may not use | |
111 | this file except in compliance with the License. You can obtain a copy | |
112 | in the file LICENSE in the source distribution or at | |
113 | L<https://www.openssl.org/source/license.html>. | |
114 | ||
115 | =cut |