libradius(3)

libradius − RADIUS クライアントライブラリ

#include <radlib.h>

struct rad_handle *

rad_acct_open(void);

int

rad_add_server(struct rad_handle *h, const char *host, int port, const char *secret, int timeout, int max_tries);

struct rad_handle *

rad_auth_open(void);

void

rad_close(struct rad_handle *h);

int

rad_config(struct rad_handle *h, const char *file);

int

rad_continue_send_request(struct rad_handle *h, int selected, int *fd, struct timeval *tv);

int

rad_create_request(struct rad_handle *h, int code);

struct in_addr

rad_cvt_addr(const void *data);

u_int32_t

rad_cvt_int(const void *data);

char *

rad_cvt_string(const void *data, size_t len);

int

rad_get_attr(struct rad_handle *h, const void **data, size_t *len);

int

rad_init_send_request(struct rad_handle *h, int *fd, struct timeval *tv);

int

rad_put_addr(struct rad_handle *h, int type, struct in_addr addr);

int

rad_put_attr(struct rad_handle *h, int type, const void *data, size_t len);

int

rad_put_int(struct rad_handle *h, int type, u_int32_t value);

int

rad_put_string(struct rad_handle *h, int type, const char *str);

int

rad_send_request(struct rad_handle *h);

const char *

rad_strerror(struct rad_handle *h);

解説

libradius ライブラリは、ユーザサービス遠隔認証ダイアル (RADIUS) のクライ アント側を実装しています。 RADIUS はおよびで定義されており、クライアント はリモート認証サーバへのネットワーク要求により認証とアカウンティングを受 けることができます。

ライブラリを使用する場合にアプリケーションは、まず rad_auth_open() か rad_acct_open() を呼び出して、次の操作のためのコンテキストを与える struct rad_handle * を取得します。前者は RADIUS 認証に使用され、後者は RADIUS ア カウンティングに使用されます。 rad_auth_open() および rad_acct_open() の 呼び出しは、仮想メモリが足りない場合を除いて、常に正常終了します。必要な メモリが割り当てられないとき、関数は NULL を返します。以前のバージョンの 本ライブラリとの互換性のために、 rad_open() が rad_auth_open() の同義語と して提供されています。

RADIUS への要求を出す前に、ライブラリはコンタクト可能なサーバを確認しなけ ればなりません。ライブラリの設定をする最も簡単な方法は rad_config() を呼 び出すことです。 rad_config() によって、ライブラリは radius.conf(5) で フォーマットが定義されているコンフィギュレーションファイルを読み込みま す。コンフィギュレーションファイルのパス名は引数 file として rad_config() へ渡されます。この引数には NULL が指定されてもかまいません。その場合は標 準コンフィギュレーションファイル /etc/radius.conf が使われます。 rad_config() は、正常終了時には 0 を返し、エラー終了時には -1 を返しま す。

ライブラリは rad_add_server() を呼び出すことによって、決まった手順で設定 することもできます。パラメータ host パラメータは、サーバホストを指定し、 完全なドメイン名 (FQDN) でも、またはドット区切りの四つの数字でテキスト形 式で書かれた IP アドレスのどちらで指定してもかまいません。パラメータ port は、サーバに接続するときの UDP ポート番号を指定します。 port の指定が 0 のとき、ライブラリはネットワークサービスデータベースの ‘radius/udp’ また は ‘radacct/udp’ サービスを検索し、見つかったポートを使用します。エントリ が見つからないときには、ライブラリは標準 RADIUS ポート、すなわち認証には 1812 をアカウンティングには 1813 を使用します。サーバホストに関する共有 シークレット情報は、パラメータ secret として渡されます。パラメータは NUL で終了するどんな文字列もかまいません。 RADIUS プロトコルでは、共有シーク レット情報の 128 バイトより後は無視されます。サーバからの受信タイムアウト は、パラメータ timeout により、秒の単位で渡されます。要求をあきらめるまで の最大繰り返し回数は、パラメータ max_tries で渡されます。 rad_add_server() は正常終了のときは 0 を返し、エラーが発生したときは -1 を返します。

rad_add_server() は、複数回呼び出しが可能で、 rad_config() と共に使用する ことができます。サーバは、10 個まで指定できます。複数サーバが指定された場 合、正しい応答が得られるか、またはサーバの max_tries 制限に達するまで、ラ ウンドロビン方式で呼び出しを試みます。

RADIUS 要求は、要求の種類を指定するコードと、ゼロあるいは付加情報を与える 複数の属性値で構成されます。新規要求の作成は、まず rad_create_request() 呼び出しから始めます。通常の struct rad_handle * に加えて、この関数は、パ ラメータ code を取り、それにより要求タイプを指定します。大抵 RAD_ACCESS_REQUEST が指定されます。 rad_create_request() は正常終了のとき は 0 を返し、エラーが発生したときは -1 を返します。

