libpurple/keyring.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
  20  */
  21
  22 #ifndef PURPLE_KEYRING_H
  23 #define PURPLE_KEYRING_H
  24 /**
  25  * SECTION:keyring
  26  * @section_id: libpurple-keyring
  27  * @short_description: <filename>keyring.h</filename>
  28  * @title: Keyring API
  29  */
  30
  31 #include "account.h"
  32 #include "request.h"
  33
  34 #define PURPLE_TYPE_KEYRING  (purple_keyring_get_type())
  35
  36 /**
  37  * PURPLE_DEFAULT_KEYRING:
  38  *
  39  * Default keyring ID.
  40  */
  41 #define PURPLE_DEFAULT_KEYRING "keyring-internal"
  42
  43 /**
  44  * PURPLE_KEYRING_ERROR:
  45  *
  46  * Keyring subsystem error domain.
  47  */
  48 #define PURPLE_KEYRING_ERROR purple_keyring_error_domain()
  49
  50 /**************************************************************************/
  51 /* Data structures and types                                              */
  52 /**************************************************************************/
  53
  54 typedef struct _PurpleKeyring PurpleKeyring;
  55
  56 /**************************************************************************/
  57 /* Callbacks for keyrings access functions                                */
  58 /**************************************************************************/
  59
  60 /**
  61  * PurpleKeyringReadCallback:
  62  * @account:  The account.
  63  * @password: The password.
  64  * @error:    Error that may have occurred.
  65  * @data:     Data passed to the callback.
  66  *
  67  * Callback for once a password is read.
  68  *
  69  * If there was a problem, the password will be NULL, and the error set.
  70  */
  71 typedef void (*PurpleKeyringReadCallback)(PurpleAccount *account,
  72         const gchar *password, GError *error, gpointer data);
  73
  74 /**
  75  * PurpleKeyringSaveCallback:
  76  * @account: The account.
  77  * @error:   Error that may have occurred.
  78  * @data:    Data passed to the callback.
  79  *
  80  * Callback for once a password has been stored.
  81  *
  82  * If there was a problem, the error will be set.
  83  */
  84 typedef void (*PurpleKeyringSaveCallback)(PurpleAccount *account, GError *error,
  85         gpointer data);
  86
  87 /**
  88  * PurpleKeyringChangeMasterCallback:
  89  * @error:  Error that has occurred.
  90  * @data:   Data passed to the callback.
  91  *
  92  * Callback for once the master password for a keyring has been changed.
  93  */
  94 typedef void (*PurpleKeyringChangeMasterCallback)(GError *error, gpointer data);
  95
  96 /**
  97  * PurpleKeyringSetInUseCallback:
  98  * @error:   An error that might have occurred.
  99  * @data:    A pointer to user supplied data.
 100  *
 101  * Callback for when we change the keyring.
 102  */
 103 typedef void (*PurpleKeyringSetInUseCallback)(GError *error, gpointer data);
 104
 105 /**************************************************************************/
 106 /* Keyrings access functions                                              */
 107 /**************************************************************************/
 108
 109 /**
 110  * PurpleKeyringRead:
 111  * @account: The account.
 112  * @cb:      A callback for once the password is found.
 113  * @data:    Data to be passed to the callback.
 114  *
 115  * Read the password for an account.
 116  */
 117 typedef void (*PurpleKeyringRead)(PurpleAccount *account,
 118         PurpleKeyringReadCallback cb, gpointer data);
 119
 120 /**
 121  * PurpleKeyringSave:
 122  * @account:  The account.
 123  * @password: The password to be stored. If the password is NULL, this
 124  *                 means that the keyring should forget about that password.
 125  * @cb:       A callback for once the password is saved.
 126  * @data:     Data to be passed to the callback.
 127  *
 128  * Store a password in the keyring.
 129  */
 130 typedef void (*PurpleKeyringSave)(PurpleAccount *account, const gchar *password,
 131         PurpleKeyringSaveCallback cb, gpointer data);
 132
 133 /**
 134  * PurpleKeyringCancelRequests:
 135  *
 136  * Cancel all running requests.
 137  *
 138  * After calling that, all queued requests should run their callbacks (most
 139  * probably, with failure result).
 140  */
 141 typedef void (*PurpleKeyringCancelRequests)(void);
 142
 143 /**
 144  * PurpleKeyringClose:
 145  *
 146  * Close the keyring.
 147  *
 148  * This will be called so the keyring can do any cleanup it needs.
 149  */
 150 typedef void (*PurpleKeyringClose)(void);
 151
 152 /**
 153  * PurpleKeyringImportPassword:
 154  * @account: The account.
 155  * @mode:    A keyring specific option that was stored. Can be NULL.
 156  * @data:    Data that was stored. Can be NULL.
 157  * @error:   Error that may have occurred.
 158  *
 159  * Import serialized (and maybe encrypted) password.
 160  *
 161  * This is not async because it is not meant to prompt for a master password and
 162  * decrypt passwords.
 163  *
 164  * Returns: TRUE on success, FALSE on failure.
 165  */
 166 typedef gboolean (*PurpleKeyringImportPassword)(PurpleAccount *account,
 167         const gchar *mode, const gchar *data, GError **error);
 168
 169 /**
 170  * PurpleKeyringExportPassword:
 171  * @account: The account.
 172  * @mode:    An option field that can be used by the plugin. This is
 173  *                expected to be a static string.
 174  * @data:    The data to be stored in the XML node. This string will be
 175  *                freed using destroy() once not needed anymore.
 176  * @error:   Will be set if a problem occured.
 177  * @destroy: A function to be called, if non NULL, to free data.
 178  *
 179  * Export serialized (and maybe encrypted) password.
 180  *
 181  * Returns: TRUE on success, FALSE on failure.
 182  */
 183 typedef gboolean (*PurpleKeyringExportPassword)(PurpleAccount *account,
 184         const gchar **mode, gchar **data, GError **error,
 185         GDestroyNotify *destroy);
 186
 187 /**
 188  * PurpleKeyringReadSettings:
 189  *
 190  * Read keyring settings.
 191  *
 192  * Returns: New copy of current settings (must be free'd with
 193  *         purple_request_fields_destroy).
 194  */
 195 typedef PurpleRequestFields * (*PurpleKeyringReadSettings)(void);
 196
 197 /**
 198  * PurpleKeyringApplySettings:
 199  * @notify_handle: A handle that can be passed to purple_notify_message.
 200  * @fields:        Modified settings (originally taken from
 201  *                      PurpleKeyringReadSettings).
 202  *
 203  * Applies modified keyring settings.
 204  *
 205  * Returns: TRUE, if succeeded, FALSE otherwise.
 206  */
 207 typedef gboolean (*PurpleKeyringApplySettings)(void *notify_handle,
 208         PurpleRequestFields *fields);
 209
 210 G_BEGIN_DECLS
 211
 212 /**************************************************************************/
 213 /* Setting used keyrings                                                  */
 214 /**************************************************************************/
 215
 216 /**
 217  * purple_keyring_find_keyring_by_id:
 218  * @id: The id for the keyring.
 219  *
 220  * Find a keyring by an id.
 221  *
 222  * Returns: The keyring, or NULL if not found.
 223  */
 224 PurpleKeyring *
 225 purple_keyring_find_keyring_by_id(const gchar *id);
 226
 227 /**
 228  * purple_keyring_get_inuse:
 229  *
 230  * Get the keyring being used.
 231  */
 232 PurpleKeyring *
 233 purple_keyring_get_inuse(void);
 234
 235 /**
 236  * purple_keyring_set_inuse:
 237  * @newkeyring:       The new keyring to use.
 238  * @force:            %FALSE if the change can be cancelled. If this is %TRUE
 239  *                    and an error occurs, data might be lost.
 240  * @cb: (scope call): A callback for once the change is complete.
 241  * @data:             Data to be passed to the callback.
 242  *
 243  * Set the keyring to use. This function will move all passwords from
 244  * the old keyring to the new one.
 245  *
 246  * If it fails, it will cancel all changes, close the new keyring, and notify
 247  * the callback. If it succeeds, it will remove all passwords from the old safe
 248  * and close that safe.
 249  */
 250 void
 251 purple_keyring_set_inuse(PurpleKeyring *newkeyring, gboolean force,
 252         PurpleKeyringSetInUseCallback cb, gpointer data);
 253
 254 /**
 255  * purple_keyring_register:
 256  * @keyring: The keyring to register.
 257  *
 258  * Register a keyring plugin.
 259  */
 260 void
 261 purple_keyring_register(PurpleKeyring *keyring);
 262
 263 /**
 264  * purple_keyring_unregister:
 265  * @keyring: The keyring to unregister.
 266  *
 267  * Unregister a keyring plugin.
 268  *
 269  * In case the keyring is in use, passwords will be moved to a fallback safe,
 270  * and the keyring to unregister will be properly closed.
 271  */
 272 void
 273 purple_keyring_unregister(PurpleKeyring *keyring);
 274
 275 /**
 276  * purple_keyring_get_options:
 277  *
 278  * Returns a GList containing the IDs and names of the registered
 279  * keyrings.
 280  *
 281  * Returns: (element-type utf8) (transfer container): The list of IDs and names.
 282  */
 283 GList *
 284 purple_keyring_get_options(void);
 285
 286 /**************************************************************************/
 287 /* Keyring plugin wrappers                                                */
 288 /**************************************************************************/
 289
 290 /**
 291  * purple_keyring_import_password:
 292  * @account:    The account.
 293  * @keyring_id: The plugin ID that was stored in the xml file. Can be NULL.
 294  * @mode:       A keyring specific option that was stored. Can be NULL.
 295  * @data:       Data that was stored, can be NULL.
 296  * @error:      Error that may have occurred.
 297  *
 298  * Import serialized (and maybe encrypted) password into current keyring.
 299  *
 300  * It's used by account.c while reading a password from xml.
 301  *
 302  * Returns: TRUE if the input was accepted, FALSE otherwise.
 303  */
 304 gboolean
 305 purple_keyring_import_password(PurpleAccount *account, const gchar *keyring_id,
 306         const gchar *mode, const gchar *data, GError **error);
 307
 308 /**
 309  * purple_keyring_export_password:
 310  * @account:    The account for which we want the info.
 311  * @keyring_id: The plugin id to be stored in the XML node. This will be
 312  *                   NULL or a string that can be considered static.
 313  * @mode:       An option field that can be used by the plugin. This will
 314  *                   be NULL or a string that can be considered static.
 315  * @data:       The data to be stored in the XML node. This string must be
 316  *                   freed using destroy() once not needed anymore if it is not
 317  *                   NULL.
 318  * @error:      Will be set if a problem occured.
 319  * @destroy:    A function to be called, if non NULL, to free data.
 320  *
 321  * Export serialized (and maybe encrypted) password out of current keyring.
 322  *
 323  * It's used by account.c while syncing accounts to xml.
 324  *
 325  * Returns: TRUE if the info was exported successfully, FALSE otherwise.
 326  */
 327 gboolean
 328 purple_keyring_export_password(PurpleAccount *account, const gchar **keyring_id,
 329         const gchar **mode, gchar **data, GError **error,
 330         GDestroyNotify *destroy);
 331
 332 /**
 333  * purple_keyring_get_password:
 334  * @account:          The account.
 335  * @cb: (scope call): A callback for once the password is read.
 336  * @data:             Data passed to the callback.
 337  *
 338  * Read a password from the current keyring.
 339  */
 340 void
 341 purple_keyring_get_password(PurpleAccount *account,
 342         PurpleKeyringReadCallback cb, gpointer data);
 343
 344 /**
 345  * purple_keyring_set_password:
 346  * @account:          The account.
 347  * @password:         The password to save.
 348  * @cb: (scope call): A callback for once the password is saved.
 349  * @data:             Data to be passed to the callback.
 350  *
 351  * Save a password to the current keyring.
 352  */
 353 void
 354 purple_keyring_set_password(PurpleAccount *account, const gchar *password,
 355         PurpleKeyringSaveCallback cb, gpointer data);
 356
 357 /**
 358  * purple_keyring_read_settings:
 359  *
 360  * Reads settings from current keyring.
 361  *
 362  * Returns: New copy of current settings (must be free'd with
 363  *         purple_request_fields_destroy).
 364  */
 365 PurpleRequestFields *
 366 purple_keyring_read_settings(void);
 367
 368 /**
 369  * purple_keyring_apply_settings:
 370  * @notify_handle: A handle that can be passed to purple_notify_message.
 371  * @fields:        Modified settings (originally taken from
 372  *                      PurpleKeyringReadSettings).
 373  *
 374  * Applies modified settings to current keyring.
 375  *
 376  * Returns: TRUE, if succeeded, FALSE otherwise.
 377  */
 378 gboolean
 379 purple_keyring_apply_settings(void *notify_handle, PurpleRequestFields *fields);
 380
 381 /**************************************************************************/
 382 /* PurpleKeyring accessors                                                */
 383 /**************************************************************************/
 384
 385 /**
 386  * purple_keyring_get_type:
 387  *
 388  * Returns: The #GType for the #PurpleKeyring boxed structure.
 389  */
 390 GType purple_keyring_get_type(void);
 391
 392 /**
 393  * purple_keyring_new:
 394  *
 395  * Creates a new keyring wrapper.
 396  */
 397 PurpleKeyring *
 398 purple_keyring_new(void);
 399
 400 /**
 401  * purple_keyring_free:
 402  * @keyring: Keyring wrapper struct.
 403  *
 404  * Frees all data allocated with purple_keyring_new.
 405  */
 406 void
 407 purple_keyring_free(PurpleKeyring *keyring);
 408
 409 /**
 410  * purple_keyring_get_name:
 411  * @keyring: The keyring.
 412  *
 413  * Gets friendly user name.
 414  *
 415  * Returns: Friendly user name.
 416  */
 417 const gchar *
 418 purple_keyring_get_name(const PurpleKeyring *keyring);
 419
 420 /**
 421  * purple_keyring_get_id:
 422  * @keyring: The keyring.
 423  *
 424  * Gets keyring ID.
 425  *
 426  * Returns: Keyring ID.
 427  */
 428 const gchar *
 429 purple_keyring_get_id(const PurpleKeyring *keyring);
 430
 431 PurpleKeyringRead
 432 purple_keyring_get_read_password(const PurpleKeyring *keyring);
 433
 434 PurpleKeyringSave
 435 purple_keyring_get_save_password(const PurpleKeyring *keyring);
 436
 437 PurpleKeyringCancelRequests
 438 purple_keyring_get_cancel_requests(const PurpleKeyring *keyring);
 439
 440 PurpleKeyringClose
 441 purple_keyring_get_close_keyring(const PurpleKeyring *keyring);
 442
 443 PurpleKeyringImportPassword
 444 purple_keyring_get_import_password(const PurpleKeyring *keyring);
 445
 446 PurpleKeyringExportPassword
 447 purple_keyring_get_export_password(const PurpleKeyring *keyring);
 448
 449 PurpleKeyringReadSettings
 450 purple_keyring_get_read_settings(const PurpleKeyring *keyring);
 451
 452 PurpleKeyringApplySettings
 453 purple_keyring_get_apply_settings(const PurpleKeyring *keyring);
 454
 455 /**
 456  * purple_keyring_set_name:
 457  * @keyring: The keyring.
 458  * @name:    Friendly user name.
 459  *
 460  * Sets friendly user name.
 461  *
 462  * This field is required.
 463  */
 464 void
 465 purple_keyring_set_name(PurpleKeyring *keyring, const gchar *name);
 466
 467 /**
 468  * purple_keyring_set_id:
 469  * @keyring: The keyring.
 470  * @id:      Keyring ID.
 471  *
 472  * Sets keyring ID.
 473  *
 474  * This field is required.
 475  */
 476 void
 477 purple_keyring_set_id(PurpleKeyring *keyring, const gchar *id);
 478
 479 /**
 480  * purple_keyring_set_read_password:
 481  * @keyring:               The keyring.
 482  * @read_cb: (scope call): Read password method.
 483  *
 484  * Sets read password method.
 485  *
 486  * This field is required.
 487  */
 488 void
 489 purple_keyring_set_read_password(PurpleKeyring *keyring,
 490         PurpleKeyringRead read_cb);
 491
 492 /**
 493  * purple_keyring_set_save_password:
 494  * @keyring:               The keyring.
 495  * @save_cb: (scope call): Save password method.
 496  *
 497  * Sets save password method.
 498  *
 499  * This field is required.
 500  */
 501 void
 502 purple_keyring_set_save_password(PurpleKeyring *keyring,
 503         PurpleKeyringSave save_cb);
 504
 505 /**
 506  * purple_keyring_set_cancel_requests:
 507  * @keyring:         The keyring.
 508  * @cancel_requests: (scope call): Cancel requests method.
 509  *
 510  * Sets cancel requests method.
 511  */
 512 void
 513 purple_keyring_set_cancel_requests(PurpleKeyring *keyring,
 514         PurpleKeyringCancelRequests cancel_requests);
 515
 516 /**
 517  * purple_keyring_set_close_keyring:
 518  * @keyring:                The keyring.
 519  * @close_cb: (scope call): Close keyring method.
 520  *
 521  * Sets close keyring method.
 522  */
 523 void
 524 purple_keyring_set_close_keyring(PurpleKeyring *keyring,
 525         PurpleKeyringClose close_cb);
 526
 527 /**
 528  * purple_keyring_set_import_password:
 529  * @keyring:         The keyring.
 530  * @import_password: (scope call): Import password method.
 531  *
 532  * Sets import password method.
 533  */
 534 void
 535 purple_keyring_set_import_password(PurpleKeyring *keyring,
 536         PurpleKeyringImportPassword import_password);
 537
 538 /**
 539  * purple_keyring_set_export_password:
 540  * @keyring:         The keyring.
 541  * @export_password: (scope call): Export password method.
 542  *
 543  * Sets export password method.
 544  */
 545 void
 546 purple_keyring_set_export_password(PurpleKeyring *keyring,
 547         PurpleKeyringExportPassword export_password);
 548
 549 /**
 550  * purple_keyring_set_read_settings:
 551  * @keyring:       The keyring.
 552  * @read_settings: (scope call): Read settings method.
 553  *
 554  * Sets read settings method.
 555  */
 556 void
 557 purple_keyring_set_read_settings(PurpleKeyring *keyring,
 558         PurpleKeyringReadSettings read_settings);
 559
 560 /**
 561  * purple_keyring_set_apply_settings:
 562  * @keyring:        The keyring.
 563  * @apply_settings: (scope call): Apply settings method.
 564  *
 565  * Sets apply settings method.
 566  */
 567 void
 568 purple_keyring_set_apply_settings(PurpleKeyring *keyring,
 569         PurpleKeyringApplySettings apply_settings);
 570
 571 /**************************************************************************/
 572 /* Error Codes                                                            */
 573 /**************************************************************************/
 574
 575 /**
 576  * purple_keyring_error_domain:
 577  *
 578  * Gets keyring subsystem error domain.
 579  *
 580  * Returns: keyring subsystem error domain.
 581  */
 582 GQuark
 583 purple_keyring_error_domain(void);
 584
 585 /**
 586  * PurpleKeyringError:
 587  * @PURPLE_KEYRING_ERROR_UNKNOWN:      Unknown error.
 588  * @PURPLE_KEYRING_ERROR_NOKEYRING:    No keyring configured.
 589  * @PURPLE_KEYRING_ERROR_INTERNAL:     Internal keyring system error.
 590  * @PURPLE_KEYRING_ERROR_BACKENDFAIL:  Failed to communicate with the backend
 591  *                                     or internal backend error.
 592  * @PURPLE_KEYRING_ERROR_NOPASSWORD:   No password stored for the specified
 593  *                                     account.
 594  * @PURPLE_KEYRING_ERROR_ACCESSDENIED: Access denied for the specified keyring
 595  *                                     or entry.
 596  * @PURPLE_KEYRING_ERROR_CANCELLED:    Operation was cancelled.
 597  *
 598  * Error codes for keyring subsystem.
 599  */
 600 enum PurpleKeyringError
 601 {
 602         PURPLE_KEYRING_ERROR_UNKNOWN = 0,
 603
 604         PURPLE_KEYRING_ERROR_NOKEYRING = 10,
 605         PURPLE_KEYRING_ERROR_INTERNAL,
 606         PURPLE_KEYRING_ERROR_BACKENDFAIL,
 607
 608         PURPLE_KEYRING_ERROR_NOPASSWORD = 20,
 609         PURPLE_KEYRING_ERROR_ACCESSDENIED,
 610         PURPLE_KEYRING_ERROR_CANCELLED
 611 };
 612
 613 /*}@*/
 614
 615 /**************************************************************************/
 616 /* Keyring Subsystem                                                      */
 617 /**************************************************************************/
 618
 619 /**
 620  * purple_keyring_init:
 621  *
 622  * Initializes the keyring subsystem.
 623  */
 624 void
 625 purple_keyring_init(void);
 626
 627 /**
 628  * purple_keyring_uninit:
 629  *
 630  * Uninitializes the keyring subsystem.
 631  */
 632 void
 633 purple_keyring_uninit(void);
 634
 635 /**
 636  * purple_keyring_get_handle:
 637  *
 638  * Returns the keyring subsystem handle.
 639  *
 640  * Returns: The keyring subsystem handle.
 641  */
 642 void *
 643 purple_keyring_get_handle(void);
 644
 645 /*}@*/
 646
 647 G_END_DECLS
 648
 649 #endif /* PURPLE_KEYRING_H */