GSS_INIT_SEC_CONTEXT(3)

Programmer's Manual

GSS_INIT_SEC_CONTEXT(3)

名称

gss_init_sec_context — ピア (相手側) アプリケーションでセキュリティコンテキストを開始します

書式

#include < gssapi/gssapi.h>

OM_uint32
gss_init_sec_context( OM_uint32 *minor_status, const gss_cred_id_t initiator_cred_handle, gss_ctx_id_t *context_handle, const gss_name_t target_name, const gss_OID mech_type, OM_uint32 req_flags, OM_uint32 time_req, const gss_channel_bindings_t input_chan_bindings, const gss_buffer_t input_token, gss_OID *actual_mech_type, gss_buffer_t output_token, OM_uint32 *ret_flags, OM_uint32 *time_rec);

解説

アプリケーションとリモートピア (相手側) の間のセキュリティコンテキストの確立を開始します。最初に、 input_token パラメータは GSS_C_NO_BUFFER として、または、長さフィールドが値 0 を含む gss_buffer_desc オブジェクトへのポインタとして指定されるべきです。このルーチンは、ピアアプリケーションに転送されるべきである output_token を返します、ここで、ピアアプリケーションは、それを gss_accept_sec_context(3) に与えます。トークンを送信する必要がないなら、 gss_init_sec_context() は、output_token 引数の length field を 0 に設定することによって、これを示します。コンテキストの確率を完了するために、1 つ以上の応答トークンが、ピアアプリケーションから要求されます。そうであれば、 gss_init_sec_context() は、補助情報ビット GSS_S_CONTINUE_NEEDED を含む状態を返します。この場合、 gss_init_sec_context() は、input_token パラメータによって応答トークンを gss_init_sec_context() へ渡して、応答トークンがピアアプリケーションから受信されるとき、再び呼び出されるべきです。

移植性のあるアプリケーションは、トークンの長さを使用して設定され、トークンが、送信するか、または待つ必要があるかどうか決定するために状態を返すべきです。したがって、一般的な移植性のある呼び出し側は、ループ中で、常に gss_init_sec_context() を呼び出すべきです:

int context_established = 0; 
gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; 
       ... 
input_token->length = 0; 
 
while (!context_established) { 
  maj_stat = gss_init_sec_context(&min_stat, 
      cred_hdl, 
      &context_hdl, 
      target_name, 
      desired_mech, 
      desired_services, 
      desired_time, 
      input_bindings, 
      input_token, 
      &actual_mech, 
      output_token, 
      &actual_services, 
      &actual_time); 
  if (GSS_ERROR(maj_stat)) { 
    report_error(maj_stat, min_stat); 
  }; 
 
  if (output_token->length != 0) { 
    send_token_to_peer(output_token); 
    gss_release_buffer(&min_stat, output_token) 
  }; 
  if (GSS_ERROR(maj_stat)) { 
 
    if (context_hdl != GSS_C_NO_CONTEXT) 
      gss_delete_sec_context(&min_stat, 
        &context_hdl, 
        GSS_C_NO_BUFFER); 
    break; 
  }; 
 
  if (maj_stat & GSS_S_CONTINUE_NEEDED) { 
    receive_token_from_peer(input_token); 
  } else { 
    context_established = 1; 
  }; 
};

ルーチンが値 GSS_S_CONTINUE_NEEDED を含んでいるメジャー状態を返すときはいつも、コンテキストが、完全に確立されるわけではなく、次の制限が出力パラメータに適用されます:

time_rec パラメータを通して返された値は、付随の ret_flags パラメータが、メッセージごとのサービスが成功して完了した状態より前に適用されたことを示す、ビット GSS_C_PROT_READY_FLAG を含むまで、未定義で、 actual_mech_type パラメータを通して返された値は、ルーチンが GSS_S_COMPLETE の主要な状態値を返すまで、未定義です。
ret_flags パラメータを通して返された GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, GSS_C_INTEG_FLAG と GSS_C_ANON_FLAG ビットの値は、実現が、コンテキストが成功して確立されるなら、有効となることが期待される値を含むべきです。特に、アプリケーションが req_flags 引数を通して委任または匿名の認証のようなサービスを要求していて、そのようなサービスが、基本的なメカニズムから利用可能でないなら、 gss_init_sec_context() は、サービスが提供されないトークンを生成し、サービスがサポートされない、 ret_flags 引数を通して示すべきです。アプリケーションが、(サービスがないとき継続することができないなら) gss_delete_sec_context(3) を呼び出すことによってコンテキストの確立を中止することを選択するか、または、(サービスが強制的ではなく、単に望まれていたなら) トークンを転送して、コンテキスト確立を継続することを選択します。
ret_flags 中の GSS_C_PROT_READY_FLAG と GSS_C_TRANS_FLAG ビットの値は、コンテキストが完全に確立されるか否かに関係なく、 gss_init_sec_context() が返る、その時点で実際の状態を示すべきです。
メッセージ毎の保護をサポートする GSS-API 実装は、(すなわち、 GSS_S_COMPLETE ステータスコードと同時に起こるとき) 呼び出し側に返される、最終的な ret_flags に GSS_C_PROT_READY_FLAG を設定することが奨励されます。しかしながら、アプリケーションは、フラグが GSS-API のバージョン 1 で定義されなかったように、この振る舞いに依存するべきではありません。代わりに、アプリケーションは、どのようなメッセージ毎のサービスが GSS_C_INTEG_FLAG と GSS_C_CONF_FLAG 値に従ってコンテキストの確立が成功した後に、利用可能であるかを決定するべきです。
ret_flags 引数内の他のすべてのビットは、0 に設定されるべきです。

