1 /* libsecret - GLib wrapper for Secret Service
3 * Copyright 2011 Collabora Ltd.
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.
10 * See the included COPYING file for more information.
12 * Author: Stef Walter <stefw@gnome.org>
17 #include "secret-attributes.h"
18 #include "secret-password.h"
19 #include "secret-private.h"
20 #include "secret-value.h"
22 #include <egg/egg-secure-memory.h>
25 * SECTION:secret-password
26 * @title: Password storage
27 * @short_description: Simple password storage and lookup
29 * This is a simple API for storing passwords and retrieving passwords in the
32 * Each password is associated with a set of attributes. Attribute values can
33 * be either strings, integers or booleans.
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.
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.
42 * These functions have an unstable API and may change across versions. Use
43 * <literal>libsecret-unstable</literal> package to access them.
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
59 * Store a password in the secret service.
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.
66 * If the attributes match a secret item already stored in the collection, then
67 * the item will be updated with these new values.
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.
73 * This method will return immediately and complete asynchronously.
76 secret_password_store (const SecretSchema *schema,
77 const gchar *collection,
79 const gchar *password,
80 GCancellable *cancellable,
81 GAsyncReadyCallback callback,
85 GHashTable *attributes;
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));
93 va_start (va, user_data);
94 attributes = secret_attributes_buildv (schema, va);
97 secret_password_storev (schema, attributes, collection, label, password,
98 cancellable, callback, user_data);
100 g_hash_table_unref (attributes);
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
114 * Store a password in the secret service.
116 * The @attributes should be a set of key and value string pairs.
118 * If the attributes match a secret item already stored in the collection, then
119 * the item will be updated with these new values.
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.
125 * This method will return immediately and complete asynchronously.
127 * Rename to: secret_password_store
130 secret_password_storev (const SecretSchema *schema,
131 GHashTable *attributes,
132 const gchar *collection,
134 const gchar *password,
135 GCancellable *cancellable,
136 GAsyncReadyCallback callback,
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));
147 /* Warnings raised already */
148 if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, FALSE))
151 value = secret_value_new (password, -1, "text/plain");
153 secret_service_store (NULL, schema, attributes, collection,
154 label, value, cancellable, callback, user_data);
156 secret_value_unref (value);
160 * secret_password_store_finish:
161 * @result: the asynchronous result passed to the callback
162 * @error: location to place an error on failure
164 * Finish asynchronous operation to store a password in the secret service.
166 * Returns: whether the storage was successful or not
169 secret_password_store_finish (GAsyncResult *result,
172 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
173 return secret_service_store_finish (NULL, result, error);
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
186 * Store a password in the secret service.
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.
193 * If the attributes match a secret item already stored in the collection, then
194 * the item will be updated with these new values.
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.
200 * This method may block indefinitely and should not be used in user interface
203 * Returns: whether the storage was successful or not
206 secret_password_store_sync (const SecretSchema *schema,
207 const gchar *collection,
209 const gchar *password,
210 GCancellable *cancellable,
214 GHashTable *attributes;
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);
224 va_start (va, error);
225 attributes = secret_attributes_buildv (schema, va);
228 ret = secret_password_storev_sync (schema, attributes, collection,
229 label, password, cancellable, error);
231 g_hash_table_unref (attributes);
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
245 * Store a password in the secret service.
247 * The @attributes should be a set of key and value string pairs.
249 * If the attributes match a secret item already stored in the collection, then
250 * the item will be updated with these new values.
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.
256 * This method may block indefinitely and should not be used in user interface
259 * Returns: whether the storage was successful or not
261 * Rename to: secret_password_store_sync
264 secret_password_storev_sync (const SecretSchema *schema,
265 GHashTable *attributes,
266 const gchar *collection,
268 const gchar *password,
269 GCancellable *cancellable,
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);
282 /* Warnings raised already */
283 if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, FALSE))
286 sync = _secret_sync_new ();
287 g_main_context_push_thread_default (sync->context);
289 secret_password_storev (schema, attributes, collection, label, password,
290 cancellable, _secret_sync_on_result, sync);
292 g_main_loop_run (sync->loop);
294 ret = secret_password_store_finish (sync->result, error);
296 g_main_context_pop_thread_default (sync->context);
297 _secret_sync_free (sync);
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
310 * Lookup a password in the secret service.
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.
317 * If no secret is found then %NULL is returned.
319 * This method will return immediately and complete asynchronously.
322 secret_password_lookup (const SecretSchema *schema,
323 GCancellable *cancellable,
324 GAsyncReadyCallback callback,
328 GHashTable *attributes;
331 g_return_if_fail (schema != NULL);
332 g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
334 va_start (va, user_data);
335 attributes = secret_attributes_buildv (schema, va);
338 secret_password_lookupv (schema, attributes, cancellable,
339 callback, user_data);
341 g_hash_table_unref (attributes);
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
352 * Lookup a password in the secret service.
354 * The @attributes should be a set of key and value string pairs.
356 * If no secret is found then %NULL is returned.
358 * This method will return immediately and complete asynchronously.
360 * Rename to: secret_password_lookup
363 secret_password_lookupv (const SecretSchema *schema,
364 GHashTable *attributes,
365 GCancellable *cancellable,
366 GAsyncReadyCallback callback,
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));
373 /* Warnings raised already */
374 if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, TRUE))
377 secret_service_lookup (NULL, schema, attributes,
378 cancellable, callback, user_data);
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
386 * Finish an asynchronous operation to lookup a password in the secret service.
388 * Returns: (transfer full): a new password string stored in nonpageable memory
389 * which must be freed with secret_password_free() when done
392 secret_password_lookup_nonpageable_finish (GAsyncResult *result,
397 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
399 value = secret_service_lookup_finish (NULL, result, error);
403 return _secret_value_unref_to_password (value);
407 * secret_password_lookup_finish:
408 * @result: the asynchronous result passed to the callback
409 * @error: location to place an error on failure
411 * Finish an asynchronous operation to lookup a password in the secret service.
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
417 secret_password_lookup_finish (GAsyncResult *result,
422 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
424 value = secret_service_lookup_finish (NULL, result, error);
428 return _secret_value_unref_to_string (value);
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
438 * Lookup a password in the secret service.
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.
445 * If no secret is found then %NULL is returned.
447 * This method may block indefinitely and should not be used in user interface
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
454 secret_password_lookup_sync (const SecretSchema *schema,
455 GCancellable *cancellable,
459 GHashTable *attributes;
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);
467 va_start (va, error);
468 attributes = secret_attributes_buildv (schema, va);
471 password = secret_password_lookupv_sync (schema, attributes,
474 g_hash_table_unref (attributes);
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
486 * Lookup a password in the secret service.
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.
493 * If no secret is found then %NULL is returned.
495 * This method may block indefinitely and should not be used in user interface
498 * Returns: (transfer full): a new password string stored in nonpageable memory
499 * which must be freed with secret_password_free() when done
502 secret_password_lookup_nonpageable_sync (const SecretSchema *schema,
503 GCancellable *cancellable,
507 GHashTable *attributes;
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);
515 va_start (va, error);
516 attributes = secret_attributes_buildv (schema, va);
519 password = secret_password_lookupv_nonpageable_sync (schema, attributes,
522 g_hash_table_unref (attributes);
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
534 * Lookup a password in the secret service.
536 * The @attributes should be a set of key and value string pairs.
538 * If no secret is found then %NULL is returned.
540 * This method may block indefinitely and should not be used in user interface
543 * Returns: (transfer full): a new password string stored in non pageable memory
544 * which should be freed with secret_password_free() when done
547 secret_password_lookupv_nonpageable_sync (const SecretSchema *schema,
548 GHashTable *attributes,
549 GCancellable *cancellable,
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);
560 /* Warnings raised already */
561 if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, TRUE))
564 sync = _secret_sync_new ();
565 g_main_context_push_thread_default (sync->context);
567 secret_password_lookupv (schema, attributes, cancellable,
568 _secret_sync_on_result, sync);
570 g_main_loop_run (sync->loop);
572 password = secret_password_lookup_nonpageable_finish (sync->result, error);
574 g_main_context_pop_thread_default (sync->context);
575 _secret_sync_free (sync);
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
587 * Lookup a password in the secret service.
589 * The @attributes should be a set of key and value string pairs.
591 * If no secret is found then %NULL is returned.
593 * This method may block indefinitely and should not be used in user interface
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
599 * Rename to: secret_password_lookup_sync
602 secret_password_lookupv_sync (const SecretSchema *schema,
603 GHashTable *attributes,
604 GCancellable *cancellable,
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);
615 /* Warnings raised already */
616 if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, TRUE))
619 sync = _secret_sync_new ();
620 g_main_context_push_thread_default (sync->context);
622 secret_password_lookupv (schema, attributes, cancellable,
623 _secret_sync_on_result, sync);
625 g_main_loop_run (sync->loop);
627 string = secret_password_lookup_finish (sync->result, error);
629 g_main_context_pop_thread_default (sync->context);
630 _secret_sync_free (sync);
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
643 * Remove passwords from the secret service.
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.
650 * If multiple items match the attributes, then only one will be deleted.
652 * This method will return immediately and complete asynchronously.
655 secret_password_remove (const SecretSchema *schema,
656 GCancellable *cancellable,
657 GAsyncReadyCallback callback,
661 GHashTable *attributes;
664 g_return_if_fail (schema != NULL);
665 g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
667 va_start (va, user_data);
668 attributes = secret_attributes_buildv (schema, va);
671 secret_password_removev (schema, attributes, cancellable,
672 callback, user_data);
674 g_hash_table_unref (attributes);
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
686 * Remove passwords from the secret service.
688 * The @attributes should be a set of key and value string pairs.
690 * All unlocked items that match the attributes will be deleted.
692 * This method will return immediately and complete asynchronously.
694 * Rename to: secret_password_remove
697 secret_password_removev (const SecretSchema *schema,
698 GHashTable *attributes,
699 GCancellable *cancellable,
700 GAsyncReadyCallback callback,
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));
707 /* Warnings raised already */
708 if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, TRUE))
711 secret_service_remove (NULL, schema, attributes,
712 cancellable, callback, user_data);
716 * secret_password_remove_finish:
717 * @result: the asynchronous result passed to the callback
718 * @error: location to place an error on failure
720 * Finish an asynchronous operation to remove passwords from the secret
723 * Returns: whether any passwords were removed
726 secret_password_remove_finish (GAsyncResult *result,
729 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
730 return secret_service_remove_finish (NULL, result, error);
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
740 * Remove passwords from the secret service.
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.
747 * All unlocked items that match the attributes will be deleted.
749 * This method may block indefinitely and should not be used in user interface
752 * Returns: whether the any passwords were removed
755 secret_password_remove_sync (const SecretSchema* schema,
756 GCancellable *cancellable,
760 GHashTable *attributes;
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);
768 va_start (va, error);
769 attributes = secret_attributes_buildv (schema, va);
772 result = secret_password_removev_sync (schema, attributes,
775 g_hash_table_unref (attributes);
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
787 * Remove passwords from the secret service.
789 * The @attributes should be a set of key and value string pairs.
791 * All unlocked items that match the attributes will be deleted.
793 * This method may block indefinitely and should not be used in user interface
796 * Returns: whether any passwords were removed
798 * Rename to: secret_password_remove_sync
801 secret_password_removev_sync (const SecretSchema *schema,
802 GHashTable *attributes,
803 GCancellable *cancellable,
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);
814 /* Warnings raised already */
815 if (!_secret_attributes_validate (schema, attributes, G_STRFUNC, TRUE))
818 sync = _secret_sync_new ();
819 g_main_context_push_thread_default (sync->context);
821 secret_password_removev (schema, attributes, cancellable,
822 _secret_sync_on_result, sync);
824 g_main_loop_run (sync->loop);
826 result = secret_password_remove_finish (sync->result, error);
828 g_main_context_pop_thread_default (sync->context);
829 _secret_sync_free (sync);
835 * secret_password_free: (skip)
836 * @password: (allow-none): password to free
838 * Clear the memory used by a password, and then free it.
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().
846 secret_password_free (gchar *password)
848 if (password == NULL)
851 egg_secure_strfree (password);
855 * secret_password_clear:
856 * @password: (allow-none): password to clear
858 * Clear the memory used by a password.
861 secret_password_clear (gchar *password)
863 if (password == NULL)
866 egg_secure_strclear (password);