D-Bus  1.9.0
Macros | Functions

DBusAuth object. More...

Macros

#define DBUS_AUTH_IN_END_STATE(auth)   ((auth)->state->handler == NULL)
 

Functions

DBusAuth_dbus_auth_server_new (const DBusString *guid)
 Creates a new auth conversation object for the server side. More...
 
DBusAuth_dbus_auth_client_new (void)
 Creates a new auth conversation object for the client side. More...
 
DBusAuth_dbus_auth_ref (DBusAuth *auth)
 Increments the refcount of an auth object. More...
 
void _dbus_auth_unref (DBusAuth *auth)
 Decrements the refcount of an auth object. More...
 
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. More...
 
DBusAuthState _dbus_auth_do_work (DBusAuth *auth)
 Analyzes buffered input and moves the auth conversation forward, returning the new state of the auth conversation. More...
 
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. More...
 
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. More...
 
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. More...
 
void _dbus_auth_return_buffer (DBusAuth *auth, DBusString *buffer)
 Returns a buffer with new data read into it. More...
 
void _dbus_auth_get_unused_bytes (DBusAuth *auth, const DBusString **str)
 Returns leftover bytes that were not used as part of the auth conversation. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
dbus_bool_t _dbus_auth_set_credentials (DBusAuth *auth, DBusCredentials *credentials)
 Sets credentials received via reliable means from the operating system. More...
 
DBusCredentials_dbus_auth_get_identity (DBusAuth *auth)
 Gets the identity we authorized the client as. More...
 
const char * _dbus_auth_get_guid_from_server (DBusAuth *auth)
 Gets the GUID from the server if we've authenticated; gets NULL otherwise. More...
 
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. More...
 
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. More...
 
dbus_bool_t _dbus_auth_get_unix_fd_negotiated (DBusAuth *auth)
 Queries whether unix fd passing was successfully negotiated. More...
 

Detailed Description

DBusAuth object.

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

Todo:
some SASL profiles require sending the empty string as a challenge/response, but we don't currently allow that in our protocol.
Todo:
right now sometimes both ends will block waiting for input from the other end, e.g. if there's an error during DBUS_COOKIE_SHA1.
Todo:
the cookie keyring needs to be cached globally not just per-auth (which raises threadsafety issues too)
Todo:
grep FIXME in dbus-auth.c

Macro Definition Documentation

#define DBUS_AUTH_IN_END_STATE (   auth)    ((auth)->state->handler == NULL)
Parameters
auththe auth conversation object
Returns
TRUE if we're in a final state

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

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

Function Documentation

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
auththe auth conversation
bytes_sentnumber of bytes written out

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

References _dbus_string_delete(), _dbus_string_get_const_data(), DBUS_AUTH_NAME, and outgoing.

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 2293 of file dbus-auth.c.

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

Referenced by _dbus_transport_init_base().

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()).

Todo:
1.0? We need to be able to distinguish "out of memory" error from "the data is hosed" error.
Parameters
auththe auth conversation
encodedthe encoded data
plaintextinitialized string where decoded data is appended
Returns
TRUE if we had enough memory and successfully decoded

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

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

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
auththe auth conversation

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

References _dbus_string_set_length(), DBUS_AUTH_IN_END_STATE, and incoming.

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
auththe auth conversation
Returns
the new state

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

References _dbus_string_get_length(), DBUS_AUTH_IN_END_STATE, DBUS_AUTH_NAME, FALSE, incoming, needed_memory, outgoing, and state.

Referenced by _dbus_transport_get_dispatch_status(), and _dbus_transport_try_to_authenticate().

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
auththe auth conversation
plaintextthe plain text data
encodedinitialized string to where encoded data is appended
Returns
TRUE if we had enough memory and successfully encoded

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

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

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
auththe auth conversation
bufferreturn location for buffer to append bytes to

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

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

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
auththe auth conversation
strreturn location for a ref to the buffer to send
Returns
FALSE if nothing to send

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

References _dbus_assert, _dbus_string_get_length(), FALSE, NULL, outgoing, and TRUE.

const char* _dbus_auth_get_guid_from_server ( DBusAuth auth)

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

Parameters
auththe auth object
Returns
the GUID in ASCII hex format

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

References _dbus_assert, _dbus_string_get_const_data(), DBUS_AUTH_CLIENT, DBUS_AUTH_IS_CLIENT, NULL, and state.

Referenced by _dbus_transport_get_server_id(), and _dbus_transport_try_to_authenticate().

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
auththe auth conversation
Returns
the credentials we've authorized BY REFERENCE do not modify

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

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

Referenced by _dbus_transport_get_adt_audit_session_data(), _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_bool_t _dbus_auth_get_unix_fd_negotiated ( DBusAuth auth)

Queries whether unix fd passing was successfully negotiated.

Parameters
auththe auth conversion
Returns
TRUE when unix fd passing was negotiated.

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

References unix_fd_negotiated.

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
auththe auth conversation
strreturn location for pointer to string of unused bytes

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

References DBUS_AUTH_IN_END_STATE, and incoming.

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
auththe auth conversation
Returns
TRUE if we need to encode the stream

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

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

Referenced by _dbus_auth_decode_data().

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
auththe auth conversation
Returns
TRUE if we need to encode the stream

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

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

Referenced by _dbus_auth_encode_data().

DBusAuth* _dbus_auth_ref ( DBusAuth auth)

Increments the refcount of an auth object.

Parameters
auththe auth conversation
Returns
the auth conversation

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

References _dbus_assert, NULL, and refcount.

void _dbus_auth_return_buffer ( DBusAuth auth,
DBusString buffer 
)

Returns a buffer with new data read into it.

Parameters
auththe auth conversation
bufferthe buffer being returned

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

References _dbus_assert, buffer_outstanding, FALSE, and incoming.

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 2247 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, side, and state.

Referenced by _dbus_transport_init_base().

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
auththe auth conversation
contextthe context
Returns
FALSE if no memory

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

References _dbus_string_get_length(), _dbus_string_replace_len(), and context.

dbus_bool_t _dbus_auth_set_credentials ( DBusAuth auth,
DBusCredentials credentials 
)

Sets credentials received via reliable means from the operating system.

Parameters
auththe auth conversation
credentialsthe credentials received
Returns
FALSE on OOM

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

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

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
auththe auth conversation
mechanismsNULL-terminated array of mechanism names
Returns
FALSE if no memory

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

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

Referenced by _dbus_transport_set_auth_mechanisms().

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
auththe auth conversation
bTRUE when unix fd passing shall be negotiated, otherwise FALSE

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

References unix_fd_possible.

Referenced by _dbus_transport_new_for_socket().

void _dbus_auth_unref ( DBusAuth auth)