]>
Commit | Line | Data |
---|---|---|
495a1e5c AS |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_srp_username, | |
6 | SSL_CTX_set_srp_password, | |
7 | SSL_CTX_set_srp_strength, | |
8 | SSL_CTX_set_srp_cb_arg, | |
9 | SSL_CTX_set_srp_username_callback, | |
10 | SSL_CTX_set_srp_client_pwd_callback, | |
11 | SSL_CTX_set_srp_verify_param_callback, | |
12 | SSL_set_srp_server_param, | |
13 | SSL_set_srp_server_param_pw, | |
14 | SSL_get_srp_g, | |
15 | SSL_get_srp_N, | |
16 | SSL_get_srp_username, | |
17 | SSL_get_srp_userinfo | |
18 | - SRP control operations | |
19 | ||
20 | =head1 SYNOPSIS | |
21 | ||
22 | #include <openssl/ssl.h> | |
23 | ||
13888e79 MC |
24 | Deprecated since OpenSSL 3.0, can be hidden entirely by defining |
25 | B<OPENSSL_API_COMPAT> with a suitable version value, see | |
26 | L<openssl_user_macros(7)>: | |
27 | ||
495a1e5c AS |
28 | int SSL_CTX_set_srp_username(SSL_CTX *ctx, char *name); |
29 | int SSL_CTX_set_srp_password(SSL_CTX *ctx, char *password); | |
30 | int SSL_CTX_set_srp_strength(SSL_CTX *ctx, int strength); | |
31 | int SSL_CTX_set_srp_cb_arg(SSL_CTX *ctx, void *arg); | |
32 | int SSL_CTX_set_srp_username_callback(SSL_CTX *ctx, | |
33 | int (*cb) (SSL *s, int *ad, void *arg)); | |
34 | int SSL_CTX_set_srp_client_pwd_callback(SSL_CTX *ctx, | |
35 | char *(*cb) (SSL *s, void *arg)); | |
36 | int SSL_CTX_set_srp_verify_param_callback(SSL_CTX *ctx, | |
37 | int (*cb) (SSL *s, void *arg)); | |
38 | ||
39 | int SSL_set_srp_server_param(SSL *s, const BIGNUM *N, const BIGNUM *g, | |
40 | BIGNUM *sa, BIGNUM *v, char *info); | |
41 | int SSL_set_srp_server_param_pw(SSL *s, const char *user, const char *pass, | |
42 | const char *grp); | |
43 | ||
44 | BIGNUM *SSL_get_srp_g(SSL *s); | |
45 | BIGNUM *SSL_get_srp_N(SSL *s); | |
46 | ||
47 | char *SSL_get_srp_username(SSL *s); | |
48 | char *SSL_get_srp_userinfo(SSL *s); | |
49 | ||
50 | =head1 DESCRIPTION | |
51 | ||
13888e79 MC |
52 | All of the functions described on this page are deprecated. There are no |
53 | available replacement functions at this time. | |
54 | ||
495a1e5c | 55 | These functions provide access to SRP (Secure Remote Password) parameters, |
490c8711 | 56 | an alternate authentication mechanism for TLS. SRP allows the use of usernames |
495a1e5c AS |
57 | and passwords over unencrypted channels without revealing the password to an |
58 | eavesdropper. SRP also supplies a shared secret at the end of the authentication | |
59 | sequence that can be used to generate encryption keys. | |
60 | ||
61 | The SRP protocol, version 3 is specified in RFC 2945. SRP version 6 is described | |
62 | in RFC 5054 with applications to TLS authentication. | |
63 | ||
64 | The SSL_CTX_set_srp_username() function sets the SRP username for B<ctx>. This | |
65 | should be called on the client prior to creating a connection to the server. | |
66 | The length of B<name> must be shorter or equal to 255 characters. | |
67 | ||
68 | The SSL_CTX_set_srp_password() function sets the SRP password for B<ctx>. This | |
69 | may be called on the client prior to creating a connection to the server. | |
70 | This overrides the effect of SSL_CTX_set_srp_client_pwd_callback(). | |
71 | ||
72 | The SSL_CTX_set_srp_strength() function sets the SRP strength for B<ctx>. This | |
73 | is the minimal length of the SRP prime in bits. If not specified 1024 is used. | |
74 | If not satisfied by the server key exchange the connection will be rejected. | |
75 | ||
76 | The SSL_CTX_set_srp_cb_arg() function sets an extra parameter that will | |
77 | be passed to all following callbacks as B<arg>. | |
78 | ||
79 | The SSL_CTX_set_srp_username_callback() function sets the server side callback | |
80 | that is invoked when an SRP username is found in a ClientHello. | |
81 | The callback parameters are the SSL connection B<s>, a writable error flag B<ad> | |
82 | and the extra argument B<arg> set by SSL_CTX_set_srp_cb_arg(). | |
83 | This callback should setup the server for the key exchange by calling | |
84 | SSL_set_srp_server_param() with the appropriate parameters for the received | |
85 | username. The username can be obtained by calling SSL_get_srp_username(). | |
1903a9b7 | 86 | See L<SRP_VBASE_init(3)> to parse the verifier file created by L<openssl-srp(1)> or |
495a1e5c AS |
87 | L<SRP_create_verifier(3)> to generate it. |
88 | The callback should return B<SSL_ERROR_NONE> to proceed with the server key exchange, | |
89 | B<SSL3_AL_FATAL> for a fatal error or any value < 0 for a retryable error. | |
90 | In the event of a B<SSL3_AL_FATAL> the alert flag given by B<*al> will be sent | |
79c44b4e | 91 | back. By default this will be B<SSL_AD_UNKNOWN_PSK_IDENTITY>. |
495a1e5c AS |
92 | |
93 | The SSL_CTX_set_srp_client_pwd_callback() function sets the client password | |
94 | callback on the client. | |
95 | The callback parameters are the SSL connection B<s> and the extra argument B<arg> | |
96 | set by SSL_CTX_set_srp_cb_arg(). | |
97 | The callback will be called as part of the generation of the client secrets. | |
98 | It should return the client password in text form or NULL to abort the connection. | |
99 | The resulting memory will be freed by the library as part of the callback resolution. | |
100 | This overrides the effect of SSL_CTX_set_srp_password(). | |
101 | ||
102 | The SSL_CTX_set_srp_verify_param_callback() sets the SRP gN parameter verification | |
103 | callback on the client. This allows the client to perform custom verification when | |
104 | receiving the server SRP proposed parameters. | |
105 | The callback parameters are the SSL connection B<s> and the extra argument B<arg> | |
106 | set by SSL_CTX_set_srp_cb_arg(). | |
107 | The callback should return a positive value to accept the server parameters. | |
108 | Returning 0 or a negative value will abort the connection. The server parameters | |
109 | can be obtained by calling SSL_get_srp_N() and SSL_get_srp_g(). | |
110 | Sanity checks are already performed by the library after the handshake | |
111 | (B % N non zero, check against the strength parameter) and are not necessary. | |
112 | If no callback is set the g and N parameters will be checked against | |
113 | known RFC 5054 values. | |
114 | ||
115 | The SSL_set_srp_server_param() function sets all SRP parameters for | |
116 | the connection B<s>. B<N> and B<g> are the SRP group parameters, B<sa> is the | |
117 | user salt, B<v> the password verifier and B<info> is the optional user info. | |
118 | ||
119 | The SSL_set_srp_server_param_pw() function sets all SRP parameters for the | |
120 | connection B<s> by generating a random salt and a password verifier. | |
c2969ff6 | 121 | B<user> is the username, B<pass> the password and B<grp> the SRP group parameters |
495a1e5c AS |
122 | identifier for L<SRP_get_default_gN(3)>. |
123 | ||
124 | The SSL_get_srp_g() function returns the SRP group generator for B<s>, or from | |
125 | the underlying SSL_CTX if it is NULL. | |
126 | ||
127 | The SSL_get_srp_N() function returns the SRP prime for B<s>, or from | |
128 | the underlying SSL_CTX if it is NULL. | |
129 | ||
130 | The SSL_get_srp_username() function returns the SRP username for B<s>, or from | |
131 | the underlying SSL_CTX if it is NULL. | |
132 | ||
133 | The SSL_get_srp_userinfo() function returns the SRP user info for B<s>, or from | |
134 | the underlying SSL_CTX if it is NULL. | |
135 | ||
136 | =head1 RETURN VALUES | |
137 | ||
138 | All SSL_CTX_set_* functions return 1 on success and 0 on failure. | |
139 | ||
140 | SSL_set_srp_server_param() returns 1 on success and -1 on failure. | |
141 | ||
142 | The SSL_get_SRP_* functions return a pointer to the requested data, the memory | |
143 | is owned by the library and should not be freed by the caller. | |
144 | ||
145 | =head1 EXAMPLES | |
146 | ||
147 | Setup SRP parameters on the client: | |
148 | ||
149 | #include <openssl/ssl.h> | |
150 | ||
151 | const char *username = "username"; | |
152 | const char *password = "password"; | |
153 | ||
154 | SSL_CTX *ctx = SSL_CTX_new(TLS_client_method()); | |
155 | if (!ctx) | |
156 | /* Error */ | |
157 | if (!SSL_CTX_set_srp_username(ctx, username)) | |
158 | /* Error */ | |
159 | if (!SSL_CTX_set_srp_password(ctx, password)) | |
160 | /* Error */ | |
161 | ||
162 | Setup SRP server with verifier file: | |
163 | ||
164 | #include <openssl/srp.h> | |
165 | #include <openssl/ssl.h> | |
166 | ||
167 | const char *srpvfile = "password.srpv"; | |
168 | ||
169 | int srpServerCallback(SSL *s, int *ad, void *arg) | |
170 | { | |
171 | SRP_VBASE *srpData = (SRP_VBASE*) arg; | |
172 | char *username = SSL_get_srp_username(s); | |
173 | ||
174 | SRP_user_pwd *user_pwd = SRP_VBASE_get1_by_user(srpData, username); | |
175 | if (!user_pwd) | |
176 | /* Error */ | |
177 | return SSL3_AL_FATAL; | |
178 | ||
179 | if (SSL_set_srp_server_param(s, user_pwd->N, user_pwd->g, | |
180 | user_pwd->s, user_pwd->v, user_pwd->info) < 0) | |
181 | /* Error */ | |
182 | ||
183 | SRP_user_pwd_free(user_pwd); | |
184 | return SSL_ERROR_NONE; | |
185 | } | |
186 | ||
187 | SSL_CTX *ctx = SSL_CTX_new(TLS_server_method()); | |
188 | if (!ctx) | |
189 | /* Error */ | |
190 | ||
191 | /* | |
192 | * seedKey should contain a NUL terminated sequence | |
193 | * of random non NUL bytes | |
194 | */ | |
195 | const char *seedKey; | |
196 | ||
197 | SRP_VBASE *srpData = SRP_VBASE_new(seedKey); | |
198 | if (SRP_VBASE_init(srpData, (char*) srpvfile) != SRP_NO_ERROR) | |
199 | /* Error */ | |
200 | ||
201 | SSL_CTX_set_srp_cb_arg(ctx, srpData); | |
202 | SSL_CTX_set_srp_username_callback(ctx, srpServerCallback); | |
203 | ||
204 | =head1 SEE ALSO | |
205 | ||
98ca37e4 | 206 | L<ssl(7)>, |
1903a9b7 | 207 | L<openssl-srp(1)>, |
495a1e5c AS |
208 | L<SRP_VBASE_new(3)>, |
209 | L<SRP_create_verifier(3)> | |
210 | ||
211 | =head1 HISTORY | |
212 | ||
13888e79 | 213 | These functions were added in OpenSSL 1.0.1 and deprecated in OpenSSL 3.0. |
495a1e5c AS |
214 | |
215 | =head1 COPYRIGHT | |
216 | ||
0f84cbc3 | 217 | Copyright 2018-2020 The OpenSSL Project Authors. All Rights Reserved. |
495a1e5c | 218 | |
4746f25a | 219 | Licensed under the Apache License 2.0 (the "License"). You may not use |
495a1e5c AS |
220 | this file except in compliance with the License. You can obtain a copy |
221 | in the file LICENSE in the source distribution or at | |
222 | L<https://www.openssl.org/source/license.html>. | |
223 | ||
224 | =cut |