PERFORCE change 164137 for review

[Robert Watson]

http://perforce.freebsd.org/chv.cgi?CH=164137

Change 164137 by rwatson at rwatson_freebsd_capabilities on 2009/06/11 18:43:51

	Cross-reference with libcapability.3.

Affected files ...

.. //depot/projects/trustedbsd/capabilities/src/lib/libc/sys/cap_enter.2#4 edit
.. //depot/projects/trustedbsd/capabilities/src/lib/libc/sys/cap_new.2#9 edit

Differences ...

==== //depot/projects/trustedbsd/capabilities/src/lib/libc/sys/cap_enter.2#4 (text+ko) ====

@@ -1,5 +1,5 @@
 .\"
-.\" Copyright (c) 2008 Robert N. M. Watson
+.\" Copyright (c) 2008-2009 Robert N. M. Watson
 .\" All rights reserved.
 .\"
 .\" WARNING: THIS IS EXPERIMENTAL SECURITY SOFTWARE THAT MUST NOT BE RELIED
@@ -32,7 +32,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 3, 2008
+.Dd June 11, 2009
 .Dt CAP_ENTER 2
 .Os
 .Sh NAME
@@ -58,6 +58,8 @@
 no-op.
 Future process descendents create with
 .Xr fork 2
+or
+.Xr pdfork 2
 will be placed in capability mode from inception.
 .Pp
 When combined with capabilities created with
@@ -65,6 +67,9 @@
 .Fn cap_enter
 may be used to create kernel-enforced sandboxes in which
 appropriately-crafted applications or application components may be run.
+Most sandboxes will be created and managed using the
+.Xr libcapability
+library, rather than using system calls directly.
 .Pp
 .Fn cap_getmode
 returns a flag indicating whether or not the process is in a capability mode
@@ -91,7 +96,8 @@
 .Rv -std cap_enter cap_getmode
 .Sh SEE ALSO
 .Xr cap_new 2 ,
-.Xr fexecve 2
+.Xr fexecve 2 ,
+.Xr libcapability 3
 .Sh HISTORY
 Support for capabilities and capabilities mode was developed as part of the
 .Tn TrustedBSD

==== //depot/projects/trustedbsd/capabilities/src/lib/libc/sys/cap_new.2#9 (text+ko) ====

@@ -32,7 +32,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd June 7, 2009
+.Dd June 11, 2009
 .Dt CAP_NEW 2
 .Os
 .Sh NAME
@@ -85,6 +85,11 @@
 .Xr dup2 2 ,
 many properties are shared between the new capability and the existing file
 descriptor, including open file flags, blocking disposition, and file offset.
+Many applications will prefer to use the
+.Xr cap_limitfd 3
+library call, part of
+.Xr libcapability 3 ,
+as it offers a more convenient interface.
 .Pp
 .Fn cap_getrights
 queries the rights associated with the capability referred to by file
@@ -449,6 +454,8 @@
 .Xr socketpair 2 ,
 .Xr unlinkat 2 ,
 .Xr write 2 ,
+.Xr cap_limitfd 3 ,
+.Xr libcapability 3 ,
 .Xr sem_getvalue 3 ,
 .Xr sem_post 3 ,
 .Xr sem_trywait 3 ,