]>
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. | |
ebfd055b | 41 | The caller is responsible for freeing the allocated B<*salt> and B<*verifier> |
495a1e5c AS |
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 | ||
495a1e5c AS |
79 | SRP_gN *gN = SRP_get_default_gN("8192"); |
80 | ||
81 | BIGNUM *salt = NULL, *verifier = NULL; | |
82 | SRP_create_verifier_BN(username, password, &salt, &verifier, gN->N, gN->g); | |
83 | ||
ebfd055b AS |
84 | SRP_user_pwd *pwd = SRP_user_pwd_new(); |
85 | SRP_user_pwd_set1_ids(pwd, username, NULL); | |
86 | SRP_user_pwd_set0_sv(pwd, salt, verifier); | |
87 | SRP_user_pwd_set_gN(pwd, gN->g, gN->N); | |
495a1e5c | 88 | |
51f03f12 | 89 | SRP_VBASE_add0_user(srpData, pwd); |
495a1e5c AS |
90 | |
91 | =head1 SEE ALSO | |
92 | ||
93 | L<srp(1)>, | |
ebfd055b AS |
94 | L<SRP_VBASE_new(3)>, |
95 | L<SRP_user_pwd_new(3)> | |
495a1e5c AS |
96 | |
97 | =head1 HISTORY | |
98 | ||
99 | These functions were first added to OpenSSL 1.0.1. | |
100 | ||
101 | =head1 COPYRIGHT | |
102 | ||
103 | Copyright 2018 The OpenSSL Project Authors. All Rights Reserved. | |
104 | ||
4746f25a | 105 | Licensed under the Apache License 2.0 (the "License"). You may not use |
495a1e5c AS |
106 | this file except in compliance with the License. You can obtain a copy |
107 | in the file LICENSE in the source distribution or at | |
108 | L<https://www.openssl.org/source/license.html>. | |
109 | ||
110 | =cut |