Update posix1e-related man pages, especially as relates to MAC, to more

accurately reflect the last ten years of work.

Approved by:	re (kib)

7 files changed, 129 insertions, 156 deletions

diff --git a/lib/libc/posix1e/Makefile.inc b/lib/libc/posix1e/Makefile.inc
index de0302b..c9e78bd 100644
--- a/lib/libc/posix1e/Makefile.inc
+++ b/lib/libc/posix1e/Makefile.inc
@@ -106,14 +106,16 @@ MLINKS+=acl_create_entry.3 acl_create_entry_np.3\
 	mac_get.3 mac_get_fd.3			\
 	mac_get.3 mac_get_file.3		\
 	mac_get.3 mac_get_link.3		\
+	mac_get.3 mac_get_peer.3		\
 	mac_get.3 mac_get_pid.3			\
 	mac_get.3 mac_get_proc.3		\
 	mac_prepare.3 mac_prepare_file_label.3	\
 	mac_prepare.3 mac_prepare_ifnet_label.3	\
 	mac_prepare.3 mac_prepare_process_label.3	\
-	mac_set.3 mac_set_link.3		\
+	mac_prepare.3 mac_prepare_type.3	\
 	mac_set.3 mac_set_fd.3			\
 	mac_set.3 mac_set_file.3		\
+	mac_set.3 mac_set_link.3		\
 	mac_set.3 mac_set_proc.3		\
 	mac_text.3 mac_from_text.3		\
 	mac_text.3 mac_to_text.3
diff --git a/lib/libc/posix1e/mac.3 b/lib/libc/posix1e/mac.3
index ac6affd..c570998 100644
--- a/lib/libc/posix1e/mac.3
+++ b/lib/libc/posix1e/mac.3
@@ -1,4 +1,5 @@
 .\" Copyright (c) 2001, 2003 Networks Associates Technology, Inc.
+.\" Copyright (c) 2009 Robert N. M. Watson
 .\" All rights reserved.
 .\"
 .\" This software was developed for the FreeBSD Project by Chris
@@ -30,7 +31,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd April 19, 2003
+.Dd August 7, 2009
 .Dt MAC 3
 .Os
 .Sh NAME
@@ -44,81 +45,82 @@
 In the kernel configuration file:
 .Cd "options MAC"
 .Sh DESCRIPTION
-.Fx
-permits administrators to define Mandatory Access Control labels
-defining levels for the privacy and integrity of data,
-overriding discretionary policies
-for those objects.
-Not all objects currently provide support for MAC labels,
-and MAC support must be explicitly enabled by the administrator.
-The library calls include routines to retrieve, duplicate,
-and set MAC labels associated with files and processes.
+Mandatory Access Control labels describe confidentiality, integrity, and
+other security attributes of operating system objects, overriding
+discretionary access control.
+Not all system objects support MAC labeling, and MAC policies must be
+explicitly enabled by the administrator.
+This API, based on POSIX.1e, includes routines to retrieve, manipulate, set,
+and convert to and from text the MAC labels on files and processes.
 .Pp
-POSIX.1e describes a set of MAC manipulation routines
-to manage the contents of MAC labels,
-as well as their relationships with
-files and processes;
-almost all of these support routines
-are implemented in
-.Fx .
+MAC labels consist of a set of (name, value) tuples, representing security
+attributes from MAC policies.
+For example, this label contains security labels defined by two policies,
+.Xr mac_biba 4
+and
+.Xr mac_mls 4 :
+.Bd -literal -offset indent
+biba/low,mls/low
+.Ed
+.Pp
+Further syntax and semantics of MAC labels may be found in
+.Xr maclabel 7 .
 .Pp
-Available functions, sorted by behavior, include:
+Applications operate on labels stored in
+.Vt mac_t ,
+but can convert between this internal format and a text format for the
+purposes of presentation to uses or external storage.
+When querying a label on an object, a
+.Vt mac_t
+must first be prepared using the interfaces described in
+.Xr mac_prepare 3 ,
+allowing the application to declare which policies it wishes to interogate.
+The application writer can also rely on default label names declared in
+.Xr mac.conf 5 .
+.Pp
+When finished with a
+.Vt mac_t ,
+the application must call
+.Xr mac_free 3
+to release its storage.
+.Pp
+The following functions are defined:
 .Bl -tag -width indent
