名称

krb5_get_default_principal, krb5_principal, krb5_build_principal, krb5_build_principal_ext, krb5_build_principal_va, krb5_build_principal_va_ext, krb5_copy_principal, krb5_free_principal, krb5_make_principal, krb5_parse_name, krb5_parse_name_flags, krb5_parse_nametype, krb5_princ_set_realm, krb5_principal_compare, krb5_principal_compare_any_realm, krb5_principal_get_comp_string, krb5_principal_get_realm, krb5_principal_get_type, krb5_principal_match, krb5_principal_set_type, krb5_realm_compare, krb5_sname_to_principal, krb5_sock_to_principal, krb5_unparse_name, krb5_unparse_name_flags, krb5_unparse_name_fixed, krb5_unparse_name_fixed_flags, krb5_unparse_name_fixed_short, krb5_unparse_name_short — Kerberos 5 プリンシパル操作関数

ライブラリ

Kerberos 5 ライブラリ (libkrb5, -lkrb5)

書式

#include < krb5.h>

krb5_principal;
void
krb5_free_principal( krb5_context context, krb5_principal principal);

krb5_error_code
krb5_parse_name( krb5_context context, const char *name, krb5_principal *principal);

krb5_error_code
krb5_parse_name_flags( krb5_context context, const char *name, int flags, krb5_principal *principal);

krb5_error_code
krb5_unparse_name( krb5_context context, krb5_const_principal principal, char **name);

krb5_error_code
krb5_unparse_name_flags( krb5_context context, krb5_const_principal principal, int flags, char **name);

krb5_error_code
krb5_unparse_name_fixed( krb5_context context, krb5_const_principal principal, char *name, size_t len);

krb5_error_code
krb5_unparse_name_fixed_flags( krb5_context context, krb5_const_principal principal, int flags, char *name, size_t len);

krb5_error_code
krb5_unparse_name_short( krb5_context context, krb5_const_principal principal, char **name);

krb5_error_code
krb5_unparse_name_fixed_short( krb5_context context, krb5_const_principal principal, char *name, size_t len);

void
krb5_princ_set_realm( krb5_context context, krb5_principal principal, krb5_realm *realm);

krb5_error_code
krb5_build_principal( krb5_context context, krb5_principal *principal, int rlen, krb5_const_realm realm, ...);

krb5_error_code
krb5_build_principal_va( krb5_context context, krb5_principal *principal, int rlen, krb5_const_realm realm, va_list ap);

krb5_error_code
krb5_build_principal_ext( krb5_context context, krb5_principal *principal, int rlen, krb5_const_realm realm, ...);

krb5_error_code
krb5_build_principal_va_ext( krb5_context context, krb5_principal *principal, int rlen, krb5_const_realm realm, va_list ap);

krb5_error_code
krb5_make_principal( krb5_context context, krb5_principal *principal, krb5_const_realm realm, ...);

krb5_error_code
krb5_copy_principal( krb5_context context, krb5_const_principal inprinc, krb5_principal *outprinc);

krb5_boolean
krb5_principal_compare( krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2);

krb5_boolean
krb5_principal_compare_any_realm( krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2);

const char *
krb5_principal_get_comp_string( krb5_context context, krb5_const_principal principal, unsigned int component);

const char *
krb5_principal_get_realm( krb5_context context, krb5_const_principal principal);

int
krb5_principal_get_type( krb5_context context, krb5_const_principal principal);

krb5_boolean
krb5_principal_match( krb5_context context, krb5_const_principal principal, krb5_const_principal pattern);

void
krb5_principal_set_type( krb5_context context, krb5_principal principal, int type);

krb5_boolean
krb5_realm_compare( krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2);

krb5_error_code
krb5_sname_to_principal( krb5_context context, const char *hostname, const char *sname, int32_t type, krb5_principal *ret_princ);

krb5_error_code
krb5_sock_to_principal( krb5_context context, int socket, const char *sname, int32_t type, krb5_principal *principal);

krb5_error_code
krb5_get_default_principal( krb5_context context, krb5_principal *princ);

krb5_error_code
krb5_parse_nametype( krb5_context context, const char *str, int32_t *type);

解説

krb5_principal は、Kerberos のユーザの名前またはサービスの名前を保持します。

プリンシパルには、2 つのパーツ (parts)、 PrincipalName と realm があります。 PrincipalName は、1 つ以上の構成要素から成ります。印刷される形式で、構成要素は、/ によって区切られます。また、PrincipalName には、名前タイプ (name-type) があります。

プリンシパルの例は、 nisse/root@EXAMPLE.COM と host/datan.kth.se@KTH.SE です。 krb5_parse_name() と krb5_parse_name_flags() は、 name のプリンシパル名を kerberos プリンシパル構造体に渡します。 krb5_parse_name_flags() は、次のフラグを渡すことができる、特別の flags 引数を取ります:

KRB5_PRINCIPAL_PARSE_NO_REALM

レルム (realm) なしである入力文字列を必要とし、レルムは、 principal 返り引数に格納されません。

KRB5_PRINCIPAL_PARSE_REQUIRE_REALM

レルムがある入力文字列を必要とします。

krb5_unparse_name() と krb5_unparse_name_flags() は、プリンシパル princ を文字列 name に印刷 (出力) します。 name は、 free(3) で解放されるべきです。 flags 引数に、次のフラグを渡すことができます:

