GSS-API のプログラミング

付録 B GSS-API リファレンス

この付録は、次のような節から構成されています。

これ以外の GSS-API 定義については、ファイル gssapi.h を参照してください。

GSS-API 関数

次の表に、GSS-API 関数のリストを示します。各関数の詳細は、それぞれのマニュアルページを参照してください。また、旧バージョンの GSS-API 関数も参照してください。

表 B–1 GSS-API 関数

ヘッダー 

機能 

gss_acquire_cred()

大域的な ID を取得する。つまり、すでに存在している資格の GSS-API 資格ハンドルを取得する。 

gss_add_cred()

資格を増分的に作成する。 

gss_inquire_cred()

資格についての情報を取得する。 

gss_inquire_cred_by_mech()

資格についての機構ごとの情報を取得する。 

gss_release_cred()

資格ハンドルを破棄する。 

gss_init_sec_context()

ピアとなるアプリケーションとのセキュリティコンテキストを起動する。 

gss_accept_sec_context()

ピアとなるアプリケーションが起動したセキュリティコンテキストを受け入れる。 

gss_delete_sec_context()

セキュリティコンテキストを破棄する。 

gss_process_context_token()

ピアとなるアプリケーションからのセキュリティコンテキストでトークンを処理する。 

gss_context_time()

コンテキストが有効である時間を決定する。 

gss_inquire_context()

セキュリティコンテキストについての情報を取得する。 

gss_wrap_size_limit()

gss_wrap() をコンテキストに実行するためにトークンのサイズの制限を決定する。

gss_export_sec_context()

セキュリティコンテキストを別のプロセスに転送する。 

gss_import_sec_context()

転送されたコンテキストをインポートする。 

gss_get_mic()

メッセージの暗号化メッセージ整合性コード (MIC) を計算する。つまり、整合性サービス。 

gss_verify_mic()

MIC をメッセージに対して検査する。つまり、受信したメッセージの整合性を検証する。 

gss_wrap()

MIC をメッセージに添付し、メッセージの内容を暗号化する (後者は省略可能)。 

gss_unwrap()

添付された MIC でメッセージを検証し、必要であれば、メッセージの内容を復号化する。 

gss_import_name()

連続する文字列名を内部形式に変換する。 

gss_display_name()

内部形式名をテキストに変換する。 

gss_compare_name()

2 つの内部形式名を比較する。 

gss_release_name()

内部形式名を破棄する。 

gss_inquire_names_for_mech()

指定した機構がサポートする名前型のリストを表示する。 

gss_inquire_mechs_for_name()

指定した名前型をサポートする機構のリストを表示する。 

gss_canonicalize_name()

内部名を MN に変換する。 

gss_export_name()

MN をエクスポート形式に変換する。 

gss_duplicate_name()

内部名のコピーを作成する。 

gss_add_oid_set_member()

オブジェクト識別子を集合に追加する。 

gss_display_status()

GSS-API 状態コードをテキストに変換する。 

gss_indicate_mechs()

使用できる実際の認証機構を決定する。 

gss_release_buffer()

バッファを破棄する。 

gss_release_oid_set()

オブジェクト識別子の集合を破棄する。 

gss_create_empty_oid_set()

オブジェクト識別子の空の集合を作成する。 

gss_test_oid_set_member()

オブジェクト識別子が集合のメンバーであるかどうかを決定する。 

旧バージョンの GSS-API 関数

この節では、旧バージョンの GSS-API 関数について説明します。

OID を処理する関数

次の関数は GSS-API の Sun の実装でサポートされています。これは、便宜上、旧バージョンの GSS-API で作成されたプログラムとの下位互換性のために提供されています。しかし、GSS-API の Sun 以外の実装ではサポートされていないため、これらの関数には依存すべきではありません。

これらの関数は機構名を文字列から OID に変換します。しかし、これらの関数を指定するのではなく、可能な限り、GSS-API が提供するデフォルトの機構を使用するべきです。

名前が変更された関数

次の関数は新しい関数に差し替えられました。どの場合も、新しい関数は古い関数と機能的に同等です。古い関数もサポートされますが、可能な限り、新しい関数に置き換えていくべきです。

