GSSContextは、GSSContextのインスタンス化、およびいずれかのcreateContextメソッドの呼出しにより作成されます。GSSManagerクラスは、他の重要なGSS APIクラスのファクトリとして機能します。これにより、GSSContext、GSSCredentialおよびGSSNameインタフェースを実装するクラスのインスタンスを作成できます。

SampleClientは、GSSManagerのstaticメソッドgetInstanceを呼び出すことにより、デフォルトのGSSManagerサブクラスのインスタンスを取得します。

GSSManager manager = GSSManager.getInstance();

デフォルトGSSManagerサブクラスのcreate*メソッド(createContextなど)が返すクラスの実装は、基盤となるテクノロジとしてKerberosをサポートします。

イニシエータ側でコンテキストを作成するGSSManagerファクトリ・メソッドは、次のシグニチャを保持します。

GSSContext createContext(GSSName peer, Oid mech, 
            GSSCredential myCred, int lifetime);

次の項では、引数について説明し、その後にcreateContextの完全な呼出しを示します。

コンテキストのインスタンス化が完了したら、コンセプト・アクセプタを使用してコンテキストを実際に確立する前に、コンテキスト・イニシエータで、目的のセキュリティ・コンテキストの特性を決定する様々なオプションを設定できます。それらの各オプションは、インスタンス化されたコンテキスト上でrequestメソッドを呼び出すことで設定されます。大半のrequestメソッドは、その機能を要求するかどうかを示すboolean引数を取ります。要求は、常に受け入れられるわけではないため、コンテキストの確立後に、いずれかのgetメソッドを呼び出して、それを確認できます。

SampleClientは、次を要求します。

1. 相互認証。コンテキスト・イニシエータは、常にアクセプタに対して認証されます。イニシエータが相互認証を要求すると、アクセプタもイニシエータに認証されます。
2. 機密性。機密性を要求するとは、wrapという名前のコンテキスト・メソッドの暗号化を有効にすることを意味します。暗号が実際に使用されるのは、wrapメソッドに渡されるMessagePropオブジェクトにより機密性が要求される場合だけです。
3. 整合性。これは、wrapおよびgetMICメソッドの整合性を要求します。整合性が要求されると、これらのメソッドの呼出し時に、メッセージ整合コード(MIC)として知られる暗号化タグが生成されます。getMICの呼出しにより返されるトークン内に、生成されたMICが含まれます。wrapが呼び出されると、MICがメッセージ(元のメッセージまたはメッセージ暗号化の結果、機密性が適用されたかどうかにより異なる)とともに1つのトークンの一部としてパッケージ化されます。次に、メッセージに対するMICを検証して、メッセージが途中で変更されていないことを確認できます。

GSSException contextに対してこれらの要求を生成するSampleClientコードを、次に示します。

context.requestMutualAuth(true);  // Mutual authentication
context.requestConf(true);  // Will use encryption later
context.requestInteg(true); // Will use integrity later

コンテキストが確立された後、クライアントは、アクセサ・メソッド(getMutualAuthState、getConfState、getIntegStateなど)を呼び出して、コンテキスト状態を明示的に確認し、いずれかのセキュリティ・コンテキストが望ましい状態でない場合はそのコンテキストを破棄する必要があります。

SampleClientは、GSSContextのインスタンス化および使用するコンテキスト・オプションの指定後に、SampleServerとのセキュリティ・コンテキストを実際に確立できます。このために、SampleClientはループ構造を保持します。各ループにより、次が反復実行されます

1. コンテキストのinitSecContextメソッドの呼出し。最初の呼出しの場合、メソッドにはnullのトークンが渡されます。それ以外の場合、SampleServerからSampleClientに直前に送信されたトークン(SampleServerによるacceptSecContextの呼出しで生成されるトークン)が渡されます。
2. initSecContextにより返されたトークン(存在する場合)のSampleServerへの送信。initSecContextへの最初の呼出しでは、常にトークンが生成されます。最後の呼出しでは、トークンが返されない場合があります。
3. コンテキストが確立されたかどうかの確認。確立されていない場合、SampleClientはSampleServerから別のトークンを受け取って、次のループ処理を開始します。

