From owner-svn-src-head@FreeBSD.ORG Wed Aug 12 10:46:48 2009 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 892B51065674; Wed, 12 Aug 2009 10:46:48 +0000 (UTC) (envelope-from rwatson@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 76F8B8FC4A; Wed, 12 Aug 2009 10:46:48 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id n7CAkmDd059306; Wed, 12 Aug 2009 10:46:48 GMT (envelope-from rwatson@svn.freebsd.org) Received: (from rwatson@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id n7CAkmAw059298; Wed, 12 Aug 2009 10:46:48 GMT (envelope-from rwatson@svn.freebsd.org) Message-Id: <200908121046.n7CAkmAw059298@svn.freebsd.org> From: Robert Watson Date: Wed, 12 Aug 2009 10:46:48 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r196123 - head/lib/libc/posix1e X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 12 Aug 2009 10:46:49 -0000 Author: rwatson Date: Wed Aug 12 10:46:48 2009 New Revision: 196123 URL: http://svn.freebsd.org/changeset/base/196123 Log: Update posix1e-related man pages, especially as relates to MAC, to more accurately reflect the last ten years of work. Approved by: re (kib) Modified: head/lib/libc/posix1e/Makefile.inc head/lib/libc/posix1e/mac.3 head/lib/libc/posix1e/mac_free.3 head/lib/libc/posix1e/mac_get.3 head/lib/libc/posix1e/mac_set.3 head/lib/libc/posix1e/mac_text.3 head/lib/libc/posix1e/posix1e.3 Modified: head/lib/libc/posix1e/Makefile.inc ============================================================================== --- head/lib/libc/posix1e/Makefile.inc Wed Aug 12 10:45:45 2009 (r196122) +++ head/lib/libc/posix1e/Makefile.inc Wed Aug 12 10:46:48 2009 (r196123) @@ -106,14 +106,16 @@ MLINKS+=acl_create_entry.3 acl_create_en 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 Modified: head/lib/libc/posix1e/mac.3 ============================================================================== --- head/lib/libc/posix1e/mac.3 Wed Aug 12 10:45:45 2009 (r196122) +++ head/lib/libc/posix1e/mac.3 Wed Aug 12 10:46:48 2009 (r196123) @@ -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. -.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 . +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 +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 +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 -Available functions, sorted by behavior, include: +The following functions are defined: .Bl -tag -width indent -.It Fn mac_get_fd -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 specific file descriptor. -.It Fn mac_get_file -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 -a named file. -.It Fn mac_get_proc -This function is 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-speci .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 Modified: head/lib/libc/posix1e/mac_free.3 ============================================================================== --- head/lib/libc/posix1e/mac_free.3 Wed Aug 12 10:45:45 2009 (r196122) +++ head/lib/libc/posix1e/mac_free.3 Wed Aug 12 10:46:48 2009 (r196123) @@ -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. Modified: head/lib/libc/posix1e/mac_get.3 ============================================================================== --- head/lib/libc/posix1e/mac_get.3 Wed Aug 12 10:45:45 2009 (r196122) +++ head/lib/libc/posix1e/mac_get.3 Wed Aug 12 10:46:48 2009 (r196123) @@ -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 Modified: head/lib/libc/posix1e/mac_set.3 ============================================================================== --- head/lib/libc/posix1e/mac_set.3 Wed Aug 12 10:45:45 2009 (r196122) +++ head/lib/libc/posix1e/mac_set.3 Wed Aug 12 10:46:48 2009 (r196123) @@ -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 Modified: head/lib/libc/posix1e/mac_text.3 ============================================================================== --- head/lib/libc/posix1e/mac_text.3 Wed Aug 12 10:45:45 2009 (r196122) +++ head/lib/libc/posix1e/mac_text.3 Wed Aug 12 10:46:48 2009 (r196123) @@ -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 Modified: head/lib/libc/posix1e/posix1e.3 ============================================================================== --- head/lib/libc/posix1e/posix1e.3 Wed Aug 12 10:45:45 2009 (r196122) +++ head/lib/libc/posix1e/posix1e.3 Wed Aug 12 10:46:48 2009 (r196123) @@ -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.