Main Page   Modules   Data Structures   File List   Data Fields   Related Pages  

Authentication
[D-BUS internal implementation details]

DBusAuth object. More...

Defines

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

Functions

DBusAuth * _dbus_auth_server_new (void)
 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, int bytes_read)
 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...

void _dbus_auth_set_credentials (DBusAuth *auth, const DBusCredentials *credentials)
 Sets credentials received via reliable means from the operating system. More...

void _dbus_auth_get_identity (DBusAuth *auth, DBusCredentials *credentials)
 Gets the identity we authorized the client as. 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...


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.

DBusAuth really needs to be rewritten as an explicit state machine. Right now it's too hard to prove to yourself by inspection that it works.

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.

the cookie keyring needs to be cached globally not just per-auth (which raises threadsafety issues too)

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


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

References outgoing.

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

References side, and state.

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

References DBusAuthMechanismHandler::client_decode_func, 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:
auth  the auth conversation

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

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

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

References incoming, needed_memory, outgoing, and state.

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

References DBusAuthMechanismHandler::client_encode_func, 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:
auth  the auth conversation
buffer  return location for buffer to append bytes to

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

References buffer_outstanding, and incoming.

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

References outgoing.

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

References authorized_identity, and state.

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

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

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

References DBusAuthMechanismHandler::client_decode_func, mech, DBusAuthMechanismHandler::server_decode_func, and state.

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

References DBusAuthMechanismHandler::client_encode_func, mech, DBusAuthMechanismHandler::server_encode_func, and state.

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

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

References buffer_outstanding, and incoming.

DBusAuth* _dbus_auth_server_new void   
 

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

References DBusAuthServer::failures, DBusAuthServer::max_failures, side, and state.

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

References 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 2353 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 2035 of file dbus-auth.c.

References allowed_mechs.

void _dbus_auth_unref DBusAuth   auth
 

Decrements the refcount of an auth object.

Parameters:
auth  the auth conversation

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

References allowed_mechs, challenge, context, identity, incoming, keyring, outgoing, and refcount.


Generated on Wed Jun 9 05:01:27 2004 for D-BUS by doxygen1.2.15