initSecContextから返される、またはSampleServerから受け取るトークンは、バイト配列に格納されます。トークンは、SampleClientおよびSampleServer間での送信時に不透明なデータとして処理され、Java GSS-APIメソッドにより解釈されます。

initSecContext引数は、トークン、トークン開始位置の配列内の開始オフセット、およびトークンの長さを含むバイト配列です。最初の呼出しでは、SampleClientは、SampleServerからトークンをまだ受け取っていないため、nullのトークンを渡します。

SampleServerとトークンを交換する際、SampleClientは、SampleServerへのソケット接続用入力および出力ストリームを使用して設定した、DataInputStream inStreamおよびDataOutputStream outStreamを使用します。トークンを記述する場合、常に、トークンのバイト数を最初に記述してから、トークン自体を記述してください。その理由は、「SampleClientとSampleServerのメッセージ交換」セクションの導入部で説明します。

次に、SampleClientのコンテキスト確立ループ、およびクライアントおよびサーバーの実体、相互認証を実際に行うかどうかなどの情報を表示するコードを示します。

byte[] token = new byte[0];

while (!context.isEstablished()) {

    // token is ignored on the first call
    token = context.initSecContext(token, 0, token.length);

    // Send a token to the server if one was generated by
    // initSecContext
    if (token != null) {
        System.out.println("Will send token of size "
                   + token.length + " from initSecContext.");
        outStream.writeInt(token.length);
        outStream.write(token);
        outStream.flush();
    }

    // If the client is done with context establishment
    // then there will be no more tokens to read in this loop
    if (!context.isEstablished()) {
        token = new byte[inStream.readInt()];
        System.out.println("Will read input token of size "
                   + token.length
                   + " for processing by initSecContext");
        inStream.readFully(token);
    }
}

System.out.println("Context Established! ");
System.out.println("Client is " + context.getSrcName());
System.out.println("Server is " + context.getTargName());
if (context.getMutualAuthState())
    System.out.println("Mutual authentication took place!");

SampleClient GSSContextのインスタンス化で説明したように、GSSContextは、GSSManagerをインスタンス化して、createContextメソッドのいずれかを呼び出すことで作成されます。

SampleClientと同様、SampleServerは、GSSManagerのstaticメソッドgetInstanceを呼び出すことにより、デフォルトのGSSManagerサブクラスのインスタンスを取得します。

GSSManager manager = GSSManager.getInstance();

アクセプタ側でコンテキストを作成するGSSManagerファクトリ・メソッドは、次のシグニチャを保持します。

GSSContext createContext(GSSCredential myCred);

SampleServerの場合と同様、GSSCredential引数にnullを渡す場合、デフォルトのクレデンシャルが使用されます。コンテキストは、次の方法でインスタンス化されます。

GSSContext context = manager.createContext((GSSCredential)null);

SampleServerは、GSSContextをインスタンス化したあとで、SampleClientとのセキュリティ・コンテキストを確立できます。これを実行するため、SampleServerはコンテキストが確立されるまで反復するループ構造を保持します。各ループにより、次の操作が反復実行されます。

1. SampleClientからのトークンの受け取り。このトークンは、SampleClient initSecContext呼出しの結果です。
2. コンテキストのacceptSecContextメソッドの呼び出し、および直前に受け取ったトークンのメソッドへの引渡し。
3. acceptSecContextがトークンを返す場合、SampleServerはこのトークンをSampleClientに送信し、コンテキストがまだ確立されていない場合、次のループ処理を開始します。

acceptSecContextから返される、またはSampleClientから受け取るトークンは、バイト配列に格納されます。

acceptSecContext引数は、トークン、トークン開始位置の配列内の開始オフセット、およびトークンの長さを含むバイト配列です。

