draft/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 .\"O .SH NAME
  27 .SH 名前
  28 .\"O capget, capset \- set/get capabilities of thread(s)
  29 capget, capset \- スレッドのケーパビリティを設定/取得する
  30 .\"O .SH SYNOPSIS
  31 .SH 書式
  32 .B #include <sys/capability.h>
  33 .sp
  34 .BI "int capget(cap_user_header_t " hdrp ", cap_user_data_t " datap );
  35 .sp
  36 .BI "int capset(cap_user_header_t " hdrp ", const cap_user_data_t " datap );
  37 .\"O .SH DESCRIPTION
  38 .SH 説明
  39 .\"O As of Linux 2.2,
  40 .\"O the power of the superuser (root) has been partitioned into
  41 .\"O a set of discrete capabilities.
  42 .\"O Each thread has a set of effective capabilities identifying
  43 .\"O which capabilities (if any) it may currently exercise.
  44 .\"O Each thread also has a set of inheritable capabilities that may be
  45 .\"O passed through an
  46 .\"O .BR execve (2)
  47 .\"O call, and a set of permitted capabilities
  48 .\"O that it can make effective or inheritable.
  49 Linux 2.2 で、スーパーユーザー (root) の権限は、個別のケーパビリティ
  50 (capabilities) へと分割され、その集合として表現されるようになった。
  51 各スレッドは「実効ケーパビリティ (effective capability) の集合」を持ち、
  52 それによって現在どの操作が実行可能かを識別できる。
  53 また、各スレッドは、
  54 「継承可能ケーパビリティ (inheritable capability) の集合」と
  55 「許可ケーパビリティ (permitted capability) の集合」を持つ。
  56 「継承可能ケーパビリティの集合」は
  57 .BR execve (2)
  58 を通じて渡すことができるケーパビリティの集合であり、
  59 「許可ケーパビリティ (permitted capability) の集合」は
  60 実効ケーパビリティや継承可能ケーパビリティとして有効にできる
  61 ケーパビリティを規定するものである。
  62 .PP
  63 .\"O These two functions are the raw kernel interface for getting and
  64 .\"O setting thread capabilities.
  65 .\"O Not only are these system calls specific to Linux,
  66 .\"O but the kernel API is likely to change and use of
  67 .\"O these functions (in particular the format of the
  68 .\"O .I cap_user_*_t
  69 .\"O types) is subject to extension with each kernel revision,
  70 .\"O but old programs will keep working.
  71 この二つの関数はスレッドのケーパビリティを取得したり設定したりするための
  72 生のカーネルインターフェースである。
  73 これらのシステムコールは Linux 特有であるというだけでなく、
  74 カーネル API は変更されるかもしれず、これらの
  75 関数の使用法 (特に
  76 .I cap_user_*_t
  77 型という書式) はカーネルのリビジョン毎に拡張されるかもしれないが、
  78 以前のプログラムはそのまま動作する。
  79 .sp
  80 .\"O The portable interfaces are
  81 .\"O .BR cap_set_proc (3)
  82 .\"O and
  83 .\"O .BR cap_get_proc (3);
  84 移植性のあるインターフェースは
  85 .BR cap_set_proc (3)
  86 と
  87 .BR cap_get_proc (3)
  88 である。
  89 .\"O if possible you should use those interfaces in applications.
  90 可能ならばアプリケーションはこれらの関数を使用すべきである。
  91 .\"O If you wish to use the Linux extensions in applications, you should
  92 .\"O use the easier-to-use interfaces
  93 .\"O .BR capsetp (3)
  94 .\"O and
  95 .\"O .BR capgetp (3).
  96 アプリケーションに Linux 拡張を使用したい場合には、より簡単に
  97 使えるインターフェースである
  98 .BR capsetp (3)
  99 と
 100 .BR capgetp (3)
 101 を使用すべきである。
 102 .\"O .SS "Current details"
 103 .SS 現在の詳細
 104 .\"O Now that you have been warned, some current kernel details.
 105 .\"O The structures are defined as follows.
 106 現在のカーネルの詳細について注意を述べておく。
 107 構造体は以下のように定義される。
 108 .sp
 109 .nf
 110 .in +4n
 111 #define _LINUX_CAPABILITY_VERSION_1  0x19980330
 112 #define _LINUX_CAPABILITY_U32S_1     1
 113
 114 #define _LINUX_CAPABILITY_VERSION_2  0x20071026
 115 #define _LINUX_CAPABILITY_U32S_2     2
 116
 117 typedef struct __user_cap_header_struct {
 118    __u32 version;
 119    int pid;
 120 } *cap_user_header_t;
 121
 122 typedef struct __user_cap_data_struct {
 123    __u32 effective;
 124    __u32 permitted;
 125    __u32 inheritable;
 126 } *cap_user_data_t;
 127 .fi
 128 .in -4n
 129 .sp
 130 .\"O .I effective, permitted, inheritable
 131 .\"O are bitmasks of the capabilities defined in
 132 .\"O .I capability(7).
 133 .\"O Note the
 134 .\"O .I CAP_*
 135 .\"O values are bit indexes and need to be bit-shifted before ORing into
 136 .\"O the bit fields.
 137 .\"O To define the structures for passing to the system call you have to use the
 138 .\"O .I struct __user_cap_header_struct
 139 .\"O and
 140 .\"O .I struct __user_cap_data_struct
 141 .\"O names because the typedefs are only pointers.
 142 .I effective, permitted, inheritable
 143 は、
 144 .BR capability (7)
 145 で定義されるケーパビリティのビットマスクである。
 146 .I CAP_*
 147 はビット番号を表すインデックス値であり、
 148 ビットフィールドに OR を行う前に
 149 .I CAP_*
 150 の値の分だけビットシフトを行う必要がある。
 151 typedef の方はポインタなので、
 152 このシステムコールに渡す構造体を定義するには、
 153 .I struct __user_cap_header_struct
 154 と
 155 .I struct __user_cap_data_struct
 156 という名前を使用しなければならない。
 157
 158 .\"O Kernels prior to 2.6.25 prefer
 159 .\"O 32-bit capabilities with version
 160 .\"O .BR _LINUX_CAPABILITY_VERSION_1 ,
 161 .\"O and kernels 2.6.25+ prefer 64-bit capabilities with version
 162 .\"O .BR _LINUX_CAPABILITY_VERSION_2 .
 163 .\"O Note, 64-bit capabilities use
 164 .\"O .IR datap [0]
 165 .\"O and
 166 .\"O .IR datap [1],
 167 .\"O whereas 32-bit capabilities use only
 168 .\"O .IR datap [0].
 169 カーネル 2.6.25 より前では、バージョン
 170 .B _LINUX_CAPABILITY_VERSION_1
 171 の 32 ビットケーパビリティが推奨である。
 172 カーネル 2.6.25 以降では、バージョン
 173 .B _LINUX_CAPABILITY_VERSION_2
 174 の 64 ビットケーパビリティが推奨である。
 175 64 ビットケーパビリティでは
 176 .IR datap [0]
 177 と
 178 .IR datap [1]
 179 が使用されるのに対し、
 180 32 ビットケーパビリティでは
 181 .IR datap [0]
 182 だけが使用される。
 183 .sp
 184 .\"O Another change affecting the behavior of these system calls is kernel
 185 .\"O support for file capabilities (VFS capability support).
 186 .\"O This support is currently a compile time option (added in kernel 2.6.24).
 187 これらのシステムコールの挙動に影響があるもう一つの変更点は、
 188 ファイルケーパビリティ (file capabilities) のカーネルによるサポート
 189 (VFS ケーパビリティのサポート) である。
 190 VFS ケーパビリティのサポートは現在のところコンパイル時のオプションである
 191 (カーネル 2.6.24 で追加された)。
 192 .sp
 193 .\"O For
 194 .\"O .BR capget ()
 195 .\"O calls, one can probe the capabilities of any process by specifying its
 196 .\"O process ID with the
 197 .\"O .I hdrp->pid
 198 .\"O field value.
 199 .BR capget ()
 200 では、
 201 .I hdrp->pid
 202 のフィールド値にケーパビリティを知りたいプロセスのプロセス ID を
 203 指定することで、任意のプロセスのケーパビリティを調べることができる。
 204 .\"O .SS With VFS Capability Support
 205 .SS VFS ケーパビリティがサポートされている場合
 206 .\"O VFS Capability support creates a file-attribute method for adding
 207 .\"O capabilities to privileged executables.
 208 .\"O This privilege model obsoletes kernel support for one process
 209 .\"O asynchronously setting the capabilities of another.
 210 .\"O That is, with VFS support, for
 211 .\"O .BR capset ()
 212 .\"O calls the only permitted values for
 213 .\"O .I hdrp->pid
 214 .\"O are 0 or
 215 .\"O .BR getpid (2),
 216 .\"O which are equivalent.
 217 VFS ケーパビリティのサポートでは、特権実行ファイルにケーパビリティを
 218 追加するためのファイル属性メソッドが作成された。
 219 この特権モデルの導入により、あるプロセスにより別のプロセスのケーパビリティ
 220 を非同期に設定する機能のカーネルによるサポートは廃止される。
 221 つまり、VFS サポートでは、
 222 .BR capset ()
 223 を呼び出す際に
 224 .I hdrp->pid
 225 の値として許されるのは 0 と
 226 .BR getpid (2)
 227 が返す値だけとなる (どちらの値でも等価である)。
 228 .\"O .SS Without VFS Capability Support
 229 .SS VFS ケーパビリティがサポートされていない場合
 230 .\"O When the kernel does not support VFS capabilities,
 231 .\"O .BR capset ()
 232 .\"O calls can operate on the capabilities of the thread specified by the
 233 .\"O .I pid
 234 .\"O field of
 235 .\"O .I hdrp
 236 .\"O when that is nonzero, or on the capabilities of the calling thread if
 237 .\"O .I pid
 238 .\"O is 0.
 239 カーネルが VFS ケーパビリティをサポートしていない場合、
 240 .I hdrp
 241 の
 242 .I pid
 243 フィールドが 0 以外であれば、
 244 .BR capset ()
 245 の操作対象は
 246 .I pid
 247 で指定されたスレッドのケーパビリティになる。
 248 .I pid
 249 が 0 の場合は呼び出し元のスレッドのケーパビリティが操作対象となる。
 250 .\"O If
 251 .\"O .I pid
 252 .\"O refers to a single-threaded process, then
 253 .\"O .I pid
 254 .\"O can be specified as a traditional process ID;
 255 .\"O operating on a thread of a multithreaded process requires a thread ID
 256 .\"O of the type returned by
 257 .\"O .BR gettid (2).
 258 .I pid
 259 がシングルスレッド・プロセスを参照している場合、
 260 .I pid
 261 は以前から使われているプロセスID を使って指定できる。
 262 マルチスレッド・プロセス内のあるスレッドを対象にする場合は、
 263 .BR gettid (2)
 264 が返すスレッドID を用いて指定する必要がある。
 265 .\"O For
 266 .\"O .BR capset (),
 267 .\"O .I pid
 268 .\"O can also be: \-1, meaning perform the change on all threads except the
 269 .\"O caller and
 270 .\"O .BR init (8);
 271 .\"O or a value less than \-1, in which case the change is applied
 272 .\"O to all members of the process group whose ID is \-\fIpid\fP.
 273 また、
 274 .BR capset ()
 275 では \-1 や \-1 より小さな値を指定することもできる。
 276 \-1 は呼び出し元と
 277 .BR init (8)
 278 を除く全てのスレッドを対象として変更を行うことを、
 279 \-1 より小さな値は ID が \-\fIpid\fP のプロセスグループの全メンバ
 280 を対象として変更を行うことを意味する。
 281
 282 .\"O For details on the data, see
 283 .\"O .BR capabilities (7).
 284 このデータの詳細は
 285 .BR capabilities (7)
 286 を参照すること。
 287 .\"O .SH "RETURN VALUE"
 288 .SH 返り値
 289 .\"O On success, zero is returned.
 290 .\"O On error, \-1 is returned, and
 291 .\"O .I errno
 292 .\"O is set appropriately.
 293 成功した場合には 0 を返す。エラーの場合には \-1 を返し、
 294 .I errno
 295 を適切に設定する。
 296
 297 .\"O The calls will fail with the error
 298 .\"O .BR EINVAL ,
 299 .\"O and set the
 300 .\"O .I version
 301 .\"O field of
 302 .\"O .I hdrp
 303 .\"O to the kernel preferred value of
 304 .\"O .B _LINUX_CAPABILITY_VERSION_?
 305 .\"O when an unsupported
 306 .\"O .I version
 307 .\"O value is specified.
 308 .I hdrp
 309 のフィールド
 310 .I version
 311 にサポートされていない値が指定された場合、
 312 呼び出しはエラー
 313 .B EINVAL
 314 で失敗し、
 315 .I version
 316 にカーネル推奨の
 317 .B _LINUX_CAPABILITY_VERSION_?
 318 を設定する。
 319 .\"O In this way, one can probe what the current
 320 .\"O preferred capability revision is.
 321 このようにして、現在の推奨ケーパビリティ・リビジョンが何かを
 322 調べることができる。
 323 .\"O .SH ERRORS
 324 .SH エラー
 325 .TP
 326 .B EFAULT
 327 .\"O Bad memory address.
 328 .\"O .I hdrp
 329 .\"O must not be NULL.
 330 .\"O .I datap
 331 .\"O may be NULL only when the user is trying to determine the preferred
 332 .\"O capability version format supported by the kernel.
 333 不正なメモリアドレス。
 334 .I hdrp
 335 は NULL であってはならない。
 336 .I datap
 337 に NULL を指定してよいのは、ユーザがカーネルがサポートしている
 338 推奨のケーパビリティ・バージョンを判定しようとしているときだけである。
 339 .TP
 340 .B EINVAL
 341 .\"O One of the arguments was invalid.
 342 引き数のどれかが無効である。
 343 .TP
 344 .B EPERM
 345 .\"O An attempt was made to add a capability to the Permitted set, or to set
 346 .\"O a capability in the Effective or Inheritable sets that is not in the
 347 .\"O Permitted set.
 348 「許可ケーパビリティセット」にケーパビリティを追加しようとしているか、
 349 もしくは「許可ケーパビリティセット」に含まれないケーパビリティを
 350 「実効ケーパビリティセット」や「継承可能ケーパビリティセット」に
 351 セットしようとしている。
 352 .TP
 353 .B EPERM
 354 .\"O The caller attempted to use
 355 .\"O .BR capset ()
 356 .\"O to modify the capabilities of a thread other than itself,
 357 .\"O but lacked sufficient privilege.
 358 .\"O For kernels supporting VFS
 359 .\"O capabilities, this is never permitted.
 360 .\"O For kernels lacking VFS
 361 .\"O support, the
 362 .\"O .B CAP_SETPCAP
 363 .\"O capability is required.
 364 .\"O (A bug in kernels before 2.6.11 meant that this error could also
 365 .\"O occur if a thread without this capability tried to change its
 366 .\"O own capabilities by specifying the
 367 .\"O .I pid
 368 .\"O field as a nonzero value (i.e., the value returned by
 369 .\"O .BR getpid (2))
 370 .\"O instead of 0.)
 371 呼び出し元が自分以外のスレッドのケーパビリティを
 372 .BR capset ()
 373 を使って修正しようとしたが、十分な特権がなかった。
 374 VFS ケーパビリティをサポートしているカーネルでは、
 375 この操作が許可されることは決してない。
 376 VFS ケーパビリティをサポートしていないカーネルでは、
 377 .B CAP_SETPCAP
 378 ケーパビリティが必要である。
 379 (バージョン 2.6.11 より前のカーネルには、
 380 このケーパビリティを持たないスレッドが
 381 .I pid
 382 フィールドに 0 でない値 (つまり、0 の代わりに
 383 .BR getpid (2)
 384 が返す値) を指定して自分自身のケーパビリティを変更しようとした場合にも、
 385 このエラーが発生するというバグがあった。)
 386 .TP
 387 .B ESRCH
 388 .\"O No such thread.
 389 そのようなスレッドが存在しない。
 390 .\"O .SH "CONFORMING TO"
 391 .SH 準拠
 392 .\"O These system calls are Linux-specific.
 393 これらのシステムコールは Linux 独自である。
 394 .\"O .SH NOTES
 395 .SH 備考
 396 .\"O The portable interface to the capability querying and setting
 397 .\"O functions is provided by the
 398 .\"O .I libcap
 399 .\"O library and is available:
 400 ケーパビリティを設定したり取得したりする機能のための移植性ある
 401 インターフェースは
 402 .I libcap
 403 ライブラリによって提供される。
 404 このライブラリは以下から入手できる:
 405 .br
 406 http://www.kernel.org/pub/linux/libs/security/linux-privs
 407 .\"O .SH "SEE ALSO"
 408 .SH 関連項目
 409 .BR clone (2),
 410 .BR gettid (2),
 411 .BR capabilities (7)