KRB5_PRINCIPAL_UNPARSE_SHORT

レルムが、ローカルレルムの 1 つであるなら、レルムなしです。

KRB5_PRINCIPAL_UNPARSE_NO_REALM

プリンシパル名のどんなレルムも決して含めません。

KRB5_PRINCIPAL_UNPARSE_DISPLAY

引用 (クォート) しません。

失敗すれば、 name は、 NULL に設定されます。 krb5_unparse_name_fixed() と krb5_unparse_name_fixed_flags() は、ちょうど krb5_unparse() のように振る舞いますが、代わりに、固定サイズのバッファの中にプリンシパルの解析の逆 (unparse) を行います。

krb5_unparse_name_short() は、プリンシパルが、デフォルトレルムにあるなら、レルムなしのプリンシパルをただ返します。プリンシパルでないなら、フルネームを返します。 krb5_unparse_name_fixed_short() は、ちょうど krb5_unparse_name_short() のように動作しますが、固定サイズのバッファで動作します。

krb5_build_principal() は、長さ rlen があるレルム realm からプリンシパルを構築します。次の引数は、プリンシパルの構成要項を形成します。構成要素のリストは、 NULL で終了されます。

krb5_build_principal_va() は、vargs を使用する krb5_build_principal() のように動作します。

krb5_build_principal_ext() と krb5_build_principal_va_ext() は、長さの値の組のリストを取り、リストは、0 の長さで終了されます。

krb5_make_principal() は、レルム自体の長さ算定することを除いて、 krb5_build_principal() と同じように動作します。

krb5_copy_principal() は、プリンシパルのコピーを作ります。コピーは、 krb5_free_principal() で解放される必要があります。

krb5_principal_compare() は、プリンシパルのレルムを含んで、2 つのプリンシパルを比較し、それらが同じであるなら、 TRUE を、そうでなければ、 FALSE を返します。

krb5_principal_compare_any_realm() は、 krb5_principal_compare() と同じように動作しますが、プリンシパルのレムルの構成要素を比較しません。

krb5_realm_compare() は、2 つのプリンシパルのレムル比較し、それらが同じであるなら、 TRUE を、そうでなければ、 FALSE を返します。

krb5_principal_match() は、 pattern に対して principal とマッチします。パターンは、グロブ (globbing) 表現で、(/ で区切られた) 各構成要素は、プリンシパルの対応する構成要素に対してマッチされます。

krb5_principal_get_realm() と krb5_principal_get_comp_string() 関数は、レルムまたは、特定の構成要素のいずれかの principal のパーツ (parts) を返します。両方の関数は、プリンシパル内のデータへの文字列ポインタを返すので、プリンシパルが存在している間のみ、それらは有効です。

krb5_principal_get_comp_string() への component 引数は、0 から構成要素の合計数 - 1 である、返される構成要素のインデックスです。インデックスが範囲外であるなら、 NULL が返されます。

krb5_principal_get_realm() と krb5_principal_get_comp_string() は、MIT API 仕様で内部的に記述された krb5_princ_component() と関連するマクロの代わりです。マクロと異なって、これらの関数は、 krb5_data ではなく、文字列を返します。 krb5_data を返す理由は、プリンシパルの構成要素が、バイナリデータを含むことができると信じられていることですが、この考えは、事実無根であり、プリンシパルの構成要素が、実際には UTF8 であると決定されているので、 0 で終了した文字列を使用することは安全です。

一般的に、プリンシパルの構成要素を調べることは必要ではありません。

krb5_principal_get_type() と krb5_principal_set_type() は、プリンシパルのための名前タイプを取得して、設定します。名前タイプの取り扱いは、トリッキーで頻繁に必要であるというわけではなく、何をするかを知らないなら、これを使用しないでください。

krb5_sname_to_principal() と krb5_sock_to_principal() は、例えば、キータブ (keytab) で検索キーに使用できる“service”プリンシパルを簡単に作成するためのものです。両方の関数において、 sname パラメータは、作成されたプリンシパルの最初の構成要素に使用されます。 sname が NULL であるなら、“host”が、代わりに使用されます。

krb5_sname_to_principal() は、2 番目の構成要素のために渡された hostname を使用します。 type が KRB5_NT_SRV_HST であるなら、この名前は、 gethostbyname() で検索されます。 hostname が NULL であるなら、ローカルのホスト名が、使用されます。

krb5_sock_to_principal() は、 AF_INET または AF_INET6 ソケットにバインドされるべき、渡された socket の“sockname”を使用します。アドレスと“sockname”の間に、マッピングがなければなりません。関数は、DNS の名前を解決しようとします。

krb5_get_default_principal() は、それが実行している環境を見ることによって何が合理的なデフォルトのプリンシパルであるかを見つけようとします。

krb5_parse_nametype() は、解析して、 type の整数値である名前タイプを返します。失敗すれば、関数は、エラーコードを返し、エラー文字列を設定します。

関連項目

krb5_425_conv_principal(3), krb5_config(3), krb5.conf(5)

バグ

利用者は、上記の可変引数関数のいくつかで、構成要素にヌル文字 (NUL) を持つことができません。誰かが、構成要素にヌル文字 (NUL) を持つための良い考えがあるような、良い例を与えることができるまで、これは修理されません。