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