doc/ja_JP.eucJP/man/man3/libradius.3

.\" 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/libradius/libradius.3,v 1.6.2.4 2001/12/17 10:08:31 ru Exp %
.\"
.\" $FreeBSD$
.Dd October 30, 1999
.Dt LIBRADIUS 3
.Os
.Sh 名称
.Nm libradius
.Nd RADIUS クライアントライブラリ
.Sh 書式
.In radlib.h
.Ft struct rad_handle *
.Fn rad_acct_open "void"
.Ft int
.Fn rad_add_server "struct rad_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int max_tries"
.Ft struct rad_handle *
.Fn rad_auth_open "void"
.Ft void
.Fn rad_close "struct rad_handle *h"
.Ft int
.Fn rad_config "struct rad_handle *h" "const char *file"
.Ft int
.Fn rad_continue_send_request "struct rad_handle *h" "int selected" "int *fd" "struct timeval *tv"
.Ft int
.Fn rad_create_request "struct rad_handle *h" "int code"
.Ft struct in_addr
.Fn rad_cvt_addr "const void *data"
.Ft u_int32_t
.Fn rad_cvt_int "const void *data"
.Ft char *
.Fn rad_cvt_string "const void *data" "size_t len"
.Ft int
.Fn rad_get_attr "struct rad_handle *h" "const void **data" "size_t *len"
.Ft int
.Fn rad_init_send_request "struct rad_handle *h" "int *fd" "struct timeval *tv"
.Ft int
.Fn rad_put_addr "struct rad_handle *h" "int type" "struct in_addr addr"
.Ft int
.Fn rad_put_attr "struct rad_handle *h" "int type" "const void *data" "size_t len"
.Ft int
.Fn rad_put_int "struct rad_handle *h" "int type" "u_int32_t value"
.Ft int
.Fn rad_put_string "struct rad_handle *h" "int type" "const char *str"
.Ft int
.Fn rad_send_request "struct rad_handle *h"
.Ft const char *
.Fn rad_strerror "struct rad_handle *h"
.Sh 解説
.Nm libradius
ライブラリは、ユーザサービス遠隔認証ダイアル (RADIUS) の
クライアント側を実装しています。
RADIUS は
.%O RFC 2138
および
.%O RFC 2138
で定義されており、
クライアントはリモート認証サーバへのネットワーク要求により
認証とアカウンティングを受けることができます。
.Sh 初期設定
ライブラリを使用する場合にアプリケーションは、まず
.Fn rad_auth_open
か
.Fn rad_acct_open
を呼び出して、次の操作のためのコンテキストを与える
.Va struct rad_handle *
を取得します。
前者は RADIUS 認証に使用され、後者は RADIUS アカウンティングに使用されます。
.Fn rad_auth_open
および
.Fn rad_acct_open
の呼び出しは、仮想メモリが足りない場合を除いて、常に正常終了します。
必要なメモリが割り当てられないとき、
関数は
.Dv NULL
を返します。
以前のバージョンの本ライブラリとの互換性のために、
.Fn rad_open
が
.Fn rad_auth_open
の同義語として提供されています。
.Pp
RADIUS への要求を出す前に、ライブラリはコンタクト可能なサーバを
確認しなければなりません。ライブラリの設定をする最も簡単な方法は
.Fn rad_config
を呼び出すことです。
.Fn rad_config
によって、ライブラリは
.Xr radius.conf 5
でフォーマットが定義されているコンフィギュレーションファイルを読み込みます。
コンフィギュレーションファイルのパス名は引数
.Va file
として
.Fn rad_config
へ渡されます。この引数には
.Dv NULL
が
指定されてもかまいません。その場合は標準コンフィギュレーションファイル
/etc/radius.conf
が使われます。
.Fn rad_config
は、正常終了時には 0 を返し、エラー終了時には -1 を返します。
.Pp
ライブラリは
.Fn rad_add_server
を呼び出すことによって、決まった手順で
設定することもできます。パラメータ
.Va host
パラメータは、サーバホストを指定し、
完全なドメイン名 (FQDN) でも、またはドット区切りの四つの数字でテキスト形式
で書かれた IP アドレスのどちらで指定してもかまいません。
パラメータ
.Va port
は、サーバに接続するときの UDP ポート番号を指定します。
.Va port
の指定が 0 のとき、ライブラリはネットワークサービスデータベースの
.Ql radius/udp
または
.Ql radacct/udp
サービスを検索し、見つかったポートを使用します。
エントリが見つからないときには、ライブラリは標準 RADIUS ポート、
すなわち認証には 1812 をアカウンティングには 1813 を使用します。
サーバホストに関する共有シークレット情報は、
パラメータ
.Va secret
として渡されます。パラメータは
.Dv NUL
で終了するどんな文字列もかまいません。
RADIUS プロトコルでは、共有
シークレット情報の 128 バイトより後は無視されます。サーバからの受信
タイムアウトは、パラメータ
.Va timeout
により、秒の単位で渡されます。要求をあきらめるまでの
最大繰り返し回数は、パラメータ
.Va max_tries
で渡されます。
.Fn rad_add_server
は
正常終了のときは
0 を返し、エラーが発生したときは -1 を返します。
.Pp
.Fn rad_add_server
は、複数回呼び出しが可能で、
.Fn rad_config
と共に使用することができます。
サーバは、10 個まで指定できます。複数サーバが
指定された場合、正しい応答が得られるか、またはサーバの
.Va max_tries
制限に達するまで、ラウンドロビン方式で呼び出しを試みます。
.Sh RADIUS 要求の生成
RADIUS 要求は、要求の種類を指定するコードと、ゼロあるいは
付加情報を与える複数の属性値で構成されます。新規要求の作成は、まず
.Fn rad_create_request
呼び出しから始めます。通常の
.Va struct rad_handle *
に加えて、
この関数は、パラメータ
.Va code
を取り、それにより要求タイプを指定します。大抵
.Dv RAD_ACCESS_REQUEST
が指定されます。
.Fn rad_create_request
は正常終了のときは 0 を返し、エラーが発生したときは -1 を返します。
.Pp
.Fn rad_create_request
により要求が生成された後、属性を付加することができます。これは、
.Fn rad_put_addr ,
.Fn rad_put_int  ,
.Fn rad_put_string
呼び出しにより行われます。これらは、属性を決めるパラメータ
.Va type
や、インターネットアドレス値、整数値、
.Dv NUL
で終了する文字列を、それぞれに受け取ります。
.Pp
ライブラリには、関数
.Fn rad_put_attr
も備わっているので、未加工で解釈できない属性も
与えることができます。引数
.Va data
は、バイト配列の先頭のポインタで、
引数
.Va len
は、その長さを指定します。
.Pp
関数
.Fn rad_put_X
は、正常終了時には 0 返し、エラー発生時には -1 を返します。
.Sh 要求の送信と応答の受信
RADIUS 要求は生成された後、
.Fn rad_send_request
または
.Fn rad_init_send_request
と
.Fn rad_continue_send_request
呼び出しの組み
合わせにより、送信されます。
.Pp
関数
.Fn rad_send_request
は、要求を送信し、必要ならば定義されたサーバに対して
ラウンドロビン方式で接続を試み、正しい応答がを待ちます。
正しい応答があった場合、
.Fn rad_send_request
は応答のタイプを指定する RADIUS コードを返します。
戻り値は、一般に
.Dv RAD_ACCESS_ACCEPT ,
.Dv RAD_ACCESS_REJECT ,
.Dv RAD_ACCESS_CHALLENGE
です。正しくない応答を受信したとき、
.Fn rad_send_request
は -1 を返します。
.Pp
応答待ちをブロックしたくない場合は、代わりに
.Fn rad_init_send_request
および
.Fn rad_continue_send_request
を使えます。
RADIUS サーバからの返答を受信するか、
またはタイムアウトになった場合、これらの関数は
.Fn rad_send_request
の項で挙げた値を返します。それ以外では、ゼロが返され、
.Ar fd
および
.Ar tv
での指す値が
.Xr select 2
に渡されるディスクリプタとタイムアウトに設定されます。
.Pp
.Fn rad_init_send_request
は最初に呼び出す必要があり、続いて、戻り値が 0 でなくなるまで
.Fn rad_continue_send_request
呼び出しを繰り返します。
それぞれの呼び出しの間に、アプリケーションは、
.Xr select 2
を呼び出す必要があり、その際
.Ar *fd
を読み出しディスクリプタとして渡し、
.Ar tv
で定義される時間経過の後、タイムアウトします。
select から制御が戻ったとき、
.Xr select 2
でディスクリプタが読み出し可能である場合は、引数
.Ar selected
に 0 でない値を設定して
.Fn rad_continue_send_request
を呼び出す必要があります。
.Pp
RADIUS への要求と同じように、各応答は 0 または、
それ以上の属性を持っています。応答が
.Fn rad_send_request
または
.Fn rad_continue_send_request
により正常に受信された後、属性は
.Fn rad_get_attr
によって、1 つずつ取り出すことができます。
.Fn rad_get_attr
呼び出しが呼ばれるたびに、現在の応答から次の属性を
取得し、参照パラメータ
.Va data
および
.Va len
を介して、データへのポインタとデータ長をそれぞれ保管します。
データは応答それ自身の中に存在し、
変更してはいけないということに注意して下さい。
.Fn rad_get_attr
呼び出しは、正常終了すると RADIUS 属性タイプを返します。
現在の応答内に属性が無くなると

