EN JA
LIBRADIUS(3)
LIBRADIUS(3) FreeBSD Library Functions Manual LIBRADIUS(3)

名称

libradiusRADIUS クライアント/サーバライブラリ

書式

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

int
rad_add_server_ex( struct rad_handle *h, const char *host, int port, const char *secret, int timeout, int max_tries, int dead_time, struct in_addr *bindto);

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

int
rad_create_response( struct rad_handle *h, int code);

struct in_addr
rad_cvt_addr( const void *data);

uint32_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_get_vendor_attr( uint32_t *vendor, 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, uint32_t value);

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

int
rad_put_message_authentic( struct rad_handle *h);

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

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

int
rad_put_vendor_int( struct rad_handle *h, int vendor, int type, uint32_t value);

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

ssize_t
rad_request_authenticator( struct rad_handle *h, char *buf, size_t len);

int
rad_receive_request( struct rad_handle *h);

int
rad_send_request( struct rad_handle *h);

int
rad_send_response( struct rad_handle *h);

struct rad_handle *
rad_server_open( int fd);

const char *
rad_server_secret( struct rad_handle *h);

void
rad_bind_to( struct rad_handle *h, in_addr_t addr);

u_char *
rad_demangle( struct rad_handle *h, const void *mangled, size_t mlen);

u_char *
rad_demangle_mppe_key( struct rad_handle *h, const void *mangled, size_t mlen, size_t *len);

const char *
rad_strerror( struct rad_handle *h);

解説

libradius ライブラリは、ユーザサービス遠隔認証ダイヤル (Remote Authentication Dial In User Service) (RADIUS) を実装しています。 RFC 2865 と 2866 で定義された RADIUS は、ネットワーク遠隔サーバへの要求の意味によってクライアントが認証とアカウンティングを実行することを可能にします。

初期設定

ライブラリを使用するために、アプリケーションは、後の操作のためにコンテキストを提供する struct rad_handle * を得るために rad_auth_open(), rad_acct_open() または rad_server_open() を最初に呼ばなければなりません。前の関数は、RADIUS 認証のために使用され、後者は、RADIUS アカウンティングのために使用されます。不十分な仮想記憶が利用可能でなければ、 rad_auth_open(), rad_acct_open() と rad_server_open() への呼び出しは、常に成功します。必要なメモリを割り付けることができないなら、関数は、 NULL を返します。このライブラリの初期のバージョンとの互換性については、 rad_open() が rad_auth_open() の同意語として提供されます。

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

また、ライブラリは、 rad_add_server() または rad_add_server_ex() への呼び出しによってプログラムで設定することができます。 rad_add_server() は、 rad_add_server_ex() によって実装された後方互換性のある関数です。 host パラメータは、完全な形でのドメイン名 (FQDN) またはテキスト形式のドットのある 4 セットの IP アドレスのいずれかでサーバホストを指定します。 port パラメータは、サーバにコンタクトするための UDP ポートを指定します。 port が 0 として与えられるなら、ライブラリは、ネットワーク services(5) データベースで‘ radius/udp’または‘ radacct/udp’サービスを調べてそこで見つかったポートを使用します。エントリが見つからないなら、ライブラリは、標準の RADIUS ポート、すなわち認証のために 1812 とアカウンティングのために 1813 を使用します。サーバホストのための共有される秘密は、 secret パラメータに渡されます。それは、バイトの ヌル文字で終了する 任意の文字列かもしれません。 RADIUS プロトコルは、共有される秘密の先導する 128 バイトのほかは皆無視します。サーバから返答を受け取るためのタイムアウトは、秒単位で timeout パラメータに渡されます。あきらめる前に繰り返される要求の最大の数は、 max_tries パラメータへ渡されます。 dead_time パラメータで (最後の試みで答えなかった) 死んでいるセットとしてマークされるなら、サーバが要求されないときの秒単位の時間間隔。 bindto パラメータは、すべての要求のためのソースアドレスとして使用されるマルチホーム (multihome) のホストの IP アドレスです。 rad_add_server() は、成功すれば、0 を返し、エラーが生じたなら、-1 を返します。

