セションのオープン/初期設定
関数名 | 関数の説明 |
|---|---|
リポジトリサーバへのセションを初期化します。 | |
リポジトリサーバへのセションを初期化します。(SSL使用) |
セションのクローズ
関数名 | 関数の説明 |
|---|---|
リポジトリサーバとのコネクションをクローズした後、セションを解放します。 | |
ldap_unbind()と同じ処理をします。 |
名前
ldap_init
形式
#include "idldap.h"
LDAP *ldap_init(
const char *hostname,
int portno );機能説明
この関数は、LDAPのセションをオープンします。
これ以降に呼び出す関数は、ここで取得したセションハンドルをパラメタに指定します。セションハンドルは、そのセションをクローズするまで有効です。
認証はDNとパスワードを使用して行われます。簡易認証については、“1.19.3 リポジトリサーバとのユーザ認証インタフェース”を参照してください。
パラメタ
リポジトリサーバのホスト名、またはIPアドレスを示す文字列のアドレスを指定します。ホスト名やIPアドレスは、空白で区切って複数指定することができます。hostnameにNULLを指定した場合、"localhost"が設定されたとみなします。複数の相手ホストが指定された場合、コネクションを確立する際に指定された順番で接続を試みて、接続に成功した最初のホストと通信します。
リポジトリサーバのポート番号を指定します。デフォルトの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のセションをオープンします。サーバとの通信を安全なものとすることができます。
これ以降に呼び出す関数は、ここで取得したセションハンドルをパラメタに指定します。セションハンドルは、そのセションをクローズするまで有効です。
認証はDNとパスワードを使用して行われます。簡易認証については、“1.19.3 リポジトリサーバとのユーザ認証インタフェース”を参照してください。
なお、この関数はスレッドアンセーフです。
パラメタ
リポジトリサーバのホスト名、またはIPアドレスを示す文字列のアドレスを指定します。ホスト名やIPアドレスは、空白で区切って複数指定することができます。hostnameにNULLを指定した場合、"localhost"が設定されたとみなします。複数の相手ホストが指定された場合、コネクションを確立する際に指定された順番で接続を試みて、接続に成功した最初のホストと通信します。
リポジトリサーバのポート番号を指定します。デフォルトのLDAPポートを使用する場合は、ポート番号に0を指定します。デフォルトのポート番号は「636」です。
SSLENV構造体のアドレスを指定します。SSLを使用する場合、ここで指定する構造体にSSLの動作環境の情報を設定し、パラメタとして渡す必要があります。この構造体の各メンバには、以下の値を設定します。
【SSLENV構造体のメンバの説明】
ssl_version
使用するSSLプロトコルのバージョンを指定します。
設定値 | 説明 |
|---|---|
2 | SSLプロトコルのバージョン2.0を使用する。 |
3 | SSLプロトコルのバージョン3.0を使用する。 |
31 (注) | TLSプロトコルのバージョン1.0を使用する。 |
32 (注) | TLSプロトコルのバージョン1.1を使用する。 |
33 (注) | TLSプロトコルのバージョン1.2を使用する。 |
注）小数点(.)を含めずに指定します。
省略時(0指定時)は、SSLバージョン3.0とみなされます。これ以外の値を指定した場合は、SSLを使用しないものとして処理されます(ldap_init()と同じ処理となります)。
ssl_verify
証明書を検証するかどうかを指定します。
設定値 (注) | 説明 |
|---|---|
0 | 証明書を検証しない場合 |
1 | クライアントの証明書だけを検証する場合 |
2 | サーバから送られてきた証明書を検証する場合 |
注）0～2以外の値を指定した場合は、以下の値が指定されたものとみなされます。
SSLバージョン2.0の場合 ： 1
SSLバージョン2.0以外の場合 ： 2
crypt（省略可）
SSLで使用する暗号化の方法を、SSLプロトコルのバージョン(ssl_version)に応じて以下から選択し、暗号化アルゴリズムを示す文字列のアドレスで指定します。暗号化の方法を複数指定する場合には、「:」で区切って指定します。MACは、メッセージ認証符号です。
通信相手となるInterstage ディレクトリサービスのサーバが使用するSSL定義と同じ設定としてください。
SSLプロトコルのバージョンの設定値 | 暗号化アルゴリズムを示す文字列 | 説明 |
|---|---|---|
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 | |
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" (注1) | 128bitのRC4暗号,MD5 MAC | |
"RSA-RC4-SHA" (注1) | 128bitのRC4暗号,SHA-1 MAC | |
"RSA-DES-SHA" (注2) | 56bitのDES暗号,SHA-1 MAC | |
"RSA-EXPORT-RC4-MD5" (注3) | 40bitのRC4暗号,MD5 MAC | |
"RSA-EXPORT-RC2-MD5" (注3) | 40bitのRC2暗号,MD5 MAC | |
"RSA-NULL-MD5" (注4) | 暗号なし,MD5 MAC | |
"RSA-NULL-SHA" (注4) | 暗号なし,SHA-1 MAC | |
32 | "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-SHA" (注1) | 128bitのRC4暗号,SHA-1 MAC | |
"RSA-RC4-MD5" (注1) | 128bitのRC4暗号,MD5 MAC | |
"RSA-DES-SHA" (注2) | 56bitのDES暗号,SHA-1 MAC | |
"RSA-NULL-SHA" (注4) | 暗号なし,SHA-1 MAC | |
"RSA-NULL-MD5" (注4) | 暗号なし,MD5 MAC | |
33 | "RSA-AES-256-GCM-SHA384" | 256bitのAES GCM暗号,SHA-384 MAC |
"RSA-AES-128-GCM-SHA256" | 128bitのAES GCM暗号,SHA-256 MAC | |
"RSA-SC2000-256-SHA256" | 256bitのSC2000暗号,SHA-256 MAC | |
"RSA-SC2000-256-SHA" | 256bitのSC2000暗号,SHA-1 MAC | |
"RSA-AES-256-SHA256" | 256bitのAES暗号,SHA-256 MAC | |
"RSA-AES-256-SHA" | 256bitのAES暗号,SHA-1 MAC | |
"RSA-SC2000-128-SHA256" | 128bitのSC2000暗号,SHA-256 MAC | |
"RSA-SC2000-128-SHA" | 128bitのSC2000暗号,SHA-1 MAC | |
"RSA-AES-128-SHA256" | 128bitのAES暗号,SHA-256 MAC | |
"RSA-AES-128-SHA" | 128bitのAES暗号,SHA-1 MAC | |
"RSA-3DES-SHA" | 168bitのトリプルDES暗号,SHA-1 MAC | |
"RSA-RC4-SHA" (注1) | 128bitのRC4暗号,SHA-1 MAC | |
"RSA-RC4-MD5" (注1) | 128bitのRC4暗号,MD5 MAC | |
"RSA-NULL-SHA256" (注4) | 暗号なし,SHA-256 MAC | |
"RSA-NULL-SHA" (注4) | 暗号なし,SHA-1 MAC | |
"RSA-NULL-MD5" (注4) | 暗号なし,MD5 MAC |
注1）本値は安全な暗号化方式ではないため（非推奨）、使用が必須ではない場合、指定しないでください。
注2）本値は安全な暗号化方式ではないため、使用が必須ではない場合、指定しないでください。
注3）本値はRSA512bitの弱暗号のため、使用が必須ではない場合、指定しないでください。
注4）本値は暗号化を行わないため、使用が必須ではない場合、指定しないでください。
ポイント
サポートしている暗号化方式(「SSL_TXT_」で始まる)に表わされる暗号化の種類を、以下に示します。
公開鍵暗号化方式 | RSA |
共通鍵暗号化方式 | DES、3DES(トリプルDES)、RC4、RC2、AES、SC2000(NULLの場合：暗号化しない) |
共通鍵暗号の処理モード | CBC(AES、SC2000)、EDE(数値はbit長)(3DES) |
ハッシュキー | SHA256、SHA、MD5 |
省略(NULLを指定)した場合は、SSLバージョン(ssl_version)の設定値に応じて、以下の値が指定されたものとみなします。
SSLバージョンの設定値 | 省略値 (注) |
|---|---|
2 | DES-CBC3-MD5: |
3 または 31 | RSA-SC2000-256-SHA: |
32 | RSA-SC2000-256-SHA: |
33 | RSA-AES-256-GCM-SHA384: |
注）暗号化の方法ごとに改行して記述していますが、実際は改行を入れずに1行で指定します。
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()はスレッドアンセーフ関数です。この関数を複数のスレッドから同時に呼び出す際は、アプリケーション側で各スレッド間の排他処理をしてください。排他をしない場合、動作の保証はできません。
証明書/鍵管理環境について
同一プロセス内で異なる証明書/鍵管理環境を使用しないでください。
名前
ldap_unbind
形式
#include "idldap.h" int ldap_unbind( LDAP *ld );
機能説明
この関数は、リポジトリサーバとのコネクション解放とセションのクローズをします。ldap_unbind()とldap_unbind_s()は、どちらも同期型として処理を行い、機能的な違いはありません。
パラメタ
ldap_init()、またはldapssl_init()で通知された、セションハンドルを指定します。
復帰値
この関数では、復帰値としてLDAPエラーコードを返します。LDAPエラーコードの値については、“メッセージ集”の“LDAPエラーコード”を参照してください。
正常終了の場合 ： LDAP_SUCCESS
異常終了の場合 ： LDAP_SUCCESS 以外のLDAPエラーコード
注意事項
セションハンドルの解放
ldap_unbind()は、指定されたセションハンドルを解放してから呼出し元に復帰します。
このため、ldap_unbind()が終了した後では、セションハンドル(ldパラメタ)を使用できなくなります。
名前
ldap_unbind_s
形式
#include "idldap.h" int ldap_unbind_s( LDAP *ld );
機能説明
この関数は、リポジトリサーバとのコネクション解放とセションのクローズをします。ldap_unbind()とldap_unbind_s()は、どちらも同期型として処理を行い、機能的な違いはありません。
パラメタ
ldap_init()、またはldapssl_init()で通知された、セションハンドルを指定します。
復帰値
この関数では、復帰値としてLDAPエラーコードを返します。LDAPエラーコードの値については、“メッセージ集”の“LDAPエラーコード”を参照してください。
正常終了の場合 ： LDAP_SUCCESS
異常終了の場合 ： LDAP_SUCCESS 以外のLDAPエラーコード
注意事項
セションハンドルの解放
ldap_unbind_s()は、指定されたセションハンドルを解放してから呼出し元に復帰します。
このため、ldap_unbind_s()が終了した後では、セションハンドル(ldパラメタ)を使用できなくなります。