adbus_Auth Struct Reference

Minimal SASL client and server to connect to DBUS. More...

Related Functions
(Note that these are not member functions.)
void	adbus_auth_free (adbus_Auth *a)
	Free an auth structure.
adbus_Auth *	adbus_sauth_new (adbus_SendCallback send, adbus_RandCallback rand, void *data)
	Create an auth structure for server use.
void	adbus_sauth_setuuid (adbus_Auth *a, const char *uuid)
	Sets the server uuid.
void	adbus_sauth_external (adbus_Auth *a, adbus_ExternalCallback cb)
	Sets up a server auth for the external auth mechanism.
adbus_Auth *	adbus_cauth_new (adbus_SendCallback send, adbus_RandCallback rand, void *data)
	Create an auth structure for client use.
void	adbus_cauth_external (adbus_Auth *a)
	Sets up a client auth to try the external auth mechanism.
int	adbus_cauth_start (adbus_Auth *a)
	Initiates the client auth.
int	adbus_auth_line (adbus_Auth *a, const char *line, size_t len)
	Parses a line received from the remote.
int	adbus_auth_parse (adbus_Auth *a, adbus_Buffer *buf)
	Consumes auth lines from the supplied buffer.

---

Detailed Description

Minimal SASL client and server to connect to DBUS.

Note:

The auth module is not tied to the adbus_Connection or adbus_Server modules and can be used independently and can be replaced if needed.

The auth module does _not_ send the leading null byte. This must be sent seperately.

If using adbus_auth_parse(), you should use the same buffer for the connnection or remote parsing, as received data after the auth is complete is left in the buffer.

The adbus_Auth is used for both client and server connections. The client specific function begin with adbus_cauth_, server specific adbus_sauth_, and common adbus_auth_.

The auth module is designed to be extendable by allowing the user of the API to manually filter out lines and handle them themselves. For example you could add a filter for "STARTTLS" which would then initiate TLS on the connection.

Client Authentication

The workflow for client auth is:

1. Create the auth structure using adbus_cauth_new().
2. Setup auth mechanisms for example adbus_cauth_external().
3. Start the auth with adbus_cauth_start().
4. Feed responses from the remote using adbus_auth_parse() or adbus_auth_line() until they return a non-zero value.
5. Free the auth structure.

For example (this is the actual code for adbus_sock_cauth):

  int Send(void* user, const char* data, size_t sz)
  {
      adbus_Socket s = *(adbus_Socket*) user;
      return send(s, data, sz, 0);
  }

  uint8_t Rand(void* user)
  {
      (void) user;
      return (uint8_t) rand();
  }

  #define RECV_SIZE 1024
  int adbus_sock_cauth(adbus_Socket sock, adbus_Buffer* buffer)
  {
      int ret = 0;

      adbus_Auth* a = adbus_cauth_new(&Send, &Rand, &sock);
      adbus_cauth_external(a);

      if (send(sock, "\0", 1, 0) != 1)
          goto err;

      if (adbus_cauth_start(a))
          goto err;

      while (!ret) {
          // Try and get some data
          char* dest = adbus_buf_recvbuf(buffer, RECV_SIZE);
          int read = recv(sock, dest, RECV_SIZE, 0);
          adbus_buf_recvd(buffer, RECV_SIZE, read);
          if (read < 0)
              goto err;

          // Hand the received data off to the auth module
          ret = adbus_auth_parse(a, buffer);
          if (ret < 0)
              goto err;
      }

      adbus_auth_free(a);
      return 0;

  err:
      adbus_auth_free(a);
      return -1;
  }

Note:

If working with blocking BSD sockets, adbus_sock_cauth() performs the entire procudure.

See also:

adbus_sock_cauth()

Server Authentication

Note:

Server here refers to the bus server, not bus services.

The workflow for server auth is:

1. Create the auth structure.
2. Setup auth mechansims eg adbus_sauth_external.
3. Feed requests from the remote using adbus_auth_parse() or adbus_auth_line() until they return a non-zero value.
4. Free the auth structure.

Note:

There is no server equivalent of adbus_cauth_start(), as the SASL protocol is client initiated.

For example:

  adbus_Bool IsExternalValid(void* user, const char* id)
  {
      adbus_Socket s = *(adbus_Socket*) user;
      return IsSocketValidForId(s, id);
  }

  int AuthRemote(adbus_Socket sock, adbus_Buffer* buffer)
  {
      int ret = 0;

      adbus_Auth* a = adbus_sauth_new(&Send, &Rand, &sock);
      adbus_sauth_external(a, &IsExternalValid);

      // Make sure we get the beginnig null correctly
      char buf[1];
      if (recv(sock, &buf, 1, 0) != 1 || buf[0] != '\0')
          goto err;

      while (!ret) {
          // Get some data
          char* dest = adbus_buf_recvbuf(buffer, RECV_SIZE);
          int read = recv(sock, dest, RECV_SIZE, 0);
          adbus_buf_recvd(buffer, RECV_SIZE, read);
          if (read < 0)
              goto err;

          // Hand the received data off to the auth module
          ret = adbus_auth_parse(a, buffer);
          if (ret < 0)
              goto err;
      }

      adbus_auth_free(a);
      return 0;

  err:
      adbus_auth_free(a);
      return -1;
  }

---

Friends And Related Function Documentation

int adbus_auth_line	(	adbus_Auth *	a,
		const char *	line,
		size_t	len
	)			[related]

Parses a line received from the remote.

This is mainly used if you want to filter the received auth lines. Otherwise its easier to use adbus_auth_parse().

Returns:

1 on success

0 on continue

-1 on error

int adbus_auth_parse	(	adbus_Auth *	a,
		adbus_Buffer *	buf
	)			[related]

Consumes auth lines from the supplied buffer.

Returns:

1 on success

0 on continue

-1 on error

void adbus_sauth_external	(	adbus_Auth *	a,
		adbus_ExternalCallback	cb
	)			[related]

Sets up a server auth for the external auth mechanism.

The supplied callback is called to see if the remote can authenticate using the external auth mechanism. The user data supplied to the callback is the user data supplied in adbus_sauth_new().

---

The documentation for this struct was generated from the following file:

• adbus/auth.c