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: (nullable): a newly allocated string containing the
 572  * handle.
 573  *
 574  * Since: 2.30
 575  */
 576 gchar*
 577 g_tls_database_create_certificate_handle (GTlsDatabase            *self,
 578                                           GTlsCertificate         *certificate)
 579 {
 580   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 581   g_return_val_if_fail (G_IS_TLS_CERTIFICATE (certificate), NULL);
 582   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->create_certificate_handle, NULL);
 583   return G_TLS_DATABASE_GET_CLASS (self)->create_certificate_handle (self,
 584                                                                      certificate);
 585 }
 586
 587 /**
 588  * g_tls_database_lookup_certificate_for_handle:
 589  * @self: a #GTlsDatabase
 590  * @handle: a certificate handle
 591  * @interaction: (allow-none): used to interact with the user if necessary
 592  * @flags: Flags which affect the lookup.
 593  * @cancellable: (allow-none): a #GCancellable, or %NULL
 594  * @error: (allow-none): a #GError, or %NULL
 595  *
 596  * Lookup a certificate by its handle.
 597  *
 598  * The handle should have been created by calling
 599  * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
 600  * the same TLS backend. The handle is designed to remain valid across
 601  * instantiations of the database.
 602  *
 603  * If the handle is no longer valid, or does not point to a certificate in
 604  * this database, then %NULL will be returned.
 605  *
 606  * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
 607  * the lookup operation asynchronously.
 608  *
 609  * Returns: (transfer full) (allow-none): a newly allocated
 610  * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
 611  *
 612  * Since: 2.30
 613  */
 614 GTlsCertificate*
 615 g_tls_database_lookup_certificate_for_handle (GTlsDatabase            *self,
 616                                               const gchar             *handle,
 617                                               GTlsInteraction         *interaction,
 618                                               GTlsDatabaseLookupFlags  flags,
 619                                               GCancellable            *cancellable,
 620                                               GError                 **error)
 621 {
 622   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 623   g_return_val_if_fail (handle != NULL, NULL);
 624   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction), NULL);
 625   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 626   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 627   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle, NULL);
 628   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle (self,
 629                                                                          handle,
 630                                                                          interaction,
 631                                                                          flags,
 632                                                                          cancellable,
 633                                                                          error);
 634 }
 635
 636
 637 /**
 638  * g_tls_database_lookup_certificate_for_handle_async:
 639  * @self: a #GTlsDatabase
 640  * @handle: a certificate handle
 641  * @interaction: (allow-none): used to interact with the user if necessary
 642  * @flags: Flags which affect the lookup.
 643  * @cancellable: (allow-none): a #GCancellable, or %NULL
 644  * @callback: callback to call when the operation completes
 645  * @user_data: the data to pass to the callback function
 646  *
 647  * Asynchronously lookup a certificate by its handle in the database. See
 648  * g_tls_database_lookup_certificate_for_handle() for more information.
 649  *
 650  * Since: 2.30
 651  */
 652 void
 653 g_tls_database_lookup_certificate_for_handle_async (GTlsDatabase            *self,
 654                                                     const gchar             *handle,
 655                                                     GTlsInteraction         *interaction,
 656                                                     GTlsDatabaseLookupFlags  flags,
 657                                                     GCancellable            *cancellable,
 658                                                     GAsyncReadyCallback      callback,
 659                                                     gpointer                 user_data)
 660 {
 661   g_return_if_fail (G_IS_TLS_DATABASE (self));
 662   g_return_if_fail (handle != NULL);
 663   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
 664   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 665   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_async);
 666   G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_async (self,
 667                                                                                handle,
 668                                                                                interaction,
 669                                                                                flags,
 670                                                                                cancellable,
 671                                                                                callback,
 672                                                                                user_data);
 673 }
 674
 675 /**
 676  * g_tls_database_lookup_certificate_for_handle_finish:
 677  * @self: a #GTlsDatabase
 678  * @result: a #GAsyncResult.
 679  * @error: a #GError pointer, or %NULL
 680  *
 681  * Finish an asynchronous lookup of a certificate by its handle. See
 682  * g_tls_database_lookup_certificate_handle() for more information.
 683  *
 684  * If the handle is no longer valid, or does not point to a certificate in
 685  * this database, then %NULL will be returned.
 686  *
 687  * Returns: (transfer full): a newly allocated #GTlsCertificate object.
 688  * Use g_object_unref() to release the certificate.
 689  *
 690  * Since: 2.30
 691  */
 692 GTlsCertificate*
 693 g_tls_database_lookup_certificate_for_handle_finish (GTlsDatabase            *self,
 694                                                      GAsyncResult            *result,
 695                                                      GError                 **error)
 696 {
 697   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 698   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
 699   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 700   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_finish, NULL);
 701   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_finish (self,
 702                                                                                 result,
 703                                                                                 error);
 704 }
 705
 706 /**
 707  * g_tls_database_lookup_certificate_issuer:
 708  * @self: a #GTlsDatabase
 709  * @certificate: a #GTlsCertificate
 710  * @interaction: (allow-none): used to interact with the user if necessary
 711  * @flags: flags which affect the lookup operation
 712  * @cancellable: (allow-none): a #GCancellable, or %NULL
 713  * @error: (allow-none): a #GError, or %NULL
 714  *
 715  * Lookup the issuer of @certificate in the database.
 716  *
 717  * The %issuer property
 718  * of @certificate is not modified, and the two certificates are not hooked
 719  * into a chain.
 720  *
 721  * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
 722  * the lookup operation asynchronously.
 723  *
 724  * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
 725  * or %NULL. Use g_object_unref() to release the certificate.
 726  *
 727  * Since: 2.30
 728  */
 729 GTlsCertificate*
 730 g_tls_database_lookup_certificate_issuer (GTlsDatabase           *self,
 731                                           GTlsCertificate        *certificate,
 732                                           GTlsInteraction        *interaction,
 733                                           GTlsDatabaseLookupFlags flags,
 734                                           GCancellable           *cancellable,
 735                                           GError                **error)
 736 {
 737   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 738   g_return_val_if_fail (G_IS_TLS_CERTIFICATE (certificate), NULL);
 739   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction), NULL);
 740   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 741   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 742   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer, NULL);
 743   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer (self,
 744                                                                      certificate,
 745                                                                      interaction,
 746                                                                      flags,
 747                                                                      cancellable,
 748                                                                      error);
 749 }
 750
 751 /**
 752  * g_tls_database_lookup_certificate_issuer_async:
 753  * @self: a #GTlsDatabase
 754  * @certificate: a #GTlsCertificate
 755  * @interaction: (allow-none): used to interact with the user if necessary
 756  * @flags: flags which affect the lookup operation
 757  * @cancellable: (allow-none): a #GCancellable, or %NULL
 758  * @callback: callback to call when the operation completes
 759  * @user_data: the data to pass to the callback function
 760  *
 761  * Asynchronously lookup the issuer of @certificate in the database. See
 762  * g_tls_database_lookup_certificate_issuer() for more information.
 763  *
 764  * Since: 2.30
 765  */
 766 void
 767 g_tls_database_lookup_certificate_issuer_async (GTlsDatabase           *self,
 768                                                 GTlsCertificate        *certificate,
 769                                                 GTlsInteraction        *interaction,
 770                                                 GTlsDatabaseLookupFlags flags,
 771                                                 GCancellable           *cancellable,
 772                                                 GAsyncReadyCallback     callback,
 773                                                 gpointer                user_data)
 774 {
 775   g_return_if_fail (G_IS_TLS_DATABASE (self));
 776   g_return_if_fail (G_IS_TLS_CERTIFICATE (certificate));
 777   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
 778   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 779   g_return_if_fail (callback != NULL);
 780   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_async);
 781   G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_async (self,
 782                                                         certificate,
 783                                                         interaction,
 784                                                         flags,
 785                                                         cancellable,
 786                                                         callback,
 787                                                         user_data);
 788 }
 789
 790 /**
 791  * g_tls_database_lookup_certificate_issuer_finish:
 792  * @self: a #GTlsDatabase
 793  * @result: a #GAsyncResult.
 794  * @error: a #GError pointer, or %NULL
 795  *
 796  * Finish an asynchronous lookup issuer operation. See
 797  * g_tls_database_lookup_certificate_issuer() for more information.
 798  *
 799  * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
 800  * or %NULL. Use g_object_unref() to release the certificate.
 801  *
 802  * Since: 2.30
 803  */
 804 GTlsCertificate*
 805 g_tls_database_lookup_certificate_issuer_finish (GTlsDatabase          *self,
 806                                                  GAsyncResult          *result,
 807                                                  GError               **error)
 808 {
 809   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 810   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
 811   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 812   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_finish, NULL);
 813   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_finish (self,
 814                                                                 result,
 815                                                                 error);
 816 }
 817
 818 /**
 819  * g_tls_database_lookup_certificates_issued_by:
 820  * @self: a #GTlsDatabase
 821  * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
 822  * @interaction: (allow-none): used to interact with the user if necessary
 823  * @flags: Flags which affect the lookup operation.
 824  * @cancellable: (allow-none): a #GCancellable, or %NULL
 825  * @error: (allow-none): a #GError, or %NULL
 826  *
 827  * Lookup certificates issued by this issuer in the database.
 828  *
 829  * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
 830  * the lookup operation asynchronously.
 831  *
 832  * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
 833  * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
 834  *
 835  * Since: 2.30
 836  */
 837 GList*
 838 g_tls_database_lookup_certificates_issued_by (GTlsDatabase           *self,
 839                                               GByteArray             *issuer_raw_dn,
 840                                               GTlsInteraction        *interaction,
 841                                               GTlsDatabaseLookupFlags flags,
 842                                               GCancellable           *cancellable,
 843                                               GError                **error)
 844 {
 845   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 846   g_return_val_if_fail (issuer_raw_dn, NULL);
 847   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction), NULL);
 848   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 849   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 850   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by, NULL);
 851   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by (self,
 852                                                                          issuer_raw_dn,
 853                                                                          interaction,
 854                                                                          flags,
 855                                                                          cancellable,
 856                                                                          error);
 857 }
 858
 859 /**
 860  * g_tls_database_lookup_certificates_issued_by_async:
 861  * @self: a #GTlsDatabase
 862  * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
 863  * @interaction: (allow-none): used to interact with the user if necessary
 864  * @flags: Flags which affect the lookup operation.
 865  * @cancellable: (allow-none): a #GCancellable, or %NULL
 866  * @callback: callback to call when the operation completes
 867  * @user_data: the data to pass to the callback function
 868  *
 869  * Asynchronously lookup certificates issued by this issuer in the database. See
 870  * g_tls_database_lookup_certificates_issued_by() for more information.
 871  *
 872  * The database may choose to hold a reference to the issuer byte array for the duration
 873  * of of this asynchronous operation. The byte array should not be modified during
 874  * this time.
 875  *
 876  * Since: 2.30
 877  */
 878 void
 879 g_tls_database_lookup_certificates_issued_by_async (GTlsDatabase           *self,
 880                                                     GByteArray             *issuer_raw_dn,
 881                                                     GTlsInteraction        *interaction,
 882                                                     GTlsDatabaseLookupFlags flags,
 883                                                     GCancellable           *cancellable,
 884                                                     GAsyncReadyCallback     callback,
 885                                                     gpointer                user_data)
 886 {
 887   g_return_if_fail (G_IS_TLS_DATABASE (self));
 888   g_return_if_fail (issuer_raw_dn != NULL);
 889   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
 890   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 891   g_return_if_fail (callback != NULL);
 892   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_async);
 893   G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_async (self,
 894                                                                         issuer_raw_dn,
 895                                                                         interaction,
 896                                                                         flags,
 897                                                                         cancellable,
 898                                                                         callback,
 899                                                                         user_data);
 900 }
 901
 902 /**
 903  * g_tls_database_lookup_certificates_issued_by_finish:
 904  * @self: a #GTlsDatabase
 905  * @result: a #GAsyncResult.
 906  * @error: a #GError pointer, or %NULL
 907  *
 908  * Finish an asynchronous lookup of certificates. See
 909  * g_tls_database_lookup_certificates_issued_by() for more information.
 910  *
 911  * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
 912  * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
 913  *
 914  * Since: 2.30
 915  */
 916 GList*
 917 g_tls_database_lookup_certificates_issued_by_finish (GTlsDatabase          *self,
 918                                                      GAsyncResult          *result,
 919                                                      GError               **error)
 920 {
 921   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 922   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
 923   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 924   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_finish, NULL);
 925   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_finish (self,
 926                                                                                 result,
 927                                                                                 error);
 928 }