From 7e050c88719553d0c74e3dc68caf7bc50ae99590 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Wed, 5 Mar 2003 02:01:34 +0000 Subject: 2003-03-04 Havoc Pennington * test/data/auth/*: adapt to changes * dbus/dbus-auth-script.c (_dbus_auth_script_run): add USERID_BASE64 and change USERNAME_BASE64 to put in username not userid * dbus/dbus-keyring.c (_dbus_keyring_validate_context): prevent more stuff from being in a context name, to make the protocol simpler to deal with * dbus/dbus-errors.c (dbus_error_has_name): new function (dbus_error_is_set): new function * dbus/dbus-auth.c: replace DBUS_STUPID_TEST_MECH auth with DBUS_COOKIE_SHA1, implement DBUS_COOKIE_SHA1 * dbus/dbus-connection.c (dbus_connection_flush): also read messages during a flush operation * dbus/Makefile.am: remove dbus-md5 since it isn't currently used. --- doc/dbus-specification.sgml | 145 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 144 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml index 48cc086d..0845d806 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.sgml @@ -476,7 +476,6 @@ The credentials sent along with the nul byte may be used with the SASL mechanism EXTERNAL. - @@ -683,6 +682,150 @@ + + Authentication mechanisms + + This section describes some new authentication mechanisms. + D-BUS also allows any standard SASL mechanism of course. + + + DBUS_COOKIE_SHA1 + + The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client + has the ability to read a private file owned by the user being + authenticated. If the client can prove that it has access to a secret + cookie stored in this file, then the client is authenticated. + Thus the security of DBUS_COOKIE_SHA1 depends on a secure home + directory. + + + Authentication proceeds as follows: + + + + The client sends the username it would like to authenticate + as. + + + + + The server sends the name of its "cookie context" (see below); a + space character; the integer ID of the secret cookie the client + must demonstrate knowledge of; a space character; then a + hex-encoded randomly-generated challenge string. + + + + + The client locates the cookie, and generates its own hex-encoded + randomly-generated challenge string. The client then + concatentates the server's hex-encoded challenge, a ":" + character, its own hex-encoded challenge, another ":" character, + and the hex-encoded cookie. It computes the SHA-1 hash of this + composite string. It sends back to the server the client's + hex-encoded challenge string, a space character, and the SHA-1 + hash. + + + + + The server generates the same concatenated string used by the + client and computes its SHA-1 hash. It compares the hash with + the hash received from the client; if the two hashes match, the + client is authenticated. + + + + + + Each server has a "cookie context," which is a name that identifies a + set of cookies that apply to that server. A sample context might be + "org_freedesktop_session_bus". Context names must be valid ASCII, + nonzero length, and may not contain the characters slash ("/"), + backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"), + tab ("\t"), or period ("."). There is a default context, + "org_freedesktop_global" that's used by servers that do not specify + otherwise. + + + Cookies are stored in a user's home directory, in the directory + ~/.dbus-keyrings/. This directory must + not be readable or writable by other users. If it is, + clients and servers must ignore it. The directory + contains cookie files named after the cookie context. + + + A cookie file contains one cookie per line. Each line + has three space-separated fields: + + + + The cookie ID number, which must be a non-negative integer and + may not be used twice in the same file. + + + + + The cookie's creation time, in UNIX seconds-since-the-epoch + format. + + + + + The cookie itself, a hex-encoded random block of bytes. + + + + + + Only server processes modify the cookie file. + They must do so with this procedure: + + + + Create a lockfile name by appending ".lock" to the name of the + cookie file. The server should attempt to create this file + using O_CREAT | O_EXCL. If file creation + fails, the lock fails. Servers should retry for a reasonable + period of time, then they may choose to delete an existing lock + to keep users from having to manually delete a stale + lock. Lockfiles are used instead of real file + locking fcntl() because real locking + implementations are still flaky on network + filesystems. + + + + + Once the lockfile has been created, the server loads the cookie + file. It should then delete any cookies that are old (the + timeout can be fairly short), or more than a reasonable + time in the future (so that cookies never accidentally + become permanent, if the clock was set far into the future + at some point). If no recent keys remain, the + server may generate a new key. + + + + + The pruned and possibly added-to cookie file + must be resaved atomically (using a temporary + file which is rename()'d). + + + + + The lock must be dropped by deleting the lockfile. + + + + + + Clients need not lock the file in order to load it, + because servers are required to save the file atomically. + + + Server Addresses -- cgit