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