SampleClientとトークンを交換する際、SampleServerは、SampleClientへのソケット接続用入力および出力ストリームを使用して設定した、DataInputStream inStreamおよびDataOutputStream outStreamを使用します。

次に、SampleServerのコンテキスト確立ループを示します。

byte[] token = null;

while (!context.isEstablished()) {

    token = new byte[inStream.readInt()];
    System.out.println("Will read input token of size "
       + token.length
       + " for processing by acceptSecContext");
    inStream.readFully(token);
    
    token = context.acceptSecContext(token, 0, token.length);
    
    // Send a token to the peer if one was generated by
    // acceptSecContext
    if (token != null) {
        System.out.println("Will send token of size "
           + token.length
           + " from acceptSecContext.");
        outStream.writeInt(token.length);
        outStream.write(token);
        outStream.flush();
    }
}

System.out.print("Context Established! ");
System.out.println("Client is " + context.getSrcName());
System.out.println("Server is " + context.getTargName());
if (context.getMutualAuthState())
    System.out.println("Mutual authentication took place!");

wrapメソッドは、メッセージ交換用のプライマリ・メソッドです。

SampleClientにより呼び出されるwrapメソッドのシグニチャは、次のようになります。

byte[] wrap (byte[] inBuf, int offset, interface len, 
                MessageProp msgProp)

wrapに、メッセージ(inBuf内)、inBuf内でのメッセージ開始位置のオフセット(offset)、およびメッセージの長さ(len)を渡します。使用するQOP (Quality-of-Protection)、および機密性(暗号化)が必要かどうかを指定する際に使用するMessagePropも渡します。QOP値により、使用する暗号化整合および暗号化(必要な場合)アルゴリズムが決定されます。基盤となるメカニズムのプロバイダにより、さまざまなQOP値に対応するアルゴリズムが指定されます。たとえば、Kerberos V5に対応する値は、RFC 1964のセクション4.2で定義されています。デフォルトのQOPを要求する場合は、通常QOP値に0を指定します。

wrapメソッドは、メッセージを含むトークンおよびその暗号化メッセージ整合コード(MIC)を返します。MessagePropにより機密性が指定されている場合、トークンに格納されたメッセージは暗号化されます。返されるトークンは、不透明なデータとして扱われるため、その形式について知る必要はありません。返されるトークンをピア・アプリケーションに送信すると、unwrapメソッドが呼び出されてトークンの「ラップが解除」され、元のメッセージの取得および整合性の検証が行われます。

指定されたメッセージの暗号化メッセージ整合コード(MIC)を含むトークンの取得だけを行う場合、getMICを呼び出します。たとえば、ピアが同じデータを保持していることを確認する場合、データ自体を相互に転送しなくても、データのMICを転送するだけで目的を達成できます。

SampleServerにより呼び出されるgetMICメソッドのシグニチャは、次のようになります。

byte[] getMIC (byte[] inMsg, int offset, int len,
            MessageProp msgProp)

getMICに、メッセージ(inMsg内)、inMsg内でのメッセージ開始位置のオフセット(offset)、およびメッセージの長さ(len)を渡します。使用するQOP (Quality-of-Protection)の指定に使うMessagePropも渡します。デフォルトのQOPを要求する場合は、通常QOP値に0を指定します。

getMICにより作成されたトークンおよびMICの計算に使用するメッセージ(またはMICを計算する予定のメッセージ)を保持する場合、verifyMICメソッドを呼び出して、メッセージのMICを検証できます。検証が成功する(GSSExceptionがスローされない)場合、メッセージが、MIC計算時のメッセージと正確に一致することが保証されます。通常、アプリケーションからメッセージを受け取るピアは、MICを検証して、途中でメッセージが変更または破損していないかどうかを確認できるように、MICも期待します。ノート: メッセージに加え、MICも必要であることが前もってわかっている場合は、wrapおよびunwrapメソッドを使用する方が便利です。ただし、メッセージとMICを別個に受け取る状況も考えられます。

