名称

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_clear_avs( struct tac_handle *h);

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);

int
tac_create_author( struct tac_handle *h, int method, int type, int service);

int
tac_create_acct( struct tac_handle *h, int acct, int action, int type, int service);

char *
tac_get_av( struct tac_handle *h, u_int index);

char *
tac_get_av_value( struct tac_handle *h, const char *attribute);

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_send_author( struct tac_handle *h);

int
tac_send_acct( struct tac_handle *h);

int
tac_set_av( struct tac_handle *h, u_int index, const char *av_pair);

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+ は、遠隔のサーバへのネットワーク要求を用いて認証、認可およびアカウンティングをクライアントが実行することを可能にします。このライブラリは、現在プロトコルの認証および認可部分だけをサポートしています。

初期設定

ライブラリを使用するために、アプリケーションは、後の操作のためにコンテキストを供給する struct tac_handle * を得るために最初に tac_open() を呼び出さなければなりません。十分な仮想メモリが利用可能であれば、 tac_open() への呼び出しは、常に成功します。必要なメモリを割り付けることができないなら、 tac_open() は、 NULL を返します。

どんな TACACS+ 要求を出す前に、ライブラリは、それがコンタクトできるサーバを知っていなければなりません。ライブラリを設定する最も容易な方法は、 tac_config() を呼ぶことです。 tac_config() は、ライブラリに tacplus.conf(5) にその形式が記述される設定ファイルを読み込ませます。設定ファイルのパス名は、 tac_config() に file 引数として渡されます。この引数も NULL として与えることができます。その場合は、標準の設定ファイル /etc/tacplus.conf が使用されます。 tac_config() は、成功すれば、0 を返し、エラーが生じるなら、-1 を返します。

また、ライブラリは、 tac_add_server() への呼び出によってプログラムで設定できます。 host パラメータは、完全な形でのドメイン名 (FQDN) またはテキスト形式のドットのある 4 セットの IP アドレスのいずれかで、サーバホストを指定します。 port パラメータは、サーバでコンタクトするために TCP ポートを指定します。 port が 0 として与えられるなら、ライブラリは、ポート 49、標準の TACACS+ ポートを使用します。サーバホストのために共有される秘密は、 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> ヘッダファイルは、これらの値のためのシンボリック定数を含んでいます。

TACACS+ 認可要求の生成

新しい認可要求を構築し始めるためには、 tac_create_author() を呼び出します。 method, type と service 引数は、TACACS+ プロトコル仕様で定義される適切な値を設定しなければなりません。 < taclib.h> ヘッダファイルは、これらの値のためのシンボリック定数を含んでいます。

TACACS+ アカウンティング要求を作成する

新しいアカウンティング要求を構成し始めるには、 tac_create_acct(). を呼び出します。 acct, action, type と service 引数は、TACACS+ プロトコル仕様で定義されるように、適切な値に設定されなければなりません。 < taclib.h> ヘッダファイルは、これらの値のためのシンボリックな定数を含んでいます。

要求でオプションパラメータを設定

要求を作成した後に、様々なオプションのパラメータは、 tac_set_av(), tac_set_data(), tac_set_port(), tac_set_priv(), tac_set_rem_addr() と tac_set_user() への呼び出しを通してそれに取り付けることができます。ライブラリは、これらの関数に供給される任意の文字列のそれ自身のコピーを作成します。そのため、呼び出し側でそれらを保存することは必要ではありません。デフォルトでは、これらのパラメータの各々は、特権レベルを除いて空です。特権レベルは、デフォルトで‘ USER’特権です。

tac_set_av() は、認可要求のコンテキストにのみ適用します。属性値ペアのための形式は、TACACS+ プロトコル仕様で定義されます。指定されたインデックスは、0 と 255 を含んで、 0 と 255 の間の任意の値でありえます、そして属性値ペアを置くリスト中の位置を示します。同じインデックスで tac_set_av() を 2 度に呼び出すことは、その位置で値を効果的に交換します。設定されたすべての属性値ペアをクリアするためには、 tac_clear_avs() を使用します。

認証要求の送信と応答の受信

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 引数は、ライブラリがヌルの終端子を含まない受信データの実際の長さを格納する位置を指します。呼び出し側が長さに興味を持たなければ、この引数は、 NULL として与えられることができます。

認証連続パケットの送信

tac_send_authen() がステータスコード TAC_AUTHEN_STATUS_GETDATA, TAC_AUTHEN_STATUS_GETUSER または TAC_AUTHEN_STATUS_GETPASS のうちの 1 つを含んでいる値を返すなら、クライアントは、TACACS+ CONTINUE パケットを用いてサーバに追加情報を提供しなければなりません。そうするために、アプリケーションは、最初に tac_set_msg() と tac_set_data() を使用して、パケットのユーザメッセージおよび/またはデータフィールドを設定しなければなりません。そして、クライアントは、 tac_send_authen() で CONTINUE パケットを送ります。 [注意] tac_create_authen() は、CONTINUE パケットを構築するためには、呼び出されててはなりません。それは、初期の認証要求のためにのみ使用されます。

