リナックスコマンド

capgetのヘルプ・マニュアル

日本語 英語

• help
• man

capget --help

man capget

CAPGET(2) Linux Programmer’s Manual CAPGET(2) 名前 capget, capset - スレッドのケーパビリティを設定/取得する 書式 #undef _POSIX_SOURCE #include 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 2.2 で、スーパーユーザー (root) の権限は、個別のケーパビリティ (capabilities) へと分割され、その集合として表現されるようになった。各ス レ ッドは「実効ケーパビリティ (effective capability) の集合」を持ち、そ れによって現在どの操作が実行可能かを識別できる。また、各スレッドは、 「 継 承可能ケーパビリティ (inheritable capability) の集合」と「許可ケーパ ビリティ (permitted capability) の集合」を持つ。「継承可能ケーパビリ テ ィの集合」は execve(2) を通じて渡すことができるケーパビリティの集合であ り、「許可ケーパビリティ (permitted capability) の集合」は実効ケーパ ビ リ ティや継承可能ケーパビリティとして有効にできるケーパビリティを規定す るものである。 この二つの関数はスレッドのケーパビリティを取得したり設定したりするた め の生のカーネルインターフェースである。これらのシステムコールは Linux 特 有であるというだけでなく、カーネル API は変更されるかもしれず、これらの 関 数の使用法 (特に cap_user_*_t 型という書式) はカーネルのリビジョン毎 に拡張されるかもしれないが、以前のプログラムはそのまま動作する。 移植性のあるインターフェースは cap_set_proc(3) と cap_get_proc(3) で あ る 。可能ならばアプリケーションはこれらの関数を使用すべきである。アプリ ケーションに Linux 拡張を使用したい場合には、より簡単に使えるインターフ ェースである capsetp(3) と capgetp(3) を使用すべきである。 現在の詳細 現 在のカーネルの詳細について注意を述べておく。構造体は以下のように定義 される。 #define _LINUX_CAPABILITY_VERSION_1 0x19980330 #define _LINUX_CAPABILITY_U32S_1 1 #define _LINUX_CAPABILITY_VERSION_2 0x20071026 #define _LINUX_CAPABILITY_U32S_2 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 は、 capability(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 ビットケーパビリティが推奨である。 64 ビットケーパビリティでは datap[0] と datap[1] が使用されるのに対し、 32 ビットケーパビリティでは datap[0] だけが使用される。 こ れらのシステムコールの挙動に影響があるもう一つの変更点は、ファイルケ ーパビリティ (file capabilities) のカーネルによるサポート (VFS ケーパビ リティのサポート) である。 VFS ケーパビリティのサポートは現在のところコ ンパイル時のオプションである (カーネル 2.6.24 で追加された)。 capget() では、 hdrp->pid のフィールド値にケーパビリティを知りたいプ ロ セ スのプロセス ID を指定することで、任意のプロセスのケーパビリティを調 べることができる。 VFS ケーパビリティがサポートされている場合 VFS ケーパビリティのサポートでは、特権実行ファイルにケーパビリティを 追 加 するためのファイル属性メソッドが作成された。この特権モデルの導入によ り、あるプロセスにより別のプロセスのケーパビリティを非同期に設定する 機 能 の カ ー ネ ルによるサポートは廃止される。つまり、VFS サポートでは、 capset() を呼び出す際に hdrp->pid の値として許されるのは 0 と getpid(2) が返す値だけとなる (どちらの値でも等価である)。 VFS ケーパビリティがサポートされていない場合 カ ーネルが VFS ケーパビリティをサポートしていない場合、 hdrp の pid フ ィールドが 0 以外であれば、 capset() の操作対象は pid で指定されたス レ ッ ドのケーパビリティになる。 pid が 0 の場合は呼び出し元のスレッドのケ ーパビリティが操作対象となる。 pid がシングルスレッド・プロセスを参照し て いる場合、 pid は以前から使われているプロセスID を使って指定できる。 マルチスレッド・プロセス内のあるスレッドを対象にする場合は、 gettid(2) が返すスレッドID を用いて指定する必要がある。また、 capset() では -1 や -1 より小さな値を指定することもできる。 -1 は呼び出し元と init(8) を 除 く 全てのスレッドを対象として変更を行うことを、 -1 より小さな値は ID が -pid のプロセスグループの全メンバを対象として変更を行うことを意味する。 このデータの詳細は capabilities(7) を参照すること。 返り値 成 功した場合には 0 を返す。エラーの場合には -1 を返し、 errno を適切に 設定する。 hdrp のフィールド version にサポートされていない値が指定された場合、 呼 び 出しはエラー EINVAL で失敗し、 version にカーネル推奨の _LINUX_CAPA- BILITY_VERSION_? を設定する。このようにして、現在の推奨ケーパビリテ ィ ・リビジョンが何かを調べることができる。 エラー EFAULT 不 正なメモリアドレス。 hdrp は NULL であってはならない。 datap に NULL を指定してよいのは、ユーザがカーネルがサポートしている推 奨のケーパビリティ・バージョンを判定しようとしているときだけであ る。 EINVAL 引き数のどれかが無効である。 EPERM 「許可ケーパビリティセット」にケーパビリティを追加しようとしてい るか、もしくは「許可ケーパビリティセット」に含まれないケーパビリ ティを「実効ケーパビリティセット」や「継承可能ケーパビリティセッ ト」にセットしようとしている。 EPERM 呼び出し元が自分以外のスレッドのケーパビリティを capset() を使っ て修正しようとしたが、十分な特権がなかった。 VFS ケーパビリテ ィ をサポートしているカーネルでは、この操作が許可されることは決して ない。 VFS ケーパビリティをサポートしていないカー ネ ル で は 、 CAP_SETPCAP ケーパビリティが必要である。 (バージョン 2.6.11 より 前のカーネルには、このケーパビリティを持たないスレッドが pid フ ィ ールドに 0 でない値 (つまり、0 の代わりに getpid(2) が返す値) を指定して自分自身のケーパビリティを変更しようとした場合にも、こ のエラーが発生するというバグがあった。) ESRCH そのようなスレッドが存在しない。 準拠 これらのシステムコールは Linux 独自である。 備考 ケ ーパビリティを設定したり取得したりする機能のための移植性あるインター フェースは libcap ライブラリによって提供される。このライブラリは以下 か ら入手できる: http://www.kernel.org/pub/linux/libs/security/linux-privs 関連項目 clone(2), gettid(2), capabilities(7) Linux 2009-01-26 CAPGET(2)

