.\" 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: src/lib/libtacplus/libtacplus.3,v 1.3.2.6 2001/12/17 10:08:32 ru Exp %
.\"
.\" $FreeBSD$
.Dd September 2, 1998
.Dt LIBTACPLUS 3
.Os
.Sh 名称
.Nm libtacplus
.Nd TACACS+ クライアントライブラリ
.Sh 書式
.In 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 解説
.Nm libtacplus
ライブラリは、TACACS+ ネットワークアクセス制御プロトコルの
クライアント側を実現しています。
TACACS+ により、クライアントは認証や、認可、および課金処理を、
リモートサーバに対するネットワーク上での要求を出すことで実行できます。
このライブラリは、現在プロトコルの認証部分だけをサポートしています。
.Pp
.Sh 初期化
このライブラリを使用するためには、アプリケーションは最初に
.Fn tac_open
呼び出しを実行して、
.Va struct tac_handle *
を得る必要があります。これにより次の
操作のためのコンテキストが準備されます。
.Fn tac_open
呼び出しは、十分な仮想メモリが
利用できれば、常に正常に完了します。必要なメモリが割り当てられないとき、
.Fn tac_open
は
.Dv ヌル
を返します。
.Pp
TACACS+ 要求を出す前に、ライブラリはコンタクトできるサーバから
認識されている必要があります。ライブラリを環境設定する簡単な方法は
.Fn tac_config
を呼び出すことです。
.Fn tac_config
により、ライブラリは、
.Xr tacplus.conf 5
でその形式が定義されている環境設定ファイルを
読むことになります。環境設定ファイルのパス名は、引数
.Va file
として
.Fn tac_config
に渡されます。この引数には
.Dv ヌル
を渡すこともでき、その場合は標準環境設定ファイル
.Pa /etc/tacplus.conf
が使われます。
.Fn tac_config
は
正常終了のとき、0 を返し、エラーの場合は -1 を返します。
.Pp
ライブラリは、
.Fn tac_add_server
を呼び出すことで、決まった手順に従って構成できます。
パラメータ
.Va host
はサーバホストを、完全修飾形のドメイン名 (FQDN)、または
ピリオドで 4 つの部分に分割表示したテキスト形式の IP アドレスによって
定義します。パラメータ
.Va port
は、サーバと接続する TCP ポートを定義します。
.Va port
が 0 と定義されていると、ライブラリは標準 TACACS+ ポートである
ポート 49 を使用します。サーバホストに対する共有シークレットは、
.Va secret
パラメータに渡されます。それは
.Dv ヌル
で終了するなんらかの文字列でもかまいません。
サーバからの受信タイムアウトは、
.Va timeout
パラメータに、秒の単位で渡されます。
.Va flags
パラメータは、フラグの
ビットマスクで、サーバの種々の性質を指定するためのものです。内容は
次のとおりです。
.Pp
.Bl -tag -width Fl
.It Dv TAC_SRVR_SINGLE_CONNECT
で、ライブラリはサーバと通信するときに、単一接続モードで
ネゴシエートしようとします。単一接続モードでは元の TCP 接続が
多重 TACACS+ セッションに対し解放されています。
旧式のサーバはこのモードはサポートしておらず、サーバによっては、
クライアントがネゴシエートしようとすると混乱してしまうものもあります。
.El
.Pp
.Fn tac_add_server
は正常終了時に 0 を返し、エラーのときは -1 を返します。
.Pp
.Fn tac_add_server
は、複数回呼び出すことができ、
.Fn tac_config
と一緒に
使用します。最大 10 のサーバまで指定できます。複数サーバの指定があると、
ラウンドロビン方式により稼働中のアクセス可能なサーバを見つけようとします。
ライブラリは、そうしたサーバを見つけると、
サーバが稼動している限りそれを使い続けます。
.Pp
.Sh TACACS+ 認証要求の生成
新規に認証要求を作り始める場合、
.Fn tac_create_authen
を呼び出します。
引数
.Va action ,
.Va type ,
.Va service
には、TACACS+ プロトコル仕様で
定義される適切な値をセットしなければなりません。ヘッダファイル
.Aq Pa taclib.h
には、これらの値のシンボリック定数が定義されています。
.Pp
.Fn tac_create_authen
で要求を生成した後、種々の任意指定パラメータを、
.Fn tac_set_data ,
.Fn tac_set_port ,
.Fn tac_set_priv ,
.Fn tac_set_rem_addr ,
.Fn tac_set_user
を呼び出して付加します。ライブラリは、これらの関数に提供された自分自身の
文字列の複製を作るので、呼び出し側で文字列を保存しておく必要はありません。
デフォルトで各パラメータは空ですが、権限レベルだけは
.Ql USER
権限にデフォルト指定されています。
.Sh 認証要求の送信と応答の受信
TACACS+ 要求が生成されると、
.Fn tac_send_authen
によって送信されます。
この関数は、未接続のときサーバ接続を行って、要求を送信し、返信を待ちます。
異常終了のとき、
.Fn tac_send_authen
は -1 を返します。正常の場合は、TACACS+ 終了コードとフラグを、
整数値にパックして返します。終了状態は
.Fn TAC_AUTHEN_STATUS
マクロを使用して抽出することができます。取り得る終了コードは、
.Aq Pa taclib.h
で定義されており、内容は次のとおりです。
.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
唯一のフラグは no-echo フラグで、
.Fn TAC_AUTHEN_NOECHO
マクロで検出できます。
.Sh サーバの応答からの情報抽出
サーバからの認証応答パケットには、サーバメッセージや文字列データ、
もしくは、その両者が含まれています。
.Fn tac_send_authen
呼び出しが成功すると、この情報は、
.Fn tac_get_msg
と
.Fn tac_get_data
呼び出しの応答から取り出すことができます。
これらの関数は、パケットからの情報の動的に割り当てられたコピーを
返します。それらが必要なくなったときには、呼び出し側が解放
しなければなりません。これらの関数から戻ってくるデータは、必ず
.Dv ヌル
で終了していることが保証されています。
.Pp
.Fn tac_get_data
の場合、引数
.Va len
は、ライブラリが終端の
.Dv ナル
文字を含まない実サイズの受信データの保管場所を指しています。
この引数には、呼び出し側が長さを問題にしない場合は、
.Dv ヌル
を指定してもかまいません。
.Sh 認証連続パケットの送信
.Fn tac_send_authen
が、終了コード
.Dv TAC_AUTHEN_STATUS_GETDATA ,
.Dv TAC_AUTHEN_STATUS_GETUSER ,
.Dv TAC_AUTHEN_STATUS_GETPASS
のうちのどれかを含む値を返す場合、
クライアントは、TACACS+ 連続パケットを使って、
サーバに対する追加情報を提供する必要があります。そのためには、
アプリケーションは最初に、
.Fn tac_set_msg
と
.Fn tac_set_data
を使って、パケットユーザメッセージやデータフィールドを
設定しなければなりません。クライアントは、
.Fn tac_send_authen
を使って連続パケットを送信します。
.Pp
.Li [注意]
.Fn tac_create_authen
は、連続パケットを生成するときには
.Em 呼び出さずに
、初期の認証要求のときにだけ使用する必要があります。
.Pp
連続パケットを受信すると、サーバは
.Dv TAC_AUTHEN_STATUS_GETDATA , 
.Dv TAC_AUTHEN_STATUS_GETUSER ,
.Dv TAC_AUTHEN_STATUS_GETPASS
を返して、更に情報を要求します。
アプリケーションは、サーバから別の状態コードが受信されるまで、
引き続き連続パケットを送信しなければなりません。
.Sh エラーメッセージの取得
引数
.Va struct tac_handle *
を受け取る関数は、異常終了するとエラーメッセージを記録します。
エラーメッセージは、
.Fn tac_strerror
を呼び出すことにより取り出すことができます。
メッセージテキストは、指定された
.Va struct tac_handle *
の新たなエラーごとに上書きされます。
従って、メッセージを保管しておかなければならないなら、
同じハンドルを使う後続のライブラリ呼び出しで複製を作らなければなりません。
.Sh クリーンアップ
TACACS+ ライブラリで使用したリソースを解放するには、
.Fn tac_close
呼び出して下さい。
.Sh 戻り値
以下の関数は、正常終了時に、負でない数値を返します。
エラーを検出すると、-1 を返し、エラーメッセージを記録します。
メッセージは
.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
以下の関数は、正常終了時にヌルでないポインタを返します。
十分な仮想メモリが割り当てられない場合、
.Dv ヌル
を返し、エラーメッセージを記録します。メッセージは
.Fn tac_strerror
で取り出せます。
.Pp
.Bl -item -offset indent -compact
.It
.Fn tac_get_data
.It
.Fn tac_get_msg
.El
.Pp
以下の関数は、正常終了時にヌルでないポインタを返します。
十分な仮想メモリが割り当てられない場合、
.Dv ヌル
を返し、エラーメッセージを記録しません。
.Pp
.Bl -item -offset indent -compact
.It
.Fn tac_open
.El
.Sh 関連ファイル
.Pa /etc/tacplus.conf
.Sh 関連項目
.Xr tacplus.conf 5
.Rs
.%A D. Carrel
.%A Lol Grant
.%T The TACACS+ Protocol, Version 1.78
.%O draft-grant-tacacs-02.txt (Internet Draft)
.Re
.Sh 作者
このソフトウェアは、
.An John Polstra
が作成し、
Juniper Networks, Inc によって
.Fx
プロジェクトに寄贈されました。