GSS-API 状態コード

メジャー状態コードは OM_uint32 に符号化されます (図 B–1 を参照)。

図 B–1 メジャー状態の符号化

Graphic

GSS-API ルーチンが上位 16 ビットに 0 以外の値が入った GSS 状態コードを戻す場合、その呼び出しは失敗したことを示します。呼び出しエラーフィールドが 0 以外の場合、呼び出し側アプリケーションのルーチンの呼び出しにエラーがあったことを示します。表 B–2 に、呼び出しエラーのリストを示します。ルーチンエラーフィールドが 0 以外の場合、ルーチン固有のエラーのためにルーチンが失敗したことを示します。表 B–3 に、ルーチンエラーのリストを示します。上位 16 ビットが失敗または成功のどちらを示すかに関わらず、ルーチンは追加情報を状態コードの補足情報フィールドに設定できます。表 B–4 に、補足情報フィールドの個々のビットの意味を示します。

GSS-API メジャー状態コードの値

次の表に、GSS-API が戻す呼び出しエラーのリストを示します。これは、特定の言語バインディング (この場合は C) に固有なエラーのことです。

表 B–2 呼び出しエラー

エラー 

フィールドの値 

意味 

GSS_S_CALL_INACCESSIBLE_READ 

要求された入力パラメータを読み取れない。 

GSS_S_CALL_INACCESSIBLE_WRITE 

要求された出力パラメータに書き込めない。 

GSS_S_CALL_BAD_STRUCTURE 

パラメータの形式が間違っている。 

次の表に、GSS-API が戻すルーチンエラーのリストを示します。つまり、GSS-API 関数が戻す一般的なエラーのことです。

表 B–3 ルーチンエラー

エラー 

フィールドの値 

意味 

GSS_S_BAD_MECH 

要求された機構がサポートされていない。 

GSS_S_BAD_NAME 

提供された名前が無効である。 

GSS_S_BAD_NAMETYPE 

提供された名前型がサポートされていない。 

GSS_S_BAD_BINDINGS 

提供されたチャネルバインディングが間違っている。 

GSS_S_BAD_STATUS 

提供された状態コードが無効である。 

GSS_S_BAD_MIC, GSS_S_BAD_SIG 

トークンが持っている MIC が無効である。 

GSS_S_NO_CRED 

資格が提供されていない。あるいは、資格を使用またはアクセスできない。 

GSS_S_NO_CONTEXT 

コンテキストが全く確立されていない。 

GSS_S_DEFECTIVE_TOKEN 

トークンが無効である。 

GSS_S_DEFECTIVE_CREDENTIAL 

10 

資格が無効である。 

GSS_S_CREDENTIALS_EXPIRED 

11 

参照された資格の有効期間が終了している。 

GSS_S_CONTEXT_EXPIRED 

12 

コンテキストの有効期間が終了している。 

GSS_S_FAILURE 

13 

その他のエラー (テキストを参照)

GSS_S_BAD_QOP 

14 

要求された保護品質を提供できない。 

GSS_S_UNAUTHORIZED 

15 

当該操作はローカルのセキュリティポリシーによって禁止されている。 

GSS_S_UNAVAILABLE 

16 

当該操作またはオプションは使用できない。 

GSS_S_DUPLICATE_ELEMENT 

17 

要求された資格要素はすでに存在している。 

GSS_S_NAME_NOT_MN 

18 

提供された名前が機構名 (MN) ではない。 

ルーチンの説明では、GSS_S_COMPLETE という名前も使用していました。この値は 0 で、API エラーと補足情報ビットがどちらも存在しないことを示します。

次の表に、GSS-API 関数が戻す補足情報の値のリストを示します。

表 B–4 補足情報コード

コード 

ビット番号 

意味 

GSS_S_CONTINUE_NEEDED 

0 (LSB) 

gss_init_sec_context() または gss_accept_sec_context() だけが戻す。関数を完了させるには、もう一度ルーチンを呼び出す必要があることを示す。

GSS_S_DUPLICATE_TOKEN 

