d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
accurately reflect the last ten years of work.

Approved by:	re (kib)
This commit is contained in:
rwatson 2009-08-12 10:46:48 +00:00
parent 9e874420d6
commit f430081d70
7 changed files with 140 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
lib/libc/posix1e/Makefile.inc
View File

@ -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

175
lib/libc/posix1e/mac.3
View File

@ -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
Available functions, sorted by behavior, include:
.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
.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
.Xr mac_set 3 ,
and may be used to set the
MAC label associated with
a named file.
.It Fn mac_set_proc
This function is described in
.Xr mac_set 3 ,
and may be used to set the
MAC label associated with
the calling process.
.It Fn mac_free
This function is described in
.Xr mac_free 3 ,
and may be used to free
userland working MAC label storage.
.It Fn mac_from_text
This function is described in
.Xr mac_text 3 ,
and may be used to convert
a text-form MAC label
into a working
.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
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 ,
and may be used to preallocate storage for MAC label retrieval.
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_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 ,
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 ,
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 ,
set the MAC labels associated with file descriptors and files.
.It Fn mac_set_proc
This function, described in
.Xr mac_set 3 ,
sets the MAC label associated with the current process.
.It Fn mac_free
This function, desribed in
.Xr mac_free 3 ,
frees working MAC label storage.
.It Fn mac_from_text
This function, described in
.Xr mac_text 3 ,
converts a text-form MAC label into working MAC label storage,
.Vt mac_t .
.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 ,
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

9
lib/libc/posix1e/mac_free.3
View File

@ -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.

1
lib/libc/posix1e/mac_get.3
View File

@ -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

1
lib/libc/posix1e/mac_set.3
View File

@ -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

1
lib/libc/posix1e/mac_text.3
View File

@ -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

116
lib/libc/posix1e/posix1e.3
View File

@ -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.
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
POSIX.1e defines both syntax and semantics for these features, but fairly
substantial changes are required to implement these features in the
operating system.
.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
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 .
.Pp
Additional patches supporting POSIX.1e features are provided by the
TrustedBSD project:
.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 extattr 9 .
While these APIs are not documented in POSIX.1e, they are similar in
structure.
.Xr setfacl 1
for access control lists, and
.Xr getfmac 8
and
.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.