1 files changed, 347 insertions, 0 deletions
diff --git a/lib/libtacplus/libtacplus.3 b/lib/libtacplus/libtacplus.3
new file mode 100644
index 0000000..bfbfa35
--- /dev/null
+++ b/lib/libtacplus/libtacplus.3
@@ -0,0 +1,347 @@
+.\" Copyright 1998 Juniper Networks, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"	$FreeBSD$
+.\"
+.Dd September 2, 1998
+.Dt LIBTACPLUS 3
+.Os FreeBSD
+.Sh NAME
+.Nm libtacplus
+.Nd TACACS+ client library
+.Sh SYNOPSIS
+.Fd #include <taclib.h>
+.Ft int
+.Fn tac_add_server "struct tac_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int flags"
+.Ft void
+.Fn tac_close "struct tac_handle *h"
+.Ft int
+.Fn tac_config "struct tac_handle *h" "const char *path"
+.Ft int
+.Fn tac_create_authen "struct tac_handle *h" "int action" "int type" "int service"
+.Ft void *
+.Fn tac_get_data "struct tac_handle *h" "size_t *len"
+.Ft char *
+.Fn tac_get_msg "struct tac_handle *h"
+.Ft struct tac_handle *
+.Fn tac_open "void"
+.Ft int
+.Fn tac_send_authen "struct tac_handle *h"
+.Ft int
+.Fn tac_set_data "struct tac_handle *h" "const void *data" "size_t data_len"
+.Ft int
+.Fn tac_set_msg "struct tac_handle *h" "const char *msg"
+.Ft int
+.Fn tac_set_port "struct tac_handle *h" "const char *port"
+.Ft int
+.Fn tac_set_priv "struct tac_handle *h" "int priv"
+.Ft int
+.Fn tac_set_rem_addr "struct tac_handle *h" "const char *addr"
+.Ft int
+.Fn tac_set_user "struct tac_handle *h" "const char *user"
+.Ft const char *
+.Fn tac_strerror "struct tac_handle *h"
+.Sh DESCRIPTION
+The
+.Nm
+library implements the client side of the TACACS+ network access
+control protocol.  TACACS+ allows clients to perform authentication,
+authorization, and accounting by means of network requests to remote
+servers.  This library currently supports only the authentication
+portion of the protocol.
+.Sh INITIALIZATION
+To use the library, an application must first call
+.Fn tac_open
+to obtain a
+.Va struct tac_handle * ,
+which provides context for subsequent operations.
+Calls to
+.Fn tac_open
+always succeed unless insufficient virtual memory is available.  If
+the necessary memory cannot be allocated,
+.Fn tac_open
+returns
+.Dv NULL .
+.Pp
+Before issuing any TACACS+ requests, the library must be made aware
+of the servers it can contact.  The easiest way to configure the
+library is to call
+.Fn tac_config .
+.Fn tac_config
+causes the library to read a configuration file whose format is
+described in
+.Xr tacplus.conf 5 .
+The pathname of the configuration file is passed as the
+.Va file
+argument to
+.Fn tac_config .
+This argument may also be given as
+.Dv NULL ,
+in which case the standard configuration file
+.Pa /etc/tacplus.conf
+is used.
+.Fn tac_config
+returns 0 on success, or -1 if an error occurs.
+.Pp
+The library can also be configured programmatically by calls to
+.Fn tac_add_server .
+The
+.Va host
+parameter specifies the server host, either as a fully qualified
+domain name or as a dotted-quad IP address in text form.
+The
+.Va port
+parameter specifies the TCP port to contact on the server.  If
+.Va port
+is given as 0, the library uses port 49, the standard TACACS+ port.
+The shared secret for the server host is passed to the
+.Va secret
+parameter.  It may be any null-terminated string of bytes.
+The timeout for receiving replies from the server is passed to the
+.Va timeout
+parameter, in units of seconds.
+The
+.Va flags
+parameter is a bit mask of flags to specify various characteristics of
+the server.  It may contain:
+.Pp
+.Bl -tag -width Fl
+.It Dv TAC_SRVR_SINGLE_CONNECT
+Causes the library to attempt to negotiate single connection mode
+when communicating with the server.  In single connection mode, the
+original TCP connection is held open for multiple TACACS+ sessions.
+Older servers do not support this mode, and some of them become
+confused if the client attempts to negotiate it.
+.El
+.Pp
+.Fn tac_add_server
+returns 0 on success, or -1 if an error occurs.
+.Pp
+.Fn tac_add_server
+may be called multiple times, and it may be used together with
+.Fn tac_config .
+At most 10 servers may be specified.
+When multiple servers are given, they are tried in round-robin
+fashion until a working, accessible server is found.  Once the
+library finds such a server, it continues to use it as long as it
+works.
+.Sh CREATING A TACACS+ AUTHENTICATION REQUEST
+To begin constructing a new authentication request, call
+.Fn tac_create_authen .
+The
+.Va action ,
+.Va type ,
+and
+.Va service
+arguments must be be set to appropriate values as defined in the
+TACACS+ protocol specification.  The
+.Aq taclib.h
+header file contains symbolic constants for these values.
+.Pp
+After creating a request with
+.Fn tac_create_authen ,
+various optional parameters may be attached to it through calls to
+.Fn tac_set_data ,
+.Fn tac_set_port ,
+.Fn tac_set_priv ,
+.Fn tac_set_rem_addr ,
+and
+.Fn tac_set_user .
+The library creates its own copies of any strings provided to these
+functions, so that it is not necessary for the caller to preserve
+them.  By default, each of these parameters is empty except for the
+privilege level, which defaults to
+.Ql USER
+privilege.
+.Sh SENDING THE AUTHENTICATION REQUEST AND RECEIVING THE RESPONSE
+After the TACACS+ request has been constructed, it is sent by means
+of
+.Fn tac_send_authen .
+This function connects to a server if not already connected, sends
+the request, and waits for a reply.  On failure,
+.Fn tac_send_authen
+returns -1.  Otherwise, it returns the TACACS+ status code and flags,
+packed into an integer value.  The status can be extracted using the
+macro
+.Fn TAC_AUTHEN_STATUS .
+Possible status codes, defined in
+.Aq taclib.h ,
+include:
+.Pp
+.Bl -item -compact -offset indent
+.It
+.Dv TAC_AUTHEN_STATUS_PASS
+.It
+.Dv TAC_AUTHEN_STATUS_FAIL
+.It
+.Dv TAC_AUTHEN_STATUS_GETDATA
+.It
+.Dv TAC_AUTHEN_STATUS_GETUSER
+.It
+.Dv TAC_AUTHEN_STATUS_GETPASS
+.It
+.Dv TAC_AUTHEN_STATUS_RESTART
+.It
+.Dv TAC_AUTHEN_STATUS_ERROR
+.It
+.Dv TAC_AUTHEN_STATUS_FOLLOW
+.El
+.Pp
+The only flag is the no-echo flag, which can be tested using the
+macro
+.Fn TAC_AUTHEN_NOECHO .
+.Sh EXTRACTING INFORMATION FROM THE SERVER'S RESPONSE
+An authentication response packet from the server may contain a
+server message, a data string, or both.  After a successful call to
+.Fn tac_send_authen ,
+this information may be retrieved from the response by calling
+.Fn tac_get_msg
+and
+.Fn tac_get_data .
+These functions return dynamically-allocated copies of the
+information from the packet.  The caller is responsible for freeing
+the copies when it no longer needs them.  The data returned from
+these functions is guaranteed to be terminated by a null byte.
+.Pp
+In the case of
+.Fn tac_get_data ,
+the
+.Va len
+argument points to a location into which the library will store the
+actual length of the received data, not including the null
+terminator.  This argument may be given as
+.Dv NULL
+if the caller is not interested in the length.
+.Sh SENDING AUTHENTICATION CONTINUE PACKETS
+If
+.Fn tac_send_authen
+returns a value containing one of the status codes
+.Dv TAC_AUTHEN_STATUS_GETDATA ,
+.Dv TAC_AUTHEN_STATUS_GETUSER ,
+or
+.Dv TAC_AUTHEN_STATUS_GETPASS ,
+then the client must provide additional information to the server by
+means of a TACACS+ CONTINUE packet.  To do so, the application must
+first set the packet's user message and/or data fields using
+.Fn tac_set_msg
+and
+.Fn tac_set_data .
+The client then sends the CONTINUE packet with
+.Fn tac_send_authen .
+N.B.,
+.Fn tac_create_authen
+should
+.Em not
+be called to construct a CONTINUE packet; it is used only for the
+initial authentication request.
+.Pp
+When it receives the CONTINUE packet, the server may again request
+more information by returning
+.Dv TAC_AUTHEN_STATUS_GETDATA , 
+.Dv TAC_AUTHEN_STATUS_GETUSER ,
+or
+.Dv TAC_AUTHEN_STATUS_GETPASS .
+The application should send further CONTINUEs until some other
+status is received from the server.
+.Sh OBTAINING ERROR MESSAGES
+Those functions which accept a
+.Va struct tac_handle *
+argument record an error message if they fail.  The error message
+can be retrieved by calling
+.Fn tac_strerror .
+The message text is overwritten on each new error for the given
+.Va struct tac_handle * .
+Thus the message must be copied if it is to be preserved through 
+subsequent library calls using the same handle.
+.Sh CLEANUP
+To free the resources used by the TACACS+ library, call
+.Fn tac_close .
+.Sh RETURN VALUES
+The following functions return a non-negative value on success.  If
+they detect an error, they return -1 and record an error message
+which can be retrieved using
+.Fn tac_strerror .
+.Pp
+.Bl -item -offset indent -compact 
+.It
+.Fn tac_add_server
+.It
+.Fn tac_config
+.It
+.Fn tac_create_authen
+.It
+.Fn tac_send_authen
+.It
+.Fn tac_set_data
+.It
+.Fn tac_set_msg
+.It
+.Fn tac_set_port
+.It
+.Fn tac_set_priv
+.It
+.Fn tac_set_rem_addr
+.It
+.Fn tac_set_user
+.El
+.Pp
+The following functions return a
+.No non- Ns Dv NULL
+pointer on success.  If they are unable to allocate sufficient
+virtual memory, they return
+.Dv NULL
+and record an error message which can be retrieved using
+.Fn tac_strerror .
+.Pp
+.Bl -item -offset indent -compact
+.It
+.Fn tac_get_data
+.It
+.Fn tac_get_msg
+.El
+.Pp
+The following functions return a
+.No non- Ns Dv NULL
+pointer on success.  If they are unable to allocate sufficient
+virtual memory, they return
+.Dv NULL ,
+without recording an error message.
+.Pp
+.Bl -item -offset indent -compact
+.It
+.Fn tac_open
+.El
+.Sh FILES
+.Pa /etc/tacplus.conf
+.Sh SEE ALSO
+.Xr tacplus.conf 5
+.Rs
+.%A D. Carrel and Lol Grant
+.%T The TACACS+ Protocol, Version 1.78
+.%O draft-grant-tacacs-02.txt (Internet Draft)
+.Re
+.Sh AUTHORS
+This software was written by
+.An John Polstra ,
+and donated to the FreeBSD project by Juniper Networks, Inc.