-.It Fn mac_get_fd
-This function is described in
-.Xr mac_get 3 ,
-and may be used to retrieve the
-MAC label associated with
-a specific file descriptor.
-.It Fn mac_get_file
-This function is described in
+.It Fn mac_is_present
+This function, described in
+.Xr mac_is_present 3 ,
+allows applications to test whether MAC is configured, as well as whether
+specific policies are configured.
+.It Fn mac_get_fd , Fn mac_get_file , Fn mac_get_link , Fn mac_get_peer
+These functions, described in
 .Xr mac_get 3 ,
-and may be used to retrieve the
-MAC label associated with
-a named file.
-.It Fn mac_get_proc
-This function is described in
+retrieve the MAC labels associated with file descriptors, files, and socket
+peers.
+.It Fn mac_get_pid , Fn mac_get_proc
+These functions, described in
 .Xr mac_get 3 ,
-and may be used to retrieve the
-MAC label associated with
-the calling process.
-.It Fn mac_set_fd
-This function is described in
-.Xr mac_set 3 ,
-and may be used to set the
-MAC label associated with
-a specific file descriptor.
-.It Fn mac_set_file
-This function is described in
+retrieve the MAC labels associated with processes.
+.It Fn mac_set_fd , Fn mac_set_file , Fn mac_set_link
+These functions, described in
 .Xr mac_set 3 ,
-and may be used to set the
-MAC label associated with
-a named file.
+set the MAC labels associated with file descriptors and files.
 .It Fn mac_set_proc
-This function is described in
+This function, described in
 .Xr mac_set 3 ,
-and may be used to set the
-MAC label associated with
-the calling process.
+sets the MAC label associated with the current process.
 .It Fn mac_free
-This function is described in
+This function, desribed in
 .Xr mac_free 3 ,
-and may be used to free
-userland working MAC label storage.
+frees working MAC label storage.
 .It Fn mac_from_text
-This function is described in
+This function, described in
 .Xr mac_text 3 ,
-and may be used to convert
-a text-form MAC label
-into a working
+converts a text-form MAC label into working MAC label storage,
 .Vt mac_t .
-.It Fn mac_prepare
-.It Fn mac_prepare_file_label
-.It Fn mac_prepare_ifnet_label
-.It Fn mac_prepare_process_label
-These functions are described in
+.It Fn mac_prepare , Fn mac_prepare_file_label , Fn mac_prepare_ifnet_label , Fn mac_prepare_process_label , Fn mac_prepare_type
+These functions,  described in
 .Xr mac_prepare 3 ,
-and may be used to preallocate storage for MAC label retrieval.
+allocate working storage for MAC label operations.
 .Xr mac_prepare 3
 prepares a label based on caller-specified label names; the other calls
 rely on the default configuration specified in
@@ -130,15 +132,6 @@ and may be used to convert a
 .Vt mac_t
 into a text-form MAC label.
 .El
-The behavior of some of these calls is influenced by the configuration
-settings found in
-.Xr mac.conf 5 ,
-the MAC library run-time configuration file.
-.Sh IMPLEMENTATION NOTES
-.Fx Ns 's
-support for POSIX.1e interfaces and features
-is
-.Ud .
 .Sh FILES
 .Bl -tag -width ".Pa /etc/mac.conf" -compact
 .It Pa /etc/mac.conf
@@ -150,24 +143,20 @@ system objects, but without policy-specific knowledge.
 .Sh SEE ALSO
 .Xr mac_free 3 ,
 .Xr mac_get 3 ,
+.Xr mac_is_present 3 ,
 .Xr mac_prepare 3 ,
 .Xr mac_set 3 ,
 .Xr mac_text 3 ,
+.Xr posix1e 3 ,
 .Xr mac 4 ,
 .Xr mac.conf 5 ,
 .Xr mac 9
 .Sh STANDARDS
-These APIs are loosely based on the APIs described in POSIX.1e.
-POSIX.1e is described in IEEE POSIX.1e draft 17.
-Discussion of the draft
-continues on the cross-platform POSIX.1e implementation mailing list.
-To join this list, see the
-.Fx
-POSIX.1e implementation page
-for more information.
-However, the resemblance of these APIs to the POSIX APIs is only loose,
-as the POSIX APIs were unable to express many notions required for
-flexible and extensible access control.
+These APIs are loosely based on the APIs described in POSIX.1e, as described
+in IEEE POSIX.1e draft 17.
+However, the resemblence of these APIS to the POSIX APIs is loose, as the
+PSOXI APIS were unable to express some notinos required for flexible and
+extensible access control.
 .Sh HISTORY
 Support for Mandatory Access Control was introduced in
 .Fx 5.0
