lib/libtacplus/libtacplus.3

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