CAPGET(2) Linux Programmer’s Manual CAPGET(2) NAME capget, capset - set/get capabilities of thread(s) SYNOPSIS #undef _POSIX_SOURCE #include 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); DESCRIPTION As of Linux 2.2, the power of the superuser (root) has been partitioned into a set of discrete capabilities. Each thread has a set of effec- tive capabilities identifying which capabilities (if any) it may cur- rently exercise. Each thread also has a set of inheritable capabili- ties that may be passed through an execve(2) call, and a set of permit- ted capabilities that it can make effective or inheritable. These two functions are the raw kernel interface for getting and set- ting thread capabilities. Not only are these system calls specific to Linux, but the kernel API is likely to change and use of these func- tions (in particular the format of the cap_user_*_t types) is subject to extension with each kernel revision, but old programs will keep working. The portable interfaces are cap_set_proc(3) and cap_get_proc(3); if possible you should use those interfaces in applications. If you wish to use the Linux extensions in applications, you should use the easier- to-use interfaces capsetp(3) and capgetp(3). Current details Now that you have been warned, some current kernel details. The struc- tures are defined as follows. #define _LINUX_CAPABILITY_VERSION_1 0x19980330 #define _LINUX_CAPABILITY_U32S_1 1 #define _LINUX_CAPABILITY_VERSION_2 0x20071026 #define _LINUX_CAPABILITY_U32S_2 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 are bitmasks of the capabilities defined in capability(7). Note the CAP_* values are bit indexes and need to be bit-shifted before ORing into the bit fields. To define the structures for passing to the system call you have to use the struct __user_cap_header_struct and struct __user_cap_data_struct names because the typedefs are only pointers. Kernels prior to 2.6.25 prefer 32-bit capabilities with version _LINUX_CAPABILITY_VERSION_1, and kernels 2.6.25+ prefer 64-bit capabil- ities with version _LINUX_CAPABILITY_VERSION_2. Note, 64-bit capabilities use datap[0] and datap[1], whereas 32-bit capabilities only use datap[0]. Another change affecting the behavior of these system calls is kernel support for file capabilities (VFS capability support). This support is currently a compile time option (added in kernel 2.6.24). For capget() calls, one can probe the capabilities of any process by specifying its process ID with the hdrp->pid field value. With VFS Capability Support VFS Capability support creates a file-attribute method for adding capa- bilities to privileged executables. This privilege model obsoletes kernel support for one process asynchronously setting the capabilities of another. That is, with VFS support, for capset() calls the only permitted values for hdrp->pid are 0 or getpid(2), which are equiva- lent. Without VFS Capability Support When the kernel does not support VFS capabilities, capset() calls can operate on the capabilities of the thread specified by the pid field of hdrp when that is non-zero, 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(8); or a value less than -1, in which case the change is applied to all members of the pro- cess group whose ID is -pid. For details on the data, see capabilities(7). RETURN VALUE On success, zero is returned. On error, -1 is returned, and errno is set appropriately. The calls will fail with the error EINVAL, and set the version field of hdrp to the kernel preferred value of _LINUX_CAPABILITY_VERSION_? when an unsupported version value is specified. In this way, one can probe what the current preferred capability revision is. ERRORS EFAULT Bad memory address. hdrp must not be NULL. datap may only be NULL when the user is trying to determine the preferred capabil- ity version format supported by the kernel. EINVAL One of the arguments was invalid. EPERM An attempt was made to add a capability to the Permitted set, or to set a capability in the Effective or Inheritable sets that is not in the Permitted set. EPERM The caller attempted to use capset() to modify the capabilities of a thread other than itself, but lacked sufficient privilege. For kernels supporting VFS capabilities, this is never permit- ted. For kernels lacking VFS support, the CAP_SETPCAP capabil- ity is required. (A bug in kernels before 2.6.11 meant that this error could also occur if a thread without this capability tried to change its own capabilities by specifying the pid field as a non-zero value (i.e., the value returned by getpid(2)) instead of 0.) ESRCH No such thread. CONFORMING TO These system calls are Linux-specific. NOTES The portable interface to the capability querying and setting functions is provided by the libcap library and is available here: http://www.kernel.org/pub/linux/libs/security/linux-privs SEE ALSO clone(2), gettid(2), capabilities(7) COLOPHON This page is part of release 3.22 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/. Linux 2009-01-26 CAPGET(2)