Authentication
D-Bus secret internal implementation details

DBusAuth object. More...

## Macros

#define | DBUS_AUTH_IN_END_STATE(auth)

## Functions

DBusAuth * | _dbus_auth_server_new (const DBusString *guid)
| Creates a new auth conversation object for the server side.
DBusAuth * | _dbus_auth_client_new (void)
| Creates a new auth conversation object for the client side.
DBusAuth * | _dbus_auth_ref (DBusAuth *auth)
| Increments the refcount of an auth object.
void | _dbus_auth_unref (DBusAuth *auth)
| Decrements the refcount of an auth object.
dbus_bool_t | _dbus_auth_set_mechanisms (DBusAuth *auth, const char **mechanisms)
| Sets an array of authentication mechanism names that we are willing to use.
DBusAuthState | _dbus_auth_do_work (DBusAuth *auth)
| Analyzes buffered input and moves the auth conversation forward, returning the new state of the auth conversation.
dbus_bool_t | _dbus_auth_get_bytes_to_send (DBusAuth *auth, const DBusString **str)
| Gets bytes that need to be sent to the peer we're conversing with.
void | _dbus_auth_bytes_sent (DBusAuth *auth, int bytes_sent)
| Notifies the auth conversation object that the given number of bytes of the outgoing buffer have been written out.
void | _dbus_auth_get_buffer (DBusAuth *auth, DBusString **buffer)
| Get a buffer to be used for reading bytes from the peer we're conversing with.
void | _dbus_auth_return_buffer (DBusAuth *auth, DBusString *buffer)
| Returns a buffer with new data read into it.
void | _dbus_auth_get_unused_bytes (DBusAuth *auth, const DBusString **str)
| Returns leftover bytes that were not used as part of the auth conversation.
void | _dbus_auth_delete_unused_bytes (DBusAuth *auth)
| Gets rid of unused bytes returned by _dbus_auth_get_unused_bytes() after we've gotten them and successfully moved them elsewhere.
dbus_bool_t | _dbus_auth_needs_encoding (DBusAuth *auth)
| Called post-authentication, indicates whether we need to encode the message stream with _dbus_auth_encode_data() prior to sending it to the peer.
dbus_bool_t | _dbus_auth_encode_data (DBusAuth *auth, const DBusString *plaintext, DBusString *encoded)
| Called post-authentication, encodes a block of bytes for sending to the peer.
dbus_bool_t | _dbus_auth_needs_decoding (DBusAuth *auth)
| Called post-authentication, indicates whether we need to decode the message stream with _dbus_auth_decode_data() after receiving it from the peer.
dbus_bool_t | _dbus_auth_decode_data (DBusAuth *auth, const DBusString *encoded, DBusString *plaintext)
| Called post-authentication, decodes a block of bytes received from the peer.
dbus_bool_t | _dbus_auth_set_credentials (DBusAuth *auth, DBusCredentials *credentials)
| Sets credentials received via reliable means from the operating system.
DBusCredentials * | _dbus_auth_get_identity (DBusAuth *auth)
| Gets the identity we authorized the client as.
const char * | _dbus_auth_get_guid_from_server (DBusAuth *auth)
| Gets the GUID from the server if we've authenticated; gets NULL otherwise.
dbus_bool_t | _dbus_auth_set_context (DBusAuth *auth, const DBusString *context)
| Sets the "authentication context" which scopes cookies with the DBUS_COOKIE_SHA1 auth mechanism for example.
void | _dbus_auth_set_unix_fd_possible (DBusAuth *auth, dbus_bool_t b)
| Sets whether unix fd passing is potentially on the transport and hence shall be negotiated.
dbus_bool_t | _dbus_auth_get_unix_fd_negotiated (DBusAuth *auth)
| Queries whether unix fd passing was successfully negotiated.
dbus_bool_t | _dbus_auth_is_supported_mechanism (DBusString *name)
| Queries whether the given auth mechanism is supported.
dbus_bool_t | _dbus_auth_dump_supported_mechanisms (DBusString *buffer)
| Return a human-readable string containing all supported auth mechanisms.

## Detailed Description

DBusAuth object.

DBusAuth manages the authentication negotiation when a connection is first established, and also manages any encryption used over a connection.

## Macro Definition Documentation

## DBUS_AUTH_IN_END_STATE

#define DBUS_AUTH_IN_END_STATE | ( |  | auth | ) |

Value:
((auth)->state->handler == NULL)
NULL
#define NULL
A null pointer, defined appropriately for C or C++.
Definition dbus-macros.h:51

Parameters

  auth | the auth conversation object

Returns
  TRUE if we're in a final state

Definition at line 2538 of file dbus-auth.c.

Referenced by _dbus_auth_delete_unused_bytes(), _dbus_auth_do_work(), and _dbus_auth_get_unused_bytes().

