1.20.1 セションのオープンとクローズインタフェース

関数名	関数の説明
ldap_init()	リポジトリサーバへのセションを初期化します。
ldapssl_init()	リポジトリサーバへのセションを初期化します。(SSL使用)

関数名	関数の説明
ldap_unbind()	リポジトリサーバとのコネクションをクローズした後、セションを解放します。
ldap_unbind_s()	ldap_unbind()と同じ処理をします。

名前

ldap_init

形式

  #include "idldap.h"
  LDAP  *ldap_init(
          const char  *hostname,
          int  portno );

機能説明

この関数は、LDAPのセションをオープンします。
これ以降に呼び出す関数は、ここで取得したセションハンドルをパラメタに指定します。セションハンドルは、そのセションをクローズするまで有効です。

認証はDNとパスワードを使用して行われます。簡易認証については、“1.20.3 リポジトリサーバとのユーザ認証インタフェース”を参照してください。

パラメタ

hostname: リポジトリサーバのホスト名、またはIPアドレスを示す文字列のアドレスを指定します。ホスト名やIPアドレスは、空白で区切って複数指定することができます。hostnameにNULLを指定した場合、"localhost"が設定されたと見なします。複数の相手ホストが指定された場合、コネクションを確立する際に指定された順番で接続を試みて、接続に成功した最初のホストと通信します。

portno: リポジトリサーバのポート番号を指定します。デフォルトのLDAPポートを使用する場合は、ポート番号に0を指定します。デフォルトのポート番号はLDAP_PORT「389」です。

復帰値

この関数は、復帰値として以下の値を返します。

正常終了の場合：セションハンドル
正常終了の場合、セションハンドルには獲得したセションハンドルへのポインタが通知されます。
異常終了の場合：NULL
異常終了の場合、以下の原因が考えられます。
- セションハンドル用のメモリが獲得できないなど、システムの資源が不足しています。
- パラメタの指定に誤りがあります。

注意事項

セションの共用について
オープンした1つのセションを複数のスレッドで共有し、各スレッドからLDAP要求をすることはできません。スレッドを使用しLDAP要求をする場合、各スレッドでldap_init()で獲得したセションを使用し、それぞれのスレッドからLDAP要求をしてください。
複数ホストの指定について
2つ以上のリポジトリに対して、指定したホストの中で起動しているリポジトリに接続するような用途には使用できません。
（1つ目のホストに接続してリポジトリが起動していなければ、2つ目のホストのリポジトリに接続を試みます。）
複数のホストを指定した場合は、1つ目のホストに対してCONNECTを行い、ソケットレベルで接続できない場合にだけ、2つ目以降のホストに対して接続を試みます。上記のようなリポジトリ起動チェックをする場合は、リポジトリの起動をldap_simple_bind()/ldap_simple_bind_s()で確認するように、APIを使用してアプリケーション側での対応が必要です。

名前

ldapssl_init

形式

  #include "idldap.h"
  LDAP  *ldapssl_init(
          const char  *hostname,
          int  portno,
          SSLENV *sslenv );

機能説明

この関数は、SSLを使用して、LDAPのセションをオープンします。サーバとの通信を安全なものとすることができます。
これ以降に呼び出す関数は、ここで取得したセションハンドルをパラメタに指定します。セションハンドルは、そのセションをクローズするまで有効です。

なお、この関数はスレッドアンセーフです。

パラメタ

hostname: リポジトリサーバのホスト名、またはIPアドレスを示す文字列のアドレスを指定します。ホスト名やIPアドレスは、空白で区切って複数指定することができます。hostnameにNULLを指定した場合、"localhost"が設定されたと見なします。複数の相手ホストが指定された場合、コネクションを確立する際に指定された順番で接続を試みて、接続に成功した最初のホストと通信します。

portno: リポジトリサーバのポート番号を指定します。デフォルトのLDAPポートを使用する場合は、ポート番号に0を指定します。デフォルトのポート番号は「636」です。

sslenv: SSLENV構造体のアドレスを指定します。SSLを使用する場合、ここで指定する構造体にSSLの動作環境の情報を設定し、パラメタとして渡す必要があります。この構造体の各メンバには、以下の値を設定します。

