keyring class
D-Bus secret internal implementation details

DBusKeyring data structure. More...

## Functions

DBusKeyring * | _dbus_keyring_ref (DBusKeyring *keyring)
| Increments reference count of the keyring. More...
void | _dbus_keyring_unref (DBusKeyring *keyring)
| Decrements refcount and finalizes if it reaches zero. More...
DBusKeyring * | _dbus_keyring_new_for_credentials (DBusCredentials *credentials, const DBusString *context, DBusError *error)
| Creates a new keyring that lives in the ~/.dbus-keyrings directory of the given user credentials. More...
dbus_bool_t | _dbus_keyring_validate_context (const DBusString *context)
| Checks whether the context is a valid context. More...
int | _dbus_keyring_get_best_key (DBusKeyring *keyring, DBusError *error)
| Gets a recent key to use for authentication. More...
dbus_bool_t | _dbus_keyring_is_for_credentials (DBusKeyring *keyring, DBusCredentials *credentials)
| Checks whether the keyring is for the same user as the given credentials. More...
dbus_bool_t | _dbus_keyring_get_hex_key (DBusKeyring *keyring, int key_id, DBusString *hex_key)
| Gets the hex-encoded secret key for the given ID. More...

## Detailed Description

DBusKeyring data structure.

Types and functions related to DBusKeyring. DBusKeyring is intended to manage cookies used to authenticate clients to servers. This is essentially the "verify that client can read the user's homedir" authentication mechanism. Both client and server must have access to the homedir.

The secret keys are not kept in locked memory, and are written to a file in the user's homedir. However they are transient (only used by a single server instance for a fixed period of time, then discarded). Also, the keys are not sent over the wire.

Todo:
  there's a memory leak on some codepath in here, I saw it once when running make check - probably some specific initial cookies present in the cookie file, then depending on what we do with them.

## Function Documentation

int _dbus_keyring_get_best_key | ( | DBusKeyring * | keyring,
|  | DBusError * | error
| ) |  |

Gets a recent key to use for authentication.

If no recent key exists, creates one. Returns the key ID. If a key can't be written to the keyring file so no recent key can be created, returns -1. All valid keys are > 0.

Parameters

  keyring | the keyring
  error | error on failure

Returns
  key ID to use for auth, or -1 on failure

Definition at line 949 of file dbus-keyring.c.

References DBUS_ERROR_FAILED, dbus_set_error_const(), DBusKey::id, and TRUE.

dbus_bool_t _dbus_keyring_get_hex_key | ( | DBusKeyring * | keyring,
|  | int | key_id,
|  | DBusString * | hex_key
| ) |  |

Gets the hex-encoded secret key for the given ID.

Returns FALSE if not enough memory. Returns TRUE but empty key on any other error such as unknown key ID.

Parameters

  keyring | the keyring
  key_id | the key ID
  hex_key | string to append hex-encoded key to

Returns
  TRUE if we had enough memory

Definition at line 1007 of file dbus-keyring.c.

References _dbus_string_get_length(), _dbus_string_hex_encode(), keys, n_keys, NULL, DBusKey::secret, and TRUE.

dbus_bool_t _dbus_keyring_is_for_credentials | ( | DBusKeyring * | keyring,
|  | DBusCredentials * | credentials
| ) |  |

Checks whether the keyring is for the same user as the given credentials.

Parameters

  keyring | the keyring
  credentials | the credentials to check

Returns
  TRUE if the keyring belongs to the given user

Definition at line 988 of file dbus-keyring.c.

References _dbus_credentials_same_user(), and credentials.

DBusKeyring* _dbus_keyring_new_for_credentials | ( | DBusCredentials * | credentials,
|  | const DBusString * | context,
|  | DBusError * | error
| ) |  |

Creates a new keyring that lives in the ~/.dbus-keyrings directory of the given user credentials.

If the credentials are NULL or empty, uses those of the current process.

Parameters

  username | username to get keyring for, or NULL
  context | which keyring to get
  error | return location for errors

Returns
  the keyring or NULL on error

Definition at line 709 of file dbus-keyring.c.

References _dbus_append_keyring_directory_for_credentials(), _dbus_assert, _dbus_check_setuid(), _dbus_concat_dir_and_file(), _dbus_create_directory(), _dbus_credentials_add_from_current_process(), _dbus_credentials_are_anonymous(), _dbus_credentials_copy(), _dbus_credentials_new_from_current_process(), _dbus_credentials_unref(), _dbus_keyring_unref(), _dbus_keyring_validate_context(), _dbus_string_append(), _dbus_string_copy(), _dbus_string_free(), _dbus_string_init(), credentials, DBUS_ERROR_FAILED, dbus_error_free(), dbus_error_init(), DBUS_ERROR_NO_MEMORY, DBUS_ERROR_NOT_SUPPORTED, dbus_set_error(), dbus_set_error_const(), directory, FALSE, filename, filename_lock, DBusError::message, NULL, and TRUE.

DBusKeyring* _dbus_keyring_ref | ( | DBusKeyring * | keyring) |  |

Increments reference count of the keyring.

Parameters

  keyring | the keyring

Returns
  the keyring

Definition at line 667 of file dbus-keyring.c.

References refcount.

void _dbus_keyring_unref | ( | DBusKeyring * | keyring) |  |

Decrements refcount and finalizes if it reaches zero.

Parameters

  keyring | the keyring

Definition at line 681 of file dbus-keyring.c.

References _dbus_credentials_unref(), _dbus_string_free(), credentials, dbus_free(), directory, filename, filename_lock, keys, n_keys, and refcount.

Referenced by _dbus_auth_unref(), and _dbus_keyring_new_for_credentials().

dbus_bool_t _dbus_keyring_validate_context | ( | const DBusString * | context) |  |

Checks whether the context is a valid context.

Contexts that might cause confusion when used in filenames are not allowed (contexts can't start with a dot or contain dir separators).

Todo:
  this is the most inefficient implementation imaginable.

Parameters

  context | the context

Returns
  TRUE if valid

Definition at line 853 of file dbus-keyring.c.

References _dbus_string_find(), _dbus_string_find_blank(), _dbus_string_get_length(), _dbus_string_validate_ascii(), FALSE, NULL, and TRUE.

Referenced by _dbus_keyring_new_for_credentials().