compact3

javax.security.sasl

インタフェースSaslClient

public interface SaslClient

SASL認証をクライアントとして実行します。

プロトコル・ライブラリ(LDAPライブラリなど)は、特定のSASLメカニズムによって定義された認証を実行するために、このクラスのインスタンスを取得します。SaslClientインスタンス・プロセスでメソッドを呼び出すと、チャレンジが処理され、SaslClientによって実装されたSASLメカニズムに従って応答が作成されます。認証が処理されるときに、SASLクライアントの認証交換の状態が暗号化されます。

次に、LDAPライブラリがどのようにSaslClientを使用するかの例を示します。まず、SaslClientのインスタンスを取得します。

 SaslClient sc = Sasl.createSaslClient(mechanisms,
     authorizationId, protocol, serverName, props, callbackHandler);

これで、クライアントを認証に使用できます。たとえば、LDAPライブラリは次のようにクライアントを使用できます。

 // Get initial response and send to server
 byte[] response = (sc.hasInitialResponse() ? sc.evaluateChallenge(new byte[0]) :
     null);
 LdapResult res = ldap.sendBindRequest(dn, sc.getName(), response);
 while (!sc.isComplete() &&
     (res.status == SASL_BIND_IN_PROGRESS || res.status == SUCCESS)) {
     response = sc.evaluateChallenge(res.getBytes());
     if (res.status == SUCCESS) {
         // we're done; don't expect to send another BIND
         if (response != null) {
             throw new SaslException(
                 "Protocol error: attempting to send response after completion");
         }
         break;
     }
     res = ldap.sendBindRequest(dn, sc.getName(), response);
 }
 if (sc.isComplete() && res.status == SUCCESS) {
    String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
    if (qop != null
        && (qop.equalsIgnoreCase("auth-int")
            || qop.equalsIgnoreCase("auth-conf"))) {

      // Use SaslClient.wrap() and SaslClient.unwrap() for future
      // communication with server
      ldap.in = new SecureInputStream(sc, ldap.in);
      ldap.out = new SecureOutputStream(sc, ldap.out);
    }
 }

メカニズムに初期応答が含まれている場合、ライブラリは空のチャレンジでevaluateChallenge()を呼び出し、初期応答を取得します。IMAP4などのプロトコルでは、サーバーへの最初の認証コマンドによる初期応答が含まれていないため、最初にhasInitialResponse()またはevaluateChallenge()を呼び出さないで認証を開始します。サーバーが認証コマンドに応答すると、初期チャレンジが送信されます。クライアントが最初にデータを送信するSASLメカニズムでは、サーバーはデータを含まないチャレンジを発行しておかなければいけません。それによって、空のチャレンジによるevaluateChallenge()への呼出しがクライアントで行われます。

導入されたバージョン:

1.5

関連項目:

Sasl、SaslClientFactory

メソッドのサマリー

修飾子と型	メソッドと説明
void	dispose() SaslClientが使用しているシステム・リソースまたはセキュリティ上重要な情報を破棄します。
byte[]	evaluateChallenge(byte[] challenge) チャレンジ・データを評価して、応答を作成します。
String	getMechanismName() このSASLクライアントのIANA登録されたメカニズム名。
Object	getNegotiatedProperty(String propName) ネゴシエートされたプロパティを取り出します。
boolean	hasInitialResponse() このメカニズムにオプションの初期応答が含まれているかどうかを調べます。
boolean	isComplete() 認証交換が完了したかどうかを判定します。
byte[]	unwrap(byte[] incoming, int offset, int len) サーバーから受信したバイト配列をラップ解除します。
byte[]	wrap(byte[] outgoing, int offset, int len) サーバーに送信するバイト配列をラップします。

メソッドの詳細

getMechanismName

String getMechanismName()

このSASLクライアントのIANA登録されたメカニズム名。(CRAM-MD5、GSSAPIなど)

戻り値:

IANA登録されたメカニズム名を表すnull以外の文字列。

hasInitialResponse

boolean hasInitialResponse()

このメカニズムにオプションの初期応答が含まれているかどうかを調べます。trueの場合、呼出し側は初期応答を取得するために空の配列でevaluateChallenge()を呼び出す必要があります。

戻り値:

このメカニズムに初期応答が含まれている場合はtrue。

