| Oracle® Fusion Middleware Oracle Identity Managementアプリケーション開発者ガイド 11g リリース1 (11.1.1) B56242-07 |
|
 前 |
 次 |
| Oracle® Fusion Middleware Oracle Identity Managementアプリケーション開発者ガイド 11g リリース1 (11.1.1) B56242-07 |
|
前 |
次 |
この章では、Oracle Internet DirectoryのC APIについて説明し、そのAPIの使用例を示します。
この章の内容は次のとおりです。
Oracle Internet Directory SDK C APIは、LDAPバージョン3 C API、およびSSLをサポートするOracleの拡張機能をベースにしています。
Oracle Internet Directory API 11gリリース1(11.1.1)は、次のモードで使用できます。
SSL: SSLを使用してすべての通信を保護します。
非SSL: クライアント/サーバー間の通信を保護しません。
APIは、TCP/IPを使用してディレクトリ・サーバーに接続します。接続するとき、デフォルトでは暗号化されていないチャネルを使用します。SSLモードを使用するには、Oracle SSLコール・インタフェースを使用する必要があります。APIを使用する際に、SSLコールの有無によってどちらのモードを使用するかを決定します。SSLモードと非SSLモードは簡単に切り替えることができます。
この項では、次の項目について説明します。
LDAP APIへのOracle SSL拡張機能は、標準的なSSLプロトコルに基づいています。SSL拡張機能は回線を通るデータの暗号化と復号化および認証を行います。
認証には次の3つのモードがあります。
認証なし: クライアントとサーバーのどちらも認証せず、SSLによる暗号化のみを使用します。
一方向: クライアントによりサーバーのみが認証されます。
双方向: サーバーとクライアントが相互に認証します。
認証のタイプは、SSLインタフェース・コールのパラメータで指定します。
次のコールを行うのみで、SSLは使用可能になります。
int ldap_init_SSL(Sockbuf *sb, char *sslwallet, char *sslwalletpasswd, int sslauthmode)
ldap_init_SSLコールは、標準的なSSLプロトコルを使用して、クライアントとサーバーの間で必要なハンドシェイクを実行します。コールが成功すると、これ以降のすべての通信は保護された接続で実行されます。
表8-1 SSLインタフェース・コールの引数
| 引数 | 説明 |
|---|---|
sb |
LDAPハンドルの一部として、 |
sslwallet |
ユーザー・ウォレットの位置。 |
sslwalletpasswd |
ウォレットを使用するために必要なパスワード。 |
sslauthmode |
ユーザーが使用できるSSL認証モード。使用できる値は次のとおりです。
|
この項では、C APIのファンクションおよびプロシージャを1つずつ取り上げます。その用途および構文について説明します。使用方法のヒントも示します。
この項の項目は次のとおりです。
表8-2に、C APIのファンクションおよびプロシージャをすべて示し、その用途を簡単に説明します。
表8-2 C APIのファンクションおよびプロシージャ
| ファンクションまたはプロシージャ | 説明 |
|---|---|
ber_free |
BerElement構造体のために割り当てられたメモリーの解放 |
ldap_abandon_ext ldap_abandon |
非同期操作の取消し |
ldap_add_ext ldap_add_ext_s ldap_add ldap_add_s |
ディレクトリに新規エントリを追加 |
ldap_compare_ext ldap_compare_ext_s ldap_compare ldap_compare_s |
ディレクトリ内のエントリの比較 |
ldap_count_entries |
一連の検索結果のエントリ件数をカウント |
ldap_count_values |
属性の文字列値をカウント |
ldap_count_values_len |
属性のバイナリ値をカウント |
ora_ldap_create_clientctx |
クライアントのコンテキストの作成およびハンドルを戻す。 |
ora_ldap_create_cred_hdl |
資格証明ハンドルの作成 |
ldap_delete_ext ldap_delete_ext_s ldap_delete ldap_delete_s |
ディレクトリからのエントリの削除 |
ora_ldap_destroy_clientctx |
クライアントのコンテキストの破棄 |
ora_ldap_free_cred_hdl |
資格証明ハンドルの破棄 |
ldap_dn2ufn |
ユーザーにわかりやすい名前に変換 |
ldap_err2string |
特定のエラー・コードのエラー・メッセージを取得 |
ldap_explode_dn |
識別名を構成要素に分割 |
ldap_explode_rdn |
|
ldap_first_attribute |
エントリ内の最初の属性の名前を取得 |
ldap_first_entry |
一連の検索結果から最初のエントリを取得 |
ora_ldap_get_cred_props |
資格証明ハンドルに関連付けられたプロパティの取得 |
ldap_get_dn |
エントリの識別名の取得 |
ldap_get_option |
セッション全体の様々なパラメータの現在の値にアクセス |
ldap_get_values |
属性の文字列値を取得 |
ldap_get_values_len |
属性のバイナリ値を取得 |
ldap_init ldap_open |
LDAPサーバーへの接続のオープン |
ora_ldap_init_SASL |
SASL認証の実行 |
ldap_memfree |
LDAP APIファンクション・コールによって割り当てられたメモリーの解放 |
ldap_modify_ext ldap_modify_ext_s ldap_modify ldap_modify_s |
ディレクトリ内のエントリの変更 |
ldap_msgfree |
検索結果あるいは他のLDAP操作結果のために割り当てられたメモリーの解放 |
ldap_first_attribute ldap_next_attribute |
エントリ内の次の属性の名前を取得 |
ldap_next_entry |
一連の検索結果から次のエントリを取得 |
ldap_perror (非推奨) |
エラー・メッセージの中から指定したメッセージを出力 |
ldap_rename ldap_rename_s |
ディレクトリ内のエントリの相対識別名を変更 |
ldap_result2error (非推奨) |
結果メッセージからエラー・コードを取得 |
ldap_result ldap_msgfree ldap_msgtype ldap_msgid |
非同期操作の結果のチェック |
ldap_sasl_bind ldap_sasl_bind_s |
LDAPサーバーへの一般認証 |
ldap_search_ext ldap_search_ext_s ldap_search ldap_search_s |
ディレクトリの検索 |
ldap_search_st |
タイムアウト値でのディレクトリの検索 |
ldap_get_option ldap_set_option |
パラメータの値を設定 |
ldap_set_rebind_proc |
参照を追跡する際、新しいサーバーへのバインド資格証明の取得に使用されるコールバック・ファンクションの設定。 |
ora_ldap_set_clientctx |
クライアントのコンテキスト・ハンドルへのプロパティの追加 |
ora_ldap_set_cred_props |
資格証明ハンドルへのプロパティの追加 |
ldap_simple_bind ldap_simple_bind_s ldap_sasl_bind ldap_sasl_bind_s |
LDAPサーバーへの簡易認証 |
ldap_unbind_ext ldap_unbind ldap_unbind_s |
LDAPセッションの終了 |
ldap_value_free |
属性の文字列値のために割り当てられたメモリーの解放 |
ldap_value_free ldap_value_free_len |
属性のバイナリ値のために割り当てられたメモリーの解放 |
この項では、RFC 1823に規定されているLDAP C APIで使用可能なすべてのコールを示します。
この項のコールは、LDAPサーバーとのセッションを初期化します。
ldap_init()はLDAPサーバーとのセッションを初期化しますが、接続のオープンは行いません。サーバーへの接続が必要となる操作が実行されるまで、実際にはサーバーに接続されません。そのため、初期化後に様々なオプションを設定できます。ldap_open()はセッションを初期化し、接続をオープンします。この2つは同じ目的を達成し、構文も同じですが、前者の使用をお薦めします。
構文
LDAP *ldap_init
(
const char *hostname,
int portno
)
;
パラメータ
表8-3 LDAPセッションを初期化するためのパラメータ
| パラメータ | 説明 |
|---|---|
hostname |
接続先のLDAPサーバーを実行しているホストのIPアドレスを示す、空白で区切られたホスト名またはドット表記の文字列のリストが入ります。リスト内の各ホスト名には、ポート番号を含めることもできます。ホスト名とポート番号はコロンで区切る必要があります。接続に成功するまで、ホストがリストの順序に従って試されます。 IPv6アドレスは、大カッコ(
|
portno |
接続先のTCPポート番号が入ります。デフォルトのLDAPポート |
使用方法
ldap_init()およびldap_open()の戻り値はセッション・ハンドルです。これは、そのセッションに関連する後続のコールに渡す必要がある不透明な構造体へのポインタです。これらのルーチンは、セッションが初期化できない場合にNULLを戻します。セッションが初期化できない場合、オペレーティング・システムのエラー・レポート・メカニズムをチェックし、コールに失敗した理由を確認してください。
LDAP v2サーバーに接続する場合は、後述するLDAPバインド・コールの1つをセッションで完了してから、他の操作を実行する必要があることに注意してください。LDAP v3では、他の操作を実行する前にバインド操作を完了する必要はありません。
コール元プログラムでは、次の項で説明するルーチンを呼び出して、セッションの様々な属性を設定できます。
ldap_init()で戻されたLDAPセッション・ハンドルは、LDAPセッションを表す不透明なデータ型へのポインタです。RFC 1823では、このデータ型はコール元に公開されていた構造体で、構造体のフィールドを設定すると、検索時のサイズや時間の制限などセッションの様々な側面を制御できました。
現在は、コール元でこの構造体に対する重要な変更を行わないように、この項で説明する1組のアクセッサ・ファンクションによってセッションの様々な側面を制御できます。
セッション全体に及ぶ様々なパラメータの現在の値にアクセスするにはldap_get_option()を使用します。それらのパラメータに値を設定するにはldap_set_option()を使用します。オプションの中には読取り専用で値が設定できないものもあります。ldap_set_option()をコールし、読取り専用のオプションに値を設定しようとした場合はエラーとなります。
自動参照追跡が有効な場合(デフォルト)、参照の追跡時に確立された接続は、参照を戻す原因となった最初のリクエストを送信したセッションに関するオプションを継承することに注意してください。
構文
int ldap_get_option (
LDAP *ld, int option, void *outvalue
) ; int ldap_set_option (
LDAP *ld, int option, const void *invalue
) ;
#define LDAP_OPT_ON ((void *)1) #define LDAP_OPT_OFF ((void *)0)
パラメータ
表8-4に、LDAPセッション・ハンドル・オプションのパラメータをリストし、説明します。
表8-4 LDAPセッション・ハンドル・オプションのパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。これが |
option |
アクセスまたは設定するオプションの名前です。このパラメータは、表8-5に示す定数のいずれかであることが必要です。定数の後に、その定数の16進値をカッコで囲んで記述します。 |
outvalue |
オプションの値を配置する位置のアドレスです。このパラメータの実際の型は、optionパラメータの設定値によって異なります。outvalueパラメータが |
invalue |
optionパラメータに指定する値へのポインタです。このパラメータの実際の型は、optionパラメータの設定値によって異なります。invalueパラメータに関連付けられたデータはAPI実装によってコピーされるため、APIのコール元はデータを解放するか、 |
定数
表8-5に、LDAPセッション・ハンドル・オプションの定数をリストし、説明します。
表8-5 LDAPセッション・ハンドル・オプションの定数
| 定数 | invalueパラメータの型 | outvalueパラメータの型 | 説明 |
|---|---|---|---|
LDAP_OPT_API_INFO(0x00) |
非適用。オプションは読取り専用です。 |
LDAPAPIInfo* |
実行時にLDAP API実装に関する基本的な情報を取得します。アプリケーションでは、コンパイル時および実行時の両方で使用する特定のAPI実装に関する情報を判断できることが必要です。このオプションは読取り専用で、設定はできません。 |
ORA_LDAP_OPT_RFRL_CACHE |
void* (LDAP_OPT_ON) void* (LDAP_OPT_OFF) |
int * |
このオプションは参照キャッシュが有効か無効かを示します。このオプションが |
ORA_LDAP_OPT_RFRL_CACHE_SZ |
int * |
int * |
このオプションは、参照キャッシュのサイズを指定します。サイズは、キャッシュを大きくできるバイト数の最大サイズです。デフォルトで1MBが設定されます。 |
LDAP_OPT_DEREF(0x02) |
int * |
int * |
検索時の別名の処理方法を判断します。 |
LDAP_OPT_SIZELIMIT(0x03) |
int * |
int * |
検索で戻されるエントリの最大数です。 |
LDAP_OPT_TIMELIMIT(0x04) |
int * |
int * |
検索を実行する最大秒数です。 |
LDAP_OPT_REFERRALS(0x08) |
void *(LDAP_OPT_ON) void *(LDAP_OPT_OFF) |
int * |
LDAPライブラリが、LDAPサーバーで戻された参照に自動的に従うかどうかを判断します。定数の |
LDAP_OPT_RESTART(0X09) |
void * (LDAP_OPT_ON) void * (LDAP_OPT_OFF) |
int * |
LDAPの入出力操作が未完了のまま停止したとき、自動的に再起動するかどうかを判断します。 |
LDAP_OPT_PROTOCOL_VERSION(0x11) |
int * |
int * |
このオプションは、プライマリLDAPサーバーとの通信時に使用するLDAPプロトコルのバージョンを示します。 |
LDAP_OPT_SERVER_CONTROLS(0x12) |
LDAPControl** |
LDAPControl*** |
各リクエストとともに送信されるLDAPサーバー・コントロールのデフォルト・リストです。 関連項目: 第8.2.7項「コントロールの使用」 |
LDAP_OPT_CLIENT_CONTROLS(0x13) |
LDAPControl** |
LDAPControl*** |
LDAPセッションに影響を与えるクライアント・コントロールのデフォルト・リストです。 関連項目: 第8.2.7項「コントロールの使用」 |
LDAP_OPT_API_FEATURE_INFO(0x15) |
非適用。オプションは読取り専用です。 |
LDAPAPIFeatureInfo * |
実行時にLDAP API拡張機能に関するバージョン情報を取得します。アプリケーションでは、コンパイル時および実行時の両方で使用する特定のAPI実装に関する情報を判断できることが必要です。このオプションは読取り専用です。設定はできません。 |
LDAP_OPT_HOST_NAME(0x30) |
char * |
char ** |
プライマリLDAPサーバーのホスト名(またはホストのリスト)です。構文については、 |
LDAP_OPT_ERROR_NUMBER(0x31) |
int * |
int * |
このセッションで発生した最新のLDAPエラーのコードです。 |
LDAP_OPT_ERROR_STRING(0x32) |
char * |
- |
このセッションで発生した最新のLDAPエラーで戻されたメッセージです。 |
LDAP_OPT_MATCHED_DN(0x33) |
char * |
char ** |
このセッションで発生した最新のLDAPエラーで戻された、一致する識別名です。 |
ORA_LDAP_OPT_CONNECT_TIMEOUT (0xD2) |
int * |
int * |
このオプションは、LDAP接続のタイムアウト値を秒数で設定します。接続タイムアウトは、 |
使用方法
ldap_get_option()およびldap_set_option()は、正常終了した場合は0(ゼロ)を、エラーが発生した場合は-1を戻します。いずれかのファンクションで-1が戻された場合は、オプション値LDAP_OPT_ERROR_NUMBERを設定してldap_get_option()をコールすると、特定のエラー・コードを取得できます。オプション値LDAP_OPT_ERROR_NUMBERを設定したldap_get_option()コールに失敗すると、特定のエラー・コードを取得する方法は他にないことに注意してください。
ldap_get_option()コールが正常終了した場合、API実装では、今後のLDAP APIコールの動作に影響を与えるような、LDAPセッション・ハンドルの状態または基礎となる実装の状態の変更は行わないでください。ldap_get_option()コールに失敗した場合、許容されるセッション・ハンドルの変更はLDAPエラー・コードの設定のみです(LDAP_OPT_ERROR_NUMBERオプションによって戻されます)。
ldap_set_option()コールに失敗した場合は、今後のLDAP APIコールの動作に影響を与えるような、LDAPセッション・ハンドルの状態または基礎となる実装の状態の変更は行わないでください。
この仕様を拡張して新規オプションを指定している規格準拠ドキュメントでは、0x1000から0x3FFFの間のオプション・マクロの値を使用する必要があります。プライベートな拡張や経験に基づく拡張では、0x4000から0x7FFFの間のオプション・マクロの値を使用する必要があります。このドキュメントで定義されていない0x1000未満および0x7FFFを超える値は、すべて予約されており使用することはできません。拡張機能の実装を支援するには、次のマクロをC LDAP API実装で定義する必要があります。
#define LDAP_OPT_PRIVATE_EXTENSION_BASE 0x4000 /* to 0x7FFF inclusive */
この項のファンクションは、参照の追跡時、新しいサーバーのバインド資格証明の取得に使用されます。
ldap_set_rebind_proc()ファンクションは、LDAP参照の追跡時に新しいサーバーに接続するためのバインド資格証明をライブラリで取得するために使用するコールバック・ファンクションの設定に使用されます。ライブラリでは、ldap_set_option()を使用してLDAP_OPT_REFERRALSが設定されている場合にのみコールバック・ファンクションを使用します。ldap_set_rebind_proc()がコールされていない場合、LDAP参照の追跡時、ライブラリでは新しいサーバーへの接続に匿名バインドを使用します。
構文
void ldap_set_rebind_proc
(
LDAP *ld,
int(*rebindproc) (LDAP *ld,
char **dnp,
char **passwdp,
int *authmethodp,
int freeit)
)
reprocbind()ファンクションは、新しいサーバーのバインド資格証明を取得するためにコールされるファンクションです。
表8-6 コールバック・ファンクションのパラメータおよびコールバック・ファンクションを設定するためのパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
rebindproc |
LDAP参照の追跡時に新しいサーバーへ接続するためのバインド資格証明の取得に使用されるコールバック・ファンクション |
ld |
新しいサーバーへのセッション・ハンドル |
dnp |
新しいサーバーに対するバインド識別名のポインタ |
|
passwdp |
新しいサーバーに対するバインド・パスワードのポインタ |
authmethodp |
新しいサーバーに対する認証方法のポインタ |
freeit |
|
freeitパラメータの値が0の場合、rebindprocは必ずバインド識別名ポインタ、バインド・パスワード・ポインタおよびバインド認証方法ポインタを戻します。freeitパラメータの値が1の場合、rebindprocは前回のコールで割り当てられたすべてのメモリーを解放します。LDAPライブラリはこのファンクションを2回コールします。1回目で資格証明をバインドし、2回目でメモリーを解放します。
この項のファンクションを使用して、LDAPディレクトリ・サーバーに対するLDAPクライアントの認証を行います。
ldap_sasl_bind()ファンクションおよびldap_sasl_bind_s()ファンクションは、Simple Authentication Security Layerを使用したLDAPでの通常および拡張認証に使用できます。いずれのルーチンも、メソッドを識別するオブジェクト識別子(OID)のドット区切りの文字列表記として使用するメソッドとして、また資格証明を保持するstruct bervalとして、バインドする識別名を使用します。簡易認証のリクエストには特別な定数値LDAP_SASL_SIMPLE (NULL)を渡すか、簡略化ルーチンldap_simple_bind()またはldap_simple_bind_s()が使用できます。
構文
int ldap_sasl_bind (
LDAP *ld, const char *dn, const char *mechanism, const struct berval *cred, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );
int ldap_sasl_bind_s(
LDAP *ld, const char *dn, const char *mechanism, const struct berval *cred, LDAPControl **serverctrls, LDAPControl **clientctrls,
);
int ldap_simple_bind(
LDAP *ld, const char *dn, const char *passwd
);
int ldap_simple_bind_s(
LDAP *ld, const char *dn, const char *passwd
);
次のルーチンの使用は非推奨です。詳細は、RFC 1823を参照してください。
int ldap_bind( LDAP *ld, const char *dn, const char *cred, int method );
int ldap_bind_s( LDAP *ld, const char *dn, const char *cred, int method );
int ldap_kerberos_bind( LDAP *ld, const char *dn );
int ldap_kerberos_bind_s( LDAP *ld, const char *dn );
パラメータ
表8-7に、ディレクトリに対する認証のパラメータをリストし、説明します。
表8-7 ディレクトリに対する認証のパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
dn |
バインドするエントリの名前です。 |
mechanism |
|
cred |
認証に使用する資格証明です。このパラメータを使用すると、任意の資格証明を渡すことができます。資格証明の書式と内容は、mechanismパラメータの設定内容によって異なります。 |
passwd |
|
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
使用方法
非推奨のルーチンに関するその他のパラメータは説明していません。詳細は、RFC 1823を参照してください。
ldap_sasl_bind()ファンクションは、非同期のバインド操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_sasl_bind()によってリクエストのメッセージIDが*msgidpに格納されます。続けてldap_result()をコールすると、バインドの結果を取得できます。
ldap_simple_bind()ファンクションは、単純な非同期のバインド操作を開始し、開始した操作のメッセージIDを戻します。続けてldap_result()をコールすると、バインドの結果を取得できます。エラーが発生した場合、ldap_simple_bind()は-1を戻し、LDAP構造体に適切なセッション・エラー・パラメータを設定します。
同期型のldap_sasl_bind_s()ファンクションおよびldap_simple_bind_s()ファンクションはいずれも、操作が正常終了した場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。
LDAP v2サーバーに接続している場合は、バインド・コールが正常に完了するまで、接続に対する他の操作ができないことに注意してください。
続けてバインド・コールを使用すると、同じ接続に対して再認証を行うことができます。また、ldap_sasl_bind()またはldap_sasl_bind_s()を連続してコールすると、複数ステップのSASL処理を実行できます。
この項の項目は次のとおりです。
ora_ldap_init_SASL()ファンクションを使用すると、SASL認証を実行できます。このファンクションは、入力引数の1つに指定したメカニズムに基づいて認証を実行します。
このファンクションは、様々な標準SASLメカニズムのクライアントとディレクトリ・サーバー間のSASLハンドシェイクをカプセル化するため、ディレクトリ・サーバーへのSASLベース接続の確立でのコーディングの負荷が軽減されます。
構文
int ora_ldap_init_SASL
(
OraLdapClientCtx * clientCtx,
LDAP *ld,
char * dn,
char * mechanism,
OraLdapHandle cred,
LDAPControl **serverctrls,
LDAPControl **clientctrls
);
パラメータ
表8-8 ora_ldap_init_sasl()に渡されるパラメータ
| パラメータ | 説明 |
|---|---|
clientCtx |
C APIのクライアント・コンテキストです。これは、 |
ld |
LDAPセッション・ハンドルです。 |
dn |
認証されるユーザーDNです。 |
mechanism |
SASLメカニズムです。 |
cred |
SASL認証に必要な資格証明です。 |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
credパラメータは、ユーザー用のSASL証明書ハンドルです。このハンドルは、ora_ldap_create_cred_hdl()、ora_ldap_set_cred_props()およびora_ldap_free_cred_hdl()ファンクションを使用して管理できます。
サポートされるSASLメカニズムは次のとおりです。
DIGEST-MD5
Oracle Internet Directory SASL APIは、DIGEST-MD5の認証のみのモードをサポートします。データ・プライバシおよびデータ整合性に対応したその他2つの認証モードは、まだサポートされていません。
Oracle Internet Directoryに対して認証する際は、ユーザーの識別名はサーバーに送信される前に正規化される必要があります。これは、DNをSASL APIに渡す前にora_ldap_normalize_dn()ファンクションを使用してSASL APIの外部で行うか、またはora_ldap_set_cred_handle()を使用して、SASL資格証明ハンドルにORA_LDAP_CRED_SASL_NORM_AUTHDNオプションを設定してSASL APIで行うことができます。
EXTERNAL
Oracle Internet DirectoryでのSASL APIおよびSASLの実装には、外部認証メカニズムの1つとしてSSL認証を使用します。
このメカニズムを使用するには、ora_ldap_init_SSL()ファンクションを使用して、ディレクトリ・サーバーに対してSSL接続(相互認証モード)を確立する必要があります。これにより、ora_ldap_init_SASL()ファンクションは、mechanism引数にEXTERNALを指定して起動できます。ディレクトリ・サーバーは、SSL接続のユーザー資格証明に基づいてユーザーを認証します。
次のファンクションを使用して、SASL資格証明ハンドルを作成および管理します。ora_ldap_create_cred_hdlファンクションは、SASL認証に使用するメカニズムのタイプをベースにした、特定のタイプのSASL資格証明ハンドルの作成に使用します。ora_ldap_set_cred_props()ファンクションは、SASL認証に必要なハンドルに関連する資格証明の追加に使用できます。ora_ldap_get_cred_props()ファンクションは、資格証明ハンドルに格納されたプロパティの取得に、ora_ldap_free_cred_hdl ()ファンクションは、使用後のハンドルの破棄に使用できます。
構文
OraLdapHandle ora_ldap_create_cred_hdl
(
OraLdapClientCtx * clientCtx,
int credType
);
OraLdapHandle ora_ldap_set_cred_props
(
OraLdapClientCtx * clientCtx,
OraLdapHandle cred,
int String[],
void * inProperty
);
OraLdapHandle ora_ldap_get_cred_props
(
OraLdapClientCtx * clientCtx,
OraLdapHandle cred,
int String[],
void * outProperty
);
OraLdapHandle ora_ldap_free_cred_hdl
(
OraLdapClientCtx * clientCtx,
OraLdapHandle cred
);
パラメータ
表8-9 SASL資格証明の管理パラメータ
| パラメータ | 説明 |
|---|---|
clientCtx |
C APIのクライアント・コンテキストです。これは、 |
credType |
SASLメカニズム固有の資格証明ハンドルのタイプです。 |
cred |
SASL認証のための固有のSASLメカニズムに必要なSASL資格証明を含む資格証明ハンドルです。 |
String[] |
資格証明ハンドルに追加する必要がある資格証明のタイプです。 |
inProperty |
資格証明ハンドルに格納されるSASL資格証明の1つです。 |
outProperty |
資格証明ハンドルに格納されたSASL資格証明の1つです。 |
コントロールを使用すると、LDAP v3操作を拡張できます。コントロールは、サーバーに送信したり、LDAPメッセージとともにクライアントに戻すことができます。このようなコントロールは、サーバー・コントロールと呼ばれます。
LDAP APIは、クライアント・コントロールを使用してクライアント側の拡張メカニズムもサポートします。このコントロールは、LDAP APIの動作にのみ影響し、サーバーに送信されることはありません。両方のタイプのコントロールを表現するため、次の共通のデータ構造が使用されます。
typedef struct ldapcontrol
{
char *ldctl_oid; struct berval ldctl_value; char ldctl_iscritical;
} LDAPControl;
表8-10に、ldapcontrol構造体のフィールドを示します。
表8-10 ldapcontrol構造体のフィールド
| フィールド | 説明 |
|---|---|
ldctl_oid |
文字列で表現されたコントロール・タイプです。 |
ldctl_value |
コントロールに対応付けられたデータ(ある場合)です。長さ0(ゼロ)の値を指定するには、 |
ldctl_iscritical |
コントロールが重要かどうかを示します。このフィールドが0(ゼロ)以外の場合は、サーバーまたはクライアント(あるいはその両方)でコントロールが認識されると、その操作のみが実行されます。LDAPのバインド解除操作および中止操作では、サーバーからのレスポンスはありません。これら2つの操作でサーバー・コントロールを使用するときは、クライアントでコントロールを重要(critical)とマークしないでください。 |
LDAP APIの一部のコールでは、ldapcontrol構造体、またはldapcontrol構造体のNULL終了配列を割り当てます。次のルーチンを使用すると、単一コントロールまたはコントロールの配列を解放できます。
void ldap_control_free( LDAPControl *ctrl ); void ldap_controls_free( LDAPControl **ctrls );
ctrlパラメータまたはctrlsパラメータがNULLの場合は、このファンクションをコールしても何も実行されません。
セッション全体に影響を与えるコントロールのセットは、ldap_set_option()ファンクション(第8.2.3.1項「ldap_get_optionおよびldap_set_option」を参照)を使用して設定できます。コントロールのリストをldap_search_ext()などの一部のLDAP APIコールに直接渡すこともできます。この場合、ldap_set_option()を使用して設定したセッションのコントロール・セットは無視されます。コントロール・リストはldapcontrol構造体へのポインタのNULL終了配列で表されます。
サーバー・コントロールは、LDAP v3プロトコル拡張ドキュメントで定義されています。たとえば、コントロールは、サーバー側での検索結果のソートをサポートするために計画されています。
この章では、1つのクライアント・コントロールが定義されています(後の項で説明)。
クライアント・コントロールの参照プロセス 第8.2.3項「LDAPセッション・ハンドル・オプション」で説明したように、アプリケーションでは、LDAP_OPT_REFERRALSオプションを設定したldap_set_option()ファンクションを使用して、セッション全体で自動参照追跡を有効にしたり無効にすることができます。これは、リクエストごとに自動参照追跡を制御する場合にも役立ちます。この機能を提供するため、1.2.840.113556.1.4.616のオブジェクト識別子(OID)を持つクライアント・コントロールがあります。
/* OID for referrals client control */ #define LDAP_CONTROL_REFERRALS "1.2.840.113556.1.4.616" /* Flags for referrals client control value */ #define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020U #define LDAP_CHASE_EXTERNAL_REFERRALS 0x00000040U
参照先クライアント・コントロールを作成するには、LDAPControl構造体のldctl_oidフィールドをLDAP_CONTROL_REFERRALS ("1.2.840.113556.1.4.616")に設定し、ldctl_valueフィールドを一連のフラグが格納された4オクテット値に設定する必要があります。ldctl_value.bv_lenフィールドは常に4に設定する必要があります。ldctl_value.bv_valフィールドは、4オクテットの整数フラグ値を指し示す必要があります。このフラグ値を0(ゼロ)に設定すると、自動参照追跡とLDAP v3リファレンスの両方を無効にできます。これ以外に、このフラグ値を、値LDAP_CHASE_SUBORDINATE_REFERRALS (0x00000020U)に設定して、LDAP v3の検索継続リファレンスのみがAPI実装によって自動的に追跡されることを示すか、値LDAP_CHASE_EXTERNAL_REFERRALS (0x00000040U)に設定して、LDAP v3参照のみが自動的に追跡されることを示すか、2つのフラグ値の論理和(0x00000060U)に設定して、参照先と参照元の両方が自動的に追跡されることを示すことができます。
|
関連項目: オブジェクト識別子の詳細は、『Oracle Fusion Middleware Oracle Internet Directory管理者ガイド』のディレクトリ・スキーマの管理の項を参照してください。 |
この項のファンクションを使用して、ディレクトリからバインドを解除し、オープンしている接続をクローズして、セッション・ハンドルを解放します。
ldap_unbind_ext()、ldap_unbind()およびldap_unbind_s()は、サーバーにバインド解除リクエストを送信し、LDAPセッション・ハンドルに関連するオープンな接続をすべてクローズし、セッション・ハンドルに関連するリソースをすべて解放した後に値が戻されるという点で、すべて同期的に動作します。ただし、LDAPバインド解除操作にはサーバー・レスポンスがないことに注意してください。3つのバインド解除ファンクションはすべて、LDAP_SUCCESSを戻します(LDAPサーバーにリクエストが送信できない場合は別のLDAPエラー・コードを戻します)。バインド解除ファンクションを1つコールすると、セッション・ハンドルldは無効となり、ldを使用した別のLDAP APIのコールはできなくなります。
ldap_unbind()ファンクションとldap_unbind_s()ファンクションは同じように動作します。ldap_unbind_ext()ファンクションを使用すると、サーバー・コントロールとクライアント・コントロールを明示的に含めることができますが、バインド解除リクエストに対するサーバーからのレスポンスがないため、バインド解除リクエストで送信されたサーバー・コントロールに対するレスポンスを受信する方法はないことに注意してください。
構文
int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls, LDAPControl **clientctrls ); int ldap_unbind( LDAP *ld ); int ldap_unbind_s( LDAP *ld );
パラメータ
この項のファンクションを使用してLDAPディレクトリを検索し、一致した各エントリについてリクエストされた属性セットを戻します。
ldap_search_ext()ファンクションは、非同期の検索操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_search_ext()によってリクエストのメッセージIDが*msgidpに格納されます。続けてldap_result()をコールすると、検索の結果を取得できます。検索結果は、後述する結果解析ルーチンを使用して解析できます。
ldap_search_ext()ファンクションと同様に、ldap_search()ファンクションは非同期の検索操作を開始し、開始した操作のメッセージIDを戻します。ldap_search_ext()の場合は、続けてldap_result()をコールすると、バインドの結果を取得できます。エラーが発生した場合、ldap_search()は-1を戻し、LDAP構造体に適切なセッション・エラー・パラメータを設定します。
同期型のldap_search_ext_s()、ldap_search_s()およびldap_search_st()の各ファンクションはいずれも、操作が正常終了した場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。検索によって戻されるエントリがある場合、resパラメータの中に収められます。このパラメータはコール元に対しては不透明です。エントリ、属性、値などは、この項で説明する解析ルーチンをコールすることで抽出できます。resに格納された結果が不要になった場合は、後述するldap_msgfree()をコールして解放する必要があります。
ldap_search_ext()ファンクションとldap_search_ext_s()ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートし、各検索操作に対して様々なサイズと制限時間を簡単に指定できます。ldap_search_st()ファンクションは、検索のローカル・タイムアウトを指定するパラメータがあること以外は、ldap_search_s()ファンクションと同じです。ローカル検索タイムアウトは、検索完了までAPI実装が待機する時間を制限するために使用します。ローカル検索タイムアウトを経過すると、API実装は中止操作を送信して検索操作を停止します。
構文
int ldap_search_ext (
LDAP *ld, const char *base, int scope, const char *filter, char **attrs, int attrsonly, LDAPControl **serverctrls, LDAPControl **clientctrls, struct timeval *timeout, int sizelimit, int *msgidp
); int ldap_search_ext_s (
LDAP *ld, const char *base, int scope, const char *filter, char **attrs, int attrsonly, LDAPControl **serverctrls, LDAPControl **clientctrls, struct timeval *timeout, int sizelimit, LDAPMessage **res
); int ldap_search (
LDAP *ld, const char *base, int scope, const char *filter, char **attrs, int attrsonly
); int ldap_search_s (
LDAP *ld, const char *base, int scope, const char *filter, char **attrs, int attrsonly, LDAPMessage **res
); int ldap_search_st );
LDAP *ld, const char *base, int scope, const char *filter, char **attrs, int attrsonly, struct timeval *timeout, LDAPMessage **res
);
パラメータ
表8-12に、検索操作のパラメータをリストし、説明します。
表8-12 検索操作のパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
base |
検索の開始点となるエントリの識別名です。 |
scope |
|
filter |
検索フィルタを表す文字列です。この値を |
attrs |
一致した各エントリのどの属性を戻すかを指定する文字列の |
attrsonly |
属性の型と値の両方を戻す場合には0(ゼロ)、属性の型のみを要求する場合には0(ゼロ)以外を指定する必要があるブール値です。 |
timeout |
|
sizelimit |
|
res |
同期コールを行うとき、コールの終了時に検索結果が入る結果パラメータです。戻される結果がない場合、 |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
LDAPでは、読取り操作を直接サポートしていません。かわりに、この操作は、ベースを読み込むエントリの識別名に設定し、有効範囲をLDAP_SCOPE_BASEに設定し、さらにフィルタを"(objectclass=*)"またはNULLに設定した検索によってエミュレーションを行います。attrsパラメータには、戻される属性のリストが格納されます。
LDAPでは、リスト操作を直接サポートしていません。かわりに、この操作は、ベースをリスト表示するエントリの識別名に設定し、有効範囲をLDAP_SCOPE_ONELEVELに設定し、さらにフィルタを"(objectclass=*)"またはNULLに設定した検索によってエミュレーションを行います。パラメータattrsには、子エントリごとに戻される属性のリストが格納されます。
これらのルーチンを使用して、属性値のアサーションをLDAPエントリと照合して比較します。
ldap_compare_ext()ファンクションは、非同期の比較操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_compare_ext()によってリクエストのメッセージIDが*msgidpに格納されます。続けてldap_result()をコールすると、比較の結果を取得できます。
ldap_compare_ext()ファンクションと同様に、ldap_compare()ファンクションは非同期の比較操作を開始し、開始した操作のメッセージIDを戻します。ldap_compare_ext()の場合は、続けてldap_result()をコールすると、バインドの結果を取得できます。エラーが発生した場合、ldap_compare()は-1を戻し、LDAP構造体に適切なセッション・エラー・パラメータを設定します。
同期型のldap_compare_ext_s()ファンクションおよびldap_compare_s()ファンクションはいずれも、操作が正常終了した場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。
ldap_compare_ext()ファンクションとldap_compare_ext_s()ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートします。
構文
int ldap_compare_ext (
LDAP *ld, const char *dn, const char *attr, const struct berval *bvalue, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp
); int ldap_compare_ext_s (
LDAP *ld, const char *dn, const char *attr, const struct berval *bvalue, LDAPControl **serverctrls, LDAPControl **clientctrls
); int ldap_compare (
LDAP *ld, const char *dn, const char *attr, const char *value
); int ldap_compare_s (
LDAP *ld, const char *dn, const char *attr, const char *value
);
パラメータ
表8-13に、比較操作のパラメータをリストし、説明します。
表8-13 比較操作のパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
dn |
比較の対象となるエントリの名前です。 |
attr |
比較の対象となる属性です。 |
bvalue |
指定のエントリで検索された属性と照合して比較される属性値です。このパラメータは拡張ルーチンで使用され、 |
value |
比較の対象となる文字列の属性値で、 |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
これらのルーチンを使用して、既存のLDAPエントリを変更します。
ldap_modify_ext()ファンクションは、非同期の変更操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_modify_ext()によってリクエストのメッセージIDが*msgidpに格納されます。続けてldap_result()をコールすると、変更の結果を取得できます。
ldap_modify_ext()ファンクションと同様に、ldap_modify()ファンクションは非同期の変更操作を開始し、開始した操作のメッセージIDを戻します。ldap_modify_ext()の場合は、続けてldap_result()をコールすると、変更の結果を取得できます。エラーが発生した場合、ldap_modify()は-1を戻し、LDAP構造体に適切なセッション・エラー・パラメータを設定します。
同期型のldap_modify_ext_s()ファンクションおよびldap_modify_s()ファンクションはいずれも、操作が正常終了した場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。
ldap_modify_ext()ファンクションとldap_modify_ext_s()ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートします。
構文
typedef struct ldapmod
{
int mod_op;
char *mod_type;
union mod_vals_u
{
char **modv_strvals; struct berval **modv_bvals; } mod_vals;
} LDAPMod;
#define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvals
int ldap_modify_ext (
LDAP *ld, const char *dn, LDAPMod **mods, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp
); int ldap_modify_ext_s (
LDAP *ld, const char *dn, LDAPMod **mods, LDAPControl **serverctrls, LDAPControl **clientctrls
); int ldap_modify (
LDAP *ld, const char *dn, LDAPMod **mods );
int ldap_modify_s (
LDAP *ld, const char *dn, LDAPMod **mods
);
パラメータ
表8-14に、変更操作のパラメータをリストし、説明します。
表8-14 変更操作のパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
dn |
変更するエントリの名前です。 |
mods |
エントリに対する変更の |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
表8-15に、LDAPMod構造体のフィールドを示します。
表8-15 LDAPMod構造体のフィールド
| フィールド | 説明 |
|---|---|
mod_op |
実行する変更操作です。 |
mod_type |
変更する属性の型です。 |
mod_vals |
追加、削除または置換する値(存在する場合)。 |
使用方法
LDAP_MOD_ADD変更の場合は、指定の値がエントリに追加され、必要に応じて属性が作成されます。
LDAP_MOD_DELETE変更の場合は、指定の値がエントリから削除され、値がない場合は属性が削除されます。すべての属性を削除する場合は、mod_valsフィールドをNULLに設定できます。
LDAP_MOD_REPLACE変更の場合、属性は変更後にリストされた値を保持します。値は必要に応じて作成され、mod_valsフィールドがNULLの場合は削除されます。すべての変更はリストされた順序で実行されます。
これらのルーチンを使用して、エントリ名を変更します。
ldap_rename()ファンクションは、非同期の識別名変更操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_rename()によってリクエストのメッセージIDが*msgidpに格納されます。続けてldap_result()をコールすると、名前の変更の結果を取得できます。
同期型のldap_rename_s()ファンクションは、操作が正常終了した場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。
ldap_rename()ファンクションとldap_rename_s()ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートします。
構文
int ldap_rename (
LDAP *ld, const char *dn, const char *newrdn, const char *newparent, int deleteoldrdn, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp
); int ldap_rename_s (
LDAP *ld, const char *dn, const char *newrdn, const char *newparent, int deleteoldrdn, LDAPControl **serverctrls, LDAPControl **clientctrls
);
次のルーチンの使用は非推奨です。詳細は、RFC 1823を参照してください。
int ldap_modrdn (
LDAP *ld, const char *dn, const char *newrdn
); int ldap_modrdn_s (
LDAP *ld, const char *dn, const char *newrdn
); int ldap_modrdn2 (
LDAP *ld, const char *dn, const char *newrdn, int deleteoldrdn
); int ldap_modrdn2_s (
LDAP *ld, const char *dn, const char *newrdn, int deleteoldrdn
);
パラメータ
表8-16に、名前の変更操作のパラメータをリストし、説明します。
表8-16 名前の変更操作のパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
dn |
識別名を変更するエントリの名前です。 |
newrdn |
エントリに指定する新規の相対識別名です。 |
newparent |
新規の親または上位エントリ。このパラメータが |
deleteoldrdn |
newrdnが古い相対識別名と異なる場合、このパラメータは名前の変更ルーチンでのみ使用されます。このパラメータはブール値で、0(ゼロ)以外の場合は古い相対識別名が削除されたことを示し、0(ゼロ)の場合は、エントリの識別されない値として古い相対識別名が保持されていることを示します。 |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
これらのファンクションを使用して、LDAPディレクトリにエントリを追加します。
ldap_add_ext()ファンクションは、非同期の追加操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_add_ext()によってリクエストのメッセージIDが*msgidpに格納されます。続けてldap_result()をコールすると、追加の結果を取得できます。
ldap_add_ext()ファンクションと同様に、ldap_add()ファンクションは非同期の追加操作を開始し、開始した操作のメッセージIDを戻します。ldap_add_ext()の場合は、続けてldap_result()をコールすると、追加の結果を取得できます。エラーが発生した場合、ldap_add()は-1を戻し、LDAP構造体に適切なセッション・エラー・パラメータを設定します。
同期型のldap_add_ext_s()ファンクションおよびldap_add_s()ファンクションはいずれも、操作が正常終了した場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。
ldap_add_ext()ファンクションとldap_add_ext_s()ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートします。
構文
int ldap_add_ext (
LDAP *ld, const char *dn, LDAPMod **attrs, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp
); int ldap_add_ext_s (
LDAP *ld, const char *dn, LDAPMod **attrs, LDAPControl **serverctrls, LDAPControl **clientctrls
); int ldap_add (
LDAP *ld, const char *dn, LDAPMod **attrs
); int ldap_add_s (
LDAP *ld, const char *dn, LDAPMod **attrs
);
パラメータ
表8-17に、追加操作のパラメータをリストし、説明します。
表8-17 追加操作のパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
dn |
追加するエントリの名前です。 |
attrs |
|
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
使用方法
追加操作を正常に行うためには、追加するエントリの親がすでに存在しているか、親が空(つまり、ルートの識別名と同じ)であることが必要です。
これらのファンクションを使用して、LDAPディレクトリからリーフ・エントリを削除します。
ldap_delete_ext()ファンクションは、非同期の削除操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_delete_ext()によってリクエストのメッセージIDが*msgidpに格納されます。続けてldap_result()をコールすると、削除の結果を取得できます。
ldap_delete_ext()ファンクションと同様に、ldap_delete()ファンクションは非同期の削除操作を開始し、開始した操作のメッセージIDを戻します。ldap_delete_ext()の場合は、続けてldap_result()をコールすると、削除の結果を取得できます。エラーが発生した場合、ldap_delete()は-1を戻し、LDAP構造体に適切なセッション・エラー・パラメータを設定します。
同期型のldap_delete_ext_s()ファンクションおよびldap_delete_s()ファンクションはいずれも、操作が正常終了した場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。
ldap_delete_ext()ファンクションとldap_delete_ext_s()ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートします。
構文
int ldap_delete_ext (
LDAP *ld, const char *dn, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp
); int ldap_delete_ext_s ( LDAP *ld,
const char *dn, LDAPControl **serverctrls, LDAPControl **clientctrls
);
int ldap_delete
(
LDAP *ld, const char *dn
); int ldap_delete_s (
LDAP *ld, const char *dn
);
パラメータ
表8-18に、削除操作のパラメータをリストし、説明します。
表8-18 削除操作のパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
dn |
削除するエントリの名前です。 |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
使用方法
削除するエントリは、リーフ・エントリ(つまり、子エントリがないエントリ)であることが必要です。1回の操作でサブツリー全体を削除する操作は、LDAPではサポートされていません。
これらのルーチンを使用すると、拡張LDAP操作をサーバーに渡し、一般的なプロトコル拡張メカニズムを提供できます。
ldap_extended_operation()ファンクションは、非同期の拡張操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを戻します。正常終了した場合、ldap_extended_operation()はリクエストのメッセージIDを*msgidpに配置します。ldap_result()を続けてコールすると拡張操作の結果を取得できます。この結果をldap_parse_extended_result()に渡すとオブジェクト識別子(OID)とレスポンスに格納されたデータを取得できます。
同期型のldap_extended_operation_s()ファンクションは、操作が正常終了した場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。retoidパラメータとretdataパラメータには、結果に含まれているOIDとデータが入力されます。戻されるOIDまたはデータがない場合、これらのパラメータはNULLに設定されます。
ldap_extended_operation()ファンクションとldap_extended_operation_s()ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートします。
構文
int ldap_extended_operation (
LDAP *ld, const char *requestoid, const struct berval *requestdata, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp
); int ldap_extended_operation_s (
LDAP *ld, const char *requestoid, const struct berval *requestdata, LDAPControl **serverctrls, LDAPControl **clientctrls, char **retoidp, struct berval **retdatap
);
パラメータ
表8-19に、拡張操作のパラメータをリストし、説明します。
表8-19 拡張操作のパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
requestoid |
リクエストを指定する、ドット表記のOIDテキスト文字列です。 |
requestdata |
操作に必要な任意のデータです( |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
retoidp |
サーバーによって戻されたドット区切りの割当て済OIDテキスト文字列に設定された、文字列へのポインタです。この文字列は |
retdatap |
サーバーによって戻されたデータの割当て済コピーに設定される |
この項のファンクションを使用して、進行中の操作を中止します。
ldap_abandon_ext()ファンクションは、msgidパラメータのメッセージIDを使用して操作を中止し、中止操作が正常終了した場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを戻します。
ldap_abandon()は、クライアント・コントロールまたはサーバー・コントロールを受け入れないこと以外はldap_abandon_ext()と同じで、中止操作が正常終了した場合は0(ゼロ)を、失敗した場合は-1を戻します。
ldap_abandon()コールまたはldap_abandon_ext()コールが正常終了した後、指定のメッセージIDを持つ結果は、引き続きldap_result()をコールしても戻されません。LDAP中止操作に対するサーバーのレスポンスはありません。
構文
int ldap_abandon_ext (
LDAP *ld, int msgid, LDAPControl **serverctrls, LDAPControl **clientctrls
); int ldap_abandon (
LDAP *ld, int msgid
);
パラメータ
表8-20に、操作の中止のパラメータをリストし、説明します。
表8-20 操作の中止のパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
msgid |
中止するリクエストのメッセージIDです。 |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
この項のファンクションを使用して、非同期で開始した操作の結果を戻します。これらのファンクションは、メッセージを型およびIDで識別します。
ldap_result()を使用して、非同期に開始した前回の操作の結果を取得します。コールの方法によって、ldap_result()が実際に戻す値が結果メッセージのリストの場合とチェーンの場合があることに注意してください。ldap_result()ファンクションは単一リクエストに対するメッセージのみを返します。検索以外のすべてのLDAP操作で想定されている結果メッセージは1つのみです。つまり、結果チェーンが複数のメッセージを格納できるのは、検索操作のからの結果が戻された場合のみです。
コール元に戻された結果セットは、そのセットを生成したLDAPリクエストとの関連をコール元で表示する方法はありません。したがって、ldap_result()または同期検索ルーチンをコールして戻された結果セットは、後続のLDAP APIコールの影響を受けることはありません(結果セットを解放するldap_msgfree()は除きます)。
ldap_msgfree()は、ldap_result()または同期検索ルーチンをコールして前に取得した結果メッセージ(結果セット全体の場合もあります)を解放します。
ldap_msgtype()はLDAPメッセージのタイプを戻します。ldap_msgid()はLDAPメッセージのメッセージIDを戻します。
構文
int ldap_result (
LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **res
); int ldap_msgfree( LDAPMessage *res ); int ldap_msgtype( LDAPMessage *res ); int ldap_msgid( LDAPMessage *res );
パラメータ
表8-21に、結果の取得とLDAPメッセージの確認のためのパラメータをリストし、説明します。
表8-21 結果の取得とLDAPメッセージの確認のためのパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
msgid |
結果が戻される操作のメッセージID、定数 |
all |
1回の |
timeout |
結果の戻りに対する待機時間を指定するタイムアウトです。 |
res |
|
使用方法
正常終了すると、ldap_result()は戻された最初の結果のタイプをresパラメータに戻します。次のいずれかの定数が戻されます。
LDAP_RES_BIND (0x61)
LDAP_RES_SEARCH_ENTRY (0x64)
LDAP_RES_SEARCH_REFERENCE (0x73): LDAP v3の新規定数
LDAP_RES_SEARCH_RESULT (0x65)
LDAP_RES_MODIFY (0x67)
LDAP_RES_ADD (0x69)
LDAP_RES_DELETE (0x6B)
LDAP_RES_MODDN (0x6D)
LDAP_RES_COMPARE (0x6F)
LDAP_RES_EXTENDED (0x78) -- LDAP v3の新規定数
ldap_result()は、タイムアウトを超過した場合は0(ゼロ)を、エラーが発生した場合は-1を戻します。エラーの発生に応じて、LDAPセッション・ハンドルのエラー・パラメータが設定されます。
ldap_msgfree()は、resパラメータが指し示す結果セット内の各メッセージを解放し、最後のメッセージのタイプを戻します。resがNULLの場合は何も処理されず、値0(ゼロ)が戻されます。
ldap_msgtype()は、パラメータとして渡されるLDAPメッセージのタイプを戻します。タイプは、前述のタイプのいずれかか、エラーの場合は-1です。
ldap_msgid()は、パラメータとして渡されたLDAPメッセージに対応付けられているメッセージIDを戻します。エラーの場合は-1を戻します。
この項のファンクションを使用して、結果から情報を抽出し、他のLDAP APIルーチンによって戻されたエラーを処理します。
ldap_parse_sasl_bind_result()およびldap_parse_extended_result()は、通常、ldap_parse_result()とともに使用して、SASLバインド操作および拡張操作の結果情報をそれぞれ取得することに注意してください。
ldap_parse_result()、ldap_parse_sasl_bind_result()およびldap_parse_extended_result()の各ファンクションは、解析する結果メッセージの検索時に、メッセージ・タイプのLDAP_RES_SEARCH_ENTRYおよびLDAP_RES_SEARCH_REFERENCEをスキップします。これらのファンクションは、結果が正常に解析された場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを戻します。サーバーで実行された操作の結果を示すLDAPエラー・コードは、ldap_parse_result()のerrcodepパラメータに格納されることに注意してください。複数の結果メッセージが含まれた結果セットがこれらのルーチンに渡されている場合、これらのルーチンは、常にその結果セット内の最初の結果から操作を開始します。
ldap_err2string()は、ldap_parse_result()、ldap_parse_sasl_bind_result()、ldap_parse_extended_result()またはAPI操作の同期コールの1つから戻された数値のLDAPエラー・コードを、エラーを説明するゼロ終了文字列メッセージに変換するために使用されます。このファンクションは、静的データへのポインタを戻します。
構文
int ldap_parse_result (
LDAP *ld, LDAPMessage *res, int *errcodep, char **matcheddnp, char **errmsgp, char ***referralsp, LDAPControl ***serverctrlsp, int freeit
);
int ldap_parse_sasl_bind_result (
LDAP *ld, LDAPMessage *res, struct berval **servercredp, int freeit
);
int ldap_parse_extended_result (
LDAP *ld, LDAPMessage *res, char **retoidp, struct berval **retdatap, int freeit
); #define LDAP_NOTICE_OF_DISCONNECTION "1.3.6.1.4.1.1466.20036" char *ldap_err2string( int err );
次のルーチンは非推奨です。詳細は、RFC 1823を参照してください。
int ldap_result2error (
LDAP *ld, LDAPMessage *res, int freeit
); void ldap_perror( LDAP *ld, const char *msg );
パラメータ
表8-22に、エラーの処理と結果の解析を行うためのパラメータをリストし、説明します。
表8-22 エラーの処理と結果の解析を行うためのパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
res |
|
errcodep |
この結果パラメータには、 |
matcheddnp |
|
errmsgp |
この結果パラメータには、 |
referralsp |
この結果パラメータには、 |
serverctrlsp |
この結果パラメータには、 |
freeit |
|
servercredp |
SASLバインド結果に関するこの結果パラメータには、相互認証が指定されている場合、サーバーから戻された資格証明が入力されます。割り当てられた |
retoidp |
拡張操作の結果に関するこの結果パラメータには、拡張操作のレスポンス名のドット区切りのOIDテキスト表現が入力されます。この文字列は |
retdatap |
拡張操作の結果に関するこの結果パラメータには、拡張操作のレスポンス・データが含まれる |
err |
|
使用方法
非推奨のルーチンに固有のパラメータについては、RFC 1823を参照してください。
この項のルーチンを使用して、ldap_result()で戻された結果セット内のメッセージ・リストを参照します。
検索操作の結果セットには、参照メッセージ、エントリ・メッセージおよび結果メッセージを格納できます。
ldap_count_messages()は、戻されたメッセージの件数をカウントします。前述のldap_msgtype()ファンクションを使用すると、異なるメッセージ・タイプを区別できます。
LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res ); LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg ); int ldap_count_messages( LDAP *ld, LDAPMessage *res );
パラメータ
表8-23に、結果リストを参照するためのパラメータをリストし、説明します。
表8-23 結果リストを参照するためのパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
res |
同期検索ルーチンのいずれか、または |
msg |
|
使用方法
ldap_first_message()およびldap_next_message()は、戻される結果セットにこれ以上メッセージが存在しない場合にNULLを戻します。エントリの参照中にエラーが発生した場合もNULLが戻されます。この場合セッション・ハンドルIDのエラー・パラメータがエラーを示すように設定されます。
正常終了した場合、ldap_count_messages()は、結果のチェーンに格納されたメッセージ数を戻します。resパラメータが無効などのエラーが発生した場合は-1が戻されます。ldap_first_message(), ldap_next_message(), ldap_first_entry(), ldap_next_entry(), ldap_first_reference(), ldap_next_reference()によって戻されたメッセージ、エントリまたはリファレンスとともにコールした場合、ldap_count_messages()コールを使用してチェーンに残っているメッセージ数をカウントすることもできます。
この項のファンクションを使用して、ldap_search()ファンクションで戻されるエントリやリファレンスを解析します。これらの結果は、この項で説明するルーチンをコールしてアクセスできる不透明な構造体に戻されます。これらのルーチンは、戻されたエントリやリファレンスの参照、エントリの属性の参照、エントリ名の取得、およびエントリ内の指定した属性に対応付けられている値の取得を行うために用意されています。
ldap_first_entry()およびldap_next_entry()ルーチンは、検索結果チェーンからのエントリのリストの参照および取得に使用されます。ldap_first_reference()およびldap_next_reference()ルーチンを使用して、検索結果チェーンからの継続リファレンスのリストの参照および取得を行います。ldap_count_entries()を使用して戻されたエントリ数をカウントします。ldap_count_references()を使用して戻されたリファレンス数をカウントします。
LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res ); LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ); LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res ); LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref ); int ldap_count_entries( LDAP *ld, LDAPMessage *res ); int ldap_count_references( LDAP *ld, LDAPMessage *res );
パラメータ
表8-24に、エントリと継続リファレンスを検索結果セットから取得したり、戻されたエントリの件数をカウントするためのパラメータをリストし、説明します。
表8-24 エントリと継続リファレンスを検索結果セットから取得したり、戻されたエントリの件数をカウントするためのパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
res |
検索結果です。同期検索ルーチンのいずれか、または |
entry |
|
ref |
|
使用方法
ldap_first_entry()、ldap_next_entry()、ldap_first_reference()およびldap_next_reference()はすべて、戻される結果セットにこれ以上エントリまたはリファレンスが存在しない場合にNULLを戻します。エントリまたはリファレンスの参照中にエラーが発生した場合もNULLが戻されます。この場合、セッション・ハンドルldのエラー・パラメータがエラーを示すように設定されます。
ldap_count_entries()は、エントリのチェーンに含まれるエントリの数を戻します。resパラメータが無効などのエラーが発生した場合、-1が戻されます。ldap_first_message(), ldap_next_message(), ldap_first_entry(), ldap_next_entry(), ldap_first_reference(), ldap_next_reference()によって戻されたメッセージ、エントリまたはリファレンスとともにコールした場合、ldap_count_entries()コールを使用してチェーンに残っているエントリの数をカウントすることもできます。
ldap_count_references()は検索結果のチェーンに含まれるリファレンスの数を戻します。resパラメータが無効などのエラーが発生した場合は-1が戻されます。ldap_count_references()コールを使用してチェーンに残っているリファレンス数をカウントすることもできます。
この項のファンクションを使用して、エントリとともに戻される属性の型のリストを参照します。
構文
char *ldap_first_attribute (
LDAP *ld, LDAPMessage *entry, BerElement **ptr
); char *ldap_next_attribute (
LDAP *ld, LDAPMessage *entry, BerElement *ptr
); void ldap_memfree( char *mem );
パラメータ
表8-25に、エントリとともに戻される属性の型を参照するためのパラメータを示します。
表8-25 エントリとともに戻される属性の型を参照するためのパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
entry |
属性を参照する対象となるエントリです。 |
ptr |
|
mem |
|
使用方法
ldap_first_attribute()およびldap_next_attribute()は、属性の最後に達したり、エラーが発生した場合に、NULLを戻します。後者の場合は、そのエラーを示すためにセッション・ハンドルldのエラー・パラメータが設定されます。
いずれのルーチンとも、現行の属性名が格納されている割当て済バッファへのポインタを戻します。不要になった場合は、ldap_memfree()をコールして解放する必要があります。
ldap_first_attribute()は、現在の位置の追跡に使用されるBerElementへのポインタをptrに割り当て、戻します。このポインタを後続のldap_next_attribute()コールに渡し、エントリの属性を参照できます。ldap_first_attribute()およびldap_next_attribute()の一連のコールの後、ptrがnull以外の場合、ber_free(ptr, 0)をコールしてこれを解放する必要があります。BerElementに関連付けられたバッファが別に割り当てられたメモリーを示さないため、このコールで2つ目のパラメータを0(ゼロ)として渡すことが非常に重要です。
戻された属性の型の名前は、関連する値を取り出すためのldap_get_values()や関連するファンクションのコールに渡すのに適しています。
ldap_get_values()およびldap_get_values_len()を使用して、指定した属性の値をエントリから取得します。ldap_count_values()およびldap_count_values_len()を使用して、戻された値をカウントします。
ldap_value_free()およびldap_value_free_len()は、値を解放します。
構文
char **ldap_get_values (
LDAP *ld, LDAPMessage *entry, const char *attr
); struct berval **ldap_get_values_len (
LDAP *ld, LDAPMessage *entry, const char *attr
); int ldap_count_values( char **vals ); int ldap_count_values_len( struct berval **vals ); void ldap_value_free( char **vals ); void ldap_value_free_len( struct berval **vals );
パラメータ
表8-26に、属性値を取得してその件数をカウントするためのパラメータをリストし、説明します。
表8-26 属性値を取得してその件数をカウントするためのパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
entry |
値を取得する元のエントリです。 |
attr |
値を取得する対象となる属性です。 |
vals |
|
使用方法
2つの形式のコールが用意されています。最初の形式は、バイナリ以外の文字列データに対してのみ使用できます。_lenが付く2番目の形式は、あらゆる種類のデータで使用できます。
ldap_get_values()およびldap_get_values_len()は、attrに値がない場合またはエラーが発生した場合、NULLを戻します。
ldap_count_values()およびldap_count_values_len()は、valsパラメータが無効などのエラーが発生した場合、-1を戻します。
NULLのvalsパラメータがldap_value_free()またはldap_value_free_len()に渡された場合、何も処理されません。
戻された値は動的に割り当てられます。不要になった場合は、ldap_value_free()またはldap_value_free_len()をコールして解放する必要があります。
ldap_get_dn()は、エントリの名前の取得に使用されます。ldap_explode_dn()およびldap_explode_rdn()は、名前の構成要素への分割に使用されます。ldap_dn2ufn()は、名前をわかりやすい形式に変換するために使用されます。
構文
char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ); char **ldap_explode_dn( const char *dn, int notypes ); char **ldap_explode_rdn( const char *rdn, int notypes ); char *ldap_dn2ufn( const char *dn );
パラメータ
表8-27に、エントリ名を取得、分割および変換するためのパラメータをリストし、説明します。
表8-27 エントリ名を取得、分割および変換するためのパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
entry |
名前を取得する対象となるエントリです。 |
dn |
|
rdn |
|
notypes |
ブール値パラメータです。0(ゼロ)以外の場合は、識別名または相対識別名の構成要素から型情報が削除されることを示します。つまり、 |
使用方法
識別名解析エラーが発生した場合、ldap_get_dn()はNULLを戻します。ファンクションはセッション・ハンドルldにエラー・パラメータを設定し、エラーを示します。新規に割り当てられた領域へのポインタを戻します。この領域は不要になった際にコール元がldap_memfree()をコールして解放する必要があります。
notypesパラメータで示されたタイプの有無にかかわらず、ldap_explode_dn()は指定されたDNのRDNコンポーネントを含むNULL終了char *配列を戻します。コンポーネントはDNに指定されている順序で戻されます。この戻された配列が不要になった場合は、ldap_value_free()をコールして解放する必要があります。
notypesパラメータで示されたタイプの有無にかかわらず、ldap_explode_rdn()は、指定されたRDNのコンポーネントを含むNULL終了char *配列を戻します。コンポーネントはRDNに指定されている順序で戻されます。この戻された配列が不要になった場合は、ldap_value_free()をコールして解放する必要があります。
ldap_dn2ufn()はDNをユーザーにわかりやすい形式に変換します。戻されたUFNは新規に割り当てられた領域です。この領域は不要になった際、ldap_memfree()コールにより解放する必要があります。
ldap_get_entry_controls()は、LDAPコントロールをエントリから抽出します。
構文
int ldap_get_entry_controls (
LDAP *ld, LDAPMessage *entry, LDAPControl ***serverctrlsp
);
パラメータ
表8-28に、LDAPコントロールをエントリから抽出するためのパラメータを示します。
表8-28 LDAPコントロールをエントリから抽出するためのパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
entry |
コントロールを抽出する元のエントリです。 |
serverctrlsp |
この結果パラメータには、エントリからコピーされたコントロールの割当て済配列が入力されます。このコントロール配列は、 |
使用方法
ldap_get_entry_controls()は、リファレンスが正常に解析されたかどうかを示すLDAPエラー・コードを戻します(正常終了の場合はLDAP_SUCCESS)。
ldap_parse_reference()を使用して、参照およびコントロールをSearchResultReferenceメッセージから抽出します。
構文
int ldap_parse_reference (
LDAP *ld, LDAPMessage *ref, char ***referralsp, LDAPControl ***serverctrlsp, int freeit
);
パラメータ
表8-29に、参照とコントロールをSearchResultReferenceメッセージから抽出するためのパラメータをリストし、説明します。
表8-29 参照とコントロールをSearchResultReferenceメッセージから抽出するためのパラメータ
| パラメータ | 説明 |
|---|---|
ld |
セッション・ハンドルです。 |
ref |
解析するリファレンスです。 |
referralsp |
この結果パラメータには、文字列の割当て済配列が入力されます。配列の要素は、refに格納されている参照(通常はLDAP URL)です。この配列が不要になった場合は、 |
serverctrlsp |
この結果パラメータには、 |
freeit |
|
使用方法
ldap_parse_reference()は、リファレンスが正常に解析されたかどうかを示すLDAPエラー・コードを戻します(正常終了の場合はLDAP_SUCCESS)。
最初の3つの例では、SSLと組み合せてC APIを使用する方法、SSLを使用せずにC APIを使用する方法およびSASL認証にC APIを使用する方法を示します。詳細な例は、RFC 1823に記載されています。また、LDAP検索を実行するコマンドライン・ツールのサンプル・コードも、SSLモードおよび非SSLモードでのAPIの使用方法を示します。
この項では、次の項目について説明します。
#include <stdio.h>
#include <ldap.h>
main()
{
LDAP *ld;
int ret = 0;
….
/* open a connection */
if ((ld = ldap_open("MyHost", 3131)) == NULL)
exit( 1 );
/* SSL initialization */
ret = ldap_init_SSL(&ld->ld_sb, "file:/sslwallet", "welcome",
GSLC_SSL_ONEWAY_AUTH );
if(ret != 0)
{
printf(" %s \n", ldap_err2string(ret));
exit(1);
}
/* authenticate as nobody */
if ( ldap_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_bind_s" );
exit( 1 );
}
. . .
}
ldap_init_SSLをコールしているので、この例でのクライアント/サーバー間の通信は、SSLを使用することによって保護されています。
#include <stdio.h>
#include <ldap.h>
main()
{
LDAP *ld; int ret = 0; . . . /* open a connection */ if ( (ld = ldap_open( "MyHost", LDAP_PORT )) == NULL ) exit( 1 ); /* authenticate as nobody */ if ( ldap_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_bind_s" ); exit( 1 ); } . . .
}
この例では、ldap_init_SSLをコールしていないので、クライアント/サーバー間の通信は保護されていません。
この例では、ディレクトリ・サーバーに対するSASLベースのDigest-MD5認証におけるLDAP SASL C-APIの使用方法を示します。
/*
EXPORT FUNCTION(S)
NONE
INTERNAL FUNCTION(S)
NONE
STATIC FUNCTION(S)
NONE
NOTES
Usage:
saslbind -h ldap_host -p ldap_port -D authentication_identity_dn \
-w password
options
-h LDAP host
-p LDAP port
-D DN of the identity for authentication
-p Password
Default SASL authentication parameters used by the demo program
SASL Security Property : Currently only "auth" security property
is supported by the C-API. This demo
program uses this security property.
SASL Mechanism : Supported mechanisms by OID
"DIGEST-MD5" - This demo program
illustrates it's usage.
"EXTERNAL" - SSL authentication is used.
(This demo program does
not illustrate it's usage.)
Authorization identity : This demo program does not use any
authorization identity.
MODIFIED (MM/DD/YY)
****** 06/12/03 - Creation
*/
/*---------------------------------------------------------------------------
PRIVATE TYPES AND CONSTANTS
---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------
STATIC FUNCTION DECLARATIONS
---------------------------------------------------------------------------*/
#include <stdio.h>
#include <stdlib.h>
#include <ldap.h>
static int ldap_version = LDAP_VERSION3;
main (int argc, char **argv)
{
LDAP* ld;
extern char* optarg;
char* ldap_host = NULL;
char* ldap_bind_dn = NULL;
char* ldap_bind_pw = NULL;
int authmethod = 0;
char ldap_local_host[256] = "localhost";
int ldap_port = 3060;
char* authcid = (char *)NULL;
char* mech = "DIGEST-MD5"; /* SASL mechanism */
char* authzid = (char *)NULL;
char* sasl_secprops = "auth";
char* realm = (char *)NULL;
int status = LDAP_SUCCESS;
OraLdapHandle sasl_cred = (OraLdapHandle )NULL;
OraLdapClientCtx *cctx = (OraLdapClientCtx *)NULL;
int i = 0;
while (( i = getopt( argc, argv,
"D:h:p:w:E:P:U:V:W:O:R:X:Y:Z"
)) != EOF ) {
switch( i ) {
case 'h': /* ldap host */
ldap_host = (char *)strdup( optarg );
break;
case 'D': /* bind DN */
authcid = (char *)strdup( optarg );
break;
case 'p': /* ldap port */
ldap_port = atoi( optarg );
break;
case 'w': /* Password */
ldap_bind_pw = (char *)strdup( optarg );
break;
default:
printf("Invalid Arguments passed\n" );
}
}
/* Get the connection to the LDAP server */
if (ldap_host == NULL)
ldap_host = ldap_local_host;
if ((ld = ldap_open (ldap_host, ldap_port)) == NULL)
{
ldap_perror (ld, "ldap_init");
exit (1);
}
/* Create the client context needed by LDAP C-API Oracle Extension functions*/
status = ora_ldap_init_clientctx(&cctx);
if(LDAP_SUCCESS != status) {
printf("Failed during creation of client context \n");
exit(1);
}
/* Create SASL credentials */
sasl_cred = ora_ldap_create_cred_hdl(cctx, ORA_LDAP_CRED_HANDLE_SASL_MD5);
ora_ldap_set_cred_props(cctx, sasl_cred, ORA_LDAP_CRED_SASL_REALM,
(void *)realm);
ora_ldap_set_cred_props(cctx, sasl_cred, ORA_LDAP_CRED_SASL_AUTH_PASSWORD,
(void *)ldap_bind_pw);
ora_ldap_set_cred_props(cctx, sasl_cred, ORA_LDAP_CRED_SASL_AUTHORIZATION_ID,
(void *)authzid);
ora_ldap_set_cred_props(cctx, sasl_cred, ORA_LDAP_CRED_SASL_SECURITY_PROPERTIES,
(void *)sasl_secprops);
/* If connecting to the directory using SASL DIGEST-MD5, the Authentication ID
has to be normalized before it's sent to the server,
the LDAP C-API does this normalization based on the following flag set in
SASL credential properties */
ora_ldap_set_cred_props(cctx, sasl_cred, ORA_LDAP_CRED_SASL_NORM_AUTHDN, (void *)NULL);
/* SASL Authetication to LDAP Server */
status = (int)ora_ldap_init_SASL(cctx, ld, (char *)authcid, (char *)ORA_LDAP_SASL_MECH_DIGEST_MD5,
sasl_cred, NULL, NULL);
if(LDAP_SUCCESS == status) {
printf("SASL bind successful \n" );
}else {
printf("SASL bind failed with status : %d\n", status);
}
/* Free SASL Credentials */
ora_ldap_free_cred_hdl(cctx, sasl_cred);
status = ora_ldap_free_clientctx(cctx);
/* Unbind from LDAP server */
ldap_unbind (ld);
return (0);
}
/* end of file saslbind.c */
コールバック・ファンクションを設定するには、ldap_set_rebind_proc()を使用します。コールバック・ファンクションは、ldap_set_option()を使用してLDAP_OPT_REFERRALSが設定されている場合にのみ使用されます。ldap_set_rebind_proc()がコールされていない場合、LDAP参照の追跡時、ライブラリでは新しいサーバーへの接続に匿名バインドを使用します。
/* referralsample.c - Sample program to demonstrate the usage of ldap_set_rebind_proc() for referrals */
#include <stdio.h>
#include <stdlib.h>
#include <ldap.h>
/*
* Prints the Entry DNs of the search result
*/
void print_entry_dns( LDAP *ld, LDAPMessage *result )
{
LDAPMessage *e;
char *dn;
for ( e = ldap_first_entry( ld, result ); e != NULL;
e = ldap_next_entry(ld, e ) )
{
if ( (dn = ldap_get_dn( ld, e )) != NULL ) {
printf( "dn: %s\n\n", dn );
ldap_memfree( dn );
}
else {
ldap_perror( ld, "ldap_get_dn" );
}
}
}
/*
* Rebind function for providing the credentials to bind referral servers
*/
int getbindcredentials(LDAP *ld, char **binddn, char **bindpwd, int *authmethod, int freeit)
{
if (freeit == 0) {
/* In this example bind credentials are static. Typically, Bind credentials are fetched from wallet or
some other means for the server information in input session handle */
*binddn = "cn=orcladmin";
*bindpwd = "xyz";
*authmethod = LDAP_AUTH_SIMPLE;
}
else {
/* In this example there is no memory allocation.
If the memory is allocated for binddn/bindpwd/authmehod, they should be freed here */
*binddn = NULL;
*bindpwd = NULL;
*authmethod = 0;
}
return 0;
}
main()
{
char ldaphost[] = "localhost";
char binddn[] = "cn=orcladmin";
char bindpwd[] = "password";
int ldapport = 3060;
char searchbase[] = "dc=oracle,dc=com";
char filter[] = "objectclass=*";
int scope = LDAP_SCOPE_SUBTREE;
LDAP *ld;
LDAPMessage *result;
int ret = 0;
if ( (ld = ldap_open( ldaphost, ldapport )) == NULL) {
printf( "ldap_open: Connection failed\n" );
exit( 1 );
}
if ( ldap_simple_bind_s(ld, binddn, bindpwd) != LDAP_SUCCESS ) {
ldap_perror(ld, "ldap_simple_bind_s");
exit( 1 );
}
/* Set this option to connect to the referrals */
ldap_set_option (ld, LDAP_OPT_REFERRALS, (void *)1);
/* set the function pointer which provides the bind credentials for referral server */
ldap_set_rebind_proc(ld, (int (*)(LDAP*, char**, char**, int*, int))getbindcredentials);
ret = ldap_search_s( ld, searchbase, scope, filter, NULL, 0, &result );
if(LDAP_SUCCESS != ret) {
ldap_perror(ld, "ldap_search_s");
exit( 1 );
}
print_entry_dns(ld, result);
ldap_unbind(ld);
return(0);
}
C APIを使用してアプリケーションを作成するには、次のことが必要です。
$ORACLE_HOME/ldap/public/ldap.hにあるヘッダー・ファイルをインクルードします。
次の場所にあるライブラリに動的にリンクします。
$ORACLE_HOME/lib/libclntsh.so.11.1 (UNIXおよびLinuxオペレーティング・システムの場合)
%ORACLE_HOME%\bin\oraldapclnt11.lib (Windowsオペレーティング・システムの場合)
このAPIは、すべてのリリースのOracle Internet Directoryで機能します。Oracle環境または最低でもグローバリゼーション・サポートなどの主要ライブラリが必要です。
SSLで別の認証モードを使用するには、ディレクトリ・サーバーの構成設定をモードに応じて変更する必要があります。
|
関連項目: 様々なSSL認証モードでのディレクトリ・サーバーの設定方法の詳細は、『Oracle Fusion Middleware Oracle Internet Directory管理者ガイド』を参照してください。 |
SSLモードでC APIを使用する場合は、ウォレットを作成するためにOracle Wallet Managerが必要となります。
TCP/IPソケット・ライブラリが必要です。
次のOracleライブラリが必要です。
Oracle SSL関連ライブラリ
Oracleシステム・ライブラリ
サンプル・コマンドライン・ツールのリリースの中には、サンプル・ライブラリが含まれています。それらのライブラリはユーザー自身のライブラリに置き換える必要があります。
この製品は、LDAP SDKの仕様(RFC 1823)に記述されている認証方式のみをサポートします。
C APIに入力されるすべての文字列はUTF-8形式の必要があります。文字列がUTF-8形式でない場合は、OCIファンクションOCINlsCharSetConvertを使用して変換できます。http://www.oracle.com/technology/documentationのOracle Database LibraryでOracle Call Interfaceプログラマーズ・ガイドを参照してください。
