CAPGET

Section: Linux Programmer's Manual (2)
Updated: 2020-02-09
Index JM Home Page roff page

名前

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 added in Linux 2.6.25; deprecated */ #define _LINUX_CAPABILITY_VERSION_2 0x20071026 #define _LINUX_CAPABILITY_U32S_2 2

/* V3 added in 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 という名前を使用しなければならない。

Kernels prior to 2.6.25 prefer 32-bit capabilities with version _LINUX_CAPABILITY_VERSION_1. Linux 2.6.25 added 64-bit capability sets, with version _LINUX_CAPABILITY_VERSION_2. There was, however, an API glitch, and Linux 2.6.26 added _LINUX_CAPABILITY_VERSION_3 to fix the problem.

Note that 64-bit capabilities use datap[0] and datap[1], whereas 32-bit capabilities use only datap[0].

On kernels that support file capabilities (VFS capabilities support), these system calls behave slightly differently. This support was added as an option in Linux 2.6.24, and became fixed (nonoptional) in Linux 2.6.33.

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

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

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

VFS capabilities employ a file extended attribute (see xattr(7)) to allow capabilities to be attached to executables. This privilege model obsoletes kernel support for one process asynchronously setting the capabilities of another. That is, on kernels that have VFS capabilities support, when calling capset(), the only permitted values for hdrp->pid are 0 or, equivalently, the value returned by gettid(2).

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

On older kernels that do not provide VFS capabilities support capset() can, if the caller has the CAP_SETPCAP capability, be used to change not only the caller's own capabilities, but also the capabilities of other threads. The call operates on the capabilities of the thread specified by the pid field of hdrp when that is nonzero, or on the capabilities of the calling thread if pid is 0. If pid refers to a single-threaded process, then pid can be specified as a traditional process ID; operating on a thread of a multithreaded process requires a thread ID of the type returned by gettid(2). For capset(), pid can also be: -1, meaning perform the change on all threads except the caller and init(1); or a value less than -1, in which case the change is applied to all members of the process group whose ID is -pid.

返り値

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

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

エラー

EFAULT

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

EINVAL

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

EPERM

An attempt was made to add a capability to the permitted set, or to set a capability in the effective set that is not in the permitted set.

EPERM

An attempt was made to add a capability to the inheritable set, and either:

*: that capability was not in the caller's bounding set; or
*: the capability was not in the caller's permitted set and the caller lacked the CAP_SETPCAP capability in its effective set.

EPERM

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

ESRCH