トークンは以前のトークンの複製である。 

GSS_S_OLD_TOKEN 

トークンの有効期間が終了している。 

GSS_S_UNSEQ_TOKEN 

後方にあるトークンをすでに処理している。 

GSS_S_GAP_TOKEN 

期待していたメッセージ毎トークンを受信していない。 

GSS メジャー状態コードの GSS_S_FAILURE は、実際の機構が特定の GSS–API 状態コードに定義されていないエラーを検出したことを示します。この場合、機構に固有な状態コード (マイナー状態コード) にエラーの詳細が提供されます。

状態コードについての詳細は、状態コードを参照してください。

状態コードの表示

gss_display_status() 関数は GSS-API 状態コードをテキスト形式に変換して、ユーザーに表示したり、テキストログに格納したりできます。gss_display_status() は一度に 1 つの状態コードしか表示できず、さらに、複数の状態を戻す関数も存在するため、gss_display_status() はループの一部として呼び出す必要があります。gss_display_status() が 0 以外の値コード (例 B–1message_context パラメータに戻される値) を示している間、関数は別の状態コードを取得できます。


例 B–1 gss_display_status() による状態コードの表示


OM_uint32 message_context;
OM_uint32 status_code;
OM_uint32 maj_status;
OM_uint32 min_status;
gss_buffer_desc status_string;

...

message_context = 0;

do {

     maj_status = gss_display_status(
               &min_status,
               status_code,
               GSS_C_GSS_CODE,
               GSS_C_NO_OID,
               &message_context,
               &status_string);

     fprintf(stderr, "%.*s\n", \
               (int)status_string.length, \
               (char *)status_string.value);

     gss_release_buffer(&min_status, &status_string,);

} while (message_context != 0);

状態コードのマクロ

マクロ GSS_CALLING_ERROR()GSS_ROUTINE_ERROR()、および GSS_SUPPLEMENTARY_INFO() はそれぞれ、GSS 状態コードを引数として受け取り、関係のないフィールドをすべて削除します。たとえば、GSS_ROUTINE_ERROR() を状態コードに適用して得た値には、呼び出しエラーフィールドと補足情報フィールドが削除され、ルーチンエラーフィールドだけが残ります。このようなマクロが提供する値は、適切な型の GSS_S_xxx シンボルと直接比較できます。また、マクロ GSS_ERROR() もあります。このマクロを GSS–API 状態コードに適用すると、状態コードが呼び出しエラーまたはルーチンエラーを示す場合は 0 以外の値を戻し、それ以外の場合は 0 の値を戻します。GSS-API で定義されているすべてのマクロは引数を 1 つだけしか受け取りません。

GSS-API データ型と値

この節では、さまざまなタイプの GSS-API データ型と値を説明します。gss_cred_id_tgss_name_t などのいくつかのデータ型はユーザーに不透明であり、その構造を知っても利点はないため、ここでは説明しません。この節では、次のことについて説明します。

基本 GSS-API データ型

次に、GSS-API で使用されるデータ型をいくつか示します。

OM_uint32

OM_uint32 はプラットフォームに依存しない 32 ビットの符号なし整数です。

gss_buffer_desc

次に、gss_buffer_descgss_buffer_t ポインタの定義を示します。


typedef struct gss_buffer_desc_struct {
        size_t length;
        void *value;
} gss_buffer_desc, *gss_buffer_t;

gss_OID_desc

次に、gss_OID_descgss_OID ポインタの定義を示します。


typedef struct gss_OID_desc_struct {
        OM_uint32 length;
        void*elements;
} gss_OID_desc, *gss_OID;

gss_OID_set_desc

次に、gss_OID_set_descgss_OID_set ポインタの定義を示します。


typedef struct gss_OID_set_desc_struct  {
        size_t  count;
        gss_OID elements;
} gss_OID_set_desc, *gss_OID_set;

gss_channel_bindings_struct

次に、gss_channel_bindings_struct 構造体と gss_channel_bindings_t ポインタの定義を示します。


