LIBTACPLUS(3)

名称
libtacplus - TACACS+ クライアントライブラリ

書式
<taclib.h> int tac_add_server(struct tac_handle *h, const char *host, int port, const char *secret, int timeout, int flags) void tac_close(struct tac_handle *h) int tac_config(struct tac_handle *h, const char *path) int tac_create_authen(struct tac_handle *h, int action, int type, int service) void * tac_get_data(struct tac_handle *h, size_t *len) char * tac_get_msg(struct tac_handle *h) struct tac_handle * tac_open(void) int tac_send_authen(struct tac_handle *h) int tac_set_data(struct tac_handle *h, const void *data, size_t data_len) int tac_set_msg(struct tac_handle *h, const char *msg) int tac_set_port(struct tac_handle *h, const char *port) int tac_set_priv(struct tac_handle *h, int priv) int tac_set_rem_addr(struct tac_handle *h, const char *addr) int tac_set_user(struct tac_handle *h, const char *user) const char * tac_strerror(struct tac_handle *h)

解説
libtacplus ライブラリは、TACACS+ ネットワークアクセス制御プロトコルの クライアント側を実現しています。 TACACS+ により、クライアントは認証や、認可、および課金処理を、 リモートサーバに対するネットワーク上での要求を出すことで実行できます。 このライブラリは、現在プロトコルの認証部分だけをサポートしています。

初期化
このライブラリを使用するためには、アプリケーションは最初に tac_open() 呼び出しを実行して、 struct tac_handle * を得る必要があります。これにより次の 操作のためのコンテキストが準備されます。 tac_open() 呼び出しは、十分な仮想メモリが 利用できれば、常に正常に完了します。必要なメモリが割り当てられないとき、 tac_open() は ヌル を返します。

TACACS+ 要求を出す前に、ライブラリはコンタクトできるサーバから 認識されている必要があります。ライブラリを環境設定する簡単な方法は tac_config() を呼び出すことです。 tac_config() により、ライブラリは、 tacplus.conf(5) でその形式が定義されている環境設定ファイルを 読むことになります。環境設定ファイルのパス名は、引数 file として tac_config() に渡されます。この引数には ヌル を渡すこともでき、その場合は標準環境設定ファイル /etc/tacplus.conf が使われます。 tac_config() は 正常終了のとき、0 を返し、エラーの場合は -1 を返します。

ライブラリは、 tac_add_server() を呼び出すことで、決まった手順に従って構成できます。 パラメータ host はサーバホストを、完全修飾形のドメイン名 (FQDN)、または ピリオドで 4 つの部分に分割表示したテキスト形式の IP アドレスによって 定義します。パラメータ port は、サーバと接続する TCP ポートを定義します。 port が 0 と定義されていると、ライブラリは標準 TACACS+ ポートである ポート 49 を使用します。サーバホストに対する共有シークレットは、 secret パラメータに渡されます。それは ヌル で終了するなんらかの文字列でもかまいません。 サーバからの受信タイムアウトは、 timeout パラメータに、秒の単位で渡されます。 flags パラメータは、フラグの ビットマスクで、サーバの種々の性質を指定するためのものです。内容は 次のとおりです。

TAC_SRVR_SINGLE_CONNECT
    で、ライブラリはサーバと通信するときに、単一接続モードで ネゴシエートしようとします。単一接続モードでは元の TCP 接続が 多重 TACACS+ セッションに対し解放されています。 旧式のサーバはこのモードはサポートしておらず、サーバによっては、 クライアントがネゴシエートしようとすると混乱してしまうものもあります。

tac_add_server() は正常終了時に 0 を返し、エラーのときは -1 を返します。

tac_add_server() は、複数回呼び出すことができ、 tac_config() と一緒に 使用します。最大 10 のサーバまで指定できます。複数サーバの指定があると、 ラウンドロビン方式により稼働中のアクセス可能なサーバを見つけようとします。 ライブラリは、そうしたサーバを見つけると、 サーバが稼動している限りそれを使い続けます。

TACACS+ 認証要求の生成
新規に認証要求を作り始める場合、 tac_create_authen() を呼び出します。 引数 action, type, service には、TACACS+ プロトコル仕様で 定義される適切な値をセットしなければなりません。ヘッダファイル <taclib.h> には、これらの値のシンボリック定数が定義されています。

tac_create_authen() で要求を生成した後、種々の任意指定パラメータを、 tac_set_data(), tac_set_port(), tac_set_priv(), tac_set_rem_addr(), tac_set_user() を呼び出して付加します。ライブラリは、これらの関数に提供された自分自身の 文字列の複製を作るので、呼び出し側で文字列を保存しておく必要はありません。 デフォルトで各パラメータは空ですが、権限レベルだけは ‘USER’ 権限にデフォルト指定されています。

認証要求の送信と応答の受信
TACACS+ 要求が生成されると、 tac_send_authen() によって送信されます。 この関数は、未接続のときサーバ接続を行って、要求を送信し、返信を待ちます。 異常終了のとき、 tac_send_authen() は -1 を返します。正常の場合は、TACACS+ 終了コードとフラグを、 整数値にパックして返します。終了状態は TAC_AUTHEN_STATUS() マクロを使用して抽出することができます。取り得る終了コードは、 <taclib.h> で定義されており、内容は次のとおりです。

TAC_AUTHEN_STATUS_PASS
TAC_AUTHEN_STATUS_FAIL
TAC_AUTHEN_STATUS_GETDATA
TAC_AUTHEN_STATUS_GETUSER
TAC_AUTHEN_STATUS_GETPASS
TAC_AUTHEN_STATUS_RESTART
TAC_AUTHEN_STATUS_ERROR
TAC_AUTHEN_STATUS_FOLLOW

唯一のフラグは no-echo フラグで、 TAC_AUTHEN_NOECHO() マクロで検出できます。

サーバの応答からの情報抽出
サーバからの認証応答パケットには、サーバメッセージや文字列データ、 もしくは、その両者が含まれています。 tac_send_authen() 呼び出しが成功すると、この情報は、 tac_get_msg() と tac_get_data() 呼び出しの応答から取り出すことができます。 これらの関数は、パケットからの情報の動的に割り当てられたコピーを 返します。それらが必要なくなったときには、呼び出し側が解放 しなければなりません。これらの関数から戻ってくるデータは、必ず ヌル で終了していることが保証されています。

tac_get_data() の場合、引数 len は、ライブラリが終端の ナル 文字を含まない実サイズの受信データの保管場所を指しています。 この引数には、呼び出し側が長さを問題にしない場合は、 ヌル を指定してもかまいません。

認証連続パケットの送信
tac_send_authen() が、終了コード TAC_AUTHEN_STATUS_GETDATA, TAC_AUTHEN_STATUS_GETUSER, TAC_AUTHEN_STATUS_GETPASS のうちのどれかを含む値を返す場合、 クライアントは、TACACS+ 連続パケットを使って、 サーバに対する追加情報を提供する必要があります。そのためには、 アプリケーションは最初に、 tac_set_msg() と tac_set_data() を使って、パケットユーザメッセージやデータフィールドを 設定しなければなりません。クライアントは、 tac_send_authen() を使って連続パケットを送信します。

[注意] tac_create_authen() は、連続パケットを生成するときには 呼び出さずに 、初期の認証要求のときにだけ使用する必要があります。

連続パケットを受信すると、サーバは TAC_AUTHEN_STATUS_GETDATA, TAC_AUTHEN_STATUS_GETUSER, TAC_AUTHEN_STATUS_GETPASS を返して、更に情報を要求します。 アプリケーションは、サーバから別の状態コードが受信されるまで、 引き続き連続パケットを送信しなければなりません。

エラーメッセージの取得
引数 struct tac_handle * を受け取る関数は、異常終了するとエラーメッセージを記録します。 エラーメッセージは、 tac_strerror() を呼び出すことにより取り出すことができます。 メッセージテキストは、指定された struct tac_handle * の新たなエラーごとに上書きされます。 従って、メッセージを保管しておかなければならないなら、 同じハンドルを使う後続のライブラリ呼び出しで複製を作らなければなりません。

クリーンアップ
TACACS+ ライブラリで使用したリソースを解放するには、 tac_close() 呼び出して下さい。

戻り値
以下の関数は、正常終了時に、負でない数値を返します。 エラーを検出すると、-1 を返し、エラーメッセージを記録します。 メッセージは tac_strerror() によって取り出せます。

tac_add_server()
tac_config()
tac_create_authen()
tac_send_authen()
tac_set_data()
tac_set_msg()
tac_set_port()
tac_set_priv()
tac_set_rem_addr()
tac_set_user()

以下の関数は、正常終了時にヌルでないポインタを返します。 十分な仮想メモリが割り当てられない場合、 ヌル を返し、エラーメッセージを記録します。メッセージは tac_strerror() で取り出せます。

tac_get_data()
tac_get_msg()

以下の関数は、正常終了時にヌルでないポインタを返します。 十分な仮想メモリが割り当てられない場合、 ヌル を返し、エラーメッセージを記録しません。

tac_open()

関連ファイル
/etc/tacplus.conf

関連項目
tacplus.conf(5) D. Carrel, Lol Grant, The TACACS+ Protocol, Version 1.78, draft-grant-tacacs-02.txt (Internet Draft).

作者
このソフトウェアは、 John Polstra が作成し、 Juniper Networks, Inc によって FreeBSD プロジェクトに寄贈されました。