Authentication
[D-Bus secret internal implementation details]

DBusAuth object. More...

Defines

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

Parameters:

auth

the auth conversation object

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, int bytes_read)

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.

void _dbus_auth_set_credentials (DBusAuth *auth, const DBusCredentials *credentials)

Sets credentials received via reliable means from the operating system.

void _dbus_auth_get_identity (DBusAuth *auth, DBusCredentials *credentials)

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.

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

Define Documentation

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

Parameters:

auth

the auth conversation object

Returns:: TRUE if we're in a final state

Definition at line 2147 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:

	auth	the auth conversation
	bytes_sent	number of bytes written out

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

References _dbus_string_delete(), and DBUS_AUTH_NAME.

DBusAuth* _dbus_auth_client_new ( void )

Creates a new auth conversation object for the client side.

See doc/dbus-sasl-profile.txt for full details on what this object does.

Returns:: the new object or NULL if no memory

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

References _dbus_auth_unref(), _dbus_string_free(), _dbus_string_init(), DBUS_AUTH_CLIENT, 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:

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

References _dbus_assert, _dbus_auth_needs_decoding(), _dbus_string_copy(), DBUS_AUTH_IS_CLIENT, FALSE, 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:

auth

the auth conversation

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

References _dbus_string_set_length(), and DBUS_AUTH_IN_END_STATE.

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

References DBUS_AUTH_IN_END_STATE, DBUS_AUTH_NAME, FALSE, and needed_memory.

Referenced by _dbus_transport_get_dispatch_status(), and _dbus_transport_get_is_authenticated().

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

References _dbus_assert, _dbus_auth_needs_encoding(), _dbus_string_copy(), DBUS_AUTH_IS_CLIENT, FALSE, 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:

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

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

References _dbus_assert, buffer_outstanding, incoming, 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:

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

Returns:: FALSE if nothing to send

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

References _dbus_assert, FALSE, 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:

auth

the auth object

Returns:: the GUID in ASCII hex format

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

References _dbus_assert, DBUS_AUTH_CLIENT, and DBUS_AUTH_IS_CLIENT.

Referenced by _dbus_transport_get_is_authenticated().

void _dbus_auth_get_identity	(	DBusAuth *	auth,
		DBusCredentials *	credentials
	)

Gets the identity we authorized the client as.

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

Parameters:

	auth	the auth conversation
	credentials	the credentials we've authorized

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

References _dbus_credentials_clear(), authorized_identity, and state.

Referenced by _dbus_transport_get_is_authenticated(), _dbus_transport_get_unix_process_id(), and _dbus_transport_get_unix_user().

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

References DBUS_AUTH_IN_END_STATE.

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

References DBUS_AUTH_IS_CLIENT, FALSE, mech, 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:

auth

the auth conversation

Returns:: TRUE if we need to encode the stream

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

References DBUS_AUTH_IS_CLIENT, FALSE, mech, and state.

Referenced by _dbus_auth_encode_data().

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

References _dbus_assert, and refcount.

void _dbus_auth_return_buffer	(	DBusAuth *	auth,
		DBusString *	buffer,
		int	bytes_read
	)

Returns a buffer with new data read into it.

Parameters:

	auth	the auth conversation
	buffer	the buffer being returned
	bytes_read	number of new bytes added

Definition at line 2265 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 doc/dbus-sasl-profile.txt for full details on what this object does.

Returns:: the new object or NULL if no memory

Definition at line 1977 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, 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:

	auth	the auth conversation
	context	the context

Returns:: FALSE if no memory

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

References _dbus_string_replace_len(), and context.

void _dbus_auth_set_credentials	(	DBusAuth *	auth,
		const DBusCredentials *	credentials
	)

Sets credentials received via reliable means from the operating system.

Parameters:

	auth	the auth conversation
	credentials	the credentials received

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

References 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:

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

Returns:: FALSE if no memory

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

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

Referenced by _dbus_transport_set_auth_mechanisms().

void _dbus_auth_unref ( DBusAuth * auth )

Decrements the refcount of an auth object.

Parameters:

auth

the auth conversation

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

References _dbus_assert, _dbus_keyring_unref(), _dbus_list_clear(), _dbus_string_free(), DBUS_AUTH_CLIENT, DBUS_AUTH_IS_CLIENT, DBUS_AUTH_IS_SERVER, DBUS_AUTH_SERVER, dbus_free(), dbus_free_string_array(), and refcount.

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

Generated on Tue Apr 15 15:54:04 2008 for D-Bus by

1.5.1

Authentication [D-Bus secret internal implementation details]

Defines

Functions

Detailed Description

Define Documentation

Function Documentation

Authentication
[D-Bus secret internal implementation details]