typedef struct gss_channel_bindings_struct {
        OM_uint32 initiator_addrtype;
        gss_buffer_desc initiator_address;
        OM_uint32 acceptor_addrtype;
        gss_buffer_desc acceptor_address;
        gss_buffer_desc application_data;
} *gss_channel_bindings_t;

名前型

名前型とは、関連する名前の形式のことです。名前と名前型についての詳細は、名前OIDを参照してください。次に、GSS-API がサポートする名前型を示します。これらはすべて gss_OID 型です。

表 B–5 名前型

名前型 

意味 

GSS_C_NO_NAME 

GSS_C_NO_NAME (推奨されるシンボリック名) は、名前の転送で使用されるパラメータの特定の値に名前が渡されないことを意味する。

GSS_C_NO_OID 

実際のオブジェクト識別子ではなく、NULL の入力値に相当する。指定した場合、関連する名前が機構に固有なデフォルトの印刷可能な構文に基づいて解釈されることを示す。 

GSS_C_NT_ANONYMOUS 

匿名を指定する方法として提供される。この名前型と比較することによって、その名前が匿名のプリンシパルを参照するかどうかを機構に依存しない方法で決定できる。 

GSS_C_NT_EXPORT_NAME 

gss_export_name() 関数でエクスポートされた名前。

GSS_C_NT_HOSTBASED_SERVICE 

ホストコンピュータと関連するサービスを表す。この名前型は 2 つの要素「サービス (service)」と「ホスト名 (hostname)」からなり、service@hostname の形式を取る。

GSS_C_NT_MACHINE_UID_NAME 

ローカルシステム上のユーザーの、数値によるユーザー識別子を示す。解釈の方法は OS に固有である。gss_import_name() 関数はこの UID を username に解釈処理し、ユーザー名形式として扱う。

GSS_C_NT_STRING_STRING_UID_NAME 

ローカルシステム上のユーザーの数値によるユーザー識別子を表す数字文字列を示す。解釈の方法は OS に固有である。この名前型はマシン UID 形式に似ているが、バッファにはユーザー ID を表す文字が入っている。 

GSS_C_NT_USER_NAME 

ローカルシステム上の指定されたユーザー。解釈の方法は OS に固有である。username の形式を取る。

チャネルバインディングのアドレス型

表 B–6 に、gss_channel_bindings_struct 構造体の initiator_addrtypeacceptor_addrtype のフィールドで使用できる値を示します。この 2 つのフィールドは名前を受け取ることができる形式を示します (たとえば ARPAnet IMP アドレス形式や AppleTalk アドレス形式など)。チャネルバインディングについては、チャネルバインディングを参照してください。

表 B–6 チャネルバインディングのアドレス型

フィールド 

値 (10 進数) 

アドレス型 

GSS_C_AF_UNSPEC 

未定のアドレス型 

GSS_C_AF_LOCAL 

ホスト - ローカル 

GSS_C_AF_INET 

インターネットアドレス型 (IP など) 

GSS_C_AF_IMPLINK 

ARPAnet IMP  

GSS_C_AF_PUP 

pup プロトコル (BSP など) 

GSS_C_AF_CHAOS 

MIT CHAOS プロトコル 

GSS_C_AF_NS 

XEROX NS 

GSS_C_AF_NBS 

nbs 

GSS_C_AF_ECMA 

ECMA 

GSS_C_AF_DATAKIT 

データキットプロトコル 

GSS_C_AF_CCITT 

10 

CCITT 

GSS_C_AF_SNA 

11 

IBM SNA 

GSS_C_AF_DECnet 

12 

DECnet 

GSS_C_AF_DLI 

13 

ダイレクトデータリンクインタフェース 

GSS_C_AF_LAT 

14 

LAT 

GSS_C_AF_HYLINK 

15 

NSC ハイパーチャネル 

GSS_C_AF_APPLETALK 

16 

AppleTalk 

GSS_C_AF_BSC 

17 

BISYNC 

GSS_C_AF_DSS 

18 

分散システムサービス 

GSS_C_AF_OSI 

19 

OSI TP4 

GSS_C_AF_X25 

21 

X.25 

GSS_C_AF_NULLADDR 

255 

アドレスは指定されていない。