rad_add_server() または rad_add_server_ex() は、複数回呼び出すことができ、それらは、 rad_config() とともに使用できます。多くても 10 個のサーバが指定できます。多数のサーバが与えられるとき、それらは、有効な応答が受け取られるまでか、各サーバの max_tries 制限に到達するまでラウンドロビン方法が試みられます。

RADIUS 要求の生成

RADIUS 要求は、要求の種類を指定するコードと付加情報を提供する 0 以上の属性から構成されます。新しい要求を構築し始めるためには、 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 パラメータ、とインターネットアドレスとなる値、整数、または ヌル文字で終了する 文字列をそれぞれ受け取ります。代わりに rad_put_vendor_addr(), rad_put_vendor_int() または rad_put_vendor_string() は、ベンダ特有属性を指定するために使用できます。ベンダ特有の定義は、 < radlib_vs.h> で見つけることができます。

ライブラリは、さらに未加工で解釈されない属性を供給するために使用することができる関数 rad_put_attr() を提供します。 data 引数は、バイトの配列を指し、 len 引数は、その長さを指定します。

メッセージ-認証符号 (Message-Authenticator) を要求に追加するのは、可能です。これは、アクセス-リクエスト (Access-Request) パケット (RFC 3579 を参照) 全体の HMAC-MD5 ハッシュです。この属性は、EAP-メッセージ (EAP-Message) 属性を含んでいるどんなパケットにも存在していなければなりません。 rad_put_message_authentic() 関数を使用することによって、追加することができます。 libradius ライブラリは、要求を送る前に、暗黙のうちに HMAC-MD5 ハッシュを計算します。メッセージ-認証符号 (Message-Authenticator) が応答パケットの中で見つけられたなら、検証が失敗したなら、パケットは、静かに落とされます。この機能を得るために、ライブラリは、OpenSSL サポートでコンパイルされるべきです。

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() で記述される値を返します。そうでなければ、0 の値は、返されます、また、 fdtv によって指される値は、 select(2) に渡されるべき記述子とタイムアウトに設定されます。

rad_init_send_request() は、0 の返り値が与えられる間 rad_continue_send_request() への繰り返しの呼び出しの後に続けて、最初に呼ばれなければなりません。各呼び出しの間で、アプリケーションは、 tv によって指定された間隔の後に読み込まれた記述子とタイミングとして *fd を渡す、 select(2) を呼び出すべきです。 select(2) から返ったとき、 select(2) が記述子が読み込み可能であることを示すなら、 rad_continue_send_request() は、0 でない値に設定された selected で呼ばれるべきです。

RADIUS 要求のように、各応答は、0 以上の属性を含むことができます。応答が rad_send_request() か rad_continue_send_request(), によって成功して受け取られた後、その属性は、一つずつ rad_get_attr() を使用して引き出すことができます。 rad_get_attr() が呼ばれるごとに、それは、現在の応答から次の属性を得て、参照パラメータ datalen によってそれぞれデータとデータの長さへのポインタを格納します。データは、応答それ自体に存在し修正されてはならないことに注意してください。 rad_get_attr() への呼び出しが成功すれば RADIUS 属性タイプを返します。現在の応答にこれ以上の属性が残らないなら、 rad_get_attr() は、0 を返します。不正な形式の属性のようなエラーが検知されるなら、-1 が返されます。

rad_get_attr() が RAD_VENDOR_SPECIFIC を返すなら、 rad_get_vendor_attr() は、ベンダを決定するために呼び出すことができます。ベンダ特有 RADIUS 属性タイプが返されます。 ( rad_get_attr() から返されたような) 参照パラメータ datalen は、 rad_get_vendor_attr() に渡され、ベンダに特有の属性データを指すために調節されます。

属性の共通のタイプは、 rad_cvt_addr(), rad_cvt_int() と rad_cvt_string() を使用してデコード (逆符号化) できます。これらの関数は、 rad_get_attr() かオプションの rad_get_vendor_attr() を使用して得られるべき属性データへのポインタを受け取ります。 rad_cvt_string() の場合は、長さ len もまた与えられなければなりません。これらの関数は、インターネットアドレス、整数または文字列として属性をそれぞれ解釈し、その値を返します。 rad_cvt_string() は、動的に割り付けられたメモリ中に ヌル文字で終了する 文字列としてその値を返します。そのアプリケーションは、それがもはや必要でない時、 free(3) 使用して、文字列を解放するべきです。