【SSLENV構造体のメンバの説明】

ssl_version
使用するSSLプロトコルのバージョンを指定します。
- SSLバージョン2.0の場合： 2
- SSLバージョン3.0の場合： 3
- TLSバージョン1.0の場合： 31
省略時(0指定時)は、SSLバージョン3.0とみなされます。これ以外の値を指定した場合は、SSLを使用しないものとして処理されます(ldap_init()と同じ処理となります)。
ssl_verify
証明書を検証するかどうかを指定します。
- 証明書を検証しない場合： 0
- クライアントの証明書だけを検証する場合： 1
- サーバから送られてきた証明書を検証する場合： 2
これ以外の値を指定した場合は、以下の値が指定されたものとみなされます。
- SSLバージョン2.0の場合： 1
- SSLバージョン3.0、またはTLSバージョン 1.0の場合： 2

crypt（省略可）

  SSLで使用する暗号化の方法を以下から選択して、暗号化アルゴリズムを示す文字列のアドレスで指定します。暗号化の方法を複数指定する場合には、「:」で区切って指定します。
  通信相手となるInterstage ディレクトリサービスのサーバが使用するSSL定義と同じ設定としてください。

  SSLプロトコルのバージョン(ssl_version)に「2」を指定した場合、以下の値を指定できます。

暗号化アルゴリズムを示す文字列	説明
"DES-CBC3-MD5"	168bitのトリプルDES暗号,MD5 MAC
"RC4-MD5"	128bitのRC4暗号,MD5 MAC
"RC2-MD5"	128bitのRC2暗号,MD5 MAC
"DES-CBC-MD5"	56bitのDES暗号,MD5 MAC
"EXP-RC4-MD5"	40bitのRC4暗号,MD5 MAC
"EXP-RC2-MD5"	40bitのRC2暗号,MD5 MAC

SSLプロトコルのバージョン(ssl_version)に「3」または「31」を指定した場合、以下の値を指定できます。

暗号化アルゴリズムを示す文字列	説明
"RSA-SC2000-256-SHA"	256bitのSC2000暗号,SHA-1 MAC
"RSA-AES-256-SHA"	256bitのAES暗号,SHA-1 MAC
"RSA-SC2000-128-SHA"	128bitのSC2000暗号,SHA-1 MAC
"RSA-AES-128-SHA"	128bitのAES暗号,SHA-1 MAC
"RSA-3DES-SHA"	168bitのトリプルDES暗号,SHA-1 MAC
"RSA-RC4-MD5"	128bitのRC4暗号,MD5 MAC
"RSA-RC4-SHA"	128bitのRC4暗号,SHA-1 MAC
"RSA-DES-SHA"	56bitのDES暗号,SHA-1 MAC
"RSA-EXPORT-RC4-MD5"	40bitのRC4暗号,MD5 MAC
"RSA-EXPORT-RC2-MD5"	40bitのRC2暗号,MD5 MAC
"RSA-NULL-MD5"	暗号なし,MD5 MAC
"RSA-NULL-SHA"	暗号なし,SHA-1 MAC

Interstage Application Serverでサポートしている暗号化方式の種類を以下に示します。

公開鍵暗号化方式：RSA
秘密鍵暗号化方式：SC2000, AES, DES, 3DES（トリプルDES）, RC4, RC2 （NULLは暗号化しないことを示す）
秘密鍵の処理モード：CBC（数値はブロック長）
ハッシュキー：SHA, MD5

MACはメッセージ認証符号です。

省略(NULLを指定)した場合は、SSLプロトコルのバージョン(ssl_version)の指定により、以下の値が指定されたものと見なします。以下の説明では、表現上、暗号化の方法ごとに改行しています。

SSLプロトコルのバージョン(ssl_version)に「2」が指定された場合
DES-CBC3-MD5:
DES-CBC-MD5:
RC4-MD5:
RC2-MD5:
EXP-RC4-MD5:
EXP-RC2-MD5
SSLプロトコルのバージョン(ssl_version)に「3」または「31」が指定された場合
RSA-SC2000-256-SHA:
RSA-AES-256-SHA:
RSA-SC2000-128-SHA:
RSA-AES-128-SHA:
RSA-3DES-SHA:
RSA-RC4-MD5:
RSA-RC4-SHA:
RSA-DES-SHA:
RSA-EXPORT-RC4-MD5:
RSA-EXPORT-RC2-MD5:

