Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_srp_password.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CTX_SET_SRP_PASSWORD 3SSL"
58 .TH SSL_CTX_SET_SRP_PASSWORD 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_CTX_set_srp_username,
65 SSL_CTX_set_srp_password,
66 SSL_CTX_set_srp_strength,
67 SSL_CTX_set_srp_cb_arg,
68 SSL_CTX_set_srp_username_callback,
69 SSL_CTX_set_srp_client_pwd_callback,
70 SSL_CTX_set_srp_verify_param_callback,
71 SSL_set_srp_server_param,
72 SSL_set_srp_server_param_pw,
73 SSL_get_srp_g,
74 SSL_get_srp_N,
75 SSL_get_srp_username,
76 SSL_get_srp_userinfo
77 \&\- SRP control operations
78 .SH SYNOPSIS
79 .IX Header "SYNOPSIS"
80 .Vb 1
81 \& #include <openssl/ssl.h>
82 .Ve
83 .PP
84 The following functions have been deprecated since OpenSSL 3.0, and can be
85 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
86 see \fBopenssl_user_macros\fR\|(7):
87 .PP
88 .Vb 10
89 \& int SSL_CTX_set_srp_username(SSL_CTX *ctx, char *name);
90 \& int SSL_CTX_set_srp_password(SSL_CTX *ctx, char *password);
91 \& int SSL_CTX_set_srp_strength(SSL_CTX *ctx, int strength);
92 \& int SSL_CTX_set_srp_cb_arg(SSL_CTX *ctx, void *arg);
93 \& int SSL_CTX_set_srp_username_callback(SSL_CTX *ctx,
94 \& int (*cb) (SSL *s, int *ad, void *arg));
95 \& int SSL_CTX_set_srp_client_pwd_callback(SSL_CTX *ctx,
96 \& char *(*cb) (SSL *s, void *arg));
97 \& int SSL_CTX_set_srp_verify_param_callback(SSL_CTX *ctx,
98 \& int (*cb) (SSL *s, void *arg));
99 \&
100 \& int SSL_set_srp_server_param(SSL *s, const BIGNUM *N, const BIGNUM *g,
101 \& BIGNUM *sa, BIGNUM *v, char *info);
102 \& int SSL_set_srp_server_param_pw(SSL *s, const char *user, const char *pass,
103 \& const char *grp);
104 \&
105 \& BIGNUM *SSL_get_srp_g(SSL *s);
106 \& BIGNUM *SSL_get_srp_N(SSL *s);
107 \&
108 \& char *SSL_get_srp_username(SSL *s);
109 \& char *SSL_get_srp_userinfo(SSL *s);
110 .Ve
111 .SH DESCRIPTION
112 .IX Header "DESCRIPTION"
113 All of the functions described on this page are deprecated. There are no
114 available replacement functions at this time.
115 .PP
116 These functions provide access to SRP (Secure Remote Password) parameters,
117 an alternate authentication mechanism for TLS. SRP allows the use of usernames
118 and passwords over unencrypted channels without revealing the password to an
119 eavesdropper. SRP also supplies a shared secret at the end of the authentication
120 sequence that can be used to generate encryption keys.
121 .PP
122 The SRP protocol, version 3 is specified in RFC 2945. SRP version 6 is described
123 in RFC 5054 with applications to TLS authentication.
124 .PP
125 The \fBSSL_CTX_set_srp_username()\fR function sets the SRP username for \fBctx\fR. This
126 should be called on the client prior to creating a connection to the server.
127 The length of \fBname\fR must be shorter or equal to 255 characters.
128 .PP
129 The \fBSSL_CTX_set_srp_password()\fR function sets the SRP password for \fBctx\fR. This
130 may be called on the client prior to creating a connection to the server.
131 This overrides the effect of \fBSSL_CTX_set_srp_client_pwd_callback()\fR.
132 .PP
133 The \fBSSL_CTX_set_srp_strength()\fR function sets the SRP strength for \fBctx\fR. This
134 is the minimal length of the SRP prime in bits. If not specified 1024 is used.
135 If not satisfied by the server key exchange the connection will be rejected.
136 .PP
137 The \fBSSL_CTX_set_srp_cb_arg()\fR function sets an extra parameter that will
138 be passed to all following callbacks as \fBarg\fR.
139 .PP
140 The \fBSSL_CTX_set_srp_username_callback()\fR function sets the server side callback
141 that is invoked when an SRP username is found in a ClientHello.
142 The callback parameters are the SSL connection \fBs\fR, a writable error flag \fBad\fR
143 and the extra argument \fBarg\fR set by \fBSSL_CTX_set_srp_cb_arg()\fR.
144 This callback should setup the server for the key exchange by calling
145 \&\fBSSL_set_srp_server_param()\fR with the appropriate parameters for the received
146 username. The username can be obtained by calling \fBSSL_get_srp_username()\fR.
147 See \fBSRP_VBASE_init\fR\|(3) to parse the verifier file created by \fBopenssl\-srp\fR\|(1) or
148 \&\fBSRP_create_verifier\fR\|(3) to generate it.
149 The callback should return \fBSSL_ERROR_NONE\fR to proceed with the server key exchange,
150 \&\fBSSL3_AL_FATAL\fR for a fatal error or any value < 0 for a retryable error.
151 In the event of a \fBSSL3_AL_FATAL\fR the alert flag given by \fB*al\fR will be sent
152 back. By default this will be \fBSSL_AD_UNKNOWN_PSK_IDENTITY\fR.
153 .PP
154 The \fBSSL_CTX_set_srp_client_pwd_callback()\fR function sets the client password
155 callback on the client.
156 The callback parameters are the SSL connection \fBs\fR and the extra argument \fBarg\fR
157 set by \fBSSL_CTX_set_srp_cb_arg()\fR.
158 The callback will be called as part of the generation of the client secrets.
159 It should return the client password in text form or NULL to abort the connection.
160 The resulting memory will be freed by the library as part of the callback resolution.
161 This overrides the effect of \fBSSL_CTX_set_srp_password()\fR.
162 .PP
163 The \fBSSL_CTX_set_srp_verify_param_callback()\fR sets the SRP gN parameter verification
164 callback on the client. This allows the client to perform custom verification when
165 receiving the server SRP proposed parameters.
166 The callback parameters are the SSL connection \fBs\fR and the extra argument \fBarg\fR
167 set by \fBSSL_CTX_set_srp_cb_arg()\fR.
168 The callback should return a positive value to accept the server parameters.
169 Returning 0 or a negative value will abort the connection. The server parameters
170 can be obtained by calling \fBSSL_get_srp_N()\fR and \fBSSL_get_srp_g()\fR.
171 Sanity checks are already performed by the library after the handshake
172 (B % N non zero, check against the strength parameter) and are not necessary.
173 If no callback is set the g and N parameters will be checked against
174 known RFC 5054 values.
175 .PP
176 The \fBSSL_set_srp_server_param()\fR function sets all SRP parameters for
177 the connection \fBs\fR. \fBN\fR and \fBg\fR are the SRP group parameters, \fBsa\fR is the
178 user salt, \fBv\fR the password verifier and \fBinfo\fR is the optional user info.
179 .PP
180 The \fBSSL_set_srp_server_param_pw()\fR function sets all SRP parameters for the
181 connection \fBs\fR by generating a random salt and a password verifier.
182 \&\fBuser\fR is the username, \fBpass\fR the password and \fBgrp\fR the SRP group parameters
183 identifier for \fBSRP_get_default_gN\fR\|(3).
184 .PP
185 The \fBSSL_get_srp_g()\fR function returns the SRP group generator for \fBs\fR, or from
186 the underlying SSL_CTX if it is NULL.
187 .PP
188 The \fBSSL_get_srp_N()\fR function returns the SRP prime for \fBs\fR, or from
189 the underlying SSL_CTX if it is NULL.
190 .PP
191 The \fBSSL_get_srp_username()\fR function returns the SRP username for \fBs\fR, or from
192 the underlying SSL_CTX if it is NULL.
193 .PP
194 The \fBSSL_get_srp_userinfo()\fR function returns the SRP user info for \fBs\fR, or from
195 the underlying SSL_CTX if it is NULL.
196 .SH "RETURN VALUES"
197 .IX Header "RETURN VALUES"
198 All SSL_CTX_set_* functions return 1 on success and 0 on failure.
199 .PP
200 \&\fBSSL_set_srp_server_param()\fR returns 1 on success and \-1 on failure.
201 .PP
202 The SSL_get_SRP_* functions return a pointer to the requested data, the memory
203 is owned by the library and should not be freed by the caller.
204 .SH EXAMPLES
205 .IX Header "EXAMPLES"
206 Setup SRP parameters on the client:
207 .PP
208 .Vb 1
209 \& #include <openssl/ssl.h>
210 \&
211 \& const char *username = "username";
212 \& const char *password = "password";
213 \&
214 \& SSL_CTX *ctx = SSL_CTX_new(TLS_client_method());
215 \& if (!ctx)
216 \& /* Error */
217 \& if (!SSL_CTX_set_srp_username(ctx, username))
218 \& /* Error */
219 \& if (!SSL_CTX_set_srp_password(ctx, password))
220 \& /* Error */
221 .Ve
222 .PP
223 Setup SRP server with verifier file:
224 .PP
225 .Vb 2
226 \& #include <openssl/srp.h>
227 \& #include <openssl/ssl.h>
228 \&
229 \& const char *srpvfile = "password.srpv";
230 \&
231 \& int srpServerCallback(SSL *s, int *ad, void *arg)
232 \& {
233 \& SRP_VBASE *srpData = (SRP_VBASE*) arg;
234 \& char *username = SSL_get_srp_username(s);
235 \&
236 \& SRP_user_pwd *user_pwd = SRP_VBASE_get1_by_user(srpData, username);
237 \& if (!user_pwd)
238 \& /* Error */
239 \& return SSL3_AL_FATAL;
240 \&
241 \& if (SSL_set_srp_server_param(s, user_pwd\->N, user_pwd\->g,
242 \& user_pwd\->s, user_pwd\->v, user_pwd\->info) < 0)
243 \& /* Error */
244 \&
245 \& SRP_user_pwd_free(user_pwd);
246 \& return SSL_ERROR_NONE;
247 \& }
248 \&
249 \& SSL_CTX *ctx = SSL_CTX_new(TLS_server_method());
250 \& if (!ctx)
251 \& /* Error */
252 \&
253 \& /*
254 \& * seedKey should contain a NUL terminated sequence
255 \& * of random non NUL bytes
256 \& */
257 \& const char *seedKey;
258 \&
259 \& SRP_VBASE *srpData = SRP_VBASE_new(seedKey);
260 \& if (SRP_VBASE_init(srpData, (char*) srpvfile) != SRP_NO_ERROR)
261 \& /* Error */
262 \&
263 \& SSL_CTX_set_srp_cb_arg(ctx, srpData);
264 \& SSL_CTX_set_srp_username_callback(ctx, srpServerCallback);
265 .Ve
266 .SH "SEE ALSO"
267 .IX Header "SEE ALSO"
268 \&\fBssl\fR\|(7),
269 \&\fBopenssl\-srp\fR\|(1),
270 \&\fBSRP_VBASE_new\fR\|(3),
271 \&\fBSRP_create_verifier\fR\|(3)
272 .SH HISTORY
273 .IX Header "HISTORY"
274 These functions were added in OpenSSL 1.0.1 and deprecated in OpenSSL 3.0.
275 .SH COPYRIGHT
276 .IX Header "COPYRIGHT"
277 Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved.
278 .PP
279 Licensed under the Apache License 2.0 (the "License"). You may not use
280 this file except in compliance with the License. You can obtain a copy
281 in the file LICENSE in the source distribution or at
282 <https://www.openssl.org/source/license.html>.