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