1.\" Copyright (c) 1998, 2001, 2002, 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 December 11, 2009 28.Dt LIBTACPLUS 3 29.Os 30.Sh NAME 31.Nm libtacplus 32.Nd TACACS+ client library 33.Sh SYNOPSIS 34.In 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_clear_avs "struct tac_handle *h" 39.Ft void 40.Fn tac_close "struct tac_handle *h" 41.Ft int 42.Fn tac_config "struct tac_handle *h" "const char *path" 43.Ft int 44.Fn tac_create_authen "struct tac_handle *h" "int action" "int type" "int service" 45.Ft int 46.Fn tac_create_author "struct tac_handle *h" "int method" "int type" "int service" 47.Ft int 48.Fn tac_create_acct "struct tac_handle *h" "int acct" "int action" "int type" "int service" 49.Ft char * 50.Fn tac_get_av "struct tac_handle *h" "u_int index" 51.Ft char * 52.Fn tac_get_av_value "struct tac_handle *h" "const char *attribute" 53.Ft void * 54.Fn tac_get_data "struct tac_handle *h" "size_t *len" 55.Ft char * 56.Fn tac_get_msg "struct tac_handle *h" 57.Ft struct tac_handle * 58.Fn tac_open "void" 59.Ft int 60.Fn tac_send_authen "struct tac_handle *h" 61.Ft int 62.Fn tac_send_author "struct tac_handle *h" 63.Ft int 64.Fn tac_send_acct "struct tac_handle *h" 65.Ft int 66.Fn tac_set_av "struct tac_handle *h" "u_int index" "const char *av_pair" 67.Ft int 68.Fn tac_set_data "struct tac_handle *h" "const void *data" "size_t data_len" 69.Ft int 70.Fn tac_set_msg "struct tac_handle *h" "const char *msg" 71.Ft int 72.Fn tac_set_port "struct tac_handle *h" "const char *port" 73.Ft int 74.Fn tac_set_priv "struct tac_handle *h" "int priv" 75.Ft int 76.Fn tac_set_rem_addr "struct tac_handle *h" "const char *addr" 77.Ft int 78.Fn tac_set_user "struct tac_handle *h" "const char *user" 79.Ft const char * 80.Fn tac_strerror "struct tac_handle *h" 81.Sh DESCRIPTION 82The 83.Nm 84library implements the client side of the TACACS+ network access 85control protocol. 86TACACS+ allows clients to perform authentication, 87authorization, and accounting by means of network requests to remote 88servers. 89This library currently supports only the authentication 90and authorization portion of the protocol. 91.Sh INITIALIZATION 92To use the library, an application must first call 93.Fn tac_open 94to obtain a 95.Va struct tac_handle * , 96which provides context for subsequent operations. 97Calls to 98.Fn tac_open 99always succeed unless insufficient virtual memory is available. 100If 101the necessary memory cannot be allocated, 102.Fn tac_open 103returns 104.Dv NULL . 105.Pp 106Before issuing any TACACS+ requests, the library must be made aware 107of the servers it can contact. 108The easiest way to configure the 109library is to call 110.Fn tac_config . 111.Fn tac_config 112causes the library to read a configuration file whose format is 113described in 114.Xr tacplus.conf 5 . 115The pathname of the configuration file is passed as the 116.Va file 117argument to 118.Fn tac_config . 119This argument may also be given as 120.Dv NULL , 121in which case the standard configuration file 122.Pa /etc/tacplus.conf 123is used. 124.Fn tac_config 125returns 0 on success, or \-1 if an error occurs. 126.Pp 127The library can also be configured programmatically by calls to 128.Fn tac_add_server . 129The 130.Va host 131parameter specifies the server host, either as a fully qualified 132domain name or as a dotted-quad IP address in text form. 133The 134.Va port 135parameter specifies the TCP port to contact on the server. 136If 137.Va port 138is given as 0, the library uses port 49, the standard TACACS+ port. 139The shared secret for the server host is passed to the 140.Va secret 141parameter. 142It may be any null-terminated string of bytes. 143The timeout for receiving replies from the server is passed to the 144.Va timeout 145parameter, in units of seconds. 146The 147.Va flags 148parameter is a bit mask of flags to specify various characteristics of 149the server. 150It may contain: 151.Bl -tag -width Fl 152.It Dv TAC_SRVR_SINGLE_CONNECT 153Causes the library to attempt to negotiate single connection mode 154when communicating with the server. 155In single connection mode, the 156original TCP connection is held open for multiple TACACS+ sessions. 157Older servers do not support this mode, and some of them become 158confused if the client attempts to negotiate it. 159.El 160.Pp 161.Fn tac_add_server 162returns 0 on success, or \-1 if an error occurs. 163.Pp 164.Fn tac_add_server 165may be called multiple times, and it may be used together with 166.Fn tac_config . 167At most 10 servers may be specified. 168When multiple servers are given, they are tried in round-robin 169fashion until a working, accessible server is found. 170Once the 171library finds such a server, it continues to use it as long as it 172works. 173.Sh CREATING A TACACS+ AUTHENTICATION REQUEST 174To begin constructing a new authentication request, call 175.Fn tac_create_authen . 176The 177.Va action , 178.Va type , 179and 180.Va service 181arguments must be set to appropriate values as defined in the 182TACACS+ protocol specification. 183The 184.In taclib.h 185header file contains symbolic constants for these values. 186.Sh CREATING A TACACS+ AUTHORIZATION REQUEST 187To begin constructing a new authorization request, call 188.Fn tac_create_author . 189The 190.Va method , 191.Va type , 192and 193.Va service 194arguments must be set to appropriate values as defined in the 195TACACS+ protocol specification. 196The 197.In taclib.h 198header file contains symbolic constants for these values. 199.Sh CREATING A TACACS+ ACCOUNTING REQUEST 200To begin constructing a new accounting request, call 201.Fn tac_create_acct . 202The 203.Va acct , 204.Va action , 205.Va type , 206and 207.Va service 208arguments must be set to appropriate values as defined in the 209TACACS+ protocol specification. 210The 211.In taclib.h 212header file contains symbolic constants for these values. 213.Sh SETTING OPTIONAL PARAMETERS ON A REQUEST 214After creating a request, 215various optional parameters may be attached to it through calls to 216.Fn tac_set_av , 217.Fn tac_set_data , 218.Fn tac_set_port , 219.Fn tac_set_priv , 220.Fn tac_set_rem_addr , 221and 222.Fn tac_set_user . 223The library creates its own copies of any strings provided to these 224functions, so that it is not necessary for the caller to preserve 225them. 226By default, each of these parameters is empty except for the 227privilege level, which defaults to 228.Ql USER 229privilege. 230.Pp 231.Fn tac_set_av 232only applies to the context of an authorization request. 233The format 234for an attribute value pair is defined in the TACACS+ protocol 235specification. 236The index specified can be any value between 0 and 237255 inclusive and indicates the position in the list to place the 238attribute value pair. 239Calling 240.Fn tac_set_av 241with same index twice effectively replaces the value at that position. 242Use 243.Fn tac_clear_avs 244to clear all attribute value pairs that may have been set. 245.Sh SENDING THE AUTHENTICATION REQUEST AND RECEIVING THE RESPONSE 246After the TACACS+ authentication request has been constructed, it is 247sent by means of 248.Fn tac_send_authen . 249This function connects to a server if not already connected, sends 250the request, and waits for a reply. 251On failure, 252.Fn tac_send_authen 253returns \-1. 254Otherwise, it returns the TACACS+ status code and flags, 255packed into an integer value. 256The status can be extracted using the 257macro 258.Fn TAC_AUTHEN_STATUS . 259Possible status codes, defined in 260.In taclib.h , 261include: 262.Pp 263.Bl -item -compact -offset indent 264.It 265.Dv TAC_AUTHEN_STATUS_PASS 266.It 267.Dv TAC_AUTHEN_STATUS_FAIL 268.It 269.Dv TAC_AUTHEN_STATUS_GETDATA 270.It 271.Dv TAC_AUTHEN_STATUS_GETUSER 272.It 273.Dv TAC_AUTHEN_STATUS_GETPASS 274.It 275.Dv TAC_AUTHEN_STATUS_RESTART 276.It 277.Dv TAC_AUTHEN_STATUS_ERROR 278.It 279.Dv TAC_AUTHEN_STATUS_FOLLOW 280.El 281.Pp 282The only flag is the no-echo flag, which can be tested using the 283macro 284.Fn TAC_AUTHEN_NOECHO . 285.Sh EXTRACTING INFORMATION FROM THE SERVER'S AUTHENTICATION RESPONSE 286An authentication response packet from the server may contain a 287server message, a data string, or both. 288After a successful call to 289.Fn tac_send_authen , 290this information may be retrieved from the response by calling 291.Fn tac_get_msg 292and 293.Fn tac_get_data . 294These functions return dynamically-allocated copies of the 295information from the packet. 296The caller is responsible for freeing 297the copies when it no longer needs them. 298The data returned from 299these functions is guaranteed to be terminated by a null byte. 300.Pp 301In the case of 302.Fn tac_get_data , 303the 304.Va len 305argument points to a location into which the library will store the 306actual length of the received data, not including the null 307terminator. 308This argument may be given as 309.Dv NULL 310if the caller is not interested in the length. 311.Sh SENDING AUTHENTICATION CONTINUE PACKETS 312If 313.Fn tac_send_authen 314returns a value containing one of the status codes 315.Dv TAC_AUTHEN_STATUS_GETDATA , 316.Dv TAC_AUTHEN_STATUS_GETUSER , 317or 318.Dv TAC_AUTHEN_STATUS_GETPASS , 319then the client must provide additional information to the server by 320means of a TACACS+ CONTINUE packet. 321To do so, the application must 322first set the packet's user message and/or data fields using 323.Fn tac_set_msg 324and 325.Fn tac_set_data . 326The client then sends the CONTINUE packet with 327.Fn tac_send_authen . 328N.B., 329.Fn tac_create_authen 330should 331.Em not 332be called to construct a CONTINUE packet; it is used only for the 333initial authentication request. 334.Pp 335When it receives the CONTINUE packet, the server may again request 336more information by returning 337.Dv TAC_AUTHEN_STATUS_GETDATA , 338.Dv TAC_AUTHEN_STATUS_GETUSER , 339or 340.Dv TAC_AUTHEN_STATUS_GETPASS . 341The application should send further CONTINUEs until some other 342status is received from the server. 343.Sh SENDING THE AUTHORIZATION REQUEST AND RECEIVING THE RESPONSE 344After the TACACS+ authorization request has been constructed, it 345is sent by means of 346.Fn tac_send_author . 347This function connects to a server if not already connected, sends 348the request, and waits for a reply. 349On failure, 350.Fn tac_send_author 351returns \-1. 352Otherwise, it returns the TACACS+ status code and 353number of attribute value (AV) pairs received packed into an 354integer value. 355The status can be extracted using the macro 356.Fn TAC_AUTHOR_STATUS . 357Possible status codes, defined in 358.In taclib.h , 359include: 360.Pp 361.Bl -item -compact -offset indent 362.It 363.Dv TAC_AUTHOR_STATUS_PASS_ADD 364.It 365.Dv TAC_AUTHOR_STATUS_PASS_REPL 366.It 367.Dv TAC_AUTHOR_STATUS_FAIL 368.It 369.Dv TAC_AUTHOR_STATUS_ERROR 370.El 371.Pp 372The number of AV pairs received is obtained using 373.Fn TAC_AUTHEN_AV_COUNT . 374.Sh SENDING THE ACCOUNTING REQUEST AND RECEIVING THE RESPONSE 375After the TACACS+ authorization request has been constructed, it 376is sent by means of 377.Fn tac_send_acct . 378This function connects to a server if not already connected, sends 379the request, and waits for a reply. 380On failure, 381.Fn tac_send_acct 382returns \-1. 383Otherwise, it returns the TACACS+ status code 384Possible status codes, defined in 385.In taclib.h , 386include: 387.Pp 388.Bl -item -compact -offset indent 389.It 390.Dv TAC_ACCT_STATUS_SUCCESS 391.It 392.Dv TAC_ACCT_STATUS_ERROR 393.It 394.Dv TAC_ACCT_STATUS_FOLLOW 395.El 396.Pp 397.Sh EXTRACTING INFORMATION FROM THE SERVER'S AUTHORIZATION RESPONSE 398Like an authentication response packet, an authorization 399response packet from the 400server may contain a server message, a data string, or both. 401Refer 402to EXTRACTING INFORMATION FROM THE SERVER'S AUTHENTICATION RESPONSE 403for instruction on extraction of those values. 404.Pp 405An authorization response packet from the server may also contain 406attribute value (AV) pairs. 407To extract these, use 408.Fn tac_get_av 409or 410.Fn tac_get_av_value . 411.Fn tac_get_av 412takes the index of the AV pair as it is positioned in the list. 413The indexes start at 0 (use 414.Fn TAC_AUTHEN_AV_COUNT 415on the return value of 416.Fn tac_send_author 417to get the total number of items in this list). 418Alternatively, 419.Fn tac_get_av_value 420can be used. 421.Fn tac_get_av_value 422takes the attribute name and returns the 423corresponding value only, not the AV pair. 424These functions return 425dynamically-allocated copies of the information from the packet. 426The caller is responsible for freeing the copies when it no longer 427needs them. 428The data returned from these functions is guaranteed 429to be terminated by a null byte. 430.Sh OBTAINING ERROR MESSAGES 431Those functions which accept a 432.Va struct tac_handle * 433argument record an error message if they fail. 434The error message 435can be retrieved by calling 436.Fn tac_strerror . 437The message text is overwritten on each new error for the given 438.Va struct tac_handle * . 439Thus the message must be copied if it is to be preserved through 440subsequent library calls using the same handle. 441.Sh CLEANUP 442To free the resources used by the TACACS+ library, call 443.Fn tac_close . 444.Sh RETURN VALUES 445The following functions return a non-negative value on success. 446If 447they detect an error, they return \-1 and record an error message 448which can be retrieved using 449.Fn tac_strerror . 450.Pp 451.Bl -item -offset indent -compact 452.It 453.Fn tac_add_server 454.It 455.Fn tac_config 456.It 457.Fn tac_create_authen 458.It 459.Fn tac_create_author 460.It 461.Fn tac_create_acct 462.It 463.Fn tac_send_authen 464.It 465.Fn tac_send_author 466.It 467.Fn tac_send_acct 468.It 469.Fn tac_set_av 470.It 471.Fn tac_set_data 472.It 473.Fn tac_set_msg 474.It 475.Fn tac_set_port 476.It 477.Fn tac_set_priv 478.It 479.Fn tac_set_rem_addr 480.It 481.Fn tac_set_user 482.El 483.Pp 484The following functions return a 485.No non- Ns Dv NULL 486pointer on success. 487If they are unable to allocate sufficient 488virtual memory, they return 489.Dv NULL 490and record an error message which can be retrieved using 491.Fn tac_strerror . 492.Pp 493.Bl -item -offset indent -compact 494.It 495.Fn tac_get_av 496.It 497.Fn tac_get_av_value 498.It 499.Fn tac_get_data 500.It 501.Fn tac_get_msg 502.El 503.Pp 504The following functions return a 505.No non- Ns Dv NULL 506pointer on success. 507If they are unable to allocate sufficient 508virtual memory, they return 509.Dv NULL , 510without recording an error message. 511.Pp 512.Bl -item -offset indent -compact 513.It 514.Fn tac_open 515.El 516.Sh FILES 517.Pa /etc/tacplus.conf 518.Sh SEE ALSO 519.Xr tacplus.conf 5 520.Rs 521.%A D. Carrel 522.%A Lol Grant 523.%T The TACACS+ Protocol, Version 1.78 524.%O draft-grant-tacacs-02.txt (Internet Draft) 525.Re 526.Sh AUTHORS 527.An -nosplit 528This software was written by 529.An John Polstra 530and 531.An Paul Fraley , 532and donated to the 533.Fx 534project by Juniper Networks, Inc. 535