]>
Commit | Line | Data |
---|---|---|
495a1e5c AS |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
4c106e20 | 5 | SRP_create_verifier_ex, |
495a1e5c | 6 | SRP_create_verifier, |
4c106e20 | 7 | SRP_create_verifier_BN_ex, |
495a1e5c AS |
8 | SRP_create_verifier_BN, |
9 | SRP_check_known_gN_param, | |
10 | SRP_get_default_gN | |
11 | - SRP authentication primitives | |
12 | ||
13 | =head1 SYNOPSIS | |
14 | ||
15 | #include <openssl/srp.h> | |
16 | ||
3dbf8243 MC |
17 | The following functions have been deprecated since OpenSSL 3.0, and can be |
18 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, | |
19 | see L<openssl_user_macros(7)>: | |
13888e79 | 20 | |
4c106e20 MC |
21 | int SRP_create_verifier_BN_ex(const char *user, const char *pass, BIGNUM **salt, |
22 | BIGNUM **verifier, const BIGNUM *N, | |
b4250010 | 23 | const BIGNUM *g, OSSL_LIB_CTX *libctx, |
4c106e20 | 24 | const char *propq); |
495a1e5c AS |
25 | char *SRP_create_verifier_BN(const char *user, const char *pass, BIGNUM **salt, |
26 | BIGNUM **verifier, const BIGNUM *N, const BIGNUM *g); | |
4c106e20 MC |
27 | char *SRP_create_verifier_ex(const char *user, const char *pass, char **salt, |
28 | char **verifier, const char *N, const char *g, | |
b4250010 | 29 | OSSL_LIB_CTX *libctx, const char *propq); |
495a1e5c AS |
30 | char *SRP_create_verifier(const char *user, const char *pass, char **salt, |
31 | char **verifier, const char *N, const char *g); | |
32 | ||
33 | char *SRP_check_known_gN_param(const BIGNUM *g, const BIGNUM *N); | |
34 | SRP_gN *SRP_get_default_gN(const char *id); | |
35 | ||
36 | =head1 DESCRIPTION | |
37 | ||
13888e79 MC |
38 | All of the functions described on this page are deprecated. There are no |
39 | available replacement functions at this time. | |
40 | ||
4c106e20 MC |
41 | The SRP_create_verifier_BN_ex() function creates an SRP password verifier from |
42 | the supplied parameters as defined in section 2.4 of RFC 5054 using the library | |
43 | context I<libctx> and property query string I<propq>. Any cryptographic | |
44 | algorithms that need to be fetched will use the I<libctx> and I<propq>. See | |
906bced1 | 45 | L<crypto(7)/ALGORITHM FETCHING>. |
4c106e20 MC |
46 | |
47 | SRP_create_verifier_BN() is the same as SRP_create_verifier_BN_ex() except the | |
48 | default library context and property query string is used. | |
49 | ||
50 | On successful exit I<*verifier> will point to a newly allocated BIGNUM containing | |
51 | the verifier and (if a salt was not provided) I<*salt> will be populated with a | |
52 | newly allocated BIGNUM containing a random salt. If I<*salt> is not NULL then | |
495a1e5c | 53 | the provided salt is used instead. |
4c106e20 | 54 | The caller is responsible for freeing the allocated I<*salt> and I<*verifier> |
495a1e5c AS |
55 | BIGNUMS (use L<BN_free(3)>). |
56 | ||
57 | The SRP_create_verifier() function is similar to SRP_create_verifier_BN() but | |
58 | all numeric parameters are in a non-standard base64 encoding originally designed | |
59 | for compatibility with libsrp. This is mainly present for historical compatibility | |
60 | and its use is discouraged. | |
4c106e20 | 61 | It is possible to pass NULL as I<N> and an SRP group id as I<g> instead to |
495a1e5c | 62 | load the appropriate gN values (see SRP_get_default_gN()). |
4c106e20 MC |
63 | If both I<N> and I<g> are NULL the 8192-bit SRP group parameters are used. |
64 | The caller is responsible for freeing the allocated I<*salt> and I<*verifier> | |
495a1e5c AS |
65 | (use L<OPENSSL_free(3)>). |
66 | ||
4c106e20 | 67 | The SRP_check_known_gN_param() function checks that I<g> and I<N> are valid |
495a1e5c AS |
68 | SRP group parameters from RFC 5054 appendix A. |
69 | ||
4c106e20 | 70 | The SRP_get_default_gN() function returns the gN parameters for the RFC 5054 I<id> |
495a1e5c AS |
71 | SRP group size. |
72 | The known ids are "1024", "1536", "2048", "3072", "4096", "6144" and "8192". | |
73 | ||
74 | =head1 RETURN VALUES | |
75 | ||
4c106e20 MC |
76 | SRP_create_verifier_BN_ex() and SRP_create_verifier_BN() return 1 on success and |
77 | 0 on failure. | |
495a1e5c | 78 | |
4c106e20 MC |
79 | SRP_create_verifier_ex() and SRP_create_verifier() return NULL on failure and a |
80 | non-NULL value on success: | |
81 | "*" if I<N> is not NULL, the selected group id otherwise. This value should | |
495a1e5c AS |
82 | not be freed. |
83 | ||
84 | SRP_check_known_gN_param() returns the text representation of the group id | |
8c1cbc72 | 85 | (i.e. the prime bit size) or NULL if the arguments are not valid SRP group parameters. |
495a1e5c AS |
86 | This value should not be freed. |
87 | ||
4c106e20 MC |
88 | SRP_get_default_gN() returns NULL if I<id> is not a valid group size, |
89 | or the 8192-bit group parameters if I<id> is NULL. | |
495a1e5c AS |
90 | |
91 | =head1 EXAMPLES | |
92 | ||
93 | Generate and store a 8192 bit password verifier (error handling | |
94 | omitted for clarity): | |
95 | ||
96 | #include <openssl/bn.h> | |
97 | #include <openssl/srp.h> | |
98 | ||
99 | const char *username = "username"; | |
100 | const char *password = "password"; | |
101 | ||
102 | SRP_VBASE *srpData = SRP_VBASE_new(NULL); | |
103 | ||
495a1e5c AS |
104 | SRP_gN *gN = SRP_get_default_gN("8192"); |
105 | ||
106 | BIGNUM *salt = NULL, *verifier = NULL; | |
4c106e20 MC |
107 | SRP_create_verifier_BN_ex(username, password, &salt, &verifier, gN->N, gN->g, |
108 | NULL, NULL); | |
495a1e5c | 109 | |
ebfd055b AS |
110 | SRP_user_pwd *pwd = SRP_user_pwd_new(); |
111 | SRP_user_pwd_set1_ids(pwd, username, NULL); | |
112 | SRP_user_pwd_set0_sv(pwd, salt, verifier); | |
113 | SRP_user_pwd_set_gN(pwd, gN->g, gN->N); | |
495a1e5c | 114 | |
51f03f12 | 115 | SRP_VBASE_add0_user(srpData, pwd); |
495a1e5c AS |
116 | |
117 | =head1 SEE ALSO | |
118 | ||
1903a9b7 | 119 | L<openssl-srp(1)>, |
ebfd055b AS |
120 | L<SRP_VBASE_new(3)>, |
121 | L<SRP_user_pwd_new(3)> | |
495a1e5c AS |
122 | |
123 | =head1 HISTORY | |
124 | ||
13888e79 MC |
125 | SRP_create_verifier_BN_ex() and SRP_create_verifier_ex() were introduced in |
126 | OpenSSL 3.0. All other functions were added in OpenSSL 1.0.1. | |
127 | ||
128 | All of these functions were deprecated in OpenSSL 3.0. | |
495a1e5c AS |
129 | |
130 | =head1 COPYRIGHT | |
131 | ||
a28d06f3 | 132 | Copyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved. |
495a1e5c | 133 | |
4746f25a | 134 | Licensed under the Apache License 2.0 (the "License"). You may not use |
495a1e5c AS |
135 | this file except in compliance with the License. You can obtain a copy |
136 | in the file LICENSE in the source distribution or at | |
137 | L<https://www.openssl.org/source/license.html>. | |
138 | ||
139 | =cut |