それが CONTINUE パケットを受け取る時、サーバは、 TAC_AUTHEN_STATUS_GETDATA, TAC_AUTHEN_STATUS_GETUSER または TAC_AUTHEN_STATUS_GETPASS を返すことにより再びより多くの情報を要求できます。他のあるステータスがサーバから受け取られるまで、そのアプリケーションは、 CONTINUE をさらに送るべきです。

認可要求の送信と応答の受信

TACACS+ 認可要求が構築された後、それは、 tac_send_author() を用いて送られます。もしまだ接続されなければ、この関数は、サーバに接続し、要求を送り、返信を待ちます。失敗すれば、 tac_send_author() は、-1 を返します。そうでなければ、それは、TACACS+ ステータスコードを返し、また、受け取られた属性値 (AV) ペアの数は、整数値へパックして (詰めて) います。ステータスは、マクロ TAC_AUTHOR_STATUS() を使用して抽出できます。 < taclib.h> に定義された指定できるステータスコードは、次のものを含んでいます:

• TAC_AUTHOR_STATUS_PASS_ADD
• TAC_AUTHOR_STATUS_PASS_REPL
• TAC_AUTHOR_STATUS_FAIL
• TAC_AUTHOR_STATUS_ERROR

受け取られた AV ペアの数は、 TAC_AUTHEN_AV_COUNT() を使用して得られます。

アカウンティング要求を送信して、応答を受信する

TACACS+ 承認要求が構成された後に、それは、 tac_send_acct() を用いて送信されます。この関数は、まだ接続されていなければ、サーバに接続し、要求を送信して、応答を待ちます。失敗すれば、 tac_send_acct() は、-1 を返します。そうでなければ、TACACS+ ステータスコードを返します。指定できるステータスコードは、次が含まれる < taclib.h> に定義されます:

• TAC_ACCT_STATUS_SUCCESS
• TAC_ACCT_STATUS_ERROR
• TAC_ACCT_STATUS_FOLLOW

サーバの認可応答からの情報を抽出

認証応答パケットのように、サーバからの認可応答パケットは、サーバメッセージ、データ文字列または両方を含むことができます。それらの値の抽出については、「サーバの認証応答から情報を抽出」を参照してください。

サーバからの認可応答パケットは、さらに属性値 (AV) ペアを含むことができます。これらを抽出するためには、 tac_get_av() か tac_get_av_value() を使用してください。それがリスト中で位置づけられるように、 tac_get_av() は、AV ペアのインデックスをとります。インデックスは、0 (このリスト中のアイテムの総数を得るために、 tac_send_author() の返り値で TAC_AUTHEN_AV_COUNT() を使用します) から始まります。代わりに、 tac_get_av_value() は、使用できます。 tac_get_av_value() は、属性名をとり、AV ペアではなく対応する値のみを返します。これらの関数は、パケットから情報のダイナミックに割り付けられたコピーを返します。呼び出し側は、それらをもはや必要としない時に、コピーを解放することに責任を負います。これらの関数から返されたデータは、ヌル文字のバイトによって終了することを保証されています。

エラーメッセージの取得

それらが失敗するなら、 struct tac_handle * 引数を受け取る関数は、エラーメッセージを記録します。エラーメッセージは、 tac_strerror() を呼び出すことにより検索する (取り出す) ことができます。メッセージテキストは、与えられた struct tac_handle * のための個々の新しいエラーで上書きされます。したがって、同じハンドルを使用して後のライブラリ呼び出しのために保存されることになっているなら、メッセージは、コピーされなければなりません。

クリーンナップ

TACACS+ ライブラリによって使用されるリソース (資源) を解放するために、 tac_close() を呼び出します。

戻り値

次の関数は、成功すれば、負でない値を返します。それらは、エラーを検出するなら、-1 を返し、 tac_strerror() を使用して検索する (取り出す) ことができるエラーメッセージを記録します。

• tac_add_server()
• tac_config()
• tac_create_authen()
• tac_create_author()
• tac_create_acct()
• tac_send_authen()
• tac_send_author()
• tac_send_acct()
• tac_set_av()
• tac_set_data()
• tac_set_msg()
• tac_set_port()
• tac_set_priv()
• tac_set_rem_addr()
• tac_set_user()

次の関数は、成功すれば、 NULL でないポインタを返します。十分な仮想メモリを割り付けることができないなら、それらは、エラーメッセージを記録せずに、 NULL を返し、 tac_strerror() を使用して検索する (取り出す) ことができるエラーメッセージを記録します。

• tac_get_av()
• tac_get_av_value()
• tac_get_data()
• tac_get_msg()

次の関数は、成功すると、 NULL でないポインタを返します。十分な仮想メモリを割り付けることができないなら、それらは、エラーメッセージを記録せずに、 NULL を返します。

• tac_open()

関連ファイル

/etc/tacplus.conf

関連項目

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

作者

このソフトウェアは、 John Polstra と Paul Fraley によって書かれました、そして Juniper Networks, Inc. によって FreeBSD プロジェクトに寄贈されました。