manual/LDP_man-pages/release/man2/capget.2

   1 .\" written by Andrew Morgan <morgan@kernel.org>
   2 .\" may be distributed as per GPL
   3 .\" Modified by David A. Wheeler <dwheeler@ida.org>
   4 .\" Modified 2004-05-27, mtk
   5 .\" Modified 2004-06-21, aeb
   6 .\" Modified 2008-04-28, morgan of kernel.org
   7 .\"     Update in line with addition of file capabilities and
   8 .\"     64-bit capability sets in kernel 2.6.2[45].
   9 .\" Modified 2009-01-26, andi kleen
  10 .\"
  11 .\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
  12 .\"         all rights reserved.
  13 .\" Translated 1999-12-26, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  14 .\" Updated & Modified 2005-02-03, Yuichi SATO <ysato444@yahoo.co.jp>
  15 .\" Updated & Modified 2006-01-31, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  16 .\" Updated & Modified 2006-07-23, Akihiro MOTOKI, LDP v2.36
  17 .\" Updated & Modified 2008-08-11, Akihiro MOTOKI, LDP v3.05
  18 .\" Updated 2009-02-24, Akihiro MOTOKI, LDP v3.19
  19 .\"
  20 .\"WORD:        capability              ケーパビリティ
  21 .\"WORD:        effective capability    実効ケーパビリティ
  22 .\"WORD:        inheritable capabilit   継承可能ケーパビリティ
  23 .\"WORD:        permitted capabily      許可ケーパビリティ
  24 .\"
  25 .TH CAPGET 2 2010-09-20 "Linux" "Linux Programmer's Manual"
  26 .SH 名前
  27 capget, capset \- スレッドのケーパビリティを設定/取得する
  28 .SH 書式
  29 .B #include <sys/capability.h>
  30 .sp
  31 .BI "int capget(cap_user_header_t " hdrp ", cap_user_data_t " datap );
  32 .sp
  33 .BI "int capset(cap_user_header_t " hdrp ", const cap_user_data_t " datap );
  34 .SH 説明
  35 Linux 2.2 で、スーパーユーザー (root) の権限は、個別のケーパビリティ
  36 (capabilities) へと分割され、その集合として表現されるようになった。
  37 各スレッドは「実効ケーパビリティ (effective capability) の集合」を持ち、
  38 それによって現在どの操作が実行可能かを識別できる。
  39 また、各スレッドは、
  40 「継承可能ケーパビリティ (inheritable capability) の集合」と
  41 「許可ケーパビリティ (permitted capability) の集合」を持つ。
  42 「継承可能ケーパビリティの集合」は
  43 .BR execve (2)
  44 を通じて渡すことができるケーパビリティの集合であり、
  45 「許可ケーパビリティ (permitted capability) の集合」は
  46 実効ケーパビリティや継承可能ケーパビリティとして有効にできる
  47 ケーパビリティを規定するものである。
  48 .PP
  49 この二つの関数はスレッドのケーパビリティを取得したり設定したりするための
  50 生のカーネルインターフェースである。
  51 これらのシステムコールは Linux 特有であるというだけでなく、
  52 カーネル API は変更されるかもしれず、これらの
  53 関数の使用法 (特に
  54 .I cap_user_*_t
  55 型という書式) はカーネルのリビジョン毎に拡張されるかもしれないが、
  56 以前のプログラムはそのまま動作する。
  57 .sp
  58 移植性のあるインターフェースは
  59 .BR cap_set_proc (3)
  60 と
  61 .BR cap_get_proc (3)
  62 である。
  63 可能ならばアプリケーションはこれらの関数を使用すべきである。
  64 アプリケーションに Linux 拡張を使用したい場合には、より簡単に
  65 使えるインターフェースである
  66 .BR capsetp (3)
  67 と
  68 .BR capgetp (3)
  69 を使用すべきである。
  70 .SS 現在の詳細
  71 現在のカーネルの詳細について注意を述べておく。
  72 構造体は以下のように定義される。
  73 .sp
  74 .nf
  75 .in +4n
  76 #define _LINUX_CAPABILITY_VERSION_1  0x19980330
  77 #define _LINUX_CAPABILITY_U32S_1     1
  78
  79 #define _LINUX_CAPABILITY_VERSION_2  0x20071026
  80 #define _LINUX_CAPABILITY_U32S_2     2
  81
  82 typedef struct __user_cap_header_struct {
  83    __u32 version;
  84    int pid;
  85 } *cap_user_header_t;
  86
  87 typedef struct __user_cap_data_struct {
  88    __u32 effective;
  89    __u32 permitted;
  90    __u32 inheritable;
  91 } *cap_user_data_t;
  92 .fi
  93 .in -4n
  94 .sp
  95 .I effective, permitted, inheritable
  96 は、
  97 .BR capability (7)
  98 で定義されるケーパビリティのビットマスクである。
  99 .I CAP_*
 100 はビット番号を表すインデックス値であり、
 101 ビットフィールドに OR を行う前に
 102 .I CAP_*
 103 の値の分だけビットシフトを行う必要がある。
 104 typedef の方はポインタなので、
 105 このシステムコールに渡す構造体を定義するには、
 106 .I struct __user_cap_header_struct
 107 と
 108 .I struct __user_cap_data_struct
 109 という名前を使用しなければならない。
 110
 111 カーネル 2.6.25 より前では、バージョン
 112 .B _LINUX_CAPABILITY_VERSION_1
 113 の 32 ビットケーパビリティが推奨である。
 114 カーネル 2.6.25 以降では、バージョン
 115 .B _LINUX_CAPABILITY_VERSION_2
 116 の 64 ビットケーパビリティが推奨である。
 117 64 ビットケーパビリティでは
 118 .IR datap [0]
 119 と
 120 .IR datap [1]
 121 が使用されるのに対し、
 122 32 ビットケーパビリティでは
 123 .IR datap [0]
 124 だけが使用される。
 125 .sp
 126 これらのシステムコールの挙動に影響があるもう一つの変更点は、
 127 ファイルケーパビリティ (file capabilities) のカーネルによるサポート
 128 (VFS ケーパビリティのサポート) である。
 129 VFS ケーパビリティのサポートは現在のところコンパイル時のオプションである
 130 (カーネル 2.6.24 で追加された)。
 131 .sp
 132 .BR capget ()
 133 では、
 134 .I hdrp->pid
 135 のフィールド値にケーパビリティを知りたいプロセスのプロセス ID を
 136 指定することで、任意のプロセスのケーパビリティを調べることができる。
 137 .SS VFS ケーパビリティがサポートされている場合
 138 VFS ケーパビリティのサポートでは、特権実行ファイルにケーパビリティを
 139 追加するためのファイル属性メソッドが作成された。
 140 この特権モデルの導入により、あるプロセスにより別のプロセスのケーパビリティ
 141 を非同期に設定する機能のカーネルによるサポートは廃止される。
 142 つまり、VFS サポートでは、
 143 .BR capset ()
 144 を呼び出す際に
 145 .I hdrp->pid
 146 の値として許されるのは 0 と
 147 .BR getpid (2)
 148 が返す値だけとなる (どちらの値でも等価である)。
 149 .SS VFS ケーパビリティがサポートされていない場合
 150 カーネルが VFS ケーパビリティをサポートしていない場合、
 151 .I hdrp
 152 の
 153 .I pid
 154 フィールドが 0 以外であれば、
 155 .BR capset ()
 156 の操作対象は
 157 .I pid
 158 で指定されたスレッドのケーパビリティになる。
 159 .I pid
 160 が 0 の場合は呼び出し元のスレッドのケーパビリティが操作対象となる。
 161 .I pid
 162 がシングルスレッド・プロセスを参照している場合、
 163 .I pid
 164 は以前から使われているプロセスID を使って指定できる。
 165 マルチスレッド・プロセス内のあるスレッドを対象にする場合は、
 166 .BR gettid (2)
 167 が返すスレッドID を用いて指定する必要がある。
 168 また、
 169 .BR capset ()
 170 では \-1 や \-1 より小さな値を指定することもできる。
 171 \-1 は呼び出し元と
 172 .BR init (8)
 173 を除く全てのスレッドを対象として変更を行うことを、
 174 \-1 より小さな値は ID が \-\fIpid\fP のプロセスグループの全メンバ
 175 を対象として変更を行うことを意味する。
 176
 177 このデータの詳細は
 178 .BR capabilities (7)
 179 を参照すること。
 180 .SH 返り値
 181 成功した場合には 0 を返す。エラーの場合には \-1 を返し、
 182 .I errno
 183 を適切に設定する。
 184
 185 .I hdrp
 186 のフィールド
 187 .I version
 188 にサポートされていない値が指定された場合、
 189 呼び出しはエラー
 190 .B EINVAL
 191 で失敗し、
 192 .I version
 193 にカーネル推奨の
 194 .B _LINUX_CAPABILITY_VERSION_?
 195 を設定する。
 196 このようにして、現在の推奨ケーパビリティ・リビジョンが何かを
 197 調べることができる。
 198 .SH エラー
 199 .TP
 200 .B EFAULT
 201 不正なメモリアドレス。
 202 .I hdrp
 203 は NULL であってはならない。
 204 .I datap
 205 に NULL を指定してよいのは、ユーザがカーネルがサポートしている
 206 推奨のケーパビリティ・バージョンを判定しようとしているときだけである。
 207 .TP
 208 .B EINVAL
 209 引き数のどれかが無効である。
 210 .TP
 211 .B EPERM
 212 「許可ケーパビリティセット」にケーパビリティを追加しようとしているか、
 213 もしくは「許可ケーパビリティセット」に含まれないケーパビリティを
 214 「実効ケーパビリティセット」や「継承可能ケーパビリティセット」に
 215 セットしようとしている。
 216 .TP
 217 .B EPERM
 218 呼び出し元が自分以外のスレッドのケーパビリティを
 219 .BR capset ()
 220 を使って修正しようとしたが、十分な特権がなかった。
 221 VFS ケーパビリティをサポートしているカーネルでは、
 222 この操作が許可されることは決してない。
 223 VFS ケーパビリティをサポートしていないカーネルでは、
 224 .B CAP_SETPCAP
 225 ケーパビリティが必要である。
 226 (バージョン 2.6.11 より前のカーネルには、
 227 このケーパビリティを持たないスレッドが
 228 .I pid
 229 フィールドに 0 でない値 (つまり、0 の代わりに
 230 .BR getpid (2)
 231 が返す値) を指定して自分自身のケーパビリティを変更しようとした場合にも、
 232 このエラーが発生するというバグがあった。)
 233 .TP
 234 .B ESRCH
 235 そのようなスレッドが存在しない。
 236 .SH 準拠
 237 これらのシステムコールは Linux 独自である。
 238 .SH 備考
 239 ケーパビリティを設定したり取得したりする機能のための移植性ある
 240 インターフェースは
 241 .I libcap
 242 ライブラリによって提供される。
 243 このライブラリは以下から入手できる:
 244 .br
 245 http://www.kernel.org/pub/linux/libs/security/linux-privs
 246 .SH 関連項目
 247 .BR clone (2),
 248 .BR gettid (2),
 249 .BR capabilities (7)