1 | /* GIO - GLib Input, Output and Streaming Library |
2 | * |
3 | * Copyright © 2010 Red Hat, Inc |
4 | * |
5 | * This library is free software; you can redistribute it and/or |
6 | * modify it under the terms of the GNU Lesser General Public |
7 | * License as published by the Free Software Foundation; either |
8 | * version 2.1 of the License, or (at your option) any later version. |
9 | * |
10 | * This library is distributed in the hope that it will be useful, |
11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | * Lesser General Public License for more details. |
14 | * |
15 | * You should have received a copy of the GNU Lesser General |
16 | * Public License along with this library; if not, see <http://www.gnu.org/licenses/>. |
17 | */ |
18 | |
19 | #include "config.h" |
20 | #include "glib.h" |
21 | |
22 | #include "gtlsclientconnection.h" |
23 | #include "ginitable.h" |
24 | #include "gioenumtypes.h" |
25 | #include "gsocket.h" |
26 | #include "gsocketconnectable.h" |
27 | #include "gtlsbackend.h" |
28 | #include "gtlscertificate.h" |
29 | #include "glibintl.h" |
30 | |
31 | /** |
32 | * SECTION:gtlsclientconnection |
33 | * @short_description: TLS client-side connection |
34 | * @include: gio/gio.h |
35 | * |
36 | * #GTlsClientConnection is the client-side subclass of |
37 | * #GTlsConnection, representing a client-side TLS connection. |
38 | */ |
39 | |
40 | /** |
41 | * GTlsClientConnection: |
42 | * |
43 | * Abstract base class for the backend-specific client connection |
44 | * type. |
45 | * |
46 | * Since: 2.28 |
47 | */ |
48 | |
49 | G_DEFINE_INTERFACE (GTlsClientConnection, g_tls_client_connection, G_TYPE_TLS_CONNECTION) |
50 | |
51 | static void |
52 | g_tls_client_connection_default_init (GTlsClientConnectionInterface *iface) |
53 | { |
54 | /** |
55 | * GTlsClientConnection:validation-flags: |
56 | * |
57 | * What steps to perform when validating a certificate received from |
58 | * a server. Server certificates that fail to validate in any of the |
59 | * ways indicated here will be rejected unless the application |
60 | * overrides the default via #GTlsConnection::accept-certificate. |
61 | * |
62 | * Since: 2.28 |
63 | */ |
64 | g_object_interface_install_property (g_iface: iface, |
65 | pspec: g_param_spec_flags (name: "validation-flags" , |
66 | P_("Validation flags" ), |
67 | P_("What certificate validation to perform" ), |
68 | flags_type: G_TYPE_TLS_CERTIFICATE_FLAGS, |
69 | default_value: G_TLS_CERTIFICATE_VALIDATE_ALL, |
70 | flags: G_PARAM_READWRITE | |
71 | G_PARAM_CONSTRUCT | |
72 | G_PARAM_STATIC_STRINGS)); |
73 | |
74 | /** |
75 | * GTlsClientConnection:server-identity: |
76 | * |
77 | * A #GSocketConnectable describing the identity of the server that |
78 | * is expected on the other end of the connection. |
79 | * |
80 | * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in |
81 | * #GTlsClientConnection:validation-flags, this object will be used |
82 | * to determine the expected identify of the remote end of the |
83 | * connection; if #GTlsClientConnection:server-identity is not set, |
84 | * or does not match the identity presented by the server, then the |
85 | * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail. |
86 | * |
87 | * In addition to its use in verifying the server certificate, |
88 | * this is also used to give a hint to the server about what |
89 | * certificate we expect, which is useful for servers that serve |
90 | * virtual hosts. |
91 | * |
92 | * Since: 2.28 |
93 | */ |
94 | g_object_interface_install_property (g_iface: iface, |
95 | pspec: g_param_spec_object (name: "server-identity" , |
96 | P_("Server identity" ), |
97 | P_("GSocketConnectable identifying the server" ), |
98 | G_TYPE_SOCKET_CONNECTABLE, |
99 | flags: G_PARAM_READWRITE | |
100 | G_PARAM_CONSTRUCT | |
101 | G_PARAM_STATIC_STRINGS)); |
102 | |
103 | /** |
104 | * GTlsClientConnection:use-ssl3: |
105 | * |
106 | * SSL 3.0 is no longer supported. See |
107 | * g_tls_client_connection_set_use_ssl3() for details. |
108 | * |
109 | * Since: 2.28 |
110 | * |
111 | * Deprecated: 2.56: SSL 3.0 is insecure. |
112 | */ |
113 | g_object_interface_install_property (g_iface: iface, |
114 | pspec: g_param_spec_boolean (name: "use-ssl3" , |
115 | P_("Use fallback" ), |
116 | P_("Use fallback version of SSL/TLS rather than most recent version" ), |
117 | FALSE, |
118 | flags: G_PARAM_READWRITE | |
119 | G_PARAM_CONSTRUCT | |
120 | G_PARAM_STATIC_STRINGS | |
121 | G_PARAM_DEPRECATED)); |
122 | |
123 | /** |
124 | * GTlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray) |
125 | * |
126 | * A list of the distinguished names of the Certificate Authorities |
127 | * that the server will accept client certificates signed by. If the |
128 | * server requests a client certificate during the handshake, then |
129 | * this property will be set after the handshake completes. |
130 | * |
131 | * Each item in the list is a #GByteArray which contains the complete |
132 | * subject DN of the certificate authority. |
133 | * |
134 | * Since: 2.28 |
135 | */ |
136 | g_object_interface_install_property (g_iface: iface, |
137 | pspec: g_param_spec_pointer (name: "accepted-cas" , |
138 | P_("Accepted CAs" ), |
139 | P_("Distinguished names of the CAs the server accepts certificates from" ), |
140 | flags: G_PARAM_READABLE | |
141 | G_PARAM_STATIC_STRINGS)); |
142 | } |
143 | |
144 | /** |
145 | * g_tls_client_connection_new: |
146 | * @base_io_stream: the #GIOStream to wrap |
147 | * @server_identity: (nullable): the expected identity of the server |
148 | * @error: #GError for error reporting, or %NULL to ignore. |
149 | * |
150 | * Creates a new #GTlsClientConnection wrapping @base_io_stream (which |
151 | * must have pollable input and output streams) which is assumed to |
152 | * communicate with the server identified by @server_identity. |
153 | * |
154 | * See the documentation for #GTlsConnection:base-io-stream for restrictions |
155 | * on when application code can run operations on the @base_io_stream after |
156 | * this function has returned. |
157 | * |
158 | * Returns: (transfer full) (type GTlsClientConnection): the new |
159 | * #GTlsClientConnection, or %NULL on error |
160 | * |
161 | * Since: 2.28 |
162 | */ |
163 | GIOStream * |
164 | g_tls_client_connection_new (GIOStream *base_io_stream, |
165 | GSocketConnectable *server_identity, |
166 | GError **error) |
167 | { |
168 | GObject *conn; |
169 | GTlsBackend *backend; |
170 | |
171 | backend = g_tls_backend_get_default (); |
172 | conn = g_initable_new (object_type: g_tls_backend_get_client_connection_type (backend), |
173 | NULL, error, |
174 | first_property_name: "base-io-stream" , base_io_stream, |
175 | "server-identity" , server_identity, |
176 | NULL); |
177 | return G_IO_STREAM (conn); |
178 | } |
179 | |
180 | /** |
181 | * g_tls_client_connection_get_validation_flags: |
182 | * @conn: the #GTlsClientConnection |
183 | * |
184 | * Gets @conn's validation flags |
185 | * |
186 | * Returns: the validation flags |
187 | * |
188 | * Since: 2.28 |
189 | */ |
190 | GTlsCertificateFlags |
191 | g_tls_client_connection_get_validation_flags (GTlsClientConnection *conn) |
192 | { |
193 | GTlsCertificateFlags flags = 0; |
194 | |
195 | g_return_val_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn), 0); |
196 | |
197 | g_object_get (G_OBJECT (conn), first_property_name: "validation-flags" , &flags, NULL); |
198 | return flags; |
199 | } |
200 | |
201 | /** |
202 | * g_tls_client_connection_set_validation_flags: |
203 | * @conn: the #GTlsClientConnection |
204 | * @flags: the #GTlsCertificateFlags to use |
205 | * |
206 | * Sets @conn's validation flags, to override the default set of |
207 | * checks performed when validating a server certificate. By default, |
208 | * %G_TLS_CERTIFICATE_VALIDATE_ALL is used. |
209 | * |
210 | * Since: 2.28 |
211 | */ |
212 | void |
213 | g_tls_client_connection_set_validation_flags (GTlsClientConnection *conn, |
214 | GTlsCertificateFlags flags) |
215 | { |
216 | g_return_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn)); |
217 | |
218 | g_object_set (G_OBJECT (conn), first_property_name: "validation-flags" , flags, NULL); |
219 | } |
220 | |
221 | /** |
222 | * g_tls_client_connection_get_server_identity: |
223 | * @conn: the #GTlsClientConnection |
224 | * |
225 | * Gets @conn's expected server identity |
226 | * |
227 | * Returns: (nullable) (transfer none): a #GSocketConnectable describing the |
228 | * expected server identity, or %NULL if the expected identity is not |
229 | * known. |
230 | * |
231 | * Since: 2.28 |
232 | */ |
233 | GSocketConnectable * |
234 | g_tls_client_connection_get_server_identity (GTlsClientConnection *conn) |
235 | { |
236 | GSocketConnectable *identity = NULL; |
237 | |
238 | g_return_val_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn), 0); |
239 | |
240 | g_object_get (G_OBJECT (conn), first_property_name: "server-identity" , &identity, NULL); |
241 | if (identity) |
242 | g_object_unref (object: identity); |
243 | return identity; |
244 | } |
245 | |
246 | /** |
247 | * g_tls_client_connection_set_server_identity: |
248 | * @conn: the #GTlsClientConnection |
249 | * @identity: a #GSocketConnectable describing the expected server identity |
250 | * |
251 | * Sets @conn's expected server identity, which is used both to tell |
252 | * servers on virtual hosts which certificate to present, and also |
253 | * to let @conn know what name to look for in the certificate when |
254 | * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. |
255 | * |
256 | * Since: 2.28 |
257 | */ |
258 | void |
259 | g_tls_client_connection_set_server_identity (GTlsClientConnection *conn, |
260 | GSocketConnectable *identity) |
261 | { |
262 | g_return_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn)); |
263 | |
264 | g_object_set (G_OBJECT (conn), first_property_name: "server-identity" , identity, NULL); |
265 | } |
266 | |
267 | /** |
268 | * g_tls_client_connection_get_use_ssl3: |
269 | * @conn: the #GTlsClientConnection |
270 | * |
271 | * SSL 3.0 is no longer supported. See |
272 | * g_tls_client_connection_set_use_ssl3() for details. |
273 | * |
274 | * Returns: %FALSE |
275 | * |
276 | * Since: 2.28 |
277 | * |
278 | * Deprecated: 2.56: SSL 3.0 is insecure. |
279 | */ |
280 | gboolean |
281 | g_tls_client_connection_get_use_ssl3 (GTlsClientConnection *conn) |
282 | { |
283 | gboolean use_ssl3 = FALSE; |
284 | |
285 | g_return_val_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn), 0); |
286 | |
287 | g_object_get (G_OBJECT (conn), first_property_name: "use-ssl3" , &use_ssl3, NULL); |
288 | return FALSE; |
289 | } |
290 | |
291 | /** |
292 | * g_tls_client_connection_set_use_ssl3: |
293 | * @conn: the #GTlsClientConnection |
294 | * @use_ssl3: a #gboolean, ignored |
295 | * |
296 | * Since GLib 2.42.1, SSL 3.0 is no longer supported. |
297 | * |
298 | * From GLib 2.42.1 through GLib 2.62, this function could be used to |
299 | * force use of TLS 1.0, the lowest-supported TLS protocol version at |
300 | * the time. In the past, this was needed to connect to broken TLS |
301 | * servers that exhibited protocol version intolerance. Such servers |
302 | * are no longer common, and using TLS 1.0 is no longer considered |
303 | * acceptable. |
304 | * |
305 | * Since GLib 2.64, this function does nothing. |
306 | * |
307 | * Since: 2.28 |
308 | * |
309 | * Deprecated: 2.56: SSL 3.0 is insecure. |
310 | */ |
311 | void |
312 | g_tls_client_connection_set_use_ssl3 (GTlsClientConnection *conn, |
313 | gboolean use_ssl3) |
314 | { |
315 | g_return_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn)); |
316 | |
317 | g_object_set (G_OBJECT (conn), first_property_name: "use-ssl3" , FALSE, NULL); |
318 | } |
319 | |
320 | /** |
321 | * g_tls_client_connection_get_accepted_cas: |
322 | * @conn: the #GTlsClientConnection |
323 | * |
324 | * Gets the list of distinguished names of the Certificate Authorities |
325 | * that the server will accept certificates from. This will be set |
326 | * during the TLS handshake if the server requests a certificate. |
327 | * Otherwise, it will be %NULL. |
328 | * |
329 | * Each item in the list is a #GByteArray which contains the complete |
330 | * subject DN of the certificate authority. |
331 | * |
332 | * Returns: (element-type GByteArray) (transfer full): the list of |
333 | * CA DNs. You should unref each element with g_byte_array_unref() and then |
334 | * the free the list with g_list_free(). |
335 | * |
336 | * Since: 2.28 |
337 | */ |
338 | GList * |
339 | g_tls_client_connection_get_accepted_cas (GTlsClientConnection *conn) |
340 | { |
341 | GList *accepted_cas = NULL; |
342 | |
343 | g_return_val_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn), NULL); |
344 | |
345 | g_object_get (G_OBJECT (conn), first_property_name: "accepted-cas" , &accepted_cas, NULL); |
346 | return accepted_cas; |
347 | } |
348 | |
349 | /** |
350 | * g_tls_client_connection_copy_session_state: |
351 | * @conn: a #GTlsClientConnection |
352 | * @source: a #GTlsClientConnection |
353 | * |
354 | * Possibly copies session state from one connection to another, for use |
355 | * in TLS session resumption. This is not normally needed, but may be |
356 | * used when the same session needs to be used between different |
357 | * endpoints, as is required by some protocols, such as FTP over TLS. |
358 | * @source should have already completed a handshake and, since TLS 1.3, |
359 | * it should have been used to read data at least once. @conn should not |
360 | * have completed a handshake. |
361 | * |
362 | * It is not possible to know whether a call to this function will |
363 | * actually do anything. Because session resumption is normally used |
364 | * only for performance benefit, the TLS backend might not implement |
365 | * this function. Even if implemented, it may not actually succeed in |
366 | * allowing @conn to resume @source's TLS session, because the server |
367 | * may not have sent a session resumption token to @source, or it may |
368 | * refuse to accept the token from @conn. There is no way to know |
369 | * whether a call to this function is actually successful. |
370 | * |
371 | * Using this function is not required to benefit from session |
372 | * resumption. If the TLS backend supports session resumption, the |
373 | * session will be resumed automatically if it is possible to do so |
374 | * without weakening the privacy guarantees normally provided by TLS, |
375 | * without need to call this function. For example, with TLS 1.3, |
376 | * a session ticket will be automatically copied from any |
377 | * #GTlsClientConnection that has previously received session tickets |
378 | * from the server, provided a ticket is available that has not |
379 | * previously been used for session resumption, since session ticket |
380 | * reuse would be a privacy weakness. Using this function causes the |
381 | * ticket to be copied without regard for privacy considerations. |
382 | * |
383 | * Since: 2.46 |
384 | */ |
385 | void |
386 | g_tls_client_connection_copy_session_state (GTlsClientConnection *conn, |
387 | GTlsClientConnection *source) |
388 | { |
389 | g_return_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn)); |
390 | g_return_if_fail (G_IS_TLS_CLIENT_CONNECTION (source)); |
391 | g_return_if_fail (G_TLS_CLIENT_CONNECTION_GET_INTERFACE (conn)->copy_session_state != NULL); |
392 | |
393 | G_TLS_CLIENT_CONNECTION_GET_INTERFACE (conn)->copy_session_state (conn, |
394 | source); |
395 | } |
396 | |