docs: use "Returns:" consistently
[platform/upstream/glib.git] / gio / gtlsdatabase.c
1 /* GIO - GLib Input, Output and Streaming Library
2  *
3  * Copyright (C) 2010 Collabora, Ltd.
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 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  * Author: Stef Walter <stefw@collabora.co.uk>
19  */
20
21 #include "config.h"
22
23 #include "gtlsdatabase.h"
24
25 #include "gasyncresult.h"
26 #include "gcancellable.h"
27 #include "glibintl.h"
28 #include "gsocketconnectable.h"
29 #include "gtask.h"
30 #include "gtlscertificate.h"
31 #include "gtlsinteraction.h"
32
33 /**
34  * SECTION:gtlsdatabase
35  * @short_description: TLS database type
36  * @include: gio/gio.h
37  *
38  * #GTlsDatabase is used to lookup certificates and other information
39  * from a certificate or key store. It is an abstract base class which
40  * TLS library specific subtypes override.
41  *
42  * Most common client applications will not directly interact with
43  * #GTlsDatabase. It is used internally by #GTlsConnection.
44  *
45  * Since: 2.30
46  */
47
48 /**
49  * GTlsDatabase:
50  *
51  * Abstract base class for the backend-specific database types.
52  *
53  * Since: 2.30
54  */
55
56 G_DEFINE_ABSTRACT_TYPE (GTlsDatabase, g_tls_database, G_TYPE_OBJECT);
57
58 enum {
59   UNLOCK_REQUIRED,
60
61   LAST_SIGNAL
62 };
63
64 /**
65  * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER:
66  *
67  * The purpose used to verify the server certificate in a TLS connection. This
68  * is the most common purpose in use. Used by TLS clients.
69  */
70
71 /**
72  * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT:
73  *
74  * The purpose used to verify the client certificate in a TLS connection.
75  * Used by TLS servers.
76  */
77
78 static void
79 g_tls_database_init (GTlsDatabase *cert)
80 {
81
82 }
83
84 typedef struct _AsyncVerifyChain {
85   GTlsCertificate *chain;
86   gchar *purpose;
87   GSocketConnectable *identity;
88   GTlsInteraction *interaction;
89   GTlsDatabaseVerifyFlags flags;
90 } AsyncVerifyChain;
91
92 static void
93 async_verify_chain_free (gpointer data)
94 {
95   AsyncVerifyChain *args = data;
96   g_clear_object (&args->chain);
97   g_free (args->purpose);
98   g_clear_object (&args->identity);
99   g_clear_object (&args->interaction);
100   g_slice_free (AsyncVerifyChain, args);
101 }
102
103 static void
104 async_verify_chain_thread (GTask         *task,
105                            gpointer       object,
106                            gpointer       task_data,
107                            GCancellable  *cancellable)
108 {
109   AsyncVerifyChain *args = task_data;
110   GTlsCertificateFlags verify_result;
111   GError *error = NULL;
112
113   verify_result = g_tls_database_verify_chain (G_TLS_DATABASE (object),
114                                                args->chain,
115                                                args->purpose,
116                                                args->identity,
117                                                args->interaction,
118                                                args->flags,
119                                                cancellable,
120                                                &error);
121   if (error)
122     g_task_return_error (task, error);
123   else
124     g_task_return_int (task, (gssize)verify_result);
125 }
126
127 static void
128 g_tls_database_real_verify_chain_async (GTlsDatabase           *self,
129                                         GTlsCertificate        *chain,
130                                         const gchar            *purpose,
131                                         GSocketConnectable     *identity,
132                                         GTlsInteraction        *interaction,
133                                         GTlsDatabaseVerifyFlags flags,
134                                         GCancellable           *cancellable,
135                                         GAsyncReadyCallback     callback,
136                                         gpointer                user_data)
137 {
138   GTask *task;
139   AsyncVerifyChain *args;
140
141   args = g_slice_new0 (AsyncVerifyChain);
142   args->chain = g_object_ref (chain);
143   args->purpose = g_strdup (purpose);
144   args->identity = identity ? g_object_ref (identity) : NULL;
145   args->interaction = interaction ? g_object_ref (interaction) : NULL;
146   args->flags = flags;
147
148   task = g_task_new (self, cancellable, callback, user_data);
149   g_task_set_task_data (task, args, async_verify_chain_free);
150   g_task_run_in_thread (task, async_verify_chain_thread);
151   g_object_unref (task);
152 }
153
154 static GTlsCertificateFlags
155 g_tls_database_real_verify_chain_finish (GTlsDatabase          *self,
156                                          GAsyncResult          *result,
157                                          GError               **error)
158 {
159   GTlsCertificateFlags ret;
160
161   g_return_val_if_fail (g_task_is_valid (result, self), G_TLS_CERTIFICATE_GENERIC_ERROR);
162
163   ret = (GTlsCertificateFlags)g_task_propagate_int (G_TASK (result), error);
164   if (ret == (GTlsCertificateFlags)-1)
165     return G_TLS_CERTIFICATE_GENERIC_ERROR;
166   else
167     return ret;
168 }
169
170 typedef struct {
171   gchar *handle;
172   GTlsInteraction *interaction;
173   GTlsDatabaseLookupFlags flags;
174 } AsyncLookupCertificateForHandle;
175
176 static void
177 async_lookup_certificate_for_handle_free (gpointer data)
178 {
179   AsyncLookupCertificateForHandle *args = data;
180
181   g_free (args->handle);
182   g_clear_object (&args->interaction);
183   g_slice_free (AsyncLookupCertificateForHandle, args);
184 }
185
186 static void
187 async_lookup_certificate_for_handle_thread (GTask         *task,
188                                             gpointer       object,
189                                             gpointer       task_data,
190                                             GCancellable  *cancellable)
191 {
192   AsyncLookupCertificateForHandle *args = task_data;
193   GTlsCertificate *result;
194   GError *error = NULL;
195
196   result = g_tls_database_lookup_certificate_for_handle (G_TLS_DATABASE (object),
197                                                          args->handle,
198                                                          args->interaction,
199                                                          args->flags,
200                                                          cancellable,
201                                                          &error);
202   if (result)
203     g_task_return_pointer (task, result, g_object_unref);
204   else
205     g_task_return_error (task, error);
206 }
207
208 static void
209 g_tls_database_real_lookup_certificate_for_handle_async (GTlsDatabase           *self,
210                                                          const gchar            *handle,
211                                                          GTlsInteraction        *interaction,
212                                                          GTlsDatabaseLookupFlags flags,
213                                                          GCancellable           *cancellable,
214                                                          GAsyncReadyCallback     callback,
215                                                          gpointer                user_data)
216 {
217   GTask *task;
218   AsyncLookupCertificateForHandle *args;
219
220   args = g_slice_new0 (AsyncLookupCertificateForHandle);
221   args->handle = g_strdup (handle);
222   args->interaction = interaction ? g_object_ref (interaction) : NULL;
223
224   task = g_task_new (self, cancellable, callback, user_data);
225   g_task_set_task_data (task, args, async_lookup_certificate_for_handle_free);
226   g_task_run_in_thread (task, async_lookup_certificate_for_handle_thread);
227   g_object_unref (task);
228 }
229
230 static GTlsCertificate*
231 g_tls_database_real_lookup_certificate_for_handle_finish (GTlsDatabase          *self,
232                                                           GAsyncResult          *result,
233                                                           GError               **error)
234 {
235   g_return_val_if_fail (g_task_is_valid (result, self), NULL);
236
237   return g_task_propagate_pointer (G_TASK (result), error);
238 }
239
240
241 typedef struct {
242   GTlsCertificate *certificate;
243   GTlsInteraction *interaction;
244   GTlsDatabaseLookupFlags flags;
245 } AsyncLookupCertificateIssuer;
246
247 static void
248 async_lookup_certificate_issuer_free (gpointer data)
249 {
250   AsyncLookupCertificateIssuer *args = data;
251
252   g_clear_object (&args->certificate);
253   g_clear_object (&args->interaction);
254   g_slice_free (AsyncLookupCertificateIssuer, args);
255 }
256
257 static void
258 async_lookup_certificate_issuer_thread (GTask         *task,
259                                         gpointer       object,
260                                         gpointer       task_data,
261                                         GCancellable  *cancellable)
262 {
263   AsyncLookupCertificateIssuer *args = task_data;
264   GTlsCertificate *issuer;
265   GError *error = NULL;
266
267   issuer = g_tls_database_lookup_certificate_issuer (G_TLS_DATABASE (object),
268                                                      args->certificate,
269                                                      args->interaction,
270                                                      args->flags,
271                                                      cancellable,
272                                                      &error);
273   if (issuer)
274     g_task_return_pointer (task, issuer, g_object_unref);
275   else
276     g_task_return_error (task, error);
277 }
278
279 static void
280 g_tls_database_real_lookup_certificate_issuer_async (GTlsDatabase           *self,
281                                                      GTlsCertificate        *certificate,
282                                                      GTlsInteraction        *interaction,
283                                                      GTlsDatabaseLookupFlags flags,
284                                                      GCancellable           *cancellable,
285                                                      GAsyncReadyCallback     callback,
286                                                      gpointer                user_data)
287 {
288   GTask *task;
289   AsyncLookupCertificateIssuer *args;
290
291   args = g_slice_new0 (AsyncLookupCertificateIssuer);
292   args->certificate = g_object_ref (certificate);
293   args->flags = flags;
294   args->interaction = interaction ? g_object_ref (interaction) : NULL;
295
296   task = g_task_new (self, cancellable, callback, user_data);
297   g_task_set_task_data (task, args, async_lookup_certificate_issuer_free);
298   g_task_run_in_thread (task, async_lookup_certificate_issuer_thread);
299   g_object_unref (task);
300 }
301
302 static GTlsCertificate *
303 g_tls_database_real_lookup_certificate_issuer_finish (GTlsDatabase          *self,
304                                                       GAsyncResult          *result,
305                                                       GError               **error)
306 {
307   g_return_val_if_fail (g_task_is_valid (result, self), NULL);
308
309   return g_task_propagate_pointer (G_TASK (result), error);
310 }
311
312 typedef struct {
313   GByteArray *issuer;
314   GTlsInteraction *interaction;
315   GTlsDatabaseLookupFlags flags;
316 } AsyncLookupCertificatesIssuedBy;
317
318 static void
319 async_lookup_certificates_issued_by_free (gpointer data)
320 {
321   AsyncLookupCertificatesIssuedBy *args = data;
322
323   g_byte_array_unref (args->issuer);
324   g_clear_object (&args->interaction);
325   g_slice_free (AsyncLookupCertificatesIssuedBy, args);
326 }
327
328 static void
329 async_lookup_certificates_free_certificates (gpointer data)
330 {
331   GList *list = data;
332
333   g_list_free_full (list, g_object_unref);
334 }
335
336 static void
337 async_lookup_certificates_issued_by_thread (GTask         *task,
338                                             gpointer       object,
339                                             gpointer       task_data,
340                                             GCancellable  *cancellable)
341 {
342   AsyncLookupCertificatesIssuedBy *args = task_data;
343   GList *results;
344   GError *error = NULL;
345
346   results = g_tls_database_lookup_certificates_issued_by (G_TLS_DATABASE (object),
347                                                           args->issuer,
348                                                           args->interaction,
349                                                           args->flags,
350                                                           cancellable,
351                                                           &error);
352   if (results)
353     g_task_return_pointer (task, results, async_lookup_certificates_free_certificates);
354   else
355     g_task_return_error (task, error);
356 }
357
358 static void
359 g_tls_database_real_lookup_certificates_issued_by_async (GTlsDatabase           *self,
360                                                          GByteArray             *issuer,
361                                                          GTlsInteraction        *interaction,
362                                                          GTlsDatabaseLookupFlags flags,
363                                                          GCancellable           *cancellable,
364                                                          GAsyncReadyCallback     callback,
365                                                          gpointer                user_data)
366 {
367   GTask *task;
368   AsyncLookupCertificatesIssuedBy *args;
369
370   args = g_slice_new0 (AsyncLookupCertificatesIssuedBy);
371   args->issuer = g_byte_array_ref (issuer);
372   args->flags = flags;
373   args->interaction = interaction ? g_object_ref (interaction) : NULL;
374
375   task = g_task_new (self, cancellable, callback, user_data);
376   g_task_set_task_data (task, args, async_lookup_certificates_issued_by_free);
377   g_task_run_in_thread (task, async_lookup_certificates_issued_by_thread);
378   g_object_unref (task);
379 }
380
381 static GList *
382 g_tls_database_real_lookup_certificates_issued_by_finish (GTlsDatabase          *self,
383                                                           GAsyncResult          *result,
384                                                           GError               **error)
385 {
386   g_return_val_if_fail (g_task_is_valid (result, self), NULL);
387
388   return g_task_propagate_pointer (G_TASK (result), error);
389 }
390
391 static void
392 g_tls_database_class_init (GTlsDatabaseClass *klass)
393 {
394   klass->verify_chain_async = g_tls_database_real_verify_chain_async;
395   klass->verify_chain_finish = g_tls_database_real_verify_chain_finish;
396   klass->lookup_certificate_for_handle_async = g_tls_database_real_lookup_certificate_for_handle_async;
397   klass->lookup_certificate_for_handle_finish = g_tls_database_real_lookup_certificate_for_handle_finish;
398   klass->lookup_certificate_issuer_async = g_tls_database_real_lookup_certificate_issuer_async;
399   klass->lookup_certificate_issuer_finish = g_tls_database_real_lookup_certificate_issuer_finish;
400   klass->lookup_certificates_issued_by_async = g_tls_database_real_lookup_certificates_issued_by_async;
401   klass->lookup_certificates_issued_by_finish = g_tls_database_real_lookup_certificates_issued_by_finish;
402 }
403
404 /**
405  * g_tls_database_verify_chain:
406  * @self: a #GTlsDatabase
407  * @chain: a #GTlsCertificate chain
408  * @purpose: the purpose that this certificate chain will be used for.
409  * @identity: (allow-none): the expected peer identity
410  * @interaction: (allow-none): used to interact with the user if necessary
411  * @flags: additional verify flags
412  * @cancellable: (allow-none): a #GCancellable, or %NULL
413  * @error: (allow-none): a #GError, or %NULL
414  *
415  * Verify's a certificate chain after looking up and adding any missing
416  * certificates to the chain.
417  *
418  * @chain is a chain of #GTlsCertificate objects each pointing to the next
419  * certificate in the chain by its %issuer property. The chain may initially
420  * consist of one or more certificates. After the verification process is
421  * complete, @chain may be modified by adding missing certificates, or removing
422  * extra certificates. If a certificate anchor was found, then it is added to
423  * the @chain.
424  *
425  * @purpose describes the purpose (or usage) for which the certificate
426  * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
427  * which means that the certificate is being used to authenticate a server
428  * (and we are acting as the client).
429  *
430  * The @identity is used to check for pinned certificates (trust exceptions)
431  * in the database. These will override the normal verification process on a
432  * host by host basis.
433  *
434  * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
435  * used.
436  *
437  * This function can block, use g_tls_database_verify_chain_async() to perform
438  * the verification operation asynchronously.
439  *
440  * Returns: the appropriate #GTlsCertificateFlags which represents the
441  * result of verification.
442  *
443  * Since: 2.30
444  */
445 GTlsCertificateFlags
446 g_tls_database_verify_chain (GTlsDatabase           *self,
447                              GTlsCertificate        *chain,
448                              const gchar            *purpose,
449                              GSocketConnectable     *identity,
450                              GTlsInteraction        *interaction,
451                              GTlsDatabaseVerifyFlags flags,
452                              GCancellable           *cancellable,
453                              GError                **error)
454 {
455   g_return_val_if_fail (G_IS_TLS_DATABASE (self), G_TLS_CERTIFICATE_GENERIC_ERROR);
456   g_return_val_if_fail (G_IS_TLS_DATABASE (self),
457                         G_TLS_CERTIFICATE_GENERIC_ERROR);
458   g_return_val_if_fail (G_IS_TLS_CERTIFICATE (chain),
459                         G_TLS_CERTIFICATE_GENERIC_ERROR);
460   g_return_val_if_fail (purpose, G_TLS_CERTIFICATE_GENERIC_ERROR);
461   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction),
462                         G_TLS_CERTIFICATE_GENERIC_ERROR);
463   g_return_val_if_fail (identity == NULL || G_IS_SOCKET_CONNECTABLE (identity),
464                         G_TLS_CERTIFICATE_GENERIC_ERROR);
465   g_return_val_if_fail (error == NULL || *error == NULL, G_TLS_CERTIFICATE_GENERIC_ERROR);
466
467   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->verify_chain,
468                         G_TLS_CERTIFICATE_GENERIC_ERROR);
469
470   return G_TLS_DATABASE_GET_CLASS (self)->verify_chain (self,
471                                                         chain,
472                                                         purpose,
473                                                         identity,
474                                                         interaction,
475                                                         flags,
476                                                         cancellable,
477                                                         error);
478 }
479
480 /**
481  * g_tls_database_verify_chain_async:
482  * @self: a #GTlsDatabase
483  * @chain: a #GTlsCertificate chain
484  * @purpose: the purpose that this certificate chain will be used for.
485  * @identity: (allow-none): the expected peer identity
486  * @interaction: (allow-none): used to interact with the user if necessary
487  * @flags: additional verify flags
488  * @cancellable: (allow-none): a #GCancellable, or %NULL
489  * @callback: callback to call when the operation completes
490  * @user_data: the data to pass to the callback function
491  *
492  * Asynchronously verify's a certificate chain after looking up and adding
493  * any missing certificates to the chain. See g_tls_database_verify_chain()
494  * for more information.
495  *
496  * Since: 2.30
497  */
498 void
499 g_tls_database_verify_chain_async (GTlsDatabase           *self,
500                                    GTlsCertificate        *chain,
501                                    const gchar            *purpose,
502                                    GSocketConnectable     *identity,
503                                    GTlsInteraction        *interaction,
504                                    GTlsDatabaseVerifyFlags flags,
505                                    GCancellable           *cancellable,
506                                    GAsyncReadyCallback     callback,
507                                    gpointer                user_data)
508 {
509   g_return_if_fail (G_IS_TLS_DATABASE (self));
510   g_return_if_fail (G_IS_TLS_CERTIFICATE (chain));
511   g_return_if_fail (purpose != NULL);
512   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
513   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
514   g_return_if_fail (identity == NULL || G_IS_SOCKET_CONNECTABLE (identity));
515   g_return_if_fail (callback != NULL);
516
517   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->verify_chain_async);
518   G_TLS_DATABASE_GET_CLASS (self)->verify_chain_async (self,
519                                                        chain,
520                                                        purpose,
521                                                        identity,
522                                                        interaction,
523                                                        flags,
524                                                        cancellable,
525                                                        callback,
526                                                        user_data);
527 }
528
529 /**
530  * g_tls_database_verify_chain_finish:
531  * @self: a #GTlsDatabase
532  * @result: a #GAsyncResult.
533  * @error: a #GError pointer, or %NULL
534  *
535  * Finish an asynchronous verify chain operation. See
536  * g_tls_database_verify_chain() for more information. *
537  * Returns: the appropriate #GTlsCertificateFlags which represents the
538  * result of verification.
539  *
540  * Since: 2.30
541  */
542 GTlsCertificateFlags
543 g_tls_database_verify_chain_finish (GTlsDatabase          *self,
544                                     GAsyncResult          *result,
545                                     GError               **error)
546 {
547   g_return_val_if_fail (G_IS_TLS_DATABASE (self), G_TLS_CERTIFICATE_GENERIC_ERROR);
548   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), G_TLS_CERTIFICATE_GENERIC_ERROR);
549   g_return_val_if_fail (error == NULL || *error == NULL, G_TLS_CERTIFICATE_GENERIC_ERROR);
550   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->verify_chain_finish,
551                         G_TLS_CERTIFICATE_GENERIC_ERROR);
552   return G_TLS_DATABASE_GET_CLASS (self)->verify_chain_finish (self,
553                                                                result,
554                                                                error);
555 }
556
557 /**
558  * g_tls_database_create_certificate_handle:
559  * @self: a #GTlsDatabase
560  * @certificate: certificate for which to create a handle.
561  *
562  * Create a handle string for the certificate. The database will only be able
563  * to create a handle for certificates that originate from the database. In
564  * cases where the database cannot create a handle for a certificate, %NULL
565  * will be returned.
566  *
567  * This handle should be stable across various instances of the application,
568  * and between applications. If a certificate is modified in the database,
569  * then it is not guaranteed that this handle will continue to point to it.
570  *
571  * Returns: (allow-none): a newly allocated string containing the handle.
572  * Since: 2.30
573  */
574 gchar*
575 g_tls_database_create_certificate_handle (GTlsDatabase            *self,
576                                           GTlsCertificate         *certificate)
577 {
578   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
579   g_return_val_if_fail (G_IS_TLS_CERTIFICATE (certificate), NULL);
580   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->create_certificate_handle, NULL);
581   return G_TLS_DATABASE_GET_CLASS (self)->create_certificate_handle (self,
582                                                                      certificate);
583 }
584
585 /**
586  * g_tls_database_lookup_certificate_for_handle:
587  * @self: a #GTlsDatabase
588  * @handle: a certificate handle
589  * @interaction: (allow-none): used to interact with the user if necessary
590  * @flags: Flags which affect the lookup.
591  * @cancellable: (allow-none): a #GCancellable, or %NULL
592  * @error: (allow-none): a #GError, or %NULL
593  *
594  * Lookup a certificate by its handle.
595  *
596  * The handle should have been created by calling
597  * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
598  * the same TLS backend. The handle is designed to remain valid across
599  * instantiations of the database.
600  *
601  * If the handle is no longer valid, or does not point to a certificate in
602  * this database, then %NULL will be returned.
603  *
604  * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
605  * the lookup operation asynchronously.
606  *
607  * Returns: (transfer full) (allow-none): a newly allocated
608  * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
609  *
610  * Since: 2.30
611  */
612 GTlsCertificate*
613 g_tls_database_lookup_certificate_for_handle (GTlsDatabase            *self,
614                                               const gchar             *handle,
615                                               GTlsInteraction         *interaction,
616                                               GTlsDatabaseLookupFlags  flags,
617                                               GCancellable            *cancellable,
618                                               GError                 **error)
619 {
620   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
621   g_return_val_if_fail (handle != NULL, NULL);
622   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction), NULL);
623   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
624   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
625   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle, NULL);
626   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle (self,
627                                                                          handle,
628                                                                          interaction,
629                                                                          flags,
630                                                                          cancellable,
631                                                                          error);
632 }
633
634
635 /**
636  * g_tls_database_lookup_certificate_for_handle_async:
637  * @self: a #GTlsDatabase
638  * @handle: a certificate handle
639  * @interaction: (allow-none): used to interact with the user if necessary
640  * @flags: Flags which affect the lookup.
641  * @cancellable: (allow-none): a #GCancellable, or %NULL
642  * @callback: callback to call when the operation completes
643  * @user_data: the data to pass to the callback function
644  *
645  * Asynchronously lookup a certificate by its handle in the database. See
646  * g_tls_database_lookup_certificate_for_handle() for more information.
647  *
648  * Since: 2.30
649  */
650 void
651 g_tls_database_lookup_certificate_for_handle_async (GTlsDatabase            *self,
652                                                     const gchar             *handle,
653                                                     GTlsInteraction         *interaction,
654                                                     GTlsDatabaseLookupFlags  flags,
655                                                     GCancellable            *cancellable,
656                                                     GAsyncReadyCallback      callback,
657                                                     gpointer                 user_data)
658 {
659   g_return_if_fail (G_IS_TLS_DATABASE (self));
660   g_return_if_fail (handle != NULL);
661   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
662   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
663   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_async);
664   G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_async (self,
665                                                                                handle,
666                                                                                interaction,
667                                                                                flags,
668                                                                                cancellable,
669                                                                                callback,
670                                                                                user_data);
671 }
672
673 /**
674  * g_tls_database_lookup_certificate_for_handle_finish:
675  * @self: a #GTlsDatabase
676  * @result: a #GAsyncResult.
677  * @error: a #GError pointer, or %NULL
678  *
679  * Finish an asynchronous lookup of a certificate by its handle. See
680  * g_tls_database_lookup_certificate_handle() for more information.
681  *
682  * If the handle is no longer valid, or does not point to a certificate in
683  * this database, then %NULL will be returned.
684  *
685  * Returns: (transfer full): a newly allocated #GTlsCertificate object.
686  * Use g_object_unref() to release the certificate.
687  *
688  * Since: 2.30
689  */
690 GTlsCertificate*
691 g_tls_database_lookup_certificate_for_handle_finish (GTlsDatabase            *self,
692                                                      GAsyncResult            *result,
693                                                      GError                 **error)
694 {
695   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
696   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
697   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
698   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_finish, NULL);
699   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_finish (self,
700                                                                                 result,
701                                                                                 error);
702 }
703
704 /**
705  * g_tls_database_lookup_certificate_issuer:
706  * @self: a #GTlsDatabase
707  * @certificate: a #GTlsCertificate
708  * @interaction: (allow-none): used to interact with the user if necessary
709  * @flags: flags which affect the lookup operation
710  * @cancellable: (allow-none): a #GCancellable, or %NULL
711  * @error: (allow-none): a #GError, or %NULL
712  *
713  * Lookup the issuer of @certificate in the database.
714  *
715  * The %issuer property
716  * of @certificate is not modified, and the two certificates are not hooked
717  * into a chain.
718  *
719  * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
720  * the lookup operation asynchronously.
721  *
722  * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
723  * or %NULL. Use g_object_unref() to release the certificate.
724  *
725  * Since: 2.30
726  */
727 GTlsCertificate*
728 g_tls_database_lookup_certificate_issuer (GTlsDatabase           *self,
729                                           GTlsCertificate        *certificate,
730                                           GTlsInteraction        *interaction,
731                                           GTlsDatabaseLookupFlags flags,
732                                           GCancellable           *cancellable,
733                                           GError                **error)
734 {
735   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
736   g_return_val_if_fail (G_IS_TLS_CERTIFICATE (certificate), NULL);
737   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction), NULL);
738   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
739   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
740   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer, NULL);
741   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer (self,
742                                                                      certificate,
743                                                                      interaction,
744                                                                      flags,
745                                                                      cancellable,
746                                                                      error);
747 }
748
749 /**
750  * g_tls_database_lookup_certificate_issuer_async:
751  * @self: a #GTlsDatabase
752  * @certificate: a #GTlsCertificate
753  * @interaction: (allow-none): used to interact with the user if necessary
754  * @flags: flags which affect the lookup operation
755  * @cancellable: (allow-none): a #GCancellable, or %NULL
756  * @callback: callback to call when the operation completes
757  * @user_data: the data to pass to the callback function
758  *
759  * Asynchronously lookup the issuer of @certificate in the database. See
760  * g_tls_database_lookup_certificate_issuer() for more information.
761  *
762  * Since: 2.30
763  */
764 void
765 g_tls_database_lookup_certificate_issuer_async (GTlsDatabase           *self,
766                                                 GTlsCertificate        *certificate,
767                                                 GTlsInteraction        *interaction,
768                                                 GTlsDatabaseLookupFlags flags,
769                                                 GCancellable           *cancellable,
770                                                 GAsyncReadyCallback     callback,
771                                                 gpointer                user_data)
772 {
773   g_return_if_fail (G_IS_TLS_DATABASE (self));
774   g_return_if_fail (G_IS_TLS_CERTIFICATE (certificate));
775   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
776   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
777   g_return_if_fail (callback != NULL);
778   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_async);
779   G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_async (self,
780                                                         certificate,
781                                                         interaction,
782                                                         flags,
783                                                         cancellable,
784                                                         callback,
785                                                         user_data);
786 }
787
788 /**
789  * g_tls_database_lookup_certificate_issuer_finish:
790  * @self: a #GTlsDatabase
791  * @result: a #GAsyncResult.
792  * @error: a #GError pointer, or %NULL
793  *
794  * Finish an asynchronous lookup issuer operation. See
795  * g_tls_database_lookup_certificate_issuer() for more information.
796  *
797  * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
798  * or %NULL. Use g_object_unref() to release the certificate.
799  *
800  * Since: 2.30
801  */
802 GTlsCertificate*
803 g_tls_database_lookup_certificate_issuer_finish (GTlsDatabase          *self,
804                                                  GAsyncResult          *result,
805                                                  GError               **error)
806 {
807   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
808   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
809   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
810   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_finish, NULL);
811   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_finish (self,
812                                                                 result,
813                                                                 error);
814 }
815
816 /**
817  * g_tls_database_lookup_certificates_issued_by:
818  * @self: a #GTlsDatabase
819  * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
820  * @interaction: (allow-none): used to interact with the user if necessary
821  * @flags: Flags which affect the lookup operation.
822  * @cancellable: (allow-none): a #GCancellable, or %NULL
823  * @error: (allow-none): a #GError, or %NULL
824  *
825  * Lookup certificates issued by this issuer in the database.
826  *
827  * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
828  * the lookup operation asynchronously.
829  *
830  * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
831  * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
832  *
833  * Since: 2.30
834  */
835 GList*
836 g_tls_database_lookup_certificates_issued_by (GTlsDatabase           *self,
837                                               GByteArray             *issuer_raw_dn,
838                                               GTlsInteraction        *interaction,
839                                               GTlsDatabaseLookupFlags flags,
840                                               GCancellable           *cancellable,
841                                               GError                **error)
842 {
843   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
844   g_return_val_if_fail (issuer_raw_dn, NULL);
845   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction), NULL);
846   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
847   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
848   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by, NULL);
849   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by (self,
850                                                                          issuer_raw_dn,
851                                                                          interaction,
852                                                                          flags,
853                                                                          cancellable,
854                                                                          error);
855 }
856
857 /**
858  * g_tls_database_lookup_certificates_issued_by_async:
859  * @self: a #GTlsDatabase
860  * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
861  * @interaction: (allow-none): used to interact with the user if necessary
862  * @flags: Flags which affect the lookup operation.
863  * @cancellable: (allow-none): a #GCancellable, or %NULL
864  * @callback: callback to call when the operation completes
865  * @user_data: the data to pass to the callback function
866  *
867  * Asynchronously lookup certificates issued by this issuer in the database. See
868  * g_tls_database_lookup_certificates_issued_by() for more information.
869  *
870  * The database may choose to hold a reference to the issuer byte array for the duration
871  * of of this asynchronous operation. The byte array should not be modified during
872  * this time.
873  *
874  * Since: 2.30
875  */
876 void
877 g_tls_database_lookup_certificates_issued_by_async (GTlsDatabase           *self,
878                                                     GByteArray             *issuer_raw_dn,
879                                                     GTlsInteraction        *interaction,
880                                                     GTlsDatabaseLookupFlags flags,
881                                                     GCancellable           *cancellable,
882                                                     GAsyncReadyCallback     callback,
883                                                     gpointer                user_data)
884 {
885   g_return_if_fail (G_IS_TLS_DATABASE (self));
886   g_return_if_fail (issuer_raw_dn != NULL);
887   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
888   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
889   g_return_if_fail (callback != NULL);
890   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_async);
891   G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_async (self,
892                                                                         issuer_raw_dn,
893                                                                         interaction,
894                                                                         flags,
895                                                                         cancellable,
896                                                                         callback,
897                                                                         user_data);
898 }
899
900 /**
901  * g_tls_database_lookup_certificates_issued_by_finish:
902  * @self: a #GTlsDatabase
903  * @result: a #GAsyncResult.
904  * @error: a #GError pointer, or %NULL
905  *
906  * Finish an asynchronous lookup of certificates. See
907  * g_tls_database_lookup_certificates_issued_by() for more information.
908  *
909  * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
910  * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
911  *
912  * Since: 2.30
913  */
914 GList*
915 g_tls_database_lookup_certificates_issued_by_finish (GTlsDatabase          *self,
916                                                      GAsyncResult          *result,
917                                                      GError               **error)
918 {
919   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
920   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
921   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
922   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_finish, NULL);
923   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_finish (self,
924                                                                                 result,
925                                                                                 error);
926 }