ADD_KEY

名前

書式

#include <sys/types.h>
#include <keyutils.h>

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

このシステムコールの glibc ラッパーは提供されていない。 「注意」のセクションを参照すること。  

説明

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

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

対象の keyring のシリアル番号は、呼び出し元が 書き込み 許可を持つ有効な鍵リングのシリアル番号でなければならない。 そうでない場合は、以下のうち 1 つの特別な鍵リング ID を指定する。

KEY_SPEC_THREAD_KEYRING

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

KEY_SPEC_PROCESS_KEYRING

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

KEY_SPEC_SESSION_KEYRING

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

KEY_SPEC_USER_KEYRING

この値は呼び出し元の UID 固有の鍵リングを指定する (user-keyring(7))。

KEY_SPEC_USER_SESSION_KEYRING

この値は呼び出し元の UID のセッションの鍵リングを指定する (user-session-keyring(7))。

鍵タイプ

keyring

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

"user"

これは様々な目的の鍵タイプであり、payload はユーザー空間のアプリケーションに 読み込まれて更新される。 鍵全体がカーネルメモリに保持される。 このタイプの鍵の payload には、 32,767 バイトまでの任意のデータの blob を入れることができる。

"logon" (since Linux 3.3)

この鍵のタイプは基本的には user と同じであるが、キーの読み込みが出来ない。 これはユーザー空間から読み込ませたくない ペイロードを格納するのに適している。

この鍵タイプは、 description の他の文字の前に ':' が含まれていることを保証するためにチェックし、 description に "service" プレフィックスが付けられていることを保証するために入念に調べる。

"big_key" (Linux 3.13 以降) この鍵タイプは user と同様であるが、1 MiB までのペイロードを保持できる。 鍵のペイロードがとても大きい場合、 カーネルメモリではなく、(スワップアウトされて) tmpfs に暗号化して格納される。

これらのキーのより詳細な情報は、 keyrings(7) を参照すること。  

返り値

エラー

EACCES

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

EDQUOT

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

EFAULT

type, description, payload の 1 つ以上が、プロセスのアクセス可能なアドレス空間の外を指した。

EINVAL

type または description で指定された文字列のサイズ (終端の null バイトを含む) が制限を越えた (制限はそれぞれ 32 バイトと 4096 バイトである)。

EINVAL

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

EINVAL

type が logon であるが、 description に service: という形式のプレフィックス文字列が付けられていない。

EKEYEXPIRED

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

EKEYREVOKED

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

ENOKEY

鍵リングが存在しない。

ENOMEM

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

EPERM

type がピリオド ('.') から始まっている。 ピリオドから始まる鍵タイプは、実装用に予約されている。

EPERM

type が keyring であり、 description がピリオド ('.') から始まっている。 ピリオドで始まる description (名前) 付きの鍵リングは、 実装用に予約されている。

バージョン

準拠

注意

例

$ ./a.out user mykey "Some payload" Key ID is 64a4dca $ grep '64a4dca' /proc/keys 064a4dca I--Q--- 1 perm 3f010000 1000 1000 user mykey: 12  

プログラムソース

int main(int argc, char *argv[]) {
    key_serial_t key;

    if (argc != 4) {
        fprintf(stderr, "Usage: %s type description payload\n",
                argv[0]);
        exit(EXIT_FAILURE);
    }

    key = add_key(argv[1], argv[2], argv[3], strlen(argv[3]),
                KEY_SPEC_SESSION_KEYRING);
    if (key == -1) {
        perror("add_key");
        exit(EXIT_FAILURE);
    }

    printf("Key ID is %lx\n", (long) key);

    exit(EXIT_SUCCESS); }  

関連項目

カーネルソースファイル Documentation/security/keys/core.rst と Documentation/keys/request-key.rst (Linux 4.13 以前ではファイル Documentation/security/keys.txt と Documentation/security/keys-request-key.txt)。  

この文書について

Index

名前

書式

説明

鍵タイプ

返り値

エラー

バージョン

準拠

注意

例

プログラムソース

関連項目

この文書について