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