diff --git a/lib/libc/posix1e/mac_free.3 b/lib/libc/posix1e/mac_free.3
index 33ef9ec..78118a1 100644
--- a/lib/libc/posix1e/mac_free.3
+++ b/lib/libc/posix1e/mac_free.3
@@ -64,6 +64,7 @@ function.
 .Xr mac_prepare 3 ,
 .Xr mac_set 3 ,
 .Xr mac_text 3 ,
+.Xr posix1e 3 ,
 .Xr mac 4 ,
 .Xr mac 9
 .Sh STANDARDS
@@ -91,8 +92,8 @@ is a complex structure in the
 .Tn TrustedBSD
 implementation,
 .Fn mac_free
-is specific to that type, and must not be used to free the character
-strings returned from
+is specific to
+.Vt mac_3 ,
+and must not be used to free the character strings returned from
 .Fn mac_to_text .
-Doing so may result in undefined behavior,
-including application failure.
+Doing so may result in undefined behavior.
diff --git a/lib/libc/posix1e/mac_get.3 b/lib/libc/posix1e/mac_get.3
index cd498d0..35fa72b 100644
--- a/lib/libc/posix1e/mac_get.3
+++ b/lib/libc/posix1e/mac_get.3
@@ -133,6 +133,7 @@ is not a directory.
 .Xr mac_prepare 3 ,
 .Xr mac_set 3 ,
 .Xr mac_text 3 ,
+.Xr posix1e 3 ,
 .Xr mac 4 ,
 .Xr mac 9
 .Sh STANDARDS
diff --git a/lib/libc/posix1e/mac_set.3 b/lib/libc/posix1e/mac_set.3
index 84a1800..0b245a0 100644
--- a/lib/libc/posix1e/mac_set.3
+++ b/lib/libc/posix1e/mac_set.3
@@ -138,6 +138,7 @@ is not a directory.
 .Xr mac_is_present 3 ,
 .Xr mac_prepare 3 ,
 .Xr mac_text 3 ,
+.Xr posix1e 3 ,
 .Xr mac 4 ,
 .Xr mac 9
 .Sh HISTORY
diff --git a/lib/libc/posix1e/mac_text.3 b/lib/libc/posix1e/mac_text.3
index 66c1e21..dde6ccf 100644
--- a/lib/libc/posix1e/mac_text.3
+++ b/lib/libc/posix1e/mac_text.3
@@ -98,6 +98,7 @@ to allocate internal storage.
 .Xr mac_is_present 3 ,
 .Xr mac_prepare 3 ,
 .Xr mac_set 3 ,
+.Xr posix1e 3 ,
 .Xr mac 4 ,
 .Xr maclabel 7
 .Sh STANDARDS
diff --git a/lib/libc/posix1e/posix1e.3 b/lib/libc/posix1e/posix1e.3
index 2065523..84ce2ec 100644
--- a/lib/libc/posix1e/posix1e.3
+++ b/lib/libc/posix1e/posix1e.3
@@ -1,5 +1,5 @@
 .\"-
-.\" Copyright (c) 2000 Robert N. M. Watson
+.\" Copyright (c) 2000, 2009 Robert N. M. Watson
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 20, 2009
+.Dd August 7, 2009
 .Dt POSIX1E 3
 .Os
 .Sh NAME
@@ -36,99 +36,77 @@
 .Sh SYNOPSIS
 .In sys/types.h
 .In sys/acl.h
-.\" .In sys/capability.h
 .In sys/mac.h
 .Sh DESCRIPTION
-The IEEE POSIX.1e specification never left draft form, but the interfaces
-it describes are now widely used despite inherent limitations.
-Currently, only a few of the interfaces and features are implemented in
-.Fx ,
-although efforts are underway to complete the integration at this time.
+POSIX.1e describes five security extensions to the POSIX.1 API: Access
+Control Lists (ACLs), Auditing, Capabilities, Mandatory Access Control, and
+Information Flow Labels.
+While IEEE POSIX.1e D17 specification has not been standardized, several of
+its interfaces are widely used.
 .Pp