gss_init_sec_context() の初期の呼び出しが失敗するなら、実装は、コンテキストオブジェクトを作成するべきでなくて、 context_handle パラメータの値を、これを示すように GSS_C_NO_CONTEXT に設定されたままにするべきです。万一、その後の呼び出しでの失敗の場合には、実装は、"半分構築"のセキュリティコンテキストを削除するのが許可されますが (その場合、それは context_handle パラメータに GSS_C_NO_CONTEXT 設定するべきです)、好ましい振る舞いは、セキュリティコンテキストをアプリケーションが ( gss_delete_sec_context(3) を使用して) 削除するように変更しないままの状態とすることです。 gssXdeleteXsecXcontext(3) )。

コンテキスト確立の間に、情報の状態ビット GSS_S_OLD_TOKEN と GSS_S_DUPLICATE_TOKEN は、致命的なエラーを示し、GSS-API メカニズムは、常に GSS_S_FAILURE の通常のエラーと関連しているそれらを返すべきです。組み合わせのためのこの要件は、GSS-API 仕様のバージョン 1 に存在しなかったので、バージョン 1 の実装以降を実行したいアプリケーションは、これらのコードの特別な場合でなければなければなりません。

パラメータ

minor_status

メカニズム特有のステータスコード。

initiator_cred_handle

要求された資格証明のためのハンドル。デフォルトの開始プログラムのプリンシパルとして動作するために GSS_C_NO_CREDENTIAL を供給します。デフォルトの開始プログラムが定義されないなら、関数は、 GSS_S_NO_CRED. を返します。

context_handle

新しいコンテキストのためのコンテキストハンドル。最初の呼び出しのために GSS_C_NO_CONTEXT を供給します。連続した呼び出しの最初の呼び出しによって返された値を使用します。このコンテキストハンドルに関連しているリソースは、 gss_delete_sec_context() への呼び出しで使用した後にアプリケーションによって解放されなければなりません。

target_name

ターゲットの名前

mech_type

必要なメカニズムのオブジェクト ID。実装の特定のデフォルトを取得するためには、 GSS_C_NO_OID を供給します。

req_flags

コンテキストが、特定のサービスオプションをサポートすることをそれぞれ要求する、様々な独立しているフラグを含んでいます。シンボル名が、各フラグに提供され、必要なフラグに対応するシンボル名は、ビットマスク値を形成するために論理的 OR されるべきです。フラグは、次の通りです:

time_req

コンテキストが有効なままで残るべきである、必要な秒数。デフォルト有効期間を要求するためには、0 を供給します。

input_chan_bindings

アプリケーションで指定されたバインド。アプリケーションは、セキュリティコンテキストへのチャネル識別情報を安全にバインドすることができます。チャネルのバインドが使用されていないなら、 GSS_C_NO_CHANNEL_BINDINGS を指定します。

input_token

ピアアプリケーションから受信されたトークン。初期の呼び出しで GSS_C_NO_BUFFER または値 GSS_C_EMPTY_BUFFER を含むバッファへのポインタを供給します。

actual_mech_type

使用される実際のメカニズム。このパラメータで返された OID は、読み込み専用として扱われるべきである静的な記憶域へのポインタとなります。特に、アプリケーションは、それを解放することを試みるべきではありません。必要でないなら、 NULL を指定します。

output_token

ピアアプリケーションに送信されるトークン。返されたバッファの長さのフィールドが 0 であるなら、トークンをピアアプリケーションに送信する必要はありません。このバッファに関連している記憶域は、 gss_release_buffer(3) への呼び出しで使用した後アプリケーションによって解放されなければなりません。

ret_flags

コンテキストが、特定のサービスオプションをサポートすることをそれぞれ示す、様々な独立しているフラグを含んでいます。必要でないなら、 NULL を指定します。シンボル名が各フラグに提供され、必要なフラグに対応するシンボル名は、与えられたオプションがコンテキストでサポートされているかどうかをテストするために ret_flags 値で論理的 AND されるべきです。フラグは、次の通りです:

GSS_C_DELEG_FLAG

GSS_C_MUTUAL_FLAG

GSS_C_REPLAY_FLAG

GSS_C_SEQUENCE_FLAG

GSS_C_CONF_FLAG

GSS_C_INTEG_FLAG

GSS_C_ANON_FLAG

GSS_C_PROT_READY_FLAG

GSS_C_TRANS_FLAG

他のすべてのビットは、0 に設定されるべきです。

time_rec

コンテキストが有効なままで残っている秒数。実装がコンテキストの期限切れをサポートしないなら、値 GSS_C_INDEFINITE が返されます。必要でないなら、 NULL を指定します。

戻り値

規格

歴史

gss_init_sec_context のマニュアルページは、 FreeBSD 7.0 ではじめて登場しました。

作者

John Wray, Iris Associates

COPYRIGHT

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

January 26, 2010

FreeBSD

YOS OPENSONAR

名称

書式

解説

パラメータ

戻り値

関連項目

規格

歴史

作者

COPYRIGHT