evaluateChallenge

byte[] evaluateChallenge(byte[] challenge)
                  throws SaslException

チャレンジ・データを評価して、応答を作成します。認証プロセス時にチャレンジがサーバーから受信された場合は、サーバーに送信する次の適切な応答を準備するために、このメソッドが呼び出されます。

パラメータ:

challenge - サーバーから送信されたnull以外のチャレンジ。チャレンジ配列の長さは0の場合もある。

戻り値:

サーバーに送信する応答(nullの場合もある)。チャレンジが「SUCCESS」状態を伴い、チャレンジにクライアントがその状態を更新するためのデータしか含まれず、さらにサーバーに送信する応答がない場合にnullになる。クライアントがデータを含まない応答を送信する場合、応答は長さ0のバイト配列となる。

例外:

SaslException - チャレンジの処理時または応答の作成時にエラーが発生した場合。

isComplete

boolean isComplete()

認証交換が完了したかどうかを判定します。このメソッドはいつでも呼び出せますが、通常は呼出し側がサーバーから交換が完了したという通知を受けるまでは呼び出されません(プロトコル固有の方法)。

戻り値:

認証交換が完了した場合はtrue、そうでない場合はfalse。

unwrap

byte[] unwrap(byte[] incoming,
              int offset,
              int len)
       throws SaslException

サーバーから受信したバイト配列をラップ解除します。このメソッドは、認証交換が完了した(isComplete()がtrueを返した)後で、認証交換の保護品質としてネゴシエートされた整合性または機密性が備わっている場合にのみ呼び出されます。そうでない場合は、IllegalStateExceptionがスローされます。

incomingは、長さを表す最初の4つのオクテット・フィールドを除く、RFC 2222に定義されたSASLバッファの内容です。offsetとlenは、incomingの使用部分を指定します。

パラメータ:

incoming - サーバーから受信したエンコードされたバイトを含むnull以外のバイト配列。

offset - 使用するバイトのincomingでの開始位置。

len - 使用するincomingのバイト数。

戻り値:

デコードされたバイトを含むnull以外のバイト配列。

例外:

SaslException - incomingを正常にラップ解除できない場合。

IllegalStateException - 認証交換が完了しなかった場合、またはネゴシエートされた保護品質に整合性も機密性も備わっていない場合。

wrap

byte[] wrap(byte[] outgoing,
            int offset,
            int len)
     throws SaslException

サーバーに送信するバイト配列をラップします。このメソッドは、認証交換が完了した(isComplete()がtrueを返した)後で、認証交換の保護品質としてネゴシエートされた整合性または機密性が備わっている場合にのみ呼び出されます。そうでない場合は、IllegalStateExceptionがスローされます。

このメソッドの結果は、長さを表す最初の4つのオクテット・フィールドを除く、RFC 2222に定義されたSASLバッファの内容を構成します。offsetとlenは、outgoingの使用部分を指定します。

パラメータ:

outgoing - エンコードするバイトを含むnull以外のバイト配列。

offset - 使用するバイトのoutgoingでの開始位置。

len - 使用するoutgoingのバイト数。

戻り値:

エンコードされたバイトを含むnull以外のバイト配列。

例外:

SaslException - outgoingを正常にラップできない場合。

IllegalStateException - 認証交換が完了しなかった場合、またはネゴシエートされた保護品質に整合性も機密性も備わっていない場合。

getNegotiatedProperty

Object getNegotiatedProperty(String propName)

ネゴシエートされたプロパティを取り出します。このメソッドは、認証交換が完了した(isComplete()がtrueを返した)後でのみ呼び出すことができます。そうでない場合は、IllegalStateExceptionがスローされます。

パラメータ:

propName - null以外のプロパティ名。

戻り値:

ネゴシエートされたプロパティの値。nullの場合は、プロパティがネゴシエートされなかったか、このメカニズムに適用できない。

例外:

IllegalStateException - この認証交換が完了しなかった場合

dispose

void dispose()
      throws SaslException

SaslClientが使用しているシステム・リソースまたはセキュリティ上重要な情報を破棄します。このメソッドを呼び出すと、SaslClientインスタンスが無効になります。このメソッドはべき等です。

例外:

SaslException - リソースを破棄しているときに問題が発生した場合。