libsecret/secret-password.c

   1 /* libsecret - GLib wrapper for Secret Service
   2  *
   3  * Copyright 2011 Collabora Ltd.
   4  *
   5  * This program is free software: you can redistribute it and/or modify
   6  * it under the terms of the GNU Lesser General Public License as published
   7  * by the Free Software Foundation; either version 2.1 of the licence or (at
   8  * your option) any later version.
   9  *
  10  * See the included COPYING file for more information.
  11  *
  12  * Author: Stef Walter <stefw@gnome.org>
  13  */
  14
  15 #include "config.h"
  16
  17 #include "secret-attributes.h"
  18 #include "secret-password.h"
  19 #include "secret-private.h"
  20 #include "secret-value.h"
  21
  22 #include <egg/egg-secure-memory.h>
  23
  24 /**
  25  * SECTION:secret-password
  26  * @title: Password storage
  27  * @short_description: Simple password storage and lookup
  28  *
  29  * This is a simple API for storing passwords and retrieving passwords in the
  30  * Secret Service.
  31  *
  32  * Each password is associated with a set of attributes. Attribute values can
  33  * be either strings, integers or booleans.
  34  *
  35  * The names and types of allowed attributes for a given password are defined
  36  * with a schema. Certain schemas are predefined. Additional schemas can be
  37  * defined via the %SecretSchema structure.
  38  *
  39  * Each of the functions accept a variable list of attributes names and their
  40  * values. Include a %NULL to terminate the list of attributes.
  41  *
  42  * These functions have an unstable API and may change across versions. Use
  43  * <literal>libsecret-unstable</literal> package to access them.
  44  *
  45  * Stability: Unstable
  46  */
  47
  48 /**
  49  * secret_password_store: (skip)
  50  * @schema: the schema for attributes
  51  * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
  52  * @label: label for the secret
  53  * @password: the null-terminated password to store
  54  * @cancellable: optional cancellation object
  55  * @callback: called when the operation completes
  56  * @user_data: data to be passed to the callback
  57  * @...: the attribute keys and values, terminated with %NULL
  58  *
  59  * Store a password in the secret service.
  60  *
  61  * The variable argument list should contain pairs of a) The attribute name as
  62  * a null-terminated string, followed by b) attribute value, either a character
  63  * string, an int number, or a gboolean value, as defined in the @schema.
  64  * The list of attribtues should be terminated with a %NULL.
  65  *
  66  * If the attributes match a secret item already stored in the collection, then
  67  * the item will be updated with these new values.
  68  *
  69  * If @collection is %NULL, then the default collection will be
  70  * used. Use #SECRET_COLLECTION_SESSION to store the password in the session
  71  * collection, which doesn't get stored across login sessions.
  72  *
  73  * This method will return immediately and complete asynchronously.
  74  */
  75 void
  76 secret_password_store (const SecretSchema *schema,
  77                        const gchar *collection,
  78                        const gchar *label,
  79                        const gchar *password,
  80                        GCancellable *cancellable,
  81                        GAsyncReadyCallback callback,
  82                        gpointer user_data,
  83                        ...)
  84 {
  85         GHashTable *attributes;
  86         va_list va;
  87
  88         g_return_if_fail (schema != NULL);
  89         g_return_if_fail (label != NULL);
  90         g_return_if_fail (password != NULL);
  91         g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
  92
  93         va_start (va, user_data);
  94         attributes = secret_attributes_buildv (schema, va);
  95         va_end (va);
  96
  97         secret_password_storev (schema, attributes, collection, label, password,
  98                                 cancellable, callback, user_data);
  99
 100         g_hash_table_unref (attributes);
 101 }
 102
 103 /**
 104  * secret_password_storev:
 105  * @schema: the schema for attributes
 106  * @attributes: (element-type utf8 utf8): the attribute keys and values
 107  * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
 108  * @label: label for the secret
 109  * @password: the null-terminated password to store
 110  * @cancellable: optional cancellation object
 111  * @callback: called when the operation completes
 112  * @user_data: data to be passed to the callback
 113  *
 114  * Store a password in the secret service.
 115  *
 116  * The @attributes should be a set of key and value string pairs.
 117  *
 118  * If the attributes match a secret item already stored in the collection, then
 119  * the item will be updated with these new values.
 120  *
 121  * If @collection is %NULL, then the default collection will be
 122  * used. Use #SECRET_COLLECTION_SESSION to store the password in the session
 123  * collection, which doesn't get stored across login sessions.
 124  *
 125  * This method will return immediately and complete asynchronously.
 126  *
 127  * Rename to: secret_password_store
 128  */
 129 void
 130 secret_password_storev (const SecretSchema *schema,
 131                         GHashTable *attributes,
 132                         const gchar *collection,
 133                         const gchar *label,
 134                         const gchar *password,
 135                         GCancellable *cancellable,
 136                         GAsyncReadyCallback callback,
 137                         gpointer user_data)
 138 {
 139         SecretValue *value;
 140
 141         g_return_if_fail (schema != NULL);
 142         g_return_if_fail (label != NULL);
 143         g_return_if_fail (password != NULL);
 144         g_return_if_fail (attributes != NULL);
 145         g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 146
 147         /* Warnings raised already */
 148         if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, FALSE))
 149                 return;
 150
 151         value = secret_value_new (password, -1, "text/plain");
 152
 153         secret_service_store (NULL, schema, attributes, collection,
 154                               label, value, cancellable, callback, user_data);
 155
 156         secret_value_unref (value);
 157 }
 158
 159 /**
 160  * secret_password_store_finish:
 161  * @result: the asynchronous result passed to the callback
 162  * @error: location to place an error on failure
 163  *
 164  * Finish asynchronous operation to store a password in the secret service.
 165  *
 166  * Returns: whether the storage was successful or not
 167  */
 168 gboolean
 169 secret_password_store_finish (GAsyncResult *result,
 170                               GError **error)
 171 {
 172         g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 173         return secret_service_store_finish (NULL, result, error);
 174 }
 175
 176 /**
 177  * secret_password_store_sync:
 178  * @schema: the schema for attributes
 179  * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
 180  * @label: label for the secret
 181  * @password: the null-terminated password to store
 182  * @cancellable: optional cancellation object
 183  * @error: location to place an error on failure
 184  * @...: the attribute keys and values, terminated with %NULL
 185  *
 186  * Store a password in the secret service.
 187  *
 188  * The variable argument list should contain pairs of a) The attribute name as
 189  * a null-terminated string, followed by b) attribute value, either a character
 190  * string, an int number, or a gboolean value, as defined in the @schema.
 191  * The list of attribtues should be terminated with a %NULL.
 192  *
 193  * If the attributes match a secret item already stored in the collection, then
 194  * the item will be updated with these new values.
 195  *
 196  * If @collection is %NULL, then the default collection will be
 197  * used. Use #SECRET_COLLECTION_SESSION to store the password in the session
 198  * collection, which doesn't get stored across login sessions.
 199  *
 200  * This method may block indefinitely and should not be used in user interface
 201  * threads.
 202  *
 203  * Returns: whether the storage was successful or not
 204  */
 205 gboolean
 206 secret_password_store_sync (const SecretSchema *schema,
 207                             const gchar *collection,
 208                             const gchar *label,
 209                             const gchar *password,
 210                             GCancellable *cancellable,
 211                             GError **error,
 212                             ...)
 213 {
 214         GHashTable *attributes;
 215         va_list va;
 216         gboolean ret;
 217
 218         g_return_val_if_fail (schema != NULL, FALSE);
 219         g_return_val_if_fail (label != NULL, FALSE);
 220         g_return_val_if_fail (password != NULL, FALSE);
 221         g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
 222         g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 223
 224         va_start (va, error);
 225         attributes = secret_attributes_buildv (schema, va);
 226         va_end (va);
 227
 228         ret = secret_password_storev_sync (schema, attributes, collection,
 229                                            label, password, cancellable, error);
 230
 231         g_hash_table_unref (attributes);
 232         return ret;
 233 }
 234
 235 /**
 236  * secret_password_storev_sync:
 237  * @schema: the schema for attributes
 238  * @attributes: (element-type utf8 utf8): the attribute keys and values
 239  * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
 240  * @label: label for the secret
 241  * @password: the null-terminated password to store
 242  * @cancellable: optional cancellation object
 243  * @error: location to place an error on failure
 244  *
 245  * Store a password in the secret service.
 246  *
 247  * The @attributes should be a set of key and value string pairs.
 248  *
 249  * If the attributes match a secret item already stored in the collection, then
 250  * the item will be updated with these new values.
 251  *
 252  * If @collection is %NULL, then the default collection will be
 253  * used. Use #SECRET_COLLECTION_SESSION to store the password in the session
 254  * collection, which doesn't get stored across login sessions.
 255  *
 256  * This method may block indefinitely and should not be used in user interface
 257  * threads.
 258  *
 259  * Returns: whether the storage was successful or not
 260  *
 261  * Rename to: secret_password_store_sync
 262  */
 263 gboolean
 264 secret_password_storev_sync (const SecretSchema *schema,
 265                              GHashTable *attributes,
 266                              const gchar *collection,
 267                              const gchar *label,
 268                              const gchar *password,
 269                              GCancellable *cancellable,
 270                              GError **error)
 271 {
 272         SecretSync *sync;
 273         gboolean ret;
 274
 275         g_return_val_if_fail (schema != NULL, FALSE);
 276         g_return_val_if_fail (label != NULL, FALSE);
 277         g_return_val_if_fail (password != NULL, FALSE);
 278         g_return_val_if_fail (attributes != NULL, FALSE);
 279         g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
 280         g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 281
 282         /* Warnings raised already */
 283         if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, FALSE))
 284                 return FALSE;
 285
 286         sync = _secret_sync_new ();
 287         g_main_context_push_thread_default (sync->context);
 288
 289         secret_password_storev (schema, attributes, collection, label, password,
 290                                 cancellable, _secret_sync_on_result, sync);
 291
 292         g_main_loop_run (sync->loop);
 293
 294         ret = secret_password_store_finish (sync->result, error);
 295
 296         g_main_context_pop_thread_default (sync->context);
 297         _secret_sync_free (sync);
 298
 299         return ret;
 300 }
 301
 302 /**
 303  * secret_password_lookup: (skip)
 304  * @schema: the schema for the attributes
 305  * @cancellable: optional cancellation object
 306  * @callback: called when the operation completes
 307  * @user_data: data to be passed to the callback
 308  * @...: the attribute keys and values, terminated with %NULL
 309  *
 310  * Lookup a password in the secret service.
 311  *
 312  * The variable argument list should contain pairs of a) The attribute name as
 313  * a null-terminated string, followed by b) attribute value, either a character
 314  * string, an int number, or a gboolean value, as defined in the password
 315  * @schema. The list of attribtues should be terminated with a %NULL.
 316  *
 317  * If no secret is found then %NULL is returned.
 318  *
 319  * This method will return immediately and complete asynchronously.
 320  */
 321 void
 322 secret_password_lookup (const SecretSchema *schema,
 323                         GCancellable *cancellable,
 324                         GAsyncReadyCallback callback,
 325                         gpointer user_data,
 326                         ...)
 327 {
 328         GHashTable *attributes;
 329         va_list va;
 330
 331         g_return_if_fail (schema != NULL);
 332         g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 333
 334         va_start (va, user_data);
 335         attributes = secret_attributes_buildv (schema, va);
 336         va_end (va);
 337
 338         secret_password_lookupv (schema, attributes, cancellable,
 339                                  callback, user_data);
 340
 341         g_hash_table_unref (attributes);
 342 }
 343
 344 /**
 345  * secret_password_lookupv:
 346  * @schema: the schema for attributes
 347  * @attributes: (element-type utf8 utf8): the attribute keys and values
 348  * @cancellable: optional cancellation object
 349  * @callback: called when the operation completes
 350  * @user_data: data to be passed to the callback
 351  *
 352  * Lookup a password in the secret service.
 353  *
 354  * The @attributes should be a set of key and value string pairs.
 355  *
 356  * If no secret is found then %NULL is returned.
 357  *
 358  * This method will return immediately and complete asynchronously.
 359  *
 360  * Rename to: secret_password_lookup
 361  */
 362 void
 363 secret_password_lookupv (const SecretSchema *schema,
 364                          GHashTable *attributes,
 365                          GCancellable *cancellable,
 366                          GAsyncReadyCallback callback,
 367                          gpointer user_data)
 368 {
 369         g_return_if_fail (schema != NULL);
 370         g_return_if_fail (attributes != NULL);
 371         g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 372
 373         /* Warnings raised already */
 374         if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, TRUE))
 375                 return;
 376
 377         secret_service_lookup (NULL, schema, attributes,
 378                                cancellable, callback, user_data);
 379 }
 380
 381 /**
 382  * secret_password_lookup_nonpageable_finish: (skip)
 383  * @result: the asynchronous result passed to the callback
 384  * @error: location to place an error on failure
 385  *
 386  * Finish an asynchronous operation to lookup a password in the secret service.
 387  *
 388  * Returns: (transfer full): a new password string stored in nonpageable memory
 389  *          which must be freed with secret_password_free() when done
 390  */
 391 gchar *
 392 secret_password_lookup_nonpageable_finish (GAsyncResult *result,
 393                                            GError **error)
 394 {
 395         SecretValue *value;
 396
 397         g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 398
 399         value = secret_service_lookup_finish (NULL, result, error);
 400         if (value == NULL)
 401                 return NULL;
 402
 403         return _secret_value_unref_to_password (value);
 404 }
 405
 406 /**
 407  * secret_password_lookup_finish:
 408  * @result: the asynchronous result passed to the callback
 409  * @error: location to place an error on failure
 410  *
 411  * Finish an asynchronous operation to lookup a password in the secret service.
 412  *
 413  * Returns: (transfer full): a new password string which should be freed with
 414  *          secret_password_free() or may be freed with g_free() when done
 415  */
 416 gchar *
 417 secret_password_lookup_finish (GAsyncResult *result,
 418                                GError **error)
 419 {
 420         SecretValue *value;
 421
 422         g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 423
 424         value = secret_service_lookup_finish (NULL, result, error);
 425         if (value == NULL)
 426                 return NULL;
 427
 428         return _secret_value_unref_to_string (value);
 429 }
 430
 431 /**
 432  * secret_password_lookup_sync: (skip)
 433  * @schema: the schema for the attributes
 434  * @cancellable: optional cancellation object
 435  * @error: location to place an error on failure
 436  * @...: the attribute keys and values, terminated with %NULL
 437  *
 438  * Lookup a password in the secret service.
 439  *
 440  * The variable argument list should contain pairs of a) The attribute name as
 441  * a null-terminated string, followed by b) attribute value, either a character
 442  * string, an int number, or a gboolean value, as defined in the password
 443  * @schema. The list of attribtues should be terminated with a %NULL.
 444  *
 445  * If no secret is found then %NULL is returned.
 446  *
 447  * This method may block indefinitely and should not be used in user interface
 448  * threads.
 449  *
 450  * Returns: (transfer full): a new password string which should be freed with
 451  *          secret_password_free() or may be freed with g_free() when done
 452  */
 453 gchar *
 454 secret_password_lookup_sync (const SecretSchema *schema,
 455                              GCancellable *cancellable,
 456                              GError **error,
 457                              ...)
 458 {
 459         GHashTable *attributes;
 460         gchar *password;
 461         va_list va;
 462
 463         g_return_val_if_fail (schema != NULL, NULL);
 464         g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 465         g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 466
 467         va_start (va, error);
 468         attributes = secret_attributes_buildv (schema, va);
 469         va_end (va);
 470
 471         password = secret_password_lookupv_sync (schema, attributes,
 472                                                  cancellable, error);
 473
 474         g_hash_table_unref (attributes);
 475
 476         return password;
 477 }
 478
 479 /**
 480  * secret_password_lookup_nonpageable_sync: (skip)
 481  * @schema: the schema for the attributes
 482  * @cancellable: optional cancellation object
 483  * @error: location to place an error on failure
 484  * @...: the attribute keys and values, terminated with %NULL
 485  *
 486  * Lookup a password in the secret service.
 487  *
 488  * The variable argument list should contain pairs of a) The attribute name as
 489  * a null-terminated string, followed by b) attribute value, either a character
 490  * string, an int number, or a gboolean value, as defined in the password
 491  * @schema. The list of attribtues should be terminated with a %NULL.
 492  *
 493  * If no secret is found then %NULL is returned.
 494  *
 495  * This method may block indefinitely and should not be used in user interface
 496  * threads.
 497  *
 498  * Returns: (transfer full): a new password string stored in nonpageable memory
 499  *          which must be freed with secret_password_free() when done
 500  */
 501 gchar *
 502 secret_password_lookup_nonpageable_sync (const SecretSchema *schema,
 503                                          GCancellable *cancellable,
 504                                          GError **error,
 505                                          ...)
 506 {
 507         GHashTable *attributes;
 508         gchar *password;
 509         va_list va;
 510
 511         g_return_val_if_fail (schema != NULL, NULL);
 512         g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 513         g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 514
 515         va_start (va, error);
 516         attributes = secret_attributes_buildv (schema, va);
 517         va_end (va);
 518
 519         password = secret_password_lookupv_nonpageable_sync (schema, attributes,
 520                                                              cancellable, error);
 521
 522         g_hash_table_unref (attributes);
 523
 524         return password;
 525 }
 526
 527 /**
 528  * secret_password_lookupv_nonpageable_sync: (skip)
 529  * @schema: the schema for attributes
 530  * @attributes: (element-type utf8 utf8): the attribute keys and values
 531  * @cancellable: optional cancellation object
 532  * @error: location to place an error on failure
 533  *
 534  * Lookup a password in the secret service.
 535  *
 536  * The @attributes should be a set of key and value string pairs.
 537  *
 538  * If no secret is found then %NULL is returned.
 539  *
 540  * This method may block indefinitely and should not be used in user interface
 541  * threads.
 542  *
 543  * Returns: (transfer full): a new password string stored in non pageable memory
 544  *          which should be freed with secret_password_free() when done
 545  */
 546 gchar *
 547 secret_password_lookupv_nonpageable_sync (const SecretSchema *schema,
 548                                           GHashTable *attributes,
 549                                           GCancellable *cancellable,
 550                                           GError **error)
 551 {
 552         SecretSync *sync;
 553         gchar *password;
 554
 555         g_return_val_if_fail (schema != NULL, NULL);
 556         g_return_val_if_fail (attributes != NULL, NULL);
 557         g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 558         g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 559
 560         /* Warnings raised already */
 561         if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, TRUE))
 562                 return FALSE;
 563
 564         sync = _secret_sync_new ();
 565         g_main_context_push_thread_default (sync->context);
 566
 567         secret_password_lookupv (schema, attributes, cancellable,
 568                                  _secret_sync_on_result, sync);
 569
 570         g_main_loop_run (sync->loop);
 571
 572         password = secret_password_lookup_nonpageable_finish (sync->result, error);
 573
 574         g_main_context_pop_thread_default (sync->context);
 575         _secret_sync_free (sync);
 576
 577         return password;
 578 }
 579
 580 /**
 581  * secret_password_lookupv_sync:
 582  * @schema: the schema for attributes
 583  * @attributes: (element-type utf8 utf8): the attribute keys and values
 584  * @cancellable: optional cancellation object
 585  * @error: location to place an error on failure
 586  *
 587  * Lookup a password in the secret service.
 588  *
 589  * The @attributes should be a set of key and value string pairs.
 590  *
 591  * If no secret is found then %NULL is returned.
 592  *
 593  * This method may block indefinitely and should not be used in user interface
 594  * threads.
 595  *
 596  * Returns: (transfer full): a new password string which should be freed with
 597  *          secret_password_free() or may be freed with g_free() when done
 598  *
 599  * Rename to: secret_password_lookup_sync
 600  */
 601 gchar *
 602 secret_password_lookupv_sync (const SecretSchema *schema,
 603                               GHashTable *attributes,
 604                               GCancellable *cancellable,
 605                               GError **error)
 606 {
 607         SecretSync *sync;
 608         gchar *string;
 609
 610         g_return_val_if_fail (schema != NULL, NULL);
 611         g_return_val_if_fail (attributes != NULL, NULL);
 612         g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 613         g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 614
 615         /* Warnings raised already */
 616         if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, TRUE))
 617                 return FALSE;
 618
 619         sync = _secret_sync_new ();
 620         g_main_context_push_thread_default (sync->context);
 621
 622         secret_password_lookupv (schema, attributes, cancellable,
 623                                  _secret_sync_on_result, sync);
 624
 625         g_main_loop_run (sync->loop);
 626
 627         string = secret_password_lookup_finish (sync->result, error);
 628
 629         g_main_context_pop_thread_default (sync->context);
 630         _secret_sync_free (sync);
 631
 632         return string;
 633 }
 634
 635 /**
 636  * secret_password_remove:
 637  * @schema: the schema for the attributes
 638  * @cancellable: optional cancellation object
 639  * @callback: called when the operation completes
 640  * @user_data: data to be passed to the callback
 641  * @...: the attribute keys and values, terminated with %NULL
 642  *
 643  * Remove a password from the secret service.
 644  *
 645  * The variable argument list should contain pairs of a) The attribute name as
 646  * a null-terminated string, followed by b) attribute value, either a character
 647  * string, an int number, or a gboolean value, as defined in the password
 648  * @schema. The list of attribtues should be terminated with a %NULL.
 649  *
 650  * If multiple items match the attributes, then only one will be deleted.
 651  *
 652  * This method will return immediately and complete asynchronously.
 653  */
 654 void
 655 secret_password_remove (const SecretSchema *schema,
 656                         GCancellable *cancellable,
 657                         GAsyncReadyCallback callback,
 658                         gpointer user_data,
 659                         ...)
 660 {
 661         GHashTable *attributes;
 662         va_list va;
 663
 664         g_return_if_fail (schema != NULL);
 665         g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 666
 667         va_start (va, user_data);
 668         attributes = secret_attributes_buildv (schema, va);
 669         va_end (va);
 670
 671         secret_password_removev (schema, attributes, cancellable,
 672                                  callback, user_data);
 673
 674         g_hash_table_unref (attributes);
 675 }
 676
 677
 678 /**
 679  * secret_password_removev:
 680  * @schema: the schema for the attributes
 681  * @attributes: (element-type utf8 utf8): the attribute keys and values
 682  * @cancellable: optional cancellation object
 683  * @callback: called when the operation completes
 684  * @user_data: data to be passed to the callback
 685  *
 686  * Remove passwords from the secret service.
 687  *
 688  * The @attributes should be a set of key and value string pairs.
 689  *
 690  * All unlocked items that match the attributes will be deleted.
 691  *
 692  * This method will return immediately and complete asynchronously.
 693  *
 694  * Rename to: secret_password_remove
 695  */
 696 void
 697 secret_password_removev (const SecretSchema *schema,
 698                          GHashTable *attributes,
 699                          GCancellable *cancellable,
 700                          GAsyncReadyCallback callback,
 701                          gpointer user_data)
 702 {
 703         g_return_if_fail (schema != NULL);
 704         g_return_if_fail (attributes != NULL);
 705         g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 706
 707         /* Warnings raised already */
 708         if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, TRUE))
 709                 return;
 710
 711         secret_service_remove (NULL, schema, attributes,
 712                                cancellable, callback, user_data);
 713 }
 714
 715 /**
 716  * secret_password_remove_finish:
 717  * @result: the asynchronous result passed to the callback
 718  * @error: location to place an error on failure
 719  *
 720  * Finish an asynchronous operation to remove passwords from the secret
 721  * service.
 722  *
 723  * Returns: whether any passwords were removed
 724  */
 725 gboolean
 726 secret_password_remove_finish (GAsyncResult *result,
 727                                GError **error)
 728 {
 729         g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 730         return secret_service_remove_finish (NULL, result, error);
 731 }
 732
 733 /**
 734  * secret_password_remove_sync:
 735  * @schema: the schema for the attributes
 736  * @cancellable: optional cancellation object
 737  * @error: location to place an error on failure
 738  * @...: the attribute keys and values, terminated with %NULL
 739  *
 740  * Remove passwords from the secret service.
 741  *
 742  * The variable argument list should contain pairs of a) The attribute name as
 743  * a null-terminated string, followed by b) attribute value, either a character
 744  * string, an int number, or a gboolean value, as defined in the password
 745  * @schema. The list of attribtues should be terminated with a %NULL.
 746  *
 747  * All unlocked items that match the attributes will be deleted.
 748  *
 749  * This method may block indefinitely and should not be used in user interface
 750  * threads.
 751  *
 752  * Returns: whether the any passwords were removed
 753  */
 754 gboolean
 755 secret_password_remove_sync (const SecretSchema* schema,
 756                              GCancellable *cancellable,
 757                              GError **error,
 758                              ...)
 759 {
 760         GHashTable *attributes;
 761         gboolean result;
 762         va_list va;
 763
 764         g_return_val_if_fail (schema != NULL, FALSE);
 765         g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
 766         g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 767
 768         va_start (va, error);
 769         attributes = secret_attributes_buildv (schema, va);
 770         va_end (va);
 771
 772         result = secret_password_removev_sync (schema, attributes,
 773                                                cancellable, error);
 774
 775         g_hash_table_unref (attributes);
 776
 777         return result;
 778 }
 779
 780 /**
 781  * secret_password_removev_sync:
 782  * @schema: the schema for the attributes
 783  * @attributes: (element-type utf8 utf8): the attribute keys and values
 784  * @cancellable: optional cancellation object
 785  * @error: location to place an error on failure
 786  *
 787  * Remove a password from the secret service.
 788  *
 789  * The @attributes should be a set of key and value string pairs.
 790  *
 791  * All unlocked items that match the attributes will be deleted.
 792  *
 793  * This method may block indefinitely and should not be used in user interface
 794  * threads.
 795  *
 796  * Returns: whether any passwords were removed
 797  *
 798  * Rename to: secret_password_remove_sync
 799  */
 800 gboolean
 801 secret_password_removev_sync (const SecretSchema *schema,
 802                               GHashTable *attributes,
 803                               GCancellable *cancellable,
 804                               GError **error)
 805 {
 806         SecretSync *sync;
 807         gboolean result;
 808
 809         g_return_val_if_fail (schema != NULL, FALSE);
 810         g_return_val_if_fail (attributes != NULL, FALSE);
 811         g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
 812         g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 813
 814         /* Warnings raised already */
 815         if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, TRUE))
 816                 return FALSE;
 817
 818         sync = _secret_sync_new ();
 819         g_main_context_push_thread_default (sync->context);
 820
 821         secret_password_removev (schema, attributes, cancellable,
 822                                  _secret_sync_on_result, sync);
 823
 824         g_main_loop_run (sync->loop);
 825
 826         result = secret_password_remove_finish (sync->result, error);
 827
 828         g_main_context_pop_thread_default (sync->context);
 829         _secret_sync_free (sync);
 830
 831         return result;
 832 }
 833
 834 /**
 835  * secret_password_free: (skip)
 836  * @password: (allow-none): password to free
 837  *
 838  * Clear the memory used by a password, and then free it.
 839  *
 840  * This function must be used to free nonpageable memory returned by
 841  * secret_password_lookup_nonpageable_finish(),
 842  * secret_password_lookup_nonpageable_sync() or
 843  * secret_password_lookupv_nonpageable_sync().
 844  */
 845 void
 846 secret_password_free (gchar *password)
 847 {
 848         if (password == NULL)
 849                 return;
 850
 851         egg_secure_strfree (password);
 852 }
 853
 854 /**
 855  * secret_password_clear:
 856  * @password: (allow-none): password to clear
 857  *
 858  * Clear the memory used by a password.
 859  */
 860 void
 861 secret_password_clear (gchar *password)
 862 {
 863         if (password == NULL)
 864                 return;
 865
 866         egg_secure_strclear (password);
 867 }