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  * Verify's a certificate chain after looking up and adding any missing
 459  * 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  * This function can block, use g_tls_database_verify_chain_async() to perform
 481  * the verification operation asynchronously.
 482  *
 483  * Returns: the appropriate #GTlsCertificateFlags which represents the
 484  * result of verification.
 485  *
 486  * Since: 2.30
 487  */
 488 GTlsCertificateFlags
 489 g_tls_database_verify_chain (GTlsDatabase           *self,
 490                              GTlsCertificate        *chain,
 491                              const gchar            *purpose,
 492                              GSocketConnectable     *identity,
 493                              GTlsInteraction        *interaction,
 494                              GTlsDatabaseVerifyFlags flags,
 495                              GCancellable           *cancellable,
 496                              GError                **error)
 497 {
 498   g_return_val_if_fail (G_IS_TLS_DATABASE (self), G_TLS_CERTIFICATE_GENERIC_ERROR);
 499   g_return_val_if_fail (G_IS_TLS_DATABASE (self),
 500                         G_TLS_CERTIFICATE_GENERIC_ERROR);
 501   g_return_val_if_fail (G_IS_TLS_CERTIFICATE (chain),
 502                         G_TLS_CERTIFICATE_GENERIC_ERROR);
 503   g_return_val_if_fail (purpose, G_TLS_CERTIFICATE_GENERIC_ERROR);
 504   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction),
 505                         G_TLS_CERTIFICATE_GENERIC_ERROR);
 506   g_return_val_if_fail (identity == NULL || G_IS_SOCKET_CONNECTABLE (identity),
 507                         G_TLS_CERTIFICATE_GENERIC_ERROR);
 508   g_return_val_if_fail (error == NULL || *error == NULL, G_TLS_CERTIFICATE_GENERIC_ERROR);
 509
 510   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->verify_chain,
 511                         G_TLS_CERTIFICATE_GENERIC_ERROR);
 512
 513   return G_TLS_DATABASE_GET_CLASS (self)->verify_chain (self,
 514                                                         chain,
 515                                                         purpose,
 516                                                         identity,
 517                                                         interaction,
 518                                                         flags,
 519                                                         cancellable,
 520                                                         error);
 521 }
 522
 523 /**
 524  * g_tls_database_verify_chain_async:
 525  * @self: a #GTlsDatabase
 526  * @chain: a #GTlsCertificate chain
 527  * @purpose: the purpose that this certificate chain will be used for.
 528  * @identity: (nullable): the expected peer identity
 529  * @interaction: (nullable): used to interact with the user if necessary
 530  * @flags: additional verify flags
 531  * @cancellable: (nullable): a #GCancellable, or %NULL
 532  * @callback: callback to call when the operation completes
 533  * @user_data: the data to pass to the callback function
 534  *
 535  * Asynchronously verify's a certificate chain after looking up and adding
 536  * any missing certificates to the chain. See g_tls_database_verify_chain()
 537  * for more information.
 538  *
 539  * Since: 2.30
 540  */
 541 void
 542 g_tls_database_verify_chain_async (GTlsDatabase           *self,
 543                                    GTlsCertificate        *chain,
 544                                    const gchar            *purpose,
 545                                    GSocketConnectable     *identity,
 546                                    GTlsInteraction        *interaction,
 547                                    GTlsDatabaseVerifyFlags flags,
 548                                    GCancellable           *cancellable,
 549                                    GAsyncReadyCallback     callback,
 550                                    gpointer                user_data)
 551 {
 552   g_return_if_fail (G_IS_TLS_DATABASE (self));
 553   g_return_if_fail (G_IS_TLS_CERTIFICATE (chain));
 554   g_return_if_fail (purpose != NULL);
 555   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
 556   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 557   g_return_if_fail (identity == NULL || G_IS_SOCKET_CONNECTABLE (identity));
 558   g_return_if_fail (callback != NULL);
 559
 560   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->verify_chain_async);
 561   G_TLS_DATABASE_GET_CLASS (self)->verify_chain_async (self,
 562                                                        chain,
 563                                                        purpose,
 564                                                        identity,
 565                                                        interaction,
 566                                                        flags,
 567                                                        cancellable,
 568                                                        callback,
 569                                                        user_data);
 570 }
 571
 572 /**
 573  * g_tls_database_verify_chain_finish:
 574  * @self: a #GTlsDatabase
 575  * @result: a #GAsyncResult.
 576  * @error: a #GError pointer, or %NULL
 577  *
 578  * Finish an asynchronous verify chain operation. See
 579  * g_tls_database_verify_chain() for more information. *
 580  * Returns: the appropriate #GTlsCertificateFlags which represents the
 581  * result of verification.
 582  *
 583  * Since: 2.30
 584  */
 585 GTlsCertificateFlags
 586 g_tls_database_verify_chain_finish (GTlsDatabase          *self,
 587                                     GAsyncResult          *result,
 588                                     GError               **error)
 589 {
 590   g_return_val_if_fail (G_IS_TLS_DATABASE (self), G_TLS_CERTIFICATE_GENERIC_ERROR);
 591   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), G_TLS_CERTIFICATE_GENERIC_ERROR);
 592   g_return_val_if_fail (error == NULL || *error == NULL, G_TLS_CERTIFICATE_GENERIC_ERROR);
 593   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->verify_chain_finish,
 594                         G_TLS_CERTIFICATE_GENERIC_ERROR);
 595   return G_TLS_DATABASE_GET_CLASS (self)->verify_chain_finish (self,
 596                                                                result,
 597                                                                error);
 598 }
 599
 600 /**
 601  * g_tls_database_create_certificate_handle:
 602  * @self: a #GTlsDatabase
 603  * @certificate: certificate for which to create a handle.
 604  *
 605  * Create a handle string for the certificate. The database will only be able
 606  * to create a handle for certificates that originate from the database. In
 607  * cases where the database cannot create a handle for a certificate, %NULL
 608  * will be returned.
 609  *
 610  * This handle should be stable across various instances of the application,
 611  * and between applications. If a certificate is modified in the database,
 612  * then it is not guaranteed that this handle will continue to point to it.
 613  *
 614  * Returns: (nullable): a newly allocated string containing the
 615  * handle.
 616  *
 617  * Since: 2.30
 618  */
 619 gchar*
 620 g_tls_database_create_certificate_handle (GTlsDatabase            *self,
 621                                           GTlsCertificate         *certificate)
 622 {
 623   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 624   g_return_val_if_fail (G_IS_TLS_CERTIFICATE (certificate), NULL);
 625   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->create_certificate_handle, NULL);
 626   return G_TLS_DATABASE_GET_CLASS (self)->create_certificate_handle (self,
 627                                                                      certificate);
 628 }
 629
 630 /**
 631  * g_tls_database_lookup_certificate_for_handle:
 632  * @self: a #GTlsDatabase
 633  * @handle: a certificate handle
 634  * @interaction: (nullable): used to interact with the user if necessary
 635  * @flags: Flags which affect the lookup.
 636  * @cancellable: (nullable): a #GCancellable, or %NULL
 637  * @error: (nullable): a #GError, or %NULL
 638  *
 639  * Lookup a certificate by its handle.
 640  *
 641  * The handle should have been created by calling
 642  * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
 643  * the same TLS backend. The handle is designed to remain valid across
 644  * instantiations of the database.
 645  *
 646  * If the handle is no longer valid, or does not point to a certificate in
 647  * this database, then %NULL will be returned.
 648  *
 649  * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
 650  * the lookup operation asynchronously.
 651  *
 652  * Returns: (transfer full) (nullable): a newly allocated
 653  * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
 654  *
 655  * Since: 2.30
 656  */
 657 GTlsCertificate*
 658 g_tls_database_lookup_certificate_for_handle (GTlsDatabase            *self,
 659                                               const gchar             *handle,
 660                                               GTlsInteraction         *interaction,
 661                                               GTlsDatabaseLookupFlags  flags,
 662                                               GCancellable            *cancellable,
 663                                               GError                 **error)
 664 {
 665   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 666   g_return_val_if_fail (handle != NULL, NULL);
 667   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction), NULL);
 668   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 669   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 670   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle, NULL);
 671   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle (self,
 672                                                                          handle,
 673                                                                          interaction,
 674                                                                          flags,
 675                                                                          cancellable,
 676                                                                          error);
 677 }
 678
 679
 680 /**
 681  * g_tls_database_lookup_certificate_for_handle_async:
 682  * @self: a #GTlsDatabase
 683  * @handle: a certificate handle
 684  * @interaction: (nullable): used to interact with the user if necessary
 685  * @flags: Flags which affect the lookup.
 686  * @cancellable: (nullable): a #GCancellable, or %NULL
 687  * @callback: callback to call when the operation completes
 688  * @user_data: the data to pass to the callback function
 689  *
 690  * Asynchronously lookup a certificate by its handle in the database. See
 691  * g_tls_database_lookup_certificate_for_handle() for more information.
 692  *
 693  * Since: 2.30
 694  */
 695 void
 696 g_tls_database_lookup_certificate_for_handle_async (GTlsDatabase            *self,
 697                                                     const gchar             *handle,
 698                                                     GTlsInteraction         *interaction,
 699                                                     GTlsDatabaseLookupFlags  flags,
 700                                                     GCancellable            *cancellable,
 701                                                     GAsyncReadyCallback      callback,
 702                                                     gpointer                 user_data)
 703 {
 704   g_return_if_fail (G_IS_TLS_DATABASE (self));
 705   g_return_if_fail (handle != NULL);
 706   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
 707   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 708   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_async);
 709   G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_async (self,
 710                                                                                handle,
 711                                                                                interaction,
 712                                                                                flags,
 713                                                                                cancellable,
 714                                                                                callback,
 715                                                                                user_data);
 716 }
 717
 718 /**
 719  * g_tls_database_lookup_certificate_for_handle_finish:
 720  * @self: a #GTlsDatabase
 721  * @result: a #GAsyncResult.
 722  * @error: a #GError pointer, or %NULL
 723  *
 724  * Finish an asynchronous lookup of a certificate by its handle. See
 725  * g_tls_database_lookup_certificate_handle() for more information.
 726  *
 727  * If the handle is no longer valid, or does not point to a certificate in
 728  * this database, then %NULL will be returned.
 729  *
 730  * Returns: (transfer full): a newly allocated #GTlsCertificate object.
 731  * Use g_object_unref() to release the certificate.
 732  *
 733  * Since: 2.30
 734  */
 735 GTlsCertificate*
 736 g_tls_database_lookup_certificate_for_handle_finish (GTlsDatabase            *self,
 737                                                      GAsyncResult            *result,
 738                                                      GError                 **error)
 739 {
 740   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 741   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
 742   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 743   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_finish, NULL);
 744   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_for_handle_finish (self,
 745                                                                                 result,
 746                                                                                 error);
 747 }
 748
 749 /**
 750  * g_tls_database_lookup_certificate_issuer:
 751  * @self: a #GTlsDatabase
 752  * @certificate: a #GTlsCertificate
 753  * @interaction: (nullable): used to interact with the user if necessary
 754  * @flags: flags which affect the lookup operation
 755  * @cancellable: (nullable): a #GCancellable, or %NULL
 756  * @error: (nullable): a #GError, or %NULL
 757  *
 758  * Lookup the issuer of @certificate in the database.
 759  *
 760  * The %issuer property
 761  * of @certificate is not modified, and the two certificates are not hooked
 762  * into a chain.
 763  *
 764  * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
 765  * the lookup operation asynchronously.
 766  *
 767  * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
 768  * or %NULL. Use g_object_unref() to release the certificate.
 769  *
 770  * Since: 2.30
 771  */
 772 GTlsCertificate*
 773 g_tls_database_lookup_certificate_issuer (GTlsDatabase           *self,
 774                                           GTlsCertificate        *certificate,
 775                                           GTlsInteraction        *interaction,
 776                                           GTlsDatabaseLookupFlags flags,
 777                                           GCancellable           *cancellable,
 778                                           GError                **error)
 779 {
 780   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 781   g_return_val_if_fail (G_IS_TLS_CERTIFICATE (certificate), NULL);
 782   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction), NULL);
 783   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 784   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 785   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer, NULL);
 786   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer (self,
 787                                                                      certificate,
 788                                                                      interaction,
 789                                                                      flags,
 790                                                                      cancellable,
 791                                                                      error);
 792 }
 793
 794 /**
 795  * g_tls_database_lookup_certificate_issuer_async:
 796  * @self: a #GTlsDatabase
 797  * @certificate: a #GTlsCertificate
 798  * @interaction: (nullable): used to interact with the user if necessary
 799  * @flags: flags which affect the lookup operation
 800  * @cancellable: (nullable): a #GCancellable, or %NULL
 801  * @callback: callback to call when the operation completes
 802  * @user_data: the data to pass to the callback function
 803  *
 804  * Asynchronously lookup the issuer of @certificate in the database. See
 805  * g_tls_database_lookup_certificate_issuer() for more information.
 806  *
 807  * Since: 2.30
 808  */
 809 void
 810 g_tls_database_lookup_certificate_issuer_async (GTlsDatabase           *self,
 811                                                 GTlsCertificate        *certificate,
 812                                                 GTlsInteraction        *interaction,
 813                                                 GTlsDatabaseLookupFlags flags,
 814                                                 GCancellable           *cancellable,
 815                                                 GAsyncReadyCallback     callback,
 816                                                 gpointer                user_data)
 817 {
 818   g_return_if_fail (G_IS_TLS_DATABASE (self));
 819   g_return_if_fail (G_IS_TLS_CERTIFICATE (certificate));
 820   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
 821   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 822   g_return_if_fail (callback != NULL);
 823   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_async);
 824   G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_async (self,
 825                                                         certificate,
 826                                                         interaction,
 827                                                         flags,
 828                                                         cancellable,
 829                                                         callback,
 830                                                         user_data);
 831 }
 832
 833 /**
 834  * g_tls_database_lookup_certificate_issuer_finish:
 835  * @self: a #GTlsDatabase
 836  * @result: a #GAsyncResult.
 837  * @error: a #GError pointer, or %NULL
 838  *
 839  * Finish an asynchronous lookup issuer operation. See
 840  * g_tls_database_lookup_certificate_issuer() for more information.
 841  *
 842  * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
 843  * or %NULL. Use g_object_unref() to release the certificate.
 844  *
 845  * Since: 2.30
 846  */
 847 GTlsCertificate*
 848 g_tls_database_lookup_certificate_issuer_finish (GTlsDatabase          *self,
 849                                                  GAsyncResult          *result,
 850                                                  GError               **error)
 851 {
 852   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 853   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
 854   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 855   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_finish, NULL);
 856   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificate_issuer_finish (self,
 857                                                                 result,
 858                                                                 error);
 859 }
 860
 861 /**
 862  * g_tls_database_lookup_certificates_issued_by:
 863  * @self: a #GTlsDatabase
 864  * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
 865  * @interaction: (nullable): used to interact with the user if necessary
 866  * @flags: Flags which affect the lookup operation.
 867  * @cancellable: (nullable): a #GCancellable, or %NULL
 868  * @error: (nullable): a #GError, or %NULL
 869  *
 870  * Lookup certificates issued by this issuer in the database.
 871  *
 872  * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
 873  * the lookup operation asynchronously.
 874  *
 875  * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
 876  * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
 877  *
 878  * Since: 2.30
 879  */
 880 GList*
 881 g_tls_database_lookup_certificates_issued_by (GTlsDatabase           *self,
 882                                               GByteArray             *issuer_raw_dn,
 883                                               GTlsInteraction        *interaction,
 884                                               GTlsDatabaseLookupFlags flags,
 885                                               GCancellable           *cancellable,
 886                                               GError                **error)
 887 {
 888   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 889   g_return_val_if_fail (issuer_raw_dn, NULL);
 890   g_return_val_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction), NULL);
 891   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 892   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 893   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by, NULL);
 894   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by (self,
 895                                                                          issuer_raw_dn,
 896                                                                          interaction,
 897                                                                          flags,
 898                                                                          cancellable,
 899                                                                          error);
 900 }
 901
 902 /**
 903  * g_tls_database_lookup_certificates_issued_by_async:
 904  * @self: a #GTlsDatabase
 905  * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
 906  * @interaction: (nullable): used to interact with the user if necessary
 907  * @flags: Flags which affect the lookup operation.
 908  * @cancellable: (nullable): a #GCancellable, or %NULL
 909  * @callback: callback to call when the operation completes
 910  * @user_data: the data to pass to the callback function
 911  *
 912  * Asynchronously lookup certificates issued by this issuer in the database. See
 913  * g_tls_database_lookup_certificates_issued_by() for more information.
 914  *
 915  * The database may choose to hold a reference to the issuer byte array for the duration
 916  * of of this asynchronous operation. The byte array should not be modified during
 917  * this time.
 918  *
 919  * Since: 2.30
 920  */
 921 void
 922 g_tls_database_lookup_certificates_issued_by_async (GTlsDatabase           *self,
 923                                                     GByteArray             *issuer_raw_dn,
 924                                                     GTlsInteraction        *interaction,
 925                                                     GTlsDatabaseLookupFlags flags,
 926                                                     GCancellable           *cancellable,
 927                                                     GAsyncReadyCallback     callback,
 928                                                     gpointer                user_data)
 929 {
 930   g_return_if_fail (G_IS_TLS_DATABASE (self));
 931   g_return_if_fail (issuer_raw_dn != NULL);
 932   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
 933   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 934   g_return_if_fail (callback != NULL);
 935   g_return_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_async);
 936   G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_async (self,
 937                                                                         issuer_raw_dn,
 938                                                                         interaction,
 939                                                                         flags,
 940                                                                         cancellable,
 941                                                                         callback,
 942                                                                         user_data);
 943 }
 944
 945 /**
 946  * g_tls_database_lookup_certificates_issued_by_finish:
 947  * @self: a #GTlsDatabase
 948  * @result: a #GAsyncResult.
 949  * @error: a #GError pointer, or %NULL
 950  *
 951  * Finish an asynchronous lookup of certificates. See
 952  * g_tls_database_lookup_certificates_issued_by() for more information.
 953  *
 954  * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
 955  * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
 956  *
 957  * Since: 2.30
 958  */
 959 GList*
 960 g_tls_database_lookup_certificates_issued_by_finish (GTlsDatabase          *self,
 961                                                      GAsyncResult          *result,
 962                                                      GError               **error)
 963 {
 964   g_return_val_if_fail (G_IS_TLS_DATABASE (self), NULL);
 965   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
 966   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 967   g_return_val_if_fail (G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_finish, NULL);
 968   return G_TLS_DATABASE_GET_CLASS (self)->lookup_certificates_issued_by_finish (self,
 969                                                                                 result,
 970                                                                                 error);
 971 }