slot_path（必須）
スロット情報ディレクトリのアドレスを指定します（ディレクトリのパス名をフルパスで指定します）。証明書/鍵管理環境の作成時に指定したスロット情報ディレクトリを指定してください。
tkn_lbl（必須）
トークンラベルのアドレスを指定します。証明書/鍵管理環境の作成時に指定したトークンラベルを指定してください。
tkn_pwd（必須）
ユーザPINのアドレスを指定します。証明書/鍵管理環境の作成時に指定したユーザPINを指定してください。
cert_path（必須）
運用管理ディレクトリのアドレスを指定します（ディレクトリのパス名をフルパスで指定します）。証明書/鍵管理環境の作成時に指定した運用管理ディレクトリを指定してください。
user_cert（省略可）
ユーザ証明書ニックネームのアドレスを指定します。省略(NULLを指定)した場合は、証明書管理に登録されている自分の証明書がすべて指定されたものとみなします。ユーザ証明書の登録時に指定したユーザ証明書ニックネームを指定してください。
ssl_err（必須）
SSLエラーコードが設定されます。必ず0で初期化する必要があります。
ssl_err_detail（必須）
SSLエラー詳細コードが設定されます。必ず0で初期化する必要があります。
ssl_timer（省略可）
SSLにおけるタイマー(秒単位)を設定します。0を指定した場合は、タイマーが3600秒となります。リポジトリサーバの応答に対する最大の待ち時間に使用されます。
ssl_err_funcinfo（省略可）
SSLライブラリの保守コードが設定されます。

証明書/鍵管理環境の作成については、“ディレクトリサービス運用ガイド”の“SSL通信環境の構築”-“クライアント側の環境構築”-“証明書/鍵管理環境の作成（クライアント）”を参照してください。
ユーザ証明書（サイト証明書）の登録については、“ディレクトリサービス運用ガイド”の“SSL通信環境の構築”-“クライアント側の環境構築”-“証明書とCRLの登録（クライアント）”を参照してください。

復帰値

この関数は、復帰値として以下の値を返します。

正常終了の場合：セションハンドル
正常終了の場合、セションハンドルには獲得したセションハンドルへのポインタが通知されます。
異常終了の場合：NULL
異常終了の場合、以下の原因が考えられます。
- セションハンドル用のメモリが獲得できないなど、システムの資源が不足しています。
- トレースを取得している場合には、トレースファイルのバックアップに失敗しています。
- SSLライブラリパッケージがインストールされていません。
- SSL環境設定に誤りがあります（必須項目が設定されていません）。
- SSLライブラリでエラーが発生しています。

注意事項

SSLENV構造体の領域について
sslenvパラメタで指定するSSLENV構造体には、ldap_unbind/ldap_unbind_sで発生したSSLライブラリのエラーコードも設定されます。このため、セションハンドルの解放が完了するまでは、sslenvパラメタで指定した領域を解放しないでください。
SSLエラーコード
ldapssl_init()で発生したSSLライブラリのエラーコードは、ldapssl_error()で参照することができません。そのため、SSLENV構造体のメンバ（ssl_errとssl_err_detail）の値でチェックする必要があります。
セションの共用について
オープンした1つのセションを複数のスレッドで共有し、各スレッドからLDAP要求をすることはできません。スレッドを使用しLDAP要求をする場合、各スレッドでldapssl_init()で獲得したセションを使用し、それぞれのスレッドからLDAP要求をしてください。
スレッドの排他処理について
ldapssl_init()はスレッドアンセーフ関数です。この関数を複数のスレッドから同時に呼び出す際は、アプリケーション側で各スレッド間の排他処理をしてください。排他をしない場合、動作の保証はできません。
証明書/鍵管理環境について
同一プロセス内で異なる証明書/鍵管理環境を使用しないでください。

1.20.1 セションのオープンとクローズインタフェース

1.20.1.1 ldap_init()

1.20.1.2 ldapssl_init()

1.20.1.3 ldap_unbind()

1.20.1.4 ldap_unbind_s()