--- name: "auth" section: "3" platform: "linux" package: "fwtk" version: "1.3-1" release: "Debian 1.3 (Bo)" platforms: ["linux"] url: "https://new.carta.tech/auth/3" --- # auth(3) auth server interface ## 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 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.** ## SEE ALSO **[authsrv(8)](/authsrv/8.md)**