-POSIX.1e describes five security extensions to the base POSIX.1 API:
-Access Control Lists (ACLs), Auditing, Capabilities, Mandatory Access
-Control, and Information Flow Labels.
 .Fx
-supports POSIX.1e ACL interfaces, as well as POSIX.1e-like MAC
-interfaces.
-The TrustedBSD Project has produced but not integrated an implementation
-of POSIX.1e Capabilities.
-.Pp
-POSIX.1e defines both syntax and semantics for these features, but fairly
-substantial changes are required to implement these features in the
-operating system.
-.Pp
-As shipped,
-.Fx 4.0
-provides API and VFS support for ACLs, but not an implementation on any
-native file system.
-.Fx 5.0
-includes support for ACLs as part of UFS1 and UFS2, as well as necessary
-VFS support for additional file systems to export ACLs as appropriate.
-Available API calls relating to ACLs are described in detail in
-.Xr acl 3 .
-.Pp
-As shipped,
-.Fx 5.0
-includes support for Mandatory Access Control as well as POSIX.1e-like
-APIs for label management.
-More information on API calls relating to MAC is available in
-.Xr mac 3 .
+implements POSIX.1e interface for access control lists, described in
+.Xr acl 3 ,
+and supports ACLs on the
+.Xr ffs 7
+file system; ACLs must be administratively enabled using
+.Xr tunefs 8 .
 .Pp
-Additional patches supporting POSIX.1e features are provided by the
-TrustedBSD project:
+.Fx
+implements a POSIX.1e-like mandatory access control interface, described in
+.Xr mac 3 ,
+although with a number of extensions and important semantic differences.
 .Pp
-http://www.TrustedBSD.org/
-.Sh IMPLEMENTATION NOTES
-.Fx Ns 's
-support for POSIX.1e interfaces and features is still under
-development at this time, and many of these features are considered new
-or experimental.
+.Fx
+does not implement the POSIX.1e audit, privilege (capability), or information
+flow label APIs.
+However,
+.Fx
+does implement the
+.Xr libbsm
+audit API.
 .Sh ENVIRONMENT
-POSIX.1e assigns security labels to all objects, extending the security
+POSIX.1e assigns security attributes to all objects, extending the security
 functionality described in POSIX.1.
-These additional labels provide
-fine-grained discretionary access control, fine-grained capabilities,
-and labels necessary for mandatory access control.
-POSIX.2c describes
-a set of userland utilities for manipulating these labels.
+These additional attributes store fine-grained discretionary access control
+information and mandatory access control labels; for files, they are stored
+in extended attributes, described in
+.Xr extattr 3 .
 .Pp
-Many of these services are supported by extended attributes, documented
-in
-.Xr extattr 2
+POSIX.2c describes
+a set of userland utilities for manipulating these attributes, including
+.Xr getfacl 1
+and
+.Xr setfacl 1
+for access control lists, and
+.Xr getfmac 8
 and
-.Xr extattr 9 .
-While these APIs are not documented in POSIX.1e, they are similar in
-structure.
+.Xr setfmac 8
+for mandatory access control labels.
 .Sh SEE ALSO
+.Xr getfacl 1 ,
+.Xr setfacl 1 ,
 .Xr extattr 2 ,
 .Xr acl 3 ,
+.Xr extattr 3 ,
 .Xr libbsm 3 ,
 .Xr mac 3 ,
+.Xr ffs 7 ,
+.Xr getfmac 8 ,
+.Xr setfmac 8 ,
+.Xr tunefs 8 ,
 .Xr acl 9 ,
 .Xr extattr 9 ,
 .Xr mac 9
 .Sh STANDARDS
 POSIX.1e is described in IEEE POSIX.1e draft 17.
-Discussion of the draft continues
-on the cross-platform POSIX.1e implementation
-mailing list.
-To join this list, see the
-.Fx
-POSIX.1e implementation
-page for more information.
 .Sh HISTORY
 POSIX.1e support was introduced in
 .Fx 4.0 ;
-most of the features are available as of
+most features were available as of
 .Fx 5.0 .
-Development continues.
 .Sh AUTHORS
 .An Robert N M Watson
 .An Chris D. Faulhaber
 .An Thomas Moestl
 .An Ilmar S Habibulin
-.Sh BUGS
-Many of these features are considered new or experimental in
-.Fx 5.0
-and should be deployed with appropriate caution.