| Oracle Fusion Middleware Oracle Identity Managementアプリケーション開発者ガイド 11gリリース1（11.1.1） B56242-01 |
|
 戻る |
 次へ |
| Oracle Fusion Middleware Oracle Identity Managementアプリケーション開発者ガイド 11gリリース1（11.1.1） B56242-01 |
|
戻る |
次へ |
この章では、Oracle Internet DirectoryのC 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拡張機能は回線を通るデータの暗号化と復号化および認証を行います。
認証のタイプは、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 定数
| 定数 | 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サーバー・コントロールのデフォルト・リストです。 関連項目: 「コントロールの使用」 |
LDAP_OPT_CLIENT_CONTROLS(0x13) |
LDAPControl** |
LDAPControl*** |
LDAPセッションに影響を与えるクライアント・コントロールのデフォルト・リストです。 関連項目: 「コントロールの使用」 |
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()ファンクションを使用すると、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, struct berval **servercredp
);
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 |
|
servercredp |
相互認証が指定されている場合は、この結果パラメータにサーバーから戻された資格証明が入力されます。割り当てられた |
使用方法
非推奨のルーチンに関するその他のパラメータは説明していません。詳細は、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()ファンクション（「ldap_get_optionおよびldap_set_option」を参照）を使用して設定できます。コントロール・リストは、ldap_search_ext()などの一部のLDAP APIコールに直接渡すこともできます。その場合、ldap_set_option()を使用してセッションに設定したコントロールは無視されます。コントロール・リストは、ldapcontrol構造体へのポインタのNULL終了配列として表されます。
サーバー・コントロールは、LDAP v3プロトコル拡張ドキュメントで定義されています。たとえば、コントロールは、サーバー側での検索結果のソートをサポートするために計画されています。
この章では、1つのクライアント・コントロールが定義されています（後の項で説明）。
クライアント・コントロールの参照プロセス「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エラー・コード）を戻します。これらのバインド解除ファンクションのいずれかをコールすると、セッション・ハンドル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が戻されます。この場合は、エラーを示すためにセッション・ハンドルldのエラー・パラメータが設定されます。
正常終了した場合、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)をコールして解放する必要があります。このコールでは、2番目のパラメータとして0（ゼロ）を渡すことが重要です。これは、BerElementに対応付けられたバッファは、別に割り当てられたメモリーを指し示していないためです。
戻された属性の型の名前は、関連する値を取り出すための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()をコールして解放する必要があります。
ldap_explode_dn()は、指定された識別名の相対識別名が含まれたNULLで終了するchar *配列を戻します。型を戻すかどうかはnotypesパラメータで指定します。構成要素は、識別名内にある順序で戻されます。戻された配列が不要になった場合は、ldap_value_free()をコールして解放する必要があります。
ldap_explode_rdn()は、指定された相対識別名の構成要素が含まれたNULLで終了するchar *配列を戻します。型を戻すかどうかはnotypesパラメータで指定します。構成要素は、相対識別名内にある順序で戻されます。戻された配列が不要になった場合は、ldap_value_free()をコールして解放する必要があります。
ldap_dn2ufn()は、識別名をユーザーにわかりやすい形式に変換します。戻されたユーザーにわかりやすい名前（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.10.1（UNIXオペレーティング・システムの場合）
%ORACLE_HOME%\bin\oraldapclnt10.dll（Windowsオペレーティング・システムの場合）
このAPIは、すべてのリリースのOracle Internet Directoryで機能します。Oracle環境または最低でもグローバリゼーション・サポートなどの主要ライブラリが必要です。
SSLで別の認証モードを使用するには、ディレクトリ・サーバーの構成設定をモードに応じて変更する必要があります。
|
関連項目: 様々なSSL認証モードでのディレクトリ・サーバーの設定方法の詳細は、『Oracle Fusion Middleware Oracle Internet Directory管理者ガイド』を参照してください。 |
SSLモードでC APIを使用する場合は、ウォレットを作成するためにOracle Wallet Managerが必要となります。
次のOracleライブラリが必要です。
サンプル・コマンドライン・ツールのリリースの中には、サンプル・ライブラリが含まれています。それらのライブラリはユーザー自身のライブラリに置き換える必要があります。
この製品は、LDAP SDKの仕様（RFC 1823）に記述されている認証方式のみをサポートします。
C APIに入力されるすべての文字列はUTF-8形式の必要があります。文字列がUTF-8形式でない場合は、OCIファンクションOCINlsCharSetConvertを使用して変換できます。Oracle Databaseライブラリ（http://www.oracle.com/technology/documentation）の『Oracle Call Interfaceプログラマーズ・ガイド』を参照してください。
