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
- そのユーザーは指定された鍵リングを変更できない。
これは Linux
のシステムコールだが、
libc には存在せず、
代わりに
libkeyutils
に存在する。
リンクする際には、
リンカーに
-lkeyutils
を指定する必要がある。
keyctl(1),
keyctl(2),
request_key(2)
この man ページは Linux
man-pages
プロジェクトのリリース
3.79 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man-pages/
に書かれている。