名前

add_key - カーネルの鍵管理機能に鍵を追加する

書式

#include <keyutils.h>

key_serial_t add_key(const char *type, const char *description,
                     const void *payload, size_t plen,
                     key_serial_t keyring);

説明

add_key() は、 指定した type と description を持つ鍵の作成、更新を行うようにカーネルに指示し、 長さ plen の payload で鍵を生成し、 指定された keyring にその鍵を追加し、 鍵リングのシリアル番号を返す。

鍵タイプによっては、 フォーマットが違っていたり、その他にも無効なものがあると、 指定したデータが拒否される場合もある。

対象の keyring に指定された type と description に合致する鍵がすでに含まれる場合、 鍵タイプがサポートしていれば、 新しい鍵が作成されるのではなく、 その鍵が更新される。 鍵タイプがサポートしていない場合、 新しい鍵が作成され、 鍵リングの現在の鍵のリンクはこの鍵で置き換えられる。

対象の keyring のシリアル番号には、 呼び出し元が書き込み許可を持つ有効な鍵リングのシリアル番号か、 以下の特別な鍵リング ID を指定する。

KEY_SPEC_THREAD_KEYRING

この値は呼び出し元スレッド固有の鍵リングを指定する。

KEY_SPEC_PROCESS_KEYRING

この値は呼び出し元プロセス固有の鍵リングを指定する。

KEY_SPEC_SESSION_KEYRING

この値は呼び出し元セッション固有の鍵リングを指定する。

KEY_SPEC_USER_KEYRING

この値は呼び出し元の UID 固有の鍵リングを指定する。

KEY_SPEC_USER_SESSION_KEYRING

この値は呼び出し元の UID のセッションの鍵リングを指定する。

鍵タイプ

コアの鍵管理コードには様々な鍵タイプがあり、 この関数でこれらを指定することができる。

“user”

ユーザー定義の鍵タイプの鍵には、 任意のデータの blob を入れることができ、 description には任意の有効な文字列を指定できるが、 鍵が対象とするサービスを表す文字列とコロンをプレフィックスに指定するのが推奨される方法である (例えば “afs:mykey”)。 このタイプの鍵には payload に空文字列つまり NULL を指定する。

“keyring”

鍵リングは、 任意のタイプの他の鍵の列へのリンクを保持できる特別な鍵タイプである。 このインターフェースを使って鍵リングを作成する場合、 payload には NULL を、 plen には 0 を指定しなければならない。

返り値

成功すると add_key() は、作成または更新した鍵のシリアル番号を返す。 エラーの場合、値 -1 が返され errno にエラーを示す値が設定される。

エラー

ENOKEY

鍵リングが存在しない。

EKEYEXPIRED

鍵リングが期限切れである。

EKEYREVOKED

鍵リングが廃止されている。

EINVAL

ペイロードデータが無効である。

ENOMEM

鍵を作成するのに十分なメモリーがない。

EDQUOT

この鍵を作成するか、鍵を鍵リングに追加すると、 このユーザーの鍵リングのクォータを超過してしまう。

EACCES

そのユーザーは指定された鍵リングを変更できない。

LINKING

これは Linux のシステムコールだが、 libc には存在せず、 代わりに libkeyutils に存在する。 リンクする際には、 リンカーに -lkeyutils を指定する必要がある。

関連項目

keyctl(1), keyctl(2), request_key(2)

この文書について

この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。