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