NAME
auth_open, auth_close, auth_recv, auth_send - auth server interface
SYNOPSIS
#include "firewall.h"
int auth_open(confp) Cfg ∗confp;
int auth_close()
int auth_send(s) char ∗s;
int auth_recv(s, siz) char ∗s; int siz;
DESCRIPTION
These functions facilitate communication with a third party authentication server authsrv. All communication with the server is in terms of newline-terminated text, with whitespace indicating token delimiters. Whitespace characters may be embedded in tokens by quoting them with matched single or double quotes.
Authenticating a user via the server is a 5 step process, consisting of opening a connection to the server, telling the server the user-id of the user who is being authenticated, getting an appropriate challenge from the server and presenting it to the user, getting the user's response and returning it to the server, and closing the connection. An annotated example in which a user is authenticated is presented below. (Error checking is removed)
1 #include <stdio.h>
2
3 #include "firewall.h"
4
5 main()
6 {
7 char cbuf[128];
8 char ubuf[128], buf[128];
9 int bad = 5;
10
11 auth_open((Cfg *)0);
12
13 /* get welcome message from auth server */
14 if(auth_recv(buf,sizeof(buf))) {
15 fprintf(stderr,"lost connection to server0);
16 exit(1);
17 }
18 if(strncmp(buf,"Authsrv ready",13)) {
19 fprintf(stderr,"%s\n",buf);
20 auth_close();
21 exit(1);
22 }
23
24 while(bad--) {
25 fprintf(stderr,"User-Id: ");
26 fgets(ubuf,sizeof(ubuf),stdin);
27
28 sprintf(cbuf,"authorize %s myapplication",ubuf);
29 auth_send(cbuf);
30 auth_recv(cbuf,sizeof(cbuf));
32
33 if(!strncmp(cbuf,"challenge ",10)) {
34 fprintf(stderr,"Challenge \"%s\": ",&cbuf[10]);
35 gets(ubuf);
36 } else
37 if(!strncmp(cbuf,"password",8)) {
38 strcpy(ubuf,getpass("Password: "));
39 } else {
40 fprintf(stderr,"%s\n",cbuf);
41 continue;
42 }
43
44 sprintf(cbuf,"response '%s'",ubuf);
45 auth_send(cbuf);
46 auth_recv(cbuf,sizeof(cbuf));
47
48 if(strncmp(cbuf,"ok",2)) {
49 printf("%s\n",cbuf);
50 continue;
51 }
52 auth_close();
53 if(cbuf[2] != '\0')
54 printf("OK: %s\n",&cbuf[3]);
55 else
56 printf("OK\n");
57 exit(0);
58 }
56 auth_close();
59 exit(1);
60}
At line #11 in the example, a connection to the authentication server is opened. This connection will persist until explicitly closed with a call to auth_close. If multiple calls to auth_open are made without matching calls to auth_close the connection is preserved and is not reset. Normally auth_open is invoked with a pointer to the configuration record of the application, read with cfg_read. If using a client library with a compiled-in address for the authentication server, a null pointer may be passed instead.
At line #14, a welcome string is read from the server. If the calling application has permission to use the server and the server is operating normally, the first 13 characters of the first line it sends will read "Authsrv ready" In the event that they are not, the message will be an error message that should be presented to the user.
At line #28, the user-id that is to be authenticated is embedded in an authentication request that is sent to the server via auth_send. The server's response is read using auth_recv. Authentication requests take the form of: authorize username. Whenever a new authentication request is send, the server will reset its current notion of the authenticated user. The additional parameter "myapplication" serves as a comment for the authentication manager, which is attached to the authentication request solely for logging purposes.
At line #33, the server's response is examined. The server will return one of three forms of responses, either:
challenge challenge-string
password
other text
If the client application sees a response of "password" it should prompt the user for a non-echoing password. If the client application sees a response of "challenge" it should issue the remainder of the line to the user as a challenge. In the event of receiving any text other than "password" or "challenge" the text is treated as an error message that may be presented to the user.
At line #44, the user's response to the challenge/password request is sent to the user as a response message. Response messages take the form of: response response-string where the response string should usually be quoted in case white space is contained within it.
At line #48, the server's response is examined. If the response begins with "ok" then the server has authenticated the user. Any other response indicates an error. The response may contain additional information from the server and should be displayed to the user. If the response begins with "ok" but the third character is not a null string terminator, then the server has returned additional response information that should be displayed to the user.
RETURN VALUES
All routines return zero to indicate success. Nonzero return values indicate a fatal error, usually a lost network connection.