次に、前述のgetMICに対応するverifyMICの署名を示します:

void verifyMIC (byte[] inToken, int tokOffset, int tokLen,
        byte[] inMsg, int msgOffset, int msgLen,
        MessageProp msgProp);

これにより、inMsg (長さがmsgLenで、オフセットmsgOffsetから始まる)内のメッセージに対応する、inToken (長さがtokLenで、オフセットtokOffsetから始まる)内のMICの検証が実行されます。基盤となるメカニズムは、MessagePropを使用して呼出し側に情報(メッセージに適用された保護の強さを示すQOPなど)を返します。

メッセージの暗号化、MICの計算、および結果のSampleServerへの送信を実行するSampleClientコードを、次に示します。

byte[] messageBytes = "Hello There!\0".getBytes();

/*
 * The first MessageProp argument is 0 to request
 * the default Quality-of-Protection.
 * The second argument is true to request
 * privacy (encryption of the message).
 */
MessageProp prop =  new MessageProp(0, true);

/*
 * Encrypt the data and send it across. Integrity protection
 * is always applied, irrespective of encryption.
 */
token = context.wrap(messageBytes, 0, messageBytes.length, 
    prop);
System.out.println("Will send wrap token of size " 
    + token.length);
outStream.writeInt(token.length);
outStream.write(token);
outStream.flush();

次のSampleServerコードは、SampleClientにより送信されたラップ済のトークンを読み取り、「ラップを解除」して元のメッセージを取得し、整合性を検証します。この場合、メッセージが暗号化されているため、ラップの解除には復号化も含まれます。

/*
 * Create a MessageProp which unwrap will use to return 
 * information such as the Quality-of-Protection that was 
 * applied to the wrapped token, whether or not it was 
 * encrypted, etc. Since the initial MessageProp values
 * are ignored, it doesn't matter what they are set to.
 */
MessageProp prop = new MessageProp(0, false);

/* 
 * Read the token. This uses the same token byte array 
 * as that used during context establishment.
 */
token = new byte[inStream.readInt()];
System.out.println("Will read token of size " 
    + token.length);
inStream.readFully(token);

byte[] bytes = context.unwrap(token, 0, token.length, prop);
String str = new String(bytes);
System.out.println("Received data \""
    + str + "\" of length " + str.length());
System.out.println("Encryption applied: "
    + prop.getPrivacy());

次に、SampleServerは、復号化されたメッセージのMICを生成して、SampleClientに送信します。このことは必須ではなく、単に、復号化されたメッセージのMICの生成を示しています。復号化されたメッセージは、SampleClientがラップしてSampleServerに送信した元のメッセージと正確に同じになるはずです。SampleServerがこれを生成してSampleClientに送信し、その後SampleClientが検証することで、SampleServerが保持する復号化済のメッセージは、SampleClientから送信された元のメッセージと正確に一致することが、SampleClientに対して保証されます。

/*
 * First reset the QOP of the MessageProp to 0
 * to ensure the default Quality-of-Protection
 * is applied.
 */
prop.setQOP(0);

token = context.getMIC(bytes, 0, bytes.length, prop);

System.out.println("Will send MIC token of size " 
                   + token.length);
outStream.writeInt(token.length);
outStream.write(token);
outStream.flush();

次のSampleClientコードは、SampleServerにより計算された(復号化済メッセージに対する) MICを読み取って、このMICが元のメッセージのMICなのかどうかを検証します。これにより、SampleServerが保持する復号化されたメッセージが、元のメッセージと同じであることが保証されます。

token = new byte[inStream.readInt()];
System.out.println("Will read token of size " + token.length);
inStream.readFully(token);

/* 
 * Recall messageBytes is the byte array containing
 * the original message and prop is the MessageProp 
 * already instantiated by SampleClient.
 */
context.verifyMIC(token, 0, token.length, 
          messageBytes, 0, messageBytes.length,
          prop);

System.out.println("Verified received MIC for message.");