十分な仮想メモリが利用可能でないなら、 rad_cvt_string() は、 NULL を返します。 rad_cvt_addr() と rad_cvt_int() は、失敗することはありません。

rad_request_authenticator() 関数は、供給された rad_handle によって現在の RADIUS サーバに関連した要求認証符号 (Request-Authenticator) 属性値を得るために使用できます。長さ len の目標バッファ buf は、供給されなければならないし、少なくとも 16 バイトであるべきです。返り値は、 buf に書き込まれたバイトの数です。または len が十分に大きくなかったことを示すために-1 です。

rad_server_secret() は、供給された rad_handle のための現在の RADIUS サーバと共有された秘密を返します。

rad_bind_to() は、現在の RADIUS サーバへのすべての要求のためのソースアドレスを割り当てます。

rad_demangle() 関数は、パスワードと MS-CHAPv1 MPPE キーを含む属性をめちゃめちゃにしません。demangle (訳注: 意味不明) 失敗するか、または平文 (プレーンテキスト) の属性ならリターン値は、 NULL です。この値は、それがもう必要でないときに、 free(3) を使用することで解放されるべきです。

rad_demangle_mppe_key() 関数は、MPPE (RFC 2548 参照) を使用するとき、 send-key と recv-key をめちゃめちゃにしません。demangle (訳注: 意味不明) 失敗するか、または平文 (プレーンテキスト) の属性ならリターン値は、 NULL です。この値は、それがもう必要でないときに、 free(3) を使用することで解放されるべきです。

エラーメッセージの取得

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

クリーンアップ

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

サーバ操作

サーバモード操作は、パケット送信と受信ステップが入れ替わっていることを除いて、クライアントモードによく似ています。サーバとして動作するために、利用者は、引数としてオープンされバインドされた UDP ソケットファイル記述子を渡して、 rad_server_open() 関数でサーバコンテキストを得るべきです。利用者は、 rad_add_server() 関数を使用して許可クライアントとそれらの秘密鍵を定義すべきです。 port, timeout と max_tries 引数は、サーバモードで無視されます。利用者は、クライアントから要求を受信するために rad_receive_request() 関数を呼び出すべきです。利用者がソケットの読み込みをブロックしたくないなら、自由にソケットのための任意の poll(), select() またはブロックしないソケットを使用できます。クライアントと同じ構文解析関数で受信要求を解析できます。要求に応答するために、利用者は、 rad_create_response() を呼び出し、クライアントと同じパケット書き込み関数で応答内容を満たすべきです。パケットの準備ができているとき、 rad_send_response() でそれを送信するべきです。

戻り値

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

  • rad_add_server()
  • rad_config()
  • rad_create_request()
  • rad_create_response()
  • rad_get_attr()
  • rad_put_addr()
  • rad_put_attr()
  • rad_put_int()
  • rad_put_string()
  • rad_put_message_authentic()
  • rad_init_send_request()
  • rad_continue_send_request()
  • rad_send_request()
  • rad_send_response()

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

  • rad_acct_open()
  • rad_auth_open()
  • rad_server_open()
  • rad_cvt_string()

次の関数は、成功すれば NULL でないポインタを返します。失敗するなら、それらは、エラーメッセージを記録すると共に NULL を返します。

  • rad_demangle()
  • rad_demangle_mppe_key()

関連ファイル

/etc/radius.conf

関連項目

radius.conf(5) C. Rigney, et al, Remote Authentication Dial In User Service (RADIUS), RFC 2865. C. Rigney, RADIUS Accounting, RFC 2866. G. Zorn, Microsoft Vendor-specific RADIUS attributes, RFC 2548. C. Rigney, et al, RADIUS extensions, RFC 2869.

作者

このソフトウェアは、 John Polstra によって始めに書かれ、 Juniper Networks, Inc. によって FreeBSD プロジェクトに寄贈されました。 Oleg Semyonov は、続いて RADIUS アカウンティングを実行する機能を追加しました。 Michael Bretterklieber によって後で追加され変更されました。サーバモードのサポートは、 Alexander Motin によって追加されました。
August 5, 2009 FreeBSD