gio/gtlsdatabase.c

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