.Fn rad_get_attr
は 0 を返します。不正な属性のようなエラーが検出されると、
-1 を返します。
.Pp
属性の共通タイプは、
.Fn rad_cvt_addr ,
.Fn rad_cvt_int ,
.Fn rad_cvt_string
によりデコードすることができます。これらの関数は、
.Fn rad_get_attr
により取得される属性データへのポインタを受け取ります。
.Fn rad_cvt_string
の
場合は、
.Va len
で長さも指定する必要があります。これらの関数は、属性を
インターネットアドレスや整数値、文字列などとして解釈し、得られた値を
戻り値として返します。
.Fn rad_cvt_string
はメモリを動的に割り当て、
.Dv NULL
で終了した文字列を返します。アプリケーションは、不要な文字列を
.Xr free 3
を使って解放しなければなりません。
.Pp
十分な仮想メモリがない場合、
.Fn rad_cvt_string
は
.Dv NULL
を返します。
.Fn rad_cvt_addr
および
.Fn rad_cvt_int
がエラー終了することはありません。
.Sh エラーメッセージ取得
引数
.Va struct rad_handle *
を受け取る関数は、異常終了の場合にエラーメッセージを記録します。
このエラーメッセージは
.Fn rad_strerror
呼び出しで取り出すことができます。メッセージテキストは、得られた
.Va struct rad_handle *
により、新しいエラーで上書きされます。
そのため、メッセージを保存しておくべきなら、
同一のハンドルを使って引き続きライブラリ呼び出しを行うことで、
複写しておかなければなりません。
.Sh クリーンアップ
RADIUS ライブラリで使用したリソースは、
.Fn rad_close
を呼び出しで解放できます。
.Sh 戻り値
以下の関数は、処理が正常に終了時、負でない値を返します。エラーを
検出したときは、
-1 を返し、
.Fn rad_strerror
を使用して取出した
エラーメッセージを記録します。
.Pp
.Bl -item -offset indent -compact
.It
.Fn rad_add_server
.It
.Fn rad_config
.It
.Fn rad_create_request
.It
.Fn rad_get_attr
.It
.Fn rad_put_addr
.It
.Fn rad_put_attr
.It
.Fn rad_put_int
.It
.Fn rad_put_string
.It
.Fn rad_init_send_request
.It
.Fn rad_continue_send_request
.It
.Fn rad_send_request
.El
.Pp
以下の関数は、処理が正常に終了した時、
.Dv NULL
でないポインタを返します。
十分な仮想メモリの割り当てができないとき、
.Dv NULL
を返しますが、
エラーメッセージは記録されません。
.Pp
.Bl -item -offset indent -compact
.It
.Fn rad_acct_open
.It
.Fn rad_auth_open
.It
.Fn rad_cvt_string
.El
.Pp
.Sh 関連ファイル
.Pa /etc/radius.conf
.Sh 関連項目
.Xr radius.conf 5
.Rs
.%A C. Rigney, et al
.%T "Remote Authentication Dial In User Service (RADIUS)"
.%O RFC 2138
.Re
.Rs
.%A C. Rigney
.%T RADIUS Accounting
.%O RFC 2139
.Re
.Sh 作者
このソフトウェアは元々
.An John Polstra
が記述し、Juniper Networks, Inc が
.Fx
プロジェクトに寄贈しました。
その後
.An Oleg Semyonov
が RADIUS アカウンティングの機能を追加しました。