gio/gtlsdatabase.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright (C) 2010 Collabora, Ltd.
   4  *
   5  * SPDX-License-Identifier: LGPL-2.1-or-later
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General
  18  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  19  *
  20  * Author: Stef Walter <stefw@collabora.co.uk>
  21  */
  22
  23 #include "config.h"
  24
  25 #include "gtlsdatabase.h"
  26
  27 #include "gasyncresult.h"
  28 #include "gcancellable.h"
  29 #include "glibintl.h"
  30 #include "gsocketconnectable.h"
  31 #include "gtask.h"
  32 #include "gtlscertificate.h"
  33 #include "gtlsinteraction.h"
  34
  35 /**
  36  * GTlsDatabase:
  37  *
  38  * `GTlsDatabase` is used to look up 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  * A `GTlsDatabase` may be accessed from multiple threads by the TLS backend.
  43  * All implementations are required to be fully thread-safe.
  44  *
  45  * Most common client applications will not directly interact with
  46  * `GTlsDatabase`. It is used internally by [class@Gio.TlsConnection].
  47  *
  48  * Since: 2.30
  49  */
  50
  51 /**
  52  * GTlsDatabaseClass:
  53  * @verify_chain: Virtual method implementing
  54  *  g_tls_database_verify_chain().
  55  * @verify_chain_async: Virtual method implementing
  56  *  g_tls_database_verify_chain_async().
  57  * @verify_chain_finish: Virtual method implementing
  58  *  g_tls_database_verify_chain_finish().
  59  * @create_certificate_handle: Virtual method implementing
  60  *  g_tls_database_create_certificate_handle().
  61  * @lookup_certificate_for_handle: Virtual method implementing
  62  *  g_tls_database_lookup_certificate_for_handle().
  63  * @lookup_certificate_for_handle_async: Virtual method implementing
  64  *  g_tls_database_lookup_certificate_for_handle_async().
  65  * @lookup_certificate_for_handle_finish: Virtual method implementing
  66  *  g_tls_database_lookup_certificate_for_handle_finish().
  67  * @lookup_certificate_issuer: Virtual method implementing
  68  *  g_tls_database_lookup_certificate_issuer().
  69  * @lookup_certificate_issuer_async: Virtual method implementing
  70  *  g_tls_database_lookup_certificate_issuer_async().
  71  * @lookup_certificate_issuer_finish: Virtual method implementing
  72  *  g_tls_database_lookup_certificate_issuer_finish().
  73  * @lookup_certificates_issued_by: Virtual method implementing
  74  *  g_tls_database_lookup_certificates_issued_by().
  75  * @lookup_certificates_issued_by_async: Virtual method implementing
  76  *  g_tls_database_lookup_certificates_issued_by_async().
  77  * @lookup_certificates_issued_by_finish: Virtual method implementing
  78  *  g_tls_database_lookup_certificates_issued_by_finish().
  79  *
  80  * The class for #GTlsDatabase. Derived classes should implement the various
  81  * virtual methods. _async and _finish methods have a default
  82  * implementation that runs the corresponding sync method in a thread.
  83  *
  84  * Since: 2.30
  85  */
  86
  87 G_DEFINE_ABSTRACT_TYPE (GTlsDatabase, g_tls_database, G_TYPE_OBJECT)
  88
  89 enum {
  90   UNLOCK_REQUIRED,
  91
  92   LAST_SIGNAL
  93 };
  94
  95 /**
  96  * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER:
  97  *
  98  * The purpose used to verify the server certificate in a TLS connection. This
  99  * is the most common purpose in use. Used by TLS clients.
 100  */
 101
 102 /**
 103  * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT:
 104  *
 105  * The purpose used to verify the client certificate in a TLS connection.
 106  * Used by TLS servers.
 107  */
 108
 109 static void
 110 g_tls_database_init (GTlsDatabase *cert)
 111 {
 112
 113 }
 114
 115 typedef struct _AsyncVerifyChain {
 116   GTlsCertificate *chain;
 117   gchar *purpose;
 118   GSocketConnectable *identity;
 119   GTlsInteraction *interaction;
 120   GTlsDatabaseVerifyFlags flags;
 121 } AsyncVerifyChain;
 122
 123 static void
 124 async_verify_chain_free (gpointer data)
 125 {
 126   AsyncVerifyChain *args = data;
 127   g_clear_object (&args->chain);
 128   g_free (args->purpose);
 129   g_clear_object (&args->identity);
 130   g_clear_object (&args->interaction);
 131   g_slice_free (AsyncVerifyChain, args);
 132 }
 133
 134 static void
 135 async_verify_chain_thread (GTask         *task,
 136                            gpointer       object,
 137                            gpointer       task_data,
 138                            GCancellable  *cancellable)
 139 {
 140   AsyncVerifyChain *args = task_data;
 141   GTlsCertificateFlags verify_result;
 142   GError *error = NULL;
 143
 144   verify_result = g_tls_database_verify_chain (G_TLS_DATABASE (object),
 145                                                args->chain,
 146                                                args->purpose,
 147                                                args->identity,
 148                                                args->interaction,
 149                                                args->flags,
 150                                                cancellable,
 151                                                &error);
 152   if (error)
 153     g_task_return_error (task, error);
 154   else
 155     g_task_return_int (task, (gssize)verify_result);
 156 }
 157
 158 static void
 159 g_tls_database_real_verify_chain_async (GTlsDatabase           *self,
 160                                         GTlsCertificate        *chain,
 161                                         const gchar            *purpose,
 162                                         GSocketConnectable     *identity,
 163                                         GTlsInteraction        *interaction,
 164                                         GTlsDatabaseVerifyFlags flags,
 165                                         GCancellable           *cancellable,
 166                                         GAsyncReadyCallback     callback,
 167                                         gpointer                user_data)
 168 {
 169   GTask *task;
 170   AsyncVerifyChain *args;
 171
 172   args = g_slice_new0 (AsyncVerifyChain);
 173   args->chain = g_object_ref (chain);
 174   args->purpose = g_strdup (purpose);
 175   args->identity = identity ? g_object_ref (identity) : NULL;
 176   args->interaction = interaction ? g_object_ref (interaction) : NULL;
 177   args->flags = flags;
 178
 179   task = g_task_new (self, cancellable, callback, user_data);
 180   g_task_set_source_tag (task, g_tls_database_real_verify_chain_async);
 181   g_task_set_name (task, "[gio] verify TLS chain");
 182   g_task_set_task_data (task, args, async_verify_chain_free);
 183   g_task_run_in_thread (task, async_verify_chain_thread);
 184   g_object_unref (task);
 185 }
 186
 187 static GTlsCertificateFlags
 188 g_tls_database_real_verify_chain_finish (GTlsDatabase          *self,
 189                                          GAsyncResult          *result,
 190                                          GError               **error)
 191 {
 192   GTlsCertificateFlags ret;
 193
 194   g_return_val_if_fail (g_task_is_valid (result, self), G_TLS_CERTIFICATE_GENERIC_ERROR);
 195
 196   ret = (GTlsCertificateFlags)g_task_propagate_int (G_TASK (result), error);
 197   if (ret == (GTlsCertificateFlags)-1)
 198     return G_TLS_CERTIFICATE_GENERIC_ERROR;
 199   else
 200     return ret;
 201 }
 202
 203 typedef struct {
 204   gchar *handle;
 205   GTlsInteraction *interaction;
 206   GTlsDatabaseLookupFlags flags;
 207 } AsyncLookupCertificateForHandle;
 208
 209 static void
 210 async_lookup_certificate_for_handle_free (gpointer data)
 211 {
 212   AsyncLookupCertificateForHandle *args = data;
 213
 214   g_free (args->handle);
 215   g_clear_object (&args->interaction);
 216   g_slice_free (AsyncLookupCertificateForHandle, args);
 217 }
 218
 219 static void
 220 async_lookup_certificate_for_handle_thread (GTask         *task,
 221                                             gpointer       object,
 222                                             gpointer       task_data,
 223                                             GCancellable  *cancellable)
 224 {
 225   AsyncLookupCertificateForHandle *args = task_data;
 226   GTlsCertificate *result;
 227   GError *error = NULL;
 228
 229   result = g_tls_database_lookup_certificate_for_handle (G_TLS_DATABASE (object),
 230                                                          args->handle,
 231                                                          args->interaction,
 232                                                          args->flags,
 233                                                          cancellable,
 234                                                          &error);
 235   if (result)
 236     g_task_return_pointer (task, result, g_object_unref);
 237   else
 238     g_task_return_error (task, error);
 239 }
 240
 241 static void
 242 g_tls_database_real_lookup_certificate_for_handle_async (GTlsDatabase           *self,
 243                                                          const gchar            *handle,
 244                                                          GTlsInteraction        *interaction,
 245                                                          GTlsDatabaseLookupFlags flags,
 246                                                          GCancellable           *cancellable,
 247                                                          GAsyncReadyCallback     callback,
 248                                                          gpointer                user_data)
 249 {
 250   GTask *task;
 251   AsyncLookupCertificateForHandle *args;
 252
 253   args = g_slice_new0 (AsyncLookupCertificateForHandle);
 254   args->handle = g_strdup (handle);
 255   args->interaction = interaction ? g_object_ref (interaction) : NULL;
 256
 257   task = g_task_new (self, cancellable, callback, user_data);
 258   g_task_set_source_tag (task,
 259                          g_tls_database_real_lookup_certificate_for_handle_async);
 260   g_task_set_name (task, "[gio] lookup TLS certificate");
 261   g_task_set_task_data (task, args, async_lookup_certificate_for_handle_free);
 262   g_task_run_in_thread (task, async_lookup_certificate_for_handle_thread);
 263   g_object_unref (task);
 264 }
 265
 266 static GTlsCertificate*
 267 g_tls_database_real_lookup_certificate_for_handle_finish (GTlsDatabase          *self,
 268                                                           GAsyncResult          *result,
 269                                                           GError               **error)
 270 {
 271   g_return_val_if_fail (g_task_is_valid (result, self), NULL);
 272
 273   return g_task_propagate_pointer (G_TASK (result), error);
 274 }
 275
 276
 277 typedef struct {
 278   GTlsCertificate *certificate;
 279   GTlsInteraction *interaction;
 280   GTlsDatabaseLookupFlags flags;
 281 } AsyncLookupCertificateIssuer;
 282
 283 static void
 284 async_lookup_certificate_issuer_free (gpointer data)
 285 {
 286   AsyncLookupCertificateIssuer *args = data;
 287
 288   g_clear_object (&args->certificate);
 289   g_clear_object (&args->interaction);
 290   g_slice_free (AsyncLookupCertificateIssuer, args);
 291 }
 292
 293 static void
 294 async_lookup_certificate_issuer_thread (GTask         *task,
 295                                         gpointer       object,
 296                                         gpointer       task_data,
 297                                         GCancellable  *cancellable)
 298 {
 299   AsyncLookupCertificateIssuer *args = task_data;
 300   GTlsCertificate *issuer;
 301   GError *error = NULL;
 302
 303   issuer = g_tls_database_lookup_certificate_issuer (G_TLS_DATABASE (object),
 304                                                      args->certificate,
 305                                                      args->interaction,
 306                                                      args->flags,
 307                                                      cancellable,
 308                                                      &error);
 309   if (issuer)
 310     g_task_return_pointer (task, issuer, g_object_unref);
 311   else
 312     g_task_return_error (task, error);
 313 }
 314
 315 static void
 316 g_tls_database_real_lookup_certificate_issuer_async (GTlsDatabase           *self,
 317                                                      GTlsCertificate        *certificate,
 318                                                      GTlsInteraction        *interaction,
 319                                                      GTlsDatabaseLookupFlags flags,
 320                                                      GCancellable           *cancellable,
 321                                                      GAsyncReadyCallback     callback,
 322                                                      gpointer                user_data)
 323 {
 324   GTask *task;
 325   AsyncLookupCertificateIssuer *args;
 326
 327   args = g_slice_new0 (AsyncLookupCertificateIssuer);
 328   args->certificate = g_object_ref (certificate);
 329   args->flags = flags;
 330   args->interaction = interaction ? g_object_ref (interaction) : NULL;
 331
 332   task = g_task_new (self, cancellable, callback, user_data);
 333   g_task_set_source_tag (task,
 334                          g_tls_database_real_lookup_certificate_issuer_async);
 335   g_task_set_name (task, "[gio] lookup certificate issuer");
 336   g_task_set_task_data (task, args, async_lookup_certificate_issuer_free);
 337   g_task_run_in_thread (task, async_lookup_certificate_issuer_thread);
 338   g_object_unref (task);
 339 }
 340
 341 static GTlsCertificate *
 342 g_tls_database_real_lookup_certificate_issuer_finish (GTlsDatabase          *self,
 343                                                       GAsyncResult          *result,
 344                                                       GError               **error)
 345 {
 346   g_return_val_if_fail (g_task_is_valid (result, self), NULL);
 347
 348   return g_task_propagate_pointer (G_TASK (result), error);
 349 }
 350
 351 typedef struct {
 352   GByteArray *issuer;
 353   GTlsInteraction *interaction;
 354   GTlsDatabaseLookupFlags flags;
 355 } AsyncLookupCertificatesIssuedBy;
 356
 357 static void
 358 async_lookup_certificates_issued_by_free (gpointer data)
 359 {
 360   AsyncLookupCertificatesIssuedBy *args = data;
 361
 362   g_byte_array_unref (args->issuer);
 363   g_clear_object (&args->interaction);
 364   g_slice_free (AsyncLookupCertificatesIssuedBy, args);
 365 }
 366
 367 static void
 368 async_lookup_certificates_free_certificates (gpointer data)
 369 {
 370   GList *list = data;
 371
 372   g_list_free_full (list, g_object_unref);
 373 }
 374
 375 static void
 376 async_lookup_certificates_issued_by_thread (GTask         *task,
 377                                             gpointer       object,
 378                                             gpointer       task_data,
 379                                             GCancellable  *cancellable)
 380 {
 381   AsyncLookupCertificatesIssuedBy *args = task_data;
 382   GList *results;
 383   GError *error = NULL;
 384
 385   results = g_tls_database_lookup_certificates_issued_by (G_TLS_DATABASE (object),
 386                                                           args->issuer,
 387                                                           args->interaction,
 388                                                           args->flags,
 389                                                           cancellable,
 390                                                           &error);
 391   if (results)
 392     g_task_return_pointer (task, results, async_lookup_certificates_free_certificates);
 393   else
 394     g_task_return_error (task, error);
 395 }
 396
 397 static void
 398 g_tls_database_real_lookup_certificates_issued_by_async (GTlsDatabase           *self,
 399                                                          GByteArray             *issuer,
 400                                                          GTlsInteraction        *interaction,
 401                                                          GTlsDatabaseLookupFlags flags,
 402                                                          GCancellable           *cancellable,
 403                                                          GAsyncReadyCallback     callback,
 404                                                          gpointer                user_data)
 405 {
 406   GTask *task;
 407   AsyncLookupCertificatesIssuedBy *args;
 408
 409   args = g_slice_new0 (AsyncLookupCertificatesIssuedBy);
 410   args->issuer = g_byte_array_ref (issuer);
 411   args->flags = flags;
 412   args->interaction = interaction ? g_object_ref (interaction) : NULL;
 413
 414   task = g_task_new (self, cancellable, callback, user_data);
 415   g_task_set_source_tag (task,
 416                          g_tls_database_real_lookup_certificates_issued_by_async);
 417   g_task_set_name (task, "[gio] lookup certificates issued by");
 418   g_task_set_task_data (task, args, async_lookup_certificates_issued_by_free);
 419   g_task_run_in_thread (task, async_lookup_certificates_issued_by_thread);
 420   g_object_unref (task);
 421 }
 422
 423 static GList *
 424 g_tls_database_real_lookup_certificates_issued_by_finish (GTlsDatabase          *self,
 425                                                           GAsyncResult          *result,
 426                                                           GError               **error)
 427 {
 428   g_return_val_if_fail (g_task_is_valid (result, self), NULL);
 429
 430   return g_task_propagate_pointer (G_TASK (result), error);
 431 }
 432
 433 static void
 434 g_tls_database_class_init (GTlsDatabaseClass *klass)
 435 {
 436   klass->verify_chain_async = g_tls_database_real_verify_chain_async;
 437   klass->verify_chain_finish = g_tls_database_real_verify_chain_finish;
 438   klass->lookup_certificate_for_handle_async = g_tls_database_real_lookup_certificate_for_handle_async;
 439   klass->lookup_certificate_for_handle_finish = g_tls_database_real_lookup_certificate_for_handle_finish;
 440   klass->lookup_certificate_issuer_async = g_tls_database_real_lookup_certificate_issuer_async;
 441   klass->lookup_certificate_issuer_finish = g_tls_database_real_lookup_certificate_issuer_finish;
 442   klass->lookup_certificates_issued_by_async = g_tls_database_real_lookup_certificates_issued_by_async;
 443   klass->lookup_certificates_issued_by_finish = g_tls_database_real_lookup_certificates_issued_by_finish;
 444 }
 445
 446 /**
 447  * g_tls_database_verify_chain:
 448  * @self: a #GTlsDatabase
 449  * @chain: a #GTlsCertificate chain
 450  * @purpose: the purpose that this certificate chain will be used for.
 451  * @identity: (nullable): the expected peer identity
 452  * @interaction: (nullable): used to interact with the user if necessary
 453  * @flags: additional verify flags
 454  * @cancellable: (nullable): a #GCancellable, or %NULL
 455  * @error: (nullable): a #GError, or %NULL
 456  *
 457  * Determines the validity of a certificate chain, outside the context
 458  * of a TLS session.
 459  *
 460  * @chain is a chain of #GTlsCertificate objects each pointing to the next
 461  * certificate in the chain by its #GTlsCertificate:issuer property.
 462  *
 463  * @purpose describes the purpose (or usage) for which the certificate
 464  * is being used. Typically @purpose will be set to %G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
 465  * which means that the certificate is being used to authenticate a server
 466  * (and we are acting as the client).
 467  *
 468  * The @identity is used to ensure the server certificate is valid for
 469  * the expected peer identity. If the identity does not match the
 470  * certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the
 471  * return value. If @identity is %NULL, that bit will never be set in
 472  * the return value. The peer identity may also be used to check for
 473  * pinned certificates (trust exceptions) in the database. These may
 474  * override the normal verification process on a host-by-host basis.
 475  *
 476  * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
 477  * used.
 478  *
 479  * If @chain is found to be valid, then the return value will be 0. If
 480  * @chain is found to be invalid, then the return value will indicate at
 481  * least one problem found. If the function is unable to determine
 482  * whether @chain is valid (for example, because @cancellable is
 483  * triggered before it completes) then the return value will be
 484  * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set accordingly.
 485  * @error is not set when @chain is successfully analyzed but found to
 486  * be invalid.
 487  *
 488  * GLib guarantees that if certificate verification fails, at least one
 489  * error will be set in the return value, but it does not guarantee
 490  * that all possible errors will be set. Accordingly, you may not safely
 491  * decide to ignore any particular type of error. For example, it would
 492  * be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow
 493  * expired certificates, because this could potentially be the only
 494  * error flag set even if other problems exist with the certificate.
 495  *
 496  * Prior to GLib 2.48, GLib's default TLS backend modified @chain to
 497  * represent the certification path built by #GTlsDatabase during
 498  * certificate verification by adjusting the #GTlsCertificate:issuer
 499  * property of each certificate in @chain. Since GLib 2.48, this no
 500  * longer occurs, so you cannot rely on #GTlsCertificate:issuer to
 501  * represent the actual certification path used during certificate
 502  * verification.
 503  *
 504  * Because TLS session context is not used, #GTlsDatabase may not
 505  * perform as many checks on the certificates as #GTlsConnection would.
 506  * For example, certificate constraints may not be honored, and
 507  * revocation checks may not be performed. The best way to verify TLS
 508  * certificates used by a TLS connection is to let #GTlsConnection
 509  * handle the verification.
 510  *
 511  * The TLS backend may attempt to look up and add missing certificates
 512  * to the chain. This may involve HTTP requests to download missing
 513  * certificates.
 514  *
 515  * This function can block. Use g_tls_database_verify_chain_async() to
 516  * perform the verification operation asynchronously.
 517  *
 518  * Returns: the appropriate #GTlsCertificateFlags which represents the
 519  * result of verification.
 520  *
 521  * Since: 2.30
 522  */
 523 GTlsCertificateFlags
 524 g_tls_database_verify_chain (GTlsDatabase           *self,
 525                              GTlsCertificate        *chain,
 526                              const gchar            *purpose,
 527                              GSocketConnectable     *identity,
 528                              GTlsInteraction        *interaction,
 529                              GTlsDatabaseVerifyFlags flags,
 530                              GCancellable           *cancellable,
 531                              GError                **error)
 532 {
 533   g_return_val_if_fail (G_IS_TLS_DATABASE (self), G_TLS_CERTIFICATE_GENERIC_ERROR);
 534   g_return_val_if_fail (G_IS_TLS_CERTIFICATE (chain),
 535                         G_TLS_CERTIFICATE_GENERIC_ERROR);
 536   g_return_val_if_fail (purpose, G_TLS_CERTIFICATE_GENERIC_ERROR);
 537   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction),
 538                         G_TLS_CERTIFICATE_GENERIC_ERROR);
 539   g_return_val_if_fail (identity == NULL || G_IS_SOCKET_CONNECTABLE (identity),
 540                         G_TLS_CERTIFICATE_GENERIC_ERROR);
 541   g_return_val_if_fail (error == NULL || *error == NULL, G_TLS_CERTIFICATE_GENERIC_ERROR);
 542
 543   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->verify_chain,
 544                         G_TLS_CERTIFICATE_GENERIC_ERROR);
 545
 546   return G_TLS_DATABASE_GET_CLASS (self)->verify_chain (self,
 547                                                         chain,
 548                                                         purpose,
 549                                                         identity,
 550                                                         interaction,
 551                                                         flags,
 552                                                         cancellable,
 553                                                         error);
 554 }
 555
 556 /**
 557  * g_tls_database_verify_chain_async:
 558  * @self: a #GTlsDatabase
 559  * @chain: a #GTlsCertificate chain
 560  * @purpose: the purpose that this certificate chain will be used for.
 561  * @identity: (nullable): the expected peer identity
 562  * @interaction: (nullable): used to interact with the user if necessary
 563  * @flags: additional verify flags
 564  * @cancellable: (nullable): a #GCancellable, or %NULL
 565  * @callback: callback to call when the operation completes
 566  * @user_data: the data to pass to the callback function
 567  *
 568  * Asynchronously determines the validity of a certificate chain after
 569  * looking up and adding any missing certificates to the chain. See
 570  * g_tls_database_verify_chain() for more information.
 571  *
 572  * Since: 2.30
 573  */
 574 void
 575 g_tls_database_verify_chain_async (GTlsDatabase           *self,
 576                                    GTlsCertificate        *chain,
 577                                    const gchar            *purpose,
 578                                    GSocketConnectable     *identity,
 579                                    GTlsInteraction        *interaction,
 580                                    GTlsDatabaseVerifyFlags flags,
 581                                    GCancellable           *cancellable,
 582                                    GAsyncReadyCallback     callback,
 583                                    gpointer                user_data)
 584 {
 585   g_return_if_fail (G_IS_TLS_DATABASE (self));
 586   g_return_if_fail (G_IS_TLS_CERTIFICATE (chain));
 587   g_return_if_fail (purpose != NULL);
 588   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
 589   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 590   g_return_if_fail (identity == NULL || G_IS_SOCKET_CONNECTABLE (identity));
 591   g_return_if_fail (callback != NULL);
 592
 593   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->verify_chain_async);
 594   G_TLS_DATABASE_GET_CLASS (self)->verify_chain_async (self,
 595                                                        chain,
 596                                                        purpose,
 597                                                        identity,
 598                                                        interaction,
 599                                                        flags,
 600                                                        cancellable,
 601                                                        callback,
 602                                                        user_data);
 603 }
 604
 605 /**
 606  * g_tls_database_verify_chain_finish:
 607  * @self: a #GTlsDatabase
 608  * @result: a #GAsyncResult.
 609  * @error: a #GError pointer, or %NULL
 610  *
 611  * Finish an asynchronous verify chain operation. See
 612  * g_tls_database_verify_chain() for more information.
 613  *
 614  * If @chain is found to be valid, then the return value will be 0. If
 615  * @chain is found to be invalid, then the return value will indicate
 616  * the problems found. If the function is unable to determine whether
 617  * @chain is valid or not (eg, because @cancellable is triggered
 618  * before it completes) then the return value will be
 619  * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set
 620  * accordingly. @error is not set when @chain is successfully analyzed
 621  * but found to be invalid.
 622  *
 623  * Returns: the appropriate #GTlsCertificateFlags which represents the
 624  * result of verification.
 625  *
 626  * Since: 2.30
 627  */
 628 GTlsCertificateFlags
 629 g_tls_database_verify_chain_finish (GTlsDatabase          *self,
 630                                     GAsyncResult          *result,
 631                                     GError               **error)
 632 {
 633   g_return_val_if_fail (G_IS_TLS_DATABASE (self), G_TLS_CERTIFICATE_GENERIC_ERROR);
 634   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), G_TLS_CERTIFICATE_GENERIC_ERROR);
 635   g_return_val_if_fail (error == NULL || *error == NULL, G_TLS_CERTIFICATE_GENERIC_ERROR);
 636   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->verify_chain_finish,
 637                         G_TLS_CERTIFICATE_GENERIC_ERROR);
 638   return G_TLS_DATABASE_GET_CLASS (self)->verify_chain_finish (self,
 639                                                                result,
 640                                                                error);
 641 }
 642
 643 /**
 644  * g_tls_database_create_certificate_handle:
 645  * @self: a #GTlsDatabase
 646  * @certificate: certificate for which to create a handle.
 647  *
 648  * Create a handle string for the certificate. The database will only be able
 649  * to create a handle for certificates that originate from the database. In
 650  * cases where the database cannot create a handle for a certificate, %NULL
 651  * will be returned.
 652  *
 653  * This handle should be stable across various instances of the application,
 654  * and between applications. If a certificate is modified in the database,
 655  * then it is not guaranteed that this handle will continue to point to it.
 656  *
 657  * Returns: (nullable): a newly allocated string containing the
 658  * handle.
 659  *
 660  * Since: 2.30
 661  */
 662 gchar*
 663 g_tls_database_create_certificate_handle (GTlsDatabase            *self,
 664                                           GTlsCertificate         *certificate)
 665 {
 666   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 667   g_return_val_if_fail (G_IS_TLS_CERTIFICATE (certificate), NULL);
 668   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->create_certificate_handle, NULL);
 669   return G_TLS_DATABASE_GET_CLASS (self)->create_certificate_handle (self,
 670                                                                      certificate);
 671 }
 672
 673 /**
 674  * g_tls_database_lookup_certificate_for_handle:
 675  * @self: a #GTlsDatabase
 676  * @handle: a certificate handle
 677  * @interaction: (nullable): used to interact with the user if necessary
 678  * @flags: Flags which affect the lookup.
 679  * @cancellable: (nullable): a #GCancellable, or %NULL
 680  * @error: (nullable): a #GError, or %NULL
 681  *
 682  * Look up a certificate by its handle.
 683  *
 684  * The handle should have been created by calling
 685  * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
 686  * the same TLS backend. The handle is designed to remain valid across
 687  * instantiations of the database.
 688  *
 689  * If the handle is no longer valid, or does not point to a certificate in
 690  * this database, then %NULL will be returned.
 691  *
 692  * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
 693  * the lookup operation asynchronously.
 694  *
 695  * Returns: (transfer full) (nullable): a newly allocated
 696  * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
 697  *
 698  * Since: 2.30
 699  */
 700 GTlsCertificate*
 701 g_tls_database_lookup_certificate_for_handle (GTlsDatabase            *self,
 702                                               const gchar             *handle,
 703                                               GTlsInteraction         *interaction,
 704                                               GTlsDatabaseLookupFlags  flags,
 705                                               GCancellable            *cancellable,
 706                                               GError                 **error)
 707 {
 708   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 709   g_return_val_if_fail (handle != NULL, NULL);
 710   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction), NULL);
 711   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 712   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 713   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle, NULL);
 714   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle (self,
 715                                                                          handle,
 716                                                                          interaction,
 717                                                                          flags,
 718                                                                          cancellable,
 719                                                                          error);
 720 }
 721
 722
 723 /**
 724  * g_tls_database_lookup_certificate_for_handle_async:
 725  * @self: a #GTlsDatabase
 726  * @handle: a certificate handle
 727  * @interaction: (nullable): used to interact with the user if necessary
 728  * @flags: Flags which affect the lookup.
 729  * @cancellable: (nullable): a #GCancellable, or %NULL
 730  * @callback: callback to call when the operation completes
 731  * @user_data: the data to pass to the callback function
 732  *
 733  * Asynchronously look up a certificate by its handle in the database. See
 734  * g_tls_database_lookup_certificate_for_handle() for more information.
 735  *
 736  * Since: 2.30
 737  */
 738 void
 739 g_tls_database_lookup_certificate_for_handle_async (GTlsDatabase            *self,
 740                                                     const gchar             *handle,
 741                                                     GTlsInteraction         *interaction,
 742                                                     GTlsDatabaseLookupFlags  flags,
 743                                                     GCancellable            *cancellable,
 744                                                     GAsyncReadyCallback      callback,
 745                                                     gpointer                 user_data)
 746 {
 747   g_return_if_fail (G_IS_TLS_DATABASE (self));
 748   g_return_if_fail (handle != NULL);
 749   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
 750   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 751   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_async);
 752   G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_async (self,
 753                                                                                handle,
 754                                                                                interaction,
 755                                                                                flags,
 756                                                                                cancellable,
 757                                                                                callback,
 758                                                                                user_data);
 759 }
 760
 761 /**
 762  * g_tls_database_lookup_certificate_for_handle_finish:
 763  * @self: a #GTlsDatabase
 764  * @result: a #GAsyncResult.
 765  * @error: a #GError pointer, or %NULL
 766  *
 767  * Finish an asynchronous lookup of a certificate by its handle. See
 768  * g_tls_database_lookup_certificate_for_handle() for more information.
 769  *
 770  * If the handle is no longer valid, or does not point to a certificate in
 771  * this database, then %NULL will be returned.
 772  *
 773  * Returns: (transfer full): a newly allocated #GTlsCertificate object.
 774  * Use g_object_unref() to release the certificate.
 775  *
 776  * Since: 2.30
 777  */
 778 GTlsCertificate*
 779 g_tls_database_lookup_certificate_for_handle_finish (GTlsDatabase            *self,
 780                                                      GAsyncResult            *result,
 781                                                      GError                 **error)
 782 {
 783   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 784   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
 785   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 786   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_finish, NULL);
 787   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_finish (self,
 788                                                                                 result,
 789                                                                                 error);
 790 }
 791
 792 /**
 793  * g_tls_database_lookup_certificate_issuer:
 794  * @self: a #GTlsDatabase
 795  * @certificate: a #GTlsCertificate
 796  * @interaction: (nullable): used to interact with the user if necessary
 797  * @flags: flags which affect the lookup operation
 798  * @cancellable: (nullable): a #GCancellable, or %NULL
 799  * @error: (nullable): a #GError, or %NULL
 800  *
 801  * Look up the issuer of @certificate in the database. The
 802  * #GTlsCertificate:issuer property of @certificate is not modified, and
 803  * the two certificates are not hooked into a chain.
 804  *
 805  * This function can block. Use g_tls_database_lookup_certificate_issuer_async()
 806  * to perform the lookup operation asynchronously.
 807  *
 808  * Beware this function cannot be used to build certification paths. The
 809  * issuer certificate returned by this function may not be the same as
 810  * the certificate that would actually be used to construct a valid
 811  * certification path during certificate verification.
 812  * [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains
 813  * why an issuer certificate cannot be naively assumed to be part of the
 814  * the certification path (though GLib's TLS backends may not follow the
 815  * path building strategies outlined in this RFC). Due to the complexity
 816  * of certification path building, GLib does not provide any way to know
 817  * which certification path will actually be used when verifying a TLS
 818  * certificate. Accordingly, this function cannot be used to make
 819  * security-related decisions. Only GLib itself should make security
 820  * decisions about TLS certificates.
 821  *
 822  * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
 823  * or %NULL. Use g_object_unref() to release the certificate.
 824  *
 825  * Since: 2.30
 826  */
 827 GTlsCertificate*
 828 g_tls_database_lookup_certificate_issuer (GTlsDatabase           *self,
 829                                           GTlsCertificate        *certificate,
 830                                           GTlsInteraction        *interaction,
 831                                           GTlsDatabaseLookupFlags flags,
 832                                           GCancellable           *cancellable,
 833                                           GError                **error)
 834 {
 835   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 836   g_return_val_if_fail (G_IS_TLS_CERTIFICATE (certificate), NULL);
 837   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction), NULL);
 838   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 839   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 840   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer, NULL);
 841   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer (self,
 842                                                                      certificate,
 843                                                                      interaction,
 844                                                                      flags,
 845                                                                      cancellable,
 846                                                                      error);
 847 }
 848
 849 /**
 850  * g_tls_database_lookup_certificate_issuer_async:
 851  * @self: a #GTlsDatabase
 852  * @certificate: a #GTlsCertificate
 853  * @interaction: (nullable): used to interact with the user if necessary
 854  * @flags: flags which affect the lookup operation
 855  * @cancellable: (nullable): a #GCancellable, or %NULL
 856  * @callback: callback to call when the operation completes
 857  * @user_data: the data to pass to the callback function
 858  *
 859  * Asynchronously look up the issuer of @certificate in the database. See
 860  * g_tls_database_lookup_certificate_issuer() for more information.
 861  *
 862  * Since: 2.30
 863  */
 864 void
 865 g_tls_database_lookup_certificate_issuer_async (GTlsDatabase           *self,
 866                                                 GTlsCertificate        *certificate,
 867                                                 GTlsInteraction        *interaction,
 868                                                 GTlsDatabaseLookupFlags flags,
 869                                                 GCancellable           *cancellable,
 870                                                 GAsyncReadyCallback     callback,
 871                                                 gpointer                user_data)
 872 {
 873   g_return_if_fail (G_IS_TLS_DATABASE (self));
 874   g_return_if_fail (G_IS_TLS_CERTIFICATE (certificate));
 875   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
 876   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 877   g_return_if_fail (callback != NULL);
 878   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_async);
 879   G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_async (self,
 880                                                         certificate,
 881                                                         interaction,
 882                                                         flags,
 883                                                         cancellable,
 884                                                         callback,
 885                                                         user_data);
 886 }
 887
 888 /**
 889  * g_tls_database_lookup_certificate_issuer_finish:
 890  * @self: a #GTlsDatabase
 891  * @result: a #GAsyncResult.
 892  * @error: a #GError pointer, or %NULL
 893  *
 894  * Finish an asynchronous lookup issuer operation. See
 895  * g_tls_database_lookup_certificate_issuer() for more information.
 896  *
 897  * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
 898  * or %NULL. Use g_object_unref() to release the certificate.
 899  *
 900  * Since: 2.30
 901  */
 902 GTlsCertificate*
 903 g_tls_database_lookup_certificate_issuer_finish (GTlsDatabase          *self,
 904                                                  GAsyncResult          *result,
 905                                                  GError               **error)
 906 {
 907   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 908   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
 909   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 910   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_finish, NULL);
 911   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_finish (self,
 912                                                                 result,
 913                                                                 error);
 914 }
 915
 916 /**
 917  * g_tls_database_lookup_certificates_issued_by:
 918  * @self: a #GTlsDatabase
 919  * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
 920  * @interaction: (nullable): used to interact with the user if necessary
 921  * @flags: Flags which affect the lookup operation.
 922  * @cancellable: (nullable): a #GCancellable, or %NULL
 923  * @error: (nullable): a #GError, or %NULL
 924  *
 925  * Look up certificates issued by this issuer in the database.
 926  *
 927  * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
 928  * the lookup operation asynchronously.
 929  *
 930  * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
 931  * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
 932  *
 933  * Since: 2.30
 934  */
 935 GList*
 936 g_tls_database_lookup_certificates_issued_by (GTlsDatabase           *self,
 937                                               GByteArray             *issuer_raw_dn,
 938                                               GTlsInteraction        *interaction,
 939                                               GTlsDatabaseLookupFlags flags,
 940                                               GCancellable           *cancellable,
 941                                               GError                **error)
 942 {
 943   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 944   g_return_val_if_fail (issuer_raw_dn, NULL);
 945   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction), NULL);
 946   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 947   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 948   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by, NULL);
 949   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by (self,
 950                                                                          issuer_raw_dn,
 951                                                                          interaction,
 952                                                                          flags,
 953                                                                          cancellable,
 954                                                                          error);
 955 }
 956
 957 /**
 958  * g_tls_database_lookup_certificates_issued_by_async:
 959  * @self: a #GTlsDatabase
 960  * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
 961  * @interaction: (nullable): used to interact with the user if necessary
 962  * @flags: Flags which affect the lookup operation.
 963  * @cancellable: (nullable): a #GCancellable, or %NULL
 964  * @callback: callback to call when the operation completes
 965  * @user_data: the data to pass to the callback function
 966  *
 967  * Asynchronously look up certificates issued by this issuer in the database. See
 968  * g_tls_database_lookup_certificates_issued_by() for more information.
 969  *
 970  * The database may choose to hold a reference to the issuer byte array for the duration
 971  * of this asynchronous operation. The byte array should not be modified during
 972  * this time.
 973  *
 974  * Since: 2.30
 975  */
 976 void
 977 g_tls_database_lookup_certificates_issued_by_async (GTlsDatabase           *self,
 978                                                     GByteArray             *issuer_raw_dn,
 979                                                     GTlsInteraction        *interaction,
 980                                                     GTlsDatabaseLookupFlags flags,
 981                                                     GCancellable           *cancellable,
 982                                                     GAsyncReadyCallback     callback,
 983                                                     gpointer                user_data)
 984 {
 985   g_return_if_fail (G_IS_TLS_DATABASE (self));
 986   g_return_if_fail (issuer_raw_dn != NULL);
 987   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
 988   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 989   g_return_if_fail (callback != NULL);
 990   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_async);
 991   G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_async (self,
 992                                                                         issuer_raw_dn,
 993                                                                         interaction,
 994                                                                         flags,
 995                                                                         cancellable,
 996                                                                         callback,
 997                                                                         user_data);
 998 }
 999
1000 /**
1001  * g_tls_database_lookup_certificates_issued_by_finish:
1002  * @self: a #GTlsDatabase
1003  * @result: a #GAsyncResult.
1004  * @error: a #GError pointer, or %NULL
1005  *
1006  * Finish an asynchronous lookup of certificates. See
1007  * g_tls_database_lookup_certificates_issued_by() for more information.
1008  *
1009  * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
1010  * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
1011  *
1012  * Since: 2.30
1013  */
1014 GList*
1015 g_tls_database_lookup_certificates_issued_by_finish (GTlsDatabase          *self,
1016                                                      GAsyncResult          *result,
1017                                                      GError               **error)
1018 {
1019   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
1020   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
1021   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
1022   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_finish, NULL);
1023   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_finish (self,
1024                                                                                 result,
1025                                                                                 error);
1026 }