rad_create_request() により要求が生成された後、属性を付加することができま す。これは、 rad_put_addr(), rad_put_int(), rad_put_string() 呼び出しによ り行われます。これらは、属性を決めるパラメータ type や、インターネットア ドレス値、整数値、 NUL で終了する文字列を、それぞれに受け取ります。

ライブラリには、関数 rad_put_attr() も備わっているので、未加工で解釈でき ない属性も与えることができます。引数 data は、バイト配列の先頭のポインタ で、引数 len は、その長さを指定します。

関数 rad_put_X() は、正常終了時には 0 返し、エラー発生時には -1 を返しま す。

RADIUS 要求は生成された後、 rad_send_request() または rad_init_send_request() と rad_continue_send_request() 呼び出しの組み合わ せにより、送信されます。

関数 rad_send_request() は、要求を送信し、必要ならば定義されたサーバに対 してラウンドロビン方式で接続を試み、正しい応答がを待ちます。正しい応答が あった場合、 rad_send_request() は応答のタイプを指定する RADIUS コードを 返します。戻り値は、一般に RAD_ACCESS_ACCEPT, RAD_ACCESS_REJECT, RAD_ACCESS_CHALLENGE です。正しくない応答を受信したとき、 rad_send_request() は -1 を返します。

応答待ちをブロックしたくない場合は、代わりに rad_init_send_request() およ び rad_continue_send_request() を使えます。 RADIUS サーバからの返答を受信 するか、またはタイムアウトになった場合、これらの関数は rad_send_request() の項で挙げた値を返します。それ以外では、ゼロが返され、 fd および tv での 指す値が select(2) に渡されるディスクリプタとタイムアウトに設定されます。

rad_init_send_request() は最初に呼び出す必要があり、続いて、戻り値が 0 で なくなるまで rad_continue_send_request() 呼び出しを繰り返します。それぞれ の呼び出しの間に、アプリケーションは、 select(2) を呼び出す必要があり、そ の際 *fd を読み出しディスクリプタとして渡し、 tv で定義される時間経過の 後、タイムアウトします。 select から制御が戻ったとき、 select(2) でディス クリプタが読み出し可能である場合は、引数 selected に 0 でない値を設定して rad_continue_send_request() を呼び出す必要があります。

RADIUS への要求と同じように、各応答は 0 または、それ以上の属性を持ってい ます。応答が rad_send_request() または rad_continue_send_request() により 正常に受信された後、属性は rad_get_attr() によって、1 つずつ取り出すこと ができます。 rad_get_attr() 呼び出しが呼ばれるたびに、現在の応答から次の 属性を取得し、参照パラメータ data および len を介して、データへのポインタ とデータ長をそれぞれ保管します。データは応答それ自身の中に存在し、変更し てはいけないということに注意して下さい。 rad_get_attr() 呼び出しは、正常 終了すると RADIUS 属性タイプを返します。現在の応答内に属性が無くなると

rad_get_attr() は 0 を返します。不正な属性のようなエラーが検出されると、 -1 を返します。

属性の共通タイプは、 rad_cvt_addr(), rad_cvt_int(), rad_cvt_string() によ りデコードすることができます。これらの関数は、 rad_get_attr() により取得 される属性データへのポインタを受け取ります。 rad_cvt_string() の場合は、 len で長さも指定する必要があります。これらの関数は、属性をインターネット アドレスや整数値、文字列などとして解釈し、得られた値を戻り値として返しま す。 rad_cvt_string() はメモリを動的に割り当て、 NULL で終了した文字列を 返します。アプリケーションは、不要な文字列を free(3) を使って解放しなけれ ばなりません。

十分な仮想メモリがない場合、 rad_cvt_string() は NULL を返します。 rad_cvt_addr() および rad_cvt_int() がエラー終了することはありません。

引数 struct rad_handle * を受け取る関数は、異常終了の場合にエラーメッセー ジを記録します。このエラーメッセージは rad_strerror() 呼び出しで取り出す ことができます。メッセージテキストは、得られた struct rad_handle * によ り、新しいエラーで上書きされます。そのため、メッセージを保存しておくべき なら、同一のハンドルを使って引き続きライブラリ呼び出しを行うことで、複写 しておかなければなりません。

RADIUS ライブラリで使用したリソースは、 rad_close() を呼び出しで解放でき ます。

以下の関数は、処理が正常に終了時、負でない値を返します。エラーを検出した ときは、 -1 を返し、 rad_strerror() を使用して取出したエラーメッセージを 記録します。

rad_add_server()
rad_config()
rad_create_request()
rad_get_attr()
rad_put_addr()
rad_put_attr()
rad_put_int()
rad_put_string()
rad_init_send_request()
rad_continue_send_request()
rad_send_request()

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

rad_acct_open()
rad_auth_open()
rad_cvt_string()

/etc/radius.conf

radius.conf(5)

このソフトウェアは元々 John Polstra が記述し、Juniper Networks, Inc が FreeBSD プロジェクトに寄贈しました。その後
Oleg Semyonov が RADIUS アカウンティングの機能を追加しました。

FreeBSD 10.0 October 30, 1999 FreeBSD 10.0