1.\" Copyright 1998 Juniper Networks, Inc. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd September 2, 1998 28.Dt LIBTACPLUS 3 29.Os FreeBSD 30.Sh NAME 31.Nm libtacplus 32.Nd TACACS+ client library 33.Sh SYNOPSIS 34.Fd #include <taclib.h> 35.Ft int 36.Fn tac_add_server "struct tac_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int flags" 37.Ft void 38.Fn tac_close "struct tac_handle *h" 39.Ft int 40.Fn tac_config "struct tac_handle *h" "const char *path" 41.Ft int 42.Fn tac_create_authen "struct tac_handle *h" "int action" "int type" "int service" 43.Ft void * 44.Fn tac_get_data "struct tac_handle *h" "size_t *len" 45.Ft char * 46.Fn tac_get_msg "struct tac_handle *h" 47.Ft struct tac_handle * 48.Fn tac_open "void" 49.Ft int 50.Fn tac_send_authen "struct tac_handle *h" 51.Ft int 52.Fn tac_set_data "struct tac_handle *h" "const void *data" "size_t data_len" 53.Ft int 54.Fn tac_set_msg "struct tac_handle *h" "const char *msg" 55.Ft int 56.Fn tac_set_port "struct tac_handle *h" "const char *port" 57.Ft int 58.Fn tac_set_priv "struct tac_handle *h" "int priv" 59.Ft int 60.Fn tac_set_rem_addr "struct tac_handle *h" "const char *addr" 61.Ft int 62.Fn tac_set_user "struct tac_handle *h" "const char *user" 63.Ft const char * 64.Fn tac_strerror "struct tac_handle *h" 65.Sh DESCRIPTION 66The 67.Nm 68library implements the client side of the TACACS+ network access 69control protocol. TACACS+ allows clients to perform authentication, 70authorization, and accounting by means of network requests to remote 71servers. This library currently supports only the authentication 72portion of the protocol. 73.Sh INITIALIZATION 74To use the library, an application must first call 75.Fn tac_open 76to obtain a 77.Va struct tac_handle * , 78which provides context for subsequent operations. 79Calls to 80.Fn tac_open 81always succeed unless insufficient virtual memory is available. If 82the necessary memory cannot be allocated, 83.Fn tac_open 84returns 85.Dv NULL . 86.Pp 87Before issuing any TACACS+ requests, the library must be made aware 88of the servers it can contact. The easiest way to configure the 89library is to call 90.Fn tac_config . 91.Fn tac_config 92causes the library to read a configuration file whose format is 93described in 94.Xr tacplus.conf 5 . 95The pathname of the configuration file is passed as the 96.Va file 97argument to 98.Fn tac_config . 99This argument may also be given as 100.Dv NULL , 101in which case the standard configuration file 102.Pa /etc/tacplus.conf 103is used. 104.Fn tac_config 105returns 0 on success, or -1 if an error occurs. 106.Pp 107The library can also be configured programmatically by calls to 108.Fn tac_add_server . 109The 110.Va host 111parameter specifies the server host, either as a fully qualified 112domain name or as a dotted-quad IP address in text form. 113The 114.Va port 115parameter specifies the TCP port to contact on the server. If 116.Va port 117is given as 0, the library uses port 49, the standard TACACS+ port. 118The shared secret for the server host is passed to the 119.Va secret 120parameter. It may be any null-terminated string of bytes. 121The timeout for receiving replies from the server is passed to the 122.Va timeout 123parameter, in units of seconds. 124The 125.Va flags 126parameter is a bit mask of flags to specify various characteristics of 127the server. It may contain: 128.Pp 129.Bl -tag -width Fl 130.It Dv TAC_SRVR_SINGLE_CONNECT 131Causes the library to attempt to negotiate single connection mode 132when communicating with the server. In single connection mode, the 133original TCP connection is held open for multiple TACACS+ sessions. 134Older servers do not support this mode, and some of them become 135confused if the client attempts to negotiate it. 136.El 137.Pp 138.Fn tac_add_server 139returns 0 on success, or -1 if an error occurs. 140.Pp 141.Fn tac_add_server 142may be called multiple times, and it may be used together with 143.Fn tac_config . 144At most 10 servers may be specified. 145When multiple servers are given, they are tried in round-robin 146fashion until a working, accessible server is found. Once the 147library finds such a server, it continues to use it as long as it 148works. 149.Sh CREATING A TACACS+ AUTHENTICATION REQUEST 150To begin constructing a new authentication request, call 151.Fn tac_create_authen . 152The 153.Va action , 154.Va type , 155and 156.Va service 157arguments must be be set to appropriate values as defined in the 158TACACS+ protocol specification. The 159.Aq taclib.h 160header file contains symbolic constants for these values. 161.Pp 162After creating a request with 163.Fn tac_create_authen , 164various optional parameters may be attached to it through calls to 165.Fn tac_set_data , 166.Fn tac_set_port , 167.Fn tac_set_priv , 168.Fn tac_set_rem_addr , 169and 170.Fn tac_set_user . 171The library creates its own copies of any strings provided to these 172functions, so that it is not necessary for the caller to preserve 173them. By default, each of these parameters is empty except for the 174privilege level, which defaults to 175.Ql USER 176privilege. 177.Sh SENDING THE AUTHENTICATION REQUEST AND RECEIVING THE RESPONSE 178After the TACACS+ request has been constructed, it is sent by means 179of 180.Fn tac_send_authen . 181This function connects to a server if not already connected, sends 182the request, and waits for a reply. On failure, 183.Fn tac_send_authen 184returns -1. Otherwise, it returns the TACACS+ status code and flags, 185packed into an integer value. The status can be extracted using the 186macro 187.Fn TAC_AUTHEN_STATUS . 188Possible status codes, defined in 189.Aq taclib.h , 190include: 191.Pp 192.Bl -item -compact -offset indent 193.It 194.Dv TAC_AUTHEN_STATUS_PASS 195.It 196.Dv TAC_AUTHEN_STATUS_FAIL 197.It 198.Dv TAC_AUTHEN_STATUS_GETDATA 199.It 200.Dv TAC_AUTHEN_STATUS_GETUSER 201.It 202.Dv TAC_AUTHEN_STATUS_GETPASS 203.It 204.Dv TAC_AUTHEN_STATUS_RESTART 205.It 206.Dv TAC_AUTHEN_STATUS_ERROR 207.It 208.Dv TAC_AUTHEN_STATUS_FOLLOW 209.El 210.Pp 211The only flag is the no-echo flag, which can be tested using the 212macro 213.Fn TAC_AUTHEN_NOECHO . 214.Sh EXTRACTING INFORMATION FROM THE SERVER'S RESPONSE 215An authentication response packet from the server may contain a 216server message, a data string, or both. After a successful call to 217.Fn tac_send_authen , 218this information may be retrieved from the response by calling 219.Fn tac_get_msg 220and 221.Fn tac_get_data . 222These functions return dynamically-allocated copies of the 223information from the packet. The caller is responsible for freeing 224the copies when it no longer needs them. The data returned from 225these functions is guaranteed to be terminated by a null byte. 226.Pp 227In the case of 228.Fn tac_get_data , 229the 230.Va len 231argument points to a location into which the library will store the 232actual length of the received data, not including the null 233terminator. This argument may be given as 234.Dv NULL 235if the caller is not interested in the length. 236.Sh SENDING AUTHENTICATION CONTINUE PACKETS 237If 238.Fn tac_send_authen 239returns a value containing one of the status codes 240.Dv TAC_AUTHEN_STATUS_GETDATA , 241.Dv TAC_AUTHEN_STATUS_GETUSER , 242or 243.Dv TAC_AUTHEN_STATUS_GETPASS , 244then the client must provide additional information to the server by 245means of a TACACS+ CONTINUE packet. To do so, the application must 246first set the packet's user message and/or data fields using 247.Fn tac_set_msg 248and 249.Fn tac_set_data . 250The client then sends the CONTINUE packet with 251.Fn tac_send_authen . 252N.B., 253.Fn tac_create_authen 254should 255.Em not 256be called to construct a CONTINUE packet; it is used only for the 257initial authentication request. 258.Pp 259When it receives the CONTINUE packet, the server may again request 260more information by returning 261.Dv TAC_AUTHEN_STATUS_GETDATA , 262.Dv TAC_AUTHEN_STATUS_GETUSER , 263or 264.Dv TAC_AUTHEN_STATUS_GETPASS . 265The application should send further CONTINUEs until some other 266status is received from the server. 267.Sh OBTAINING ERROR MESSAGES 268Those functions which accept a 269.Va struct tac_handle * 270argument record an error message if they fail. The error message 271can be retrieved by calling 272.Fn tac_strerror . 273The message text is overwritten on each new error for the given 274.Va struct tac_handle * . 275Thus the message must be copied if it is to be preserved through 276subsequent library calls using the same handle. 277.Sh CLEANUP 278To free the resources used by the TACACS+ library, call 279.Fn tac_close . 280.Sh RETURN VALUES 281The following functions return a non-negative value on success. If 282they detect an error, they return -1 and record an error message 283which can be retrieved using 284.Fn tac_strerror . 285.Pp 286.Bl -item -offset indent -compact 287.It 288.Fn tac_add_server 289.It 290.Fn tac_config 291.It 292.Fn tac_create_authen 293.It 294.Fn tac_send_authen 295.It 296.Fn tac_set_data 297.It 298.Fn tac_set_msg 299.It 300.Fn tac_set_port 301.It 302.Fn tac_set_priv 303.It 304.Fn tac_set_rem_addr 305.It 306.Fn tac_set_user 307.El 308.Pp 309The following functions return a 310.No non- Ns Dv NULL 311pointer on success. If they are unable to allocate sufficient 312virtual memory, they return 313.Dv NULL 314and record an error message which can be retrieved using 315.Fn tac_strerror . 316.Pp 317.Bl -item -offset indent -compact 318.It 319.Fn tac_get_data 320.It 321.Fn tac_get_msg 322.El 323.Pp 324The following functions return a 325.No non- Ns Dv NULL 326pointer on success. If they are unable to allocate sufficient 327virtual memory, they return 328.Dv NULL , 329without recording an error message. 330.Pp 331.Bl -item -offset indent -compact 332.It 333.Fn tac_open 334.El 335.Sh FILES 336.Pa /etc/tacplus.conf 337.Sh SEE ALSO 338.Xr tacplus.conf 5 339.Rs 340.%A D. Carrel and Lol Grant 341.%T The TACACS+ Protocol, Version 1.78 342.%O draft-grant-tacacs-02.txt (Internet Draft) 343.Re 344.Sh AUTHORS 345This software was written by 346.An John Polstra , 347and donated to the FreeBSD project by Juniper Networks, Inc. 348