## Function Documentation

## _dbus_auth_bytes_sent()

void _dbus_auth_bytes_sent | ( | DBusAuth * | auth,
|  | int | bytes_sent )

Notifies the auth conversation object that the given number of bytes of the outgoing buffer have been written out.

Parameters

  auth | the auth conversation
  bytes_sent | number of bytes written out

Definition at line 2617 of file dbus-auth.c.

References _dbus_string_delete(), DBUS_AUTH_NAME, and DBusAuth::outgoing.

## _dbus_auth_client_new()

DBusAuth * _dbus_auth_client_new | ( | void |  | ) |

Creates a new auth conversation object for the client side.

See http://dbus.freedesktop.org/doc/dbus-specification.html#auth-protocol for full details on what this object does.

Returns
  the new object or NULL if no memory

Definition at line 2410 of file dbus-auth.c.

References _dbus_auth_unref(), _dbus_string_free(), _dbus_string_init(), DBUS_AUTH_CLIENT, NULL, DBusAuth::side, and DBusAuth::state.

Referenced by _dbus_transport_init_base().

## _dbus_auth_decode_data()

dbus_bool_t _dbus_auth_decode_data | ( | DBusAuth * | auth,
|  | const DBusString * | encoded,
|  | DBusString * | plaintext )

Called post-authentication, decodes a block of bytes received from the peer.

If no encoding was negotiated, just copies the bytes (you can avoid this by checking _dbus_auth_needs_decoding()).

Parameters

  auth | the auth conversation
  encoded | the encoded data
  plaintext | initialized string where decoded data is appended

Returns
  TRUE if we had enough memory and successfully decoded

Definition at line 2798 of file dbus-auth.c.

References _dbus_assert, _dbus_auth_needs_decoding(), _dbus_string_copy(), DBusAuthMechanismHandler::client_decode_func, DBUS_AUTH_IS_CLIENT, FALSE, DBusAuth::mech, DBusAuthMechanismHandler::server_decode_func, and DBusAuth::state.

## _dbus_auth_delete_unused_bytes()

void _dbus_auth_delete_unused_bytes | ( | DBusAuth * | auth | ) |

Gets rid of unused bytes returned by _dbus_auth_get_unused_bytes() after we've gotten them and successfully moved them elsewhere.

Parameters

  auth | the auth conversation

Definition at line 2691 of file dbus-auth.c.

References _dbus_string_set_length(), DBUS_AUTH_IN_END_STATE, and DBusAuth::incoming.

## _dbus_auth_do_work()

DBusAuthState _dbus_auth_do_work | ( | DBusAuth * | auth | ) |

Analyzes buffered input and moves the auth conversation forward, returning the new state of the auth conversation.

Parameters

  auth | the auth conversation

Returns
  the new state

Definition at line 2548 of file dbus-auth.c.

References DBUS_AUTH_IN_END_STATE, DBUS_AUTH_NAME, FALSE, DBusAuth::incoming, DBusAuth::needed_memory, DBusAuth::outgoing, and DBusAuth::state.

Referenced by _dbus_transport_get_dispatch_status(), and _dbus_transport_try_to_authenticate().

## _dbus_auth_dump_supported_mechanisms()

dbus_bool_t _dbus_auth_dump_supported_mechanisms | ( | DBusString * | buffer | ) |

Return a human-readable string containing all supported auth mechanisms.

Parameters

  string | to hold the supported auth mechanisms

Returns
  FALSE on oom

Definition at line 2944 of file dbus-auth.c.

References _dbus_assert, _dbus_string_append(), FALSE, NULL, and TRUE.

## _dbus_auth_encode_data()

dbus_bool_t _dbus_auth_encode_data | ( | DBusAuth * | auth,
|  | const DBusString * | plaintext,
|  | DBusString * | encoded )

Called post-authentication, encodes a block of bytes for sending to the peer.

If no encoding was negotiated, just copies the bytes (you can avoid this by checking _dbus_auth_needs_encoding()).

Parameters

  auth | the auth conversation
  plaintext | the plain text data
  encoded | initialized string to where encoded data is appended

Returns
  TRUE if we had enough memory and successfully encoded

Definition at line 2735 of file dbus-auth.c.

References _dbus_assert, _dbus_auth_needs_encoding(), _dbus_string_copy(), DBusAuthMechanismHandler::client_encode_func, DBUS_AUTH_IS_CLIENT, FALSE, DBusAuth::mech, DBusAuthMechanismHandler::server_encode_func, and DBusAuth::state.

## _dbus_auth_get_buffer()

void _dbus_auth_get_buffer | ( | DBusAuth * | auth,
|  | DBusString ** | buffer )

Get a buffer to be used for reading bytes from the peer we're conversing with.

Bytes should be appended to this buffer.

Parameters

  auth | the auth conversation
  buffer | return location for buffer to append bytes to

Definition at line 2637 of file dbus-auth.c.

References _dbus_assert, DBusAuth::buffer_outstanding, DBusAuth::incoming, NULL, and TRUE.

## _dbus_auth_get_bytes_to_send()

dbus_bool_t _dbus_auth_get_bytes_to_send | ( | DBusAuth * | auth,
|  | const DBusString ** | str )

Gets bytes that need to be sent to the peer we're conversing with.

After writing some bytes, _dbus_auth_bytes_sent() must be called to notify the auth object that they were written.

Parameters

  auth | the auth conversation
  str | return location for a ref to the buffer to send

Returns
  FALSE if nothing to send

Definition at line 2592 of file dbus-auth.c.

References _dbus_assert, FALSE, NULL, DBusAuth::outgoing, and TRUE.

## _dbus_auth_get_guid_from_server()

const char * _dbus_auth_get_guid_from_server | ( | DBusAuth * | auth | ) |

Gets the GUID from the server if we've authenticated; gets NULL otherwise.

Parameters

  auth | the auth object

Returns
  the GUID in ASCII hex format

Definition at line 2872 of file dbus-auth.c.

References _dbus_assert, DBUS_AUTH_CLIENT, DBUS_AUTH_IS_CLIENT, NULL, and DBusAuth::state.

Referenced by _dbus_transport_get_server_id(), and _dbus_transport_try_to_authenticate().

## _dbus_auth_get_identity()

DBusCredentials * _dbus_auth_get_identity | ( | DBusAuth * | auth | ) |

Gets the identity we authorized the client as.

Apps may have different policies as to what identities they allow.

Returned credentials are not a copy and should not be modified

Parameters

  auth | the auth conversation

Returns
  the credentials we've authorized BY REFERENCE do not modify

Definition at line 2848 of file dbus-auth.c.

References _dbus_assert, _dbus_credentials_are_empty(), DBusAuth::authorized_identity, and DBusAuth::state.

Referenced by _dbus_transport_get_adt_audit_session_data(), _dbus_transport_get_credentials(), _dbus_transport_get_is_anonymous(), _dbus_transport_get_unix_process_id(), _dbus_transport_get_unix_user(), _dbus_transport_get_windows_user(), and _dbus_transport_try_to_authenticate().

## _dbus_auth_get_unix_fd_negotiated()

dbus_bool_t _dbus_auth_get_unix_fd_negotiated | ( | DBusAuth * | auth | ) |

Queries whether unix fd passing was successfully negotiated.

Parameters

  auth | the auth conversion

Returns
  TRUE when unix fd passing was negotiated.

Definition at line 2918 of file dbus-auth.c.

References DBusAuth::unix_fd_negotiated.

## _dbus_auth_get_unused_bytes()

void _dbus_auth_get_unused_bytes | ( | DBusAuth * | auth,
|  | const DBusString ** | str )

Returns leftover bytes that were not used as part of the auth conversation.

These bytes will be part of the message stream instead. This function may not be called until authentication has succeeded.

Parameters

  auth | the auth conversation
  str | return location for pointer to string of unused bytes

Definition at line 2674 of file dbus-auth.c.

References DBUS_AUTH_IN_END_STATE, and DBusAuth::incoming.

## _dbus_auth_is_supported_mechanism()

dbus_bool_t _dbus_auth_is_supported_mechanism | ( | DBusString * | name | ) |

Queries whether the given auth mechanism is supported.

Parameters

  auth | the auth mechanism to query for

Returns
  TRUE when auth mechanism is supported

Definition at line 2930 of file dbus-auth.c.

References _dbus_assert, and NULL.

## _dbus_auth_needs_decoding()

dbus_bool_t _dbus_auth_needs_decoding | ( | DBusAuth * | auth | ) |

Called post-authentication, indicates whether we need to decode the message stream with _dbus_auth_decode_data() after receiving it from the peer.

Parameters

  auth | the auth conversation

Returns
  TRUE if we need to encode the stream

Definition at line 2767 of file dbus-auth.c.

References DBusAuthMechanismHandler::client_decode_func, DBUS_AUTH_IS_CLIENT, FALSE, DBusAuth::mech, NULL, DBusAuthMechanismHandler::server_decode_func, and DBusAuth::state.

Referenced by _dbus_auth_decode_data().

## _dbus_auth_needs_encoding()

dbus_bool_t _dbus_auth_needs_encoding | ( | DBusAuth * | auth | ) |

Called post-authentication, indicates whether we need to encode the message stream with _dbus_auth_encode_data() prior to sending it to the peer.

Parameters

  auth | the auth conversation

Returns
  TRUE if we need to encode the stream

Definition at line 2708 of file dbus-auth.c.

References DBusAuthMechanismHandler::client_encode_func, DBUS_AUTH_IS_CLIENT, FALSE, DBusAuth::mech, NULL, DBusAuthMechanismHandler::server_encode_func, and DBusAuth::state.

Referenced by _dbus_auth_encode_data().

## _dbus_auth_ref()

DBusAuth * _dbus_auth_ref | ( | DBusAuth * | auth | ) |

Increments the refcount of an auth object.

Parameters

  auth | the auth conversation

Returns
  the auth conversation

Definition at line 2448 of file dbus-auth.c.

References _dbus_assert, NULL, and DBusAuth::refcount.

## _dbus_auth_return_buffer()

void _dbus_auth_return_buffer | ( | DBusAuth * | auth,
|  | DBusString * | buffer )

Returns a buffer with new data read into it.

Parameters

  auth | the auth conversation
  buffer | the buffer being returned

Definition at line 2655 of file dbus-auth.c.

References _dbus_assert, DBusAuth::buffer_outstanding, FALSE, and DBusAuth::incoming.

## _dbus_auth_server_new()

DBusAuth * _dbus_auth_server_new | ( | const DBusString * | guid | ) |

Creates a new auth conversation object for the server side.

See http://dbus.freedesktop.org/doc/dbus-specification.html#auth-protocol for full details on what this object does.

Returns
  the new object or NULL if no memory

Definition at line 2364 of file dbus-auth.c.

References _dbus_string_copy(), _dbus_string_free(), _dbus_string_init(), DBUS_AUTH_SERVER, DBusAuthServer::failures, DBusAuthServer::guid, DBusAuthServer::max_failures, NULL, DBusAuth::side, and DBusAuth::state.

Referenced by _dbus_transport_init_base().

## _dbus_auth_set_context()

dbus_bool_t _dbus_auth_set_context | ( | DBusAuth * | auth,
|  | const DBusString * | context )

Sets the "authentication context" which scopes cookies with the DBUS_COOKIE_SHA1 auth mechanism for example.

Parameters

  auth | the auth conversation
  context | the context

Returns
  FALSE if no memory

Definition at line 2891 of file dbus-auth.c.

References _dbus_string_replace_len(), and DBusAuth::context.

## _dbus_auth_set_credentials()

dbus_bool_t _dbus_auth_set_credentials | ( | DBusAuth * | auth,
|  | DBusCredentials * | credentials )

Sets credentials received via reliable means from the operating system.

Parameters

  auth | the auth conversation
  credentials | the credentials received

Returns
  FALSE on OOM

Definition at line 2830 of file dbus-auth.c.

References _dbus_credentials_add_credentials(), _dbus_credentials_clear(), and DBusAuth::credentials.

## _dbus_auth_set_mechanisms()

dbus_bool_t _dbus_auth_set_mechanisms | ( | DBusAuth * | auth,
|  | const char ** | mechanisms )

Sets an array of authentication mechanism names that we are willing to use.

Parameters

  auth | the auth conversation
  mechanisms | NULL-terminated array of mechanism names

Returns
  FALSE if no memory

Definition at line 2513 of file dbus-auth.c.

References _dbus_dup_string_array(), DBusAuth::allowed_mechs, dbus_free_string_array(), FALSE, NULL, and TRUE.

Referenced by _dbus_transport_set_auth_mechanisms().

## _dbus_auth_set_unix_fd_possible()

void _dbus_auth_set_unix_fd_possible | ( | DBusAuth * | auth,
|  | dbus_bool_t | b )

Sets whether unix fd passing is potentially on the transport and hence shall be negotiated.

Parameters

  auth | the auth conversation
  b | TRUE when unix fd passing shall be negotiated, otherwise FALSE

Definition at line 2906 of file dbus-auth.c.

References DBusAuth::unix_fd_possible.

Referenced by _dbus_transport_new_for_socket().

## _dbus_auth_unref()

void _dbus_auth_unref | ( | DBusAuth * | auth | ) |

Decrements the refcount of an auth object.

Parameters

  auth | the auth conversation

Definition at line 2463 of file dbus-auth.c.

References _dbus_assert, _dbus_credentials_unref(), _dbus_keyring_unref(), _dbus_list_clear(), _dbus_string_free(), DBusAuth::allowed_mechs, DBusAuth::authorized_identity, DBusAuth::challenge, DBusAuth::context, DBusAuth::credentials, DBUS_AUTH_CLIENT, DBUS_AUTH_IS_CLIENT, DBUS_AUTH_IS_SERVER, DBUS_AUTH_SERVER, dbus_free(), dbus_free_string_array(), DBusAuth::desired_identity, DBusAuth::identity, DBusAuth::incoming, DBusAuth::keyring, NULL, DBusAuth::outgoing, and DBusAuth::refcount.

Referenced by _dbus_auth_client_new(), _dbus_transport_finalize_base(), and _dbus_transport_init_base().