AUTH(3)                    Library Functions Manual                    AUTH(3)

       auth_open, auth_close, auth_recv, auth_send - auth server interface

       #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;

       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>
            3    #include "firewall.h"
            5    main()
            6    {
            7        char        cbuf[128];
            8        char        ubuf[128], buf[128];
            9        int         bad = 5;
           11        auth_open((Cfg *)0);
           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        }
           24        while(bad--) {
           25            fprintf(stderr,"User-Id: ");
           26            fgets(ubuf,sizeof(ubuf),stdin);
           28            sprintf(cbuf,"authorize %s myapplication",ubuf);
           29            auth_send(cbuf);
           30            auth_recv(cbuf,sizeof(cbuf));
           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            }
           44            sprintf(cbuf,"response '%s'",ubuf);
           45            auth_send(cbuf);
           46            auth_recv(cbuf,sizeof(cbuf));
           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);

       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
       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.

       All routines return zero to indicate success. Nonzero return values
       indicate a fatal error, usually a lost network connection.


                               17 September 1993                       AUTH(3)