Appendix C

Authentication Utility Functions

As discussed in this document, the means by which authentication data is obtained by the ICE library (for Connection Setups or Protocol Setups) is implementation dependent*

This appendix describes some utility functions which manipulate an ICE authority file. The authority file can be used to pass authentication data between clients

The basic operations on the .ICEauthority file are: get file name, lock, unlock, read entry, write entry, and search for entry. These are fairly low level operations. and it is expected that a program like "iceauth" would exist to add, remove, and display entries in the file

In order to use these utility functions, the <X11/ICE/ICEutil.h> header file must be included

An entry in the .ICEauthority file is defined by the following data structure

typedef struct {
	char *protocol_name;
	unsigned short protocol_data_length;
	char *protocol_data;
	char *network_id;
	char *auth_name;
	unsigned short auth_data_length;
	char *auth_data;
}IceAuthFileEntry;

The protocol_name is either "ICE" for connection setup authentication, or the sub-protocol name, such as "XSMP" For each entry, protocol specific data can be specified in the protocol_datafield This can be used to search for old entries that need to be removed from the file.

network_id is the network ID of the client accepting authentication (for example, the network ID of a session manager) A network ID has the form...

auth_name is the name of the authentication method auth_data is the actual authentication data, and auth_data_length is the number of bytes in the data

To obtain the default authorization file name, call the IceAuthFileName funcfion.

char *IceAuthFlleName()

If the ICEAUTHORITY environment variable if set, this value is returned. Otherwise, the default authorization file name is $HOME/.ICEauthority This name is statically allocated and should not be freed.

In order to synchronously update the authorization file, the file must be locked with a call to IceLockAuthFile. This function takes advantage of the fact that the "link" system call will fail if the name of the new link already exists

int IceLockAuthFile(file_name, retries, timeout, dead )

char *file name;
int retries;
int timeout;
long dead;

One of three values is returned:

To unlock an authorization file, call the IceUnlockAuthFile function

void IceUnlockAuthFile (file_name )

char *file_name;

To read the next entry in an authorization file, call the IceReadAuthFileEntry function

IceAuthFileEntry *IceReadAuthFileEntry(auth_file)

FILE *aush_file;

Note that it is the responsibility of the application to open the file for reading before calling this function If an error is encountered, or there are no more entries to read, NULL is returned.

Entries should be free with a call to IceFreeAuthFileEntry (see below).

To write an entry in an authorization file, call the IceWriteAuthFileEntry function

Status IceWriteAuthFileEntry(authfile, entry)

FILE *auth_file;
IceAuthFileEntry *entry;

Note that it is the responsibility of the application to open the file for writing before calling this function. The function returns a non-zero status if the operation was successful

To search the default authorization file for an entry matching a given protocol_name/network_id/auth_name tuple, call the IceGetAuthFileEntry function.

IceAuthFileEntry *IceGetAuthFileEntry (protocol_narne, network_id, auth_narne)

char *protocol_name;
char *network_id;
char *auth_name;

If IceGetAuthFileEntry fails to find such an entry, NULL is returned

To free an entry returned by IceReadAuthFileEntry or IceGetAuthFileEntry, call the IceFreeAuth FileEntry function

void IceFreeAuthFileEntry (entry )

IceAuthFileEntry *entry;

The X Consortium's ICElib implementation assumes the presence of an ICE authority file