CAPGET

Section: Linux Programmer's Manual (2)
Updated: 2020-02-09
Index Return to Main Contents

名前

capget, capset - スレッドのケーパビリティを設定/取得する

書式

#include <sys/capability.h>

int capget(cap_user_header_t hdrp, cap_user_data_t datap);

int capset(cap_user_header_t hdrp, const cap_user_data_t datap);

説明

この二つのシステムコールはスレッドのケーパビリティを取得したり設定したりするための生のカーネルインターフェースである。これらのシステムコールは Linux 特有であるというだけでなく、カーネル API は変更されるかもしれず、これらのシステムコールの使用法 (特に cap_user_*_t 型という書式) はカーネルのリビジョン毎に拡張されるかもしれないが、以前のプログラムはそのまま動作する。

移植性のあるインターフェースは cap_set_proc(3) と cap_get_proc(3) である。可能ならばアプリケーションはこれらの関数を使用すべきである。

現在の詳細

現在のカーネルの詳細について注意を述べておく。構造体は以下のように定義される。

#define _LINUX_CAPABILITY_VERSION_1 0x19980330 #define _LINUX_CAPABILITY_U32S_1 1

/* V2 は in Linux 2.6.25 で追加された; 古い */ #define _LINUX_CAPABILITY_VERSION_2 0x20071026 #define _LINUX_CAPABILITY_U32S_2 2

/* V3 は Linux 2.6.26 で追加された */ #define _LINUX_CAPABILITY_VERSION_3 0x20080522 #define _LINUX_CAPABILITY_U32S_3 2

typedef struct __user_cap_header_struct {
__u32 version;
int pid; } *cap_user_header_t;

typedef struct __user_cap_data_struct {
   __u32 effective;
   __u32 permitted;
   __u32 inheritable; } *cap_user_data_t;

フィールド effective, permitted, inheritable は、 capabilities(7) で定義されるケーパビリティのビットマスクである。 CAP_* はビット番号を表すインデックス値であり、ビットフィールドに OR を行う前に CAP_* の値の分だけビットシフトを行う必要がある。 typedef の方はポインターなので、このシステムコールに渡す構造体を定義するには、 struct __user_cap_header_struct と struct __user_cap_data_struct という名前を使用しなければならない。

カーネル 2.6.25 より前では、バージョン _LINUX_CAPABILITY_VERSION_1 の 32 ビットケーパビリティが推奨である。カーネル 2.6.25 では、バージョン _LINUX_CAPABILITY_VERSION_2 の 64 ビットケーパビリティが追加された。しかし、API に不具合があったので、問題を解消するため、 Linux 2.6.26 で _LINUX_CAPABILITY_VERSION_3 が追加された。

64 ビットケーパビリティでは datap[0] と datap[1] が使用されるのに対し、 32 ビットケーパビリティでは datap[0] だけが使用される。

ファイルケーパビリティ (VFS ケーパビリティ) をサポートするカーネルでは、これらのシステムコールの挙動が微妙に異なる。 VFS ケーパビリティのサポートは、Linux 2.6.24 でオプションとして追加され、 Linux 2.6.33 で (オプションではなく) 固定となった。

capget() では、 hdrp->pid のフィールド値にケーパビリティを知りたいプロセスのプロセス ID を指定することで、任意のプロセスのケーパビリティを調べることができる。

データの詳細は、 capabilities(7) を参照すること。

VFS ケーパビリティがサポートされている場合

VFS ケーパビリティは、ファイル拡張属性 (xattr(7) を参照) を使い、実行ファイルにケーパビリティを付与する。この特権モデルの導入により、あるプロセスにより別のプロセスのケーパビリティを非同期に設定する機能のカーネルによるサポートは廃止される。つまり、VFS ケーパビリティをサポートするカーネルでは、 capset() を呼び出す際に hdrp->pid の値として許されるのは 0 と getpid(2) が返す値だけとなる (どちらの値でも等価である)。

VFS ケーパビリティがサポートされていない場合

VFS ケーパビリティをサポートしていない古いカーネルでは、呼び出し元が CAP_SETPCAP ケーパビリティを持っている場合、 capset() は呼び出し元自体のケーパビリティを変更するだけでなく、他のスレッドのケーパビリティも変更するのに使われる。この呼び出しでは、hdrp の pid フィールドが 0 以外であれば、 capset() の操作対象は pid で指定されたスレッドのケーパビリティになる。 pid が 0 の場合は呼び出し元のスレッドのケーパビリティが操作対象となる。 pid がシングルスレッドプロセスを参照している場合、 pid は以前から使われているプロセスID を使って指定できる。マルチスレッドプロセス内のあるスレッドを対象にする場合は、 gettid(2) が返すスレッドID を用いて指定する必要がある。また、 capset() では -1 や -1 より小さな値を指定することもできる。 -1 は呼び出し元と init(1) を除く全てのスレッドを対象として変更を行うことを、 -1 より小さな値は ID が -pid のプロセスグループの全メンバを対象として変更を行うことを意味する。

返り値

成功した場合は 0 が返される。エラーの場合は -1 が返され、 errno が適切に設定される。

hdrp のフィールド version にサポートされていない値が指定された場合、呼び出しはエラー EINVAL で失敗し、 version にカーネル推奨の _LINUX_CAPABILITY_VERSION_? を設定する。このようにして、現在の推奨ケーパビリティリビジョンが何かを調べることができる。

エラー

EFAULT

不正なメモリーアドレス。 hdrp は NULL であってはならない。 datap に NULL を指定してよいのは、ユーザーがカーネルがサポートしている推奨のケーパビリティバージョンを判定しようとしているときだけである。

EINVAL

引き数のどれかが無効である。

EPERM

「許可ケーパビリティセット」にケーパビリティを追加しようとしているか、もしくは「許可ケーパビリティセット」に含まれないケーパビリティを「実効ケーパビリティセット」にセットしようとしている。

EPERM

「継承可能ケーパビリティセット」にケーパビリティを追加しようとしていて、かつ以下のいずれかである。

*: そのケーパビリティが、呼び出し元に紐づけられたセットにない。
*: そのケーパビリティが、呼び出し元の「許可ケーパビリティセット」になく、かつ、呼び出し元の「実効ケーパビリティセット」に CAP_SETPCAP ケーパビリティがない。

EPERM

呼び出し元が自分以外のスレッドのケーパビリティを capset() を使って修正しようとしたが、十分な特権がなかった。 VFS ケーパビリティをサポートしているカーネルでは、この操作が許可されることは決してない。 VFS ケーパビリティをサポートしていないカーネルでは、 CAP_SETPCAP ケーパビリティが必要である。 (バージョン 2.6.11 より前のカーネルには、このケーパビリティを持たないスレッドが pid フィールドに 0 でない値 (つまり、0 の代わりに getpid(2) が返す値) を指定して自分自身のケーパビリティを変更しようとした場合にも、このエラーが発生するというバグがあった。)

ESRCH