libtacplus(3)

libtacplus − TACACS+ クライアントライブラリ

#include <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 パラメータは、フラグのビットマスクで、サーバの種 々の性質を指定するためのものです。内容は次のとおりです。

で、ライブラリはサーバと通信するときに、単一接続モードでネゴ シエートしようとします。単一接続モードでは元の 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)

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

FreeBSD 10.0 September 2, 1998 FreeBSD 10.0