PSSG Draft 17

STANDARDS PROJECT
Draft Standard for Information Technology—
Portable Operating System Interface (POSIX)—
Part 1:
System Application Program
Interface (API)— Amendment #:Protection, Audit and Control Interfaces [C Language]
SponsorPortable Applications Standards Committeeof theIEEE Computer Society
Work Item Number: JTC1 22.42%

Abstract: IEEE Std 1003.1e is part of the POSIX series of standards. It defines
security interfaces to open systems for access control lists, audit, separation of +privilege (capabilities), mandatory access control, and information label mechan- +isms. This standard is stated in terms of its C binding.
Keywords: auditing, access control lists, application portability, capability, +information labels, mandatory access control, privilege, open systems, operating
systems, portable application, POSIX, POSIX.1, security, user portability

PSSG / D17
October 1997
Copyright  1997 by the Institute of Electrical and Electronics Engineers, Inc
345 East 47th Street,
New York, NY 10017, USA
All rights reserved.

ISBN-xxxx-xxxxx-x

Library of Congress Catalog Number 90-xxxxx

IEEE Draft P1003.1e, Copyright  IEEE.
All Rights Reserved by IEEE.
The IEEE disclaims any responsibility or liability resulting from theplacement and use of this document.
This copyrighted document may be downloaded for personal use by one (1)individual user.
No further copying or distribution is permitted without the express written
permission or an appropriate license from the IEEE.
This is a withdrawn IEEE Standards Draft.
Permission is hereby granted for IEEE Standards Committee participants to
reproduce this document for purposes of IEEE standardization activities.
Permission is also granted for member bodies and technical committees of
ISO and IEC to reproduce this document for purposes of developing anational position.
Other entities seeking permission to reproduce this document forstandardization or other activities, or to reproduce portions of thisdocument for these or other uses, must contact the IEEE Standards
Department for the appropriate license.
Use of information contained in this unapproved draft is at your own risk.
IEEE Standards Department
Copyright and Permissions
445 Hoes Lane, P.O. Box 1331
Piscataway, NJ 08855-1331, USA
October 1997

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

XXXXXXX

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

Foreword
NOTE: This foreword is not a normative part of the standard and is included for informative purposes only.

The purpose of this standard is to define a standard interface and environment
for Computer Operating Systems that require certain security mechanisms. The
standard is intended for system implementors and application software developers. It is an extension to IEEE Std 1003.1-1990.
c

Organization of the Standard
The standard is divided into several parts:— Revisions to the General Section (Section 1)— Revisions to Terminology and General Requirements (Section 2)— Revisions to Process Primitives (Section 3)— Revisions to Process Environment (Section 4)— Revisions to Files and Directories (Section 5)— Revisions to Input and Output Primitives (Section 6)— Revisions to Language Specific Services for C Programming Language (Section 8)— Access Control Lists (Section 23)— Audit (Section 24)— Capability (Section 25)— Mandatory Access Control (Section 26)— Information Labeling (Section 27)— Annex B - Revisions to Rationale and Notes— Annex F - Ballot Instructions
Conformance Measurement
Changes to the draft since the previous ballot are indicated by one of four marksin the right-hand margin. These change marks should aid the balloter in determining what has changed and therefore what is candidate text for comments andobjections during this ballot. A bar ("|") indicates changes to the line between
drafts 15 and 16. A plus ("+") indicates that text has been added in draft 16. A
minus ("-") indicates that text present in that location in draft 15 has been deleted
in draft 16. A percent ("%") indicates that a change was made at that location in
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

xi

%
%
%
%
%
%
%

draft 17.
In publishing this standard, both IEEE and the security working group simply
intend to provide a yardstick against which various operating system implementations can be measured for conformance. It is not the intent of either IEEE or the
security working group to measure or rate any products, to reward or sanction
any vendors of products for conformance or lack of conformance to this standard,
or to attempt to enforce this standard by these or any other means. The responsibility for determining the degree of conformance or lack thereof with this standard rests solely with the individual who is evaluating the product claiming to be
in conformance with this standard.
Extensions and Supplements to This Standard
Activities to extend this standard to address additional requirements can be anticipated in the future. This is an outline of how these extensions will be incorporated, and also how users of this document can keep track of that status.
Extensions are approved as ‘‘Supplements’’ to this document, following the IEEE
Standards Procedures. Approved Supplements are published separately and are
obtained from the IEEE with orders for this document until the full document isreprinted and such supplements are incorporated in their proper positions.
If you have any questions regarding this or other POSIX documents, you may contact the the IEEE Standards Office by calling IEEE at:
1 (800) 678-IEEE from within the US
1+ (908) 981-1393 from outside the UScto determine which supplements have been published. Published supplements areavailable for a modest fee.
Supplements are numbered in the same format as the main document withunique positions as either subsections or main sections. A supplement may
include new subsections in various sections of the main document as well as new
main sections. Supplements may include new sections in already approved supplements. However, the overall numbering shall be unique so that two supplements only use the same numbers when one replaces the other. Supplements
may contain either required or optional facilities. Supplements may add additional conformance requirements (see POSIX.1, Implementation Conformance,1.3) defining new classes of conforming systems or applications.
It is desirable, but perhaps unattainable, that supplements do not change thefunctionality of the already defined facilities. Supplements are not used to provide a general update of the standard. A general update of the standard is done
through the review procedure as specified by the IEEE.
If you have interest in participating in any of the PASC working groups please
send your name, address, and phone number to the Secretary, IEEE Standards
Board, Institute of Electrical and Electronics Engineers, Inc., P.O. Box 1331, 445
Hoes Lane, Piscataway, NJ 08855-1331, and ask to have your request forwarded
to the chairperson of the appropriate TCOS working group. If you have interest
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

xii

c

c

in participating in this work at the international level, contact your ISO/IEC
national body.
Please report typographical errors and editorial changes for this draft standard
directly to:
Casey Schaufler
Silicon Graphics
2011 North Shoreline Blvd.
P.O. Box 7311
Mountain View, CA 94039-7311(415) 933-1634 (voice)(415) 962-8404 (fax)casey@sgi.com
Schaufler@DOCKMASTER.NCSC.MILWITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

xiii

IEEE Std 1003.1e was prepared by the security Working Group, sponsored by thePortable Applications Standards Committee of the IEEE Computer Society.
Portable Applications Standards Committee (PASC)
Chair:
Treasurer:
Secretary:

Lowell Johnson
Barry NeedhamCharles SeverenceccSecurity Working Group Officials
Chair:
Technical Editor:

Lynne Ambuel
Casey Schaufler−

The following people participated in the Security Working Group to develop
the standard.
Lynne AmbuelMartin Bailey
Lowell Bogard
Matthew Brisse
Mark Carson
Roland Clouse
Anthony D’Alessandro
Ana Maria De Alvare’
Maryland R. Edwards
Jeremy EpsteinDavid Ferbrache
Morrie Gasser
Henry Hall
Rand Hoven
Paul A. Karger
Yvon Klein
Steven LaFountain
Warren E. Loper
Richard E. Mcnaney
Jim Moseman
Rose Odonnell
Gordon ParryDavid Rogers
Craig Rubin
Mark Schaffer
Larry Scott
Rick Siebenaler
Dennis Steinauer
Doug Steves
Charlie Testa
Catherine West

Jeanne Baccash
John-Olaf Bauner
Kevin Brady
Joseph Bulger
Charisse CastagnoliPeter E. Cordsen
Daniel D. Daugherty
Terence Dowling
Ron ElliottFrank Fadden
Carl Freeman
Gerald B. Green
Craig Heath
Chris Hughes
Joseph Keenan
Andy Kochis
Danielle Lahmani
Jeff Mainville
Chris Milsom
Kevin V. Murphy
Gary Oing
Jeff PicciottoPeter L. Rosencrantz
Roman Saucedo
Casey Schaufler
Eric Shaffer
Alan Silverstein
Chris Steinbroner
Steve Sutton
Jeff Tofano
Ken Witte

Lee Badger
D. Elliott BellJoe Brame
Lisa Carnahan
Paul Close
Janet Cugini
Manilal Daya
Jack Dwyer
Lloyd English
Kevin Fall
Mark Funkenhauser
John Griffith
Tom Houghton
Howard Israel
Jerry Keselman
Steve Kramer
Jason Levitt
Doug Mansur
Mark Modig
Greg Nuss
Larry Parker
Michael Ressler
Shawn Rovansek
Stuart Schaeffer
Michael Schmitz
Olin Sibert
Jon Spencer
Michael Steuerwalt
W. Lee Terrell
Brian Weis

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

xiv

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

0Information technology—Portable operating
1 system interface for computer environments

2

Section 1: Revisions to the General Section

34⇒ 1.1 Scope This scope is to be revised and integrated appropriately into thescope when POSIX.1e is approved:

5
6
7
8
9
10
11
12
13

This standard, P1003.1e/D17: October 1997 (POSIX.1e), defines five indepen- %dent, optional sets of interfaces that will be used to implement protection,
audit, and control mechanisms. Implementation of any or all of these interfaces does not ensure the security of the conforming system nor of conforming
applications. In addition, implementation of these interfaces does not imply
that a conforming system can achieve any class or level of any security evaluation criteria. These interfaces will become integrated into the ISO/IEC 9945-1:
1990 (System Application Program Interface) standard (POSIX.1) as they areapproved and published. The sets of interfaces for implementation are:

14(1) Access Control Lists (ACL)

15(2) Security Auditing

16(3) Capability

17(4) Mandatory Access Controls (MAC)

18(5) Information Labeling (IL)19
20

Each option defines new functions, as well as security-related constraints for thefunctions and utilities defined by other POSIX standards.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
1 Revisions to the General Section1

21⇒ 1.2 Normative References (POSIX.1: line 39)

22
23
24
25
26
27
28

The following standards contain provisions that, through references in thistext, constitute provisions of this standard. At the time of publication, the editions indicated were valid. All standards are subject to revision, and parties toagreements based on this part of this standard are encouraged to investigate
the possibility of applying the most recent editions of the standards listed
below. Members of IEC and ISO maintain registers of currently valid International Standards.

29
30
31

(1) ISO/IEC 9945-1: 1990, Information Technology—Portable Operating System Interface (POSIX)—Part 1: System Application Program Interface(API) [C Language]32
33(2) IEEE Standard for Information Technology—Portable Operating System
Interface (POSIX)—Part 2: Shell and Utilities.
c

34
35
36

(3) P1003.2c/D17: October 1997, Draft Standard for Information %Technology—Portable Operating System Interface (POSIX)—Part 2:
Shell and Utilities—Amendment #: Protection and Control Utilities

37
38⇒ 1.3.1.3 Conforming Implementation Options (POSIX.1: line 98)
the following options in alphabetic order:

39{_POSIX_ACL} Access control list option (in 2.9.3)
c

40{_POSIX_AUD} Auditing option (in 2.9.3)
c

41{_POSIX_CAP} Capability option (in 2.9.3)
c

42{_POSIX_MAC} Mandatory access control option (in 2.9.3)
c

43{_POSIX_INF} Information label option (in 2.9.3)
c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

2

Insert1 Revisions to the General Section

1

Section 2: Revisions to Terminology and General Requirements2⇒ 2.2.1 Terminology

34⇒ 2.2.2 General Terms (POSIX.1: lines 89-397) Add the following definitions in alphabetical order:

5
6
7
8

2.2.2.1 access: A specific type of interaction between a process and an object
that results in the flow of information from one to the other. Possible information
flows include the transfer of attributes pertaining to that object, the transfer ofdata pertaining to that object, or the fact of existence of that object.

9102.2.2.2 access acl: An access control list (ACL) which is used in making discretionary access control decisions for an object.

11
12
13

2.2.2.3 access control: The prevention of unauthorized access to objects byprocesses and, conversely, the permitting of authorized access to objects byprocesses.

14
15
16

2.2.2.4 access control list (ACL): A discretionary access control entity associated with an object, consisting of a list of entries where each entry is an identifier(e.g. user or group of users) coupled with a set of access permissions.

17
18

2.2.2.5 access control policy: A set of rules, part of a security policy, by which
a user’s authorization to access an object is determined.

19
20

2.2.2.6 audit: The procedure of capturing, storing, analyzing, maintaining andmanaging data concerning security-relevant activities.
c

21
22

2.2.2.7 auditable event: An activity which may cause an audit record to bereported in an audit log.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
2 Revisions to Terminology and General Requirements

3

23
24

2.2.2.8 audit event type: A field within an audit record that identifies theactivity reported by the record and defines the required content of the record.

25

2.2.2.9 audit ID: An identifier for the user accountable for an audit event.

26
27

2.2.2.10 audit record: The discrete unit of data reportable in an audit log on
the occurrence of an audit event.

28
29

2.2.2.11 audit log: The destination of audit records that are generated and thesource of records read by an audit post-processing application.

30
31

2.2.2.12 availability: The property of an object or subject being accessible andusable upon demand by an authorized user.

32
33
34

2.2.2.13 capability: An attribute of a process that is included in the determina- %tion of whether or not a process has the appropriate privilege to perform a specific
POSIX.1 action where appropriate privilege is required.
−

35
36
37

2.2.2.14 capability flag: A per-capability attribute of a file or process that is +used during exec() processing in computing the capability of the process executingcthat file.

38
39

2.2.2.15 capability state: A grouping of all of the flags defined by an implementation for all capabilities defined for the implementation.

40
41

2.2.2.16 channel: An information transfer path within a system or a mechanism
by which the path is effected.

42
43
44

2.2.2.17 confidentiality: The property that the existence of an object and/or its
contents and/or attributes are not made available nor disclosed to unauthorizedprocesses.

45
46
47
48

2.2.2.18 covert channel: A communications channel that allows a process totransfer information in a manner that violates the system’s security policy. Covert
channels are typically realized by the exploitation of mechanisms not intended to
be used for communication.

49
50

2.2.2.19 data descriptor: An internal representation which uniquely identifies
a data object.

51
52

2.2.2.20 default acl: An ACL which is used in determining the initial discretionary access control information for objects.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

4

2 Revisions to Terminology and General Requirements

53
54

2.2.2.21 denial of service: The unauthorized prevention of authorized access toresources or the delaying of time-critical operations.
−

55
56
57
58
59

2.2.2.22 discretionary access control (DAC): A means of restricting access toobjects based on the identity of the user, process, and/or groups to which theobjects belong. The controls are discretionary in the sense that a subject withsome access permission is capable of passing that permission (perhaps indirectly)
on to other subjects.

60
61

2.2.2.23 dominate: An implementation-defined relation between the values of
MAC labels or information labels.

62
63

2.2.2.24 downgrade: An operation which changes a MAC label or information
label to a value that does not dominate the current label.
−

64
65
66

2.2.2.25 equivalent: An implementation-defined relation between the values of
MAC labels or of information labels. Two labels are equivalent if each of the labels
dominates the other.

67
68

2.2.2.26 extended ACL:
minimum ACL.

69
70

2.2.2.27 exportable data: Opaque data objects for which the data is selfcontained and persistent. As a result, they can be copied or stored freely.

71
72

2.2.2.28 file group class: The property of a file indicating access permissions
for a process related to the process’s group identification.

73
74
75

A process is in the file group class of a file if the process is not in the file ownerclass and if the effective group ID or one of the supplementary group IDs of theprocess matches the group ID associated with the file.

76
77

If {_POSIX_ACL} is defined, then a process is also in the file group class if the pro-c
cess is not in the file owner class and

78
79(1) the effective user ID of the process matches the qualifier of one of the
ACL_USER entries in the ACL associated with the file, or

80
81
82

(2) the effective group ID or one of the supplementary group IDs of the process matches the qualifier of one of the ACL_GROUP entries in the ACL
associated with the file.

An ACL that contains entries in addition to a83

Other members of the class may be implementation defined.

84
85

2.2.2.29 formal security policy model: A precise statement of a system security policy.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
2 Revisions to Terminology and General Requirements

5

86
87
88

2.2.2.30 information label: The representation of a security attribute of a subject or object that applies to the data contained in that subject or object and is not
used for mandatory access control.

89
90
91

2.2.2.31 information label floating: The operation whereby one information
label is combined with another information label. The specific algorithm used todefine the result of a combination of two labels is implementation defined.

92
93
94

2.2.2.32 information label policy: The policy that determines how information
labels associated with objects and subjects are automatically adjusted as dataflows through the system.

95
96
97

2.2.2.33 MAC label: The representation of a security attribute of a subject orobject which represents the sensitivity of the subject or object and is used for
mandatory access control decisions.
−

98
99
100
101
102

2.2.2.34 mandatory access control (MAC): A means of restricting and permitting access to objects based on an implementation-defined security policy using
MAC labels and the use of the implementation-defined dominate operator. The
restrictions are mandatory in the sense that they are always imposed by the system.

103

2.2.2.35 minimum ACL: An ACL that contains only the required ACL entries. −

104
105

2.2.2.36 object: A passive entity that contains or receives data. Access to an
object potentially implies access to the data that it contains.

106
107
108

2.2.2.37 opaque data object: A data repository whose structure and representation is unspecified. Access to data contained in these objects is possible through−the use of defined programming interfaces.

109
110
111
112

2.2.2.38 persistent: A state in which data retains its original meaning as longas the system configuration remains unchanged, even across system reboots.
However, any change to the system configuration (such as adding or deleting user
IDs and modifying the set of valid labels) may render such data invalid.
−

113
114
115
116

2.2.2.39 principle of least privilege: A security design principle that statesthat a process or program be granted only those privileges (e.g., capabilities)
necessary to accomplish its legitimate function, and only for the time that suchprivileges are actually required.

117
118

2.2.2.40 query: Any operation which obtains either data or attributes from asubject or object.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

6

2 Revisions to Terminology and General Requirements

119
120

2.2.2.41 read: A fundamental operation that obtains data from an object or subject.

121
122
123

2.2.2.42 required ACL entries: The three ACL entries that must exist in every
valid ACL. These entries are exactly one entry each for the owning user, the owning group, and other users not specifically enumerated in the ACL.

124
125

2.2.2.43 security: The set of measures defined within a system as necessary toadequately protect the information to be processed by the system.

126
127

2.2.2.44 security administrator: An authority responsible for implementing
the security policy for a security domain.

128
129

2.2.2.45 security attribute: An attribute associated with subjects or objects
which is used to determine access rights to an object by a subject.

130
131
132
133

2.2.2.46 security domain: A set of elements, a security policy, a security
authority and a set of security-relevant activities in which the set of elements are
subject to the security policy, administered by the security authority, for the
specified activities.

134
135

2.2.2.47 security policy: The set of laws, rules, and practices that regulate how
an organization manages, protects, and distributes sensitive information.

136
137

2.2.2.48 security policy model: A precise presentation of the security policy
enforced by a system.
+

138
139
140

2.2.2.49 strictly dominate: A relation between the values of two MAC labels or
information labels whereby one label dominates but is not equivalent to the otherlabel.

141
142

2.2.2.50 subject: An active entity that causes information to flow between
objects or changes the system state; e.g., a process acting on behalf of a user.
c

143
144

2.2.2.51 tranquillity: Property whereby the MAC label of an object can bechanged only while it is not being accessed.
−

145
146

2.2.2.52 upgrade: An operation that changes the value of a MAC label or information label to a value that strictly dominates its previous value.

147
148

2.2.2.53 user: Any person who interacts with a computer system. Operations
are performed on behalf of the user by one or more processes.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
2 Revisions to Terminology and General Requirements

7

149
150

2.2.2.54 write: A fundamental operation that results only in the flow of information from a subject to an object.

151⇒ 2.2.3 Abbreviations (POSIX.1: line 404)

152

For the purpose of this standard, the following abbreviations apply:

153
154
155

(1) POSIX.1: ISO/IEC 9845-1: 1990: Information Technology—Portable
Operating System Interface (POSIX)—Part 1: System Application Program Interface (API) [C Language]

156
157
158

(2) POSIX.2: ISO/IEC 9845-1: 1992: Information IEEE Standard for Infor- cmation Technology—Portable Operating System Interface (POSIX)—Part
2: Shell and Utilities

159
160
161

(3) POSIX.1e: IEEE Std 1003.1e/D17: October 1997, Draft Standard forInformation
Technology—Portable
Operating
SystemInterface(POSIX)—Protection, Audit and Control Interfaces
c

162
163
164

(4) POSIX.2c: IEEE Std 1003.2c/D17: October 1997, Draft Standard forInformation
Technology—Portable
Operating
SystemInterface(POSIX)—Protection and Control Utilitiesc165⇒ 2.3 General Concepts (POSIX.1: lines 406-498)

166
167
168

⇒ 2.3.2 file access permissions (POSIX.1: line 413) Change this sub-clause to c
"2.3.2 file access controls", and incorporate the concept of "file access permissions" under it along with the following new concepts:

169
170
171

One standard file access control mechanism based on file permission bits andtwo optional file access control mechanisms based on access control lists and −MAC labels are defined by this document.

172
173
174

⇒ 2.3.2.1 file access permissions (POSIX.1: line 414) After the above change
to section 2.3.2, create a new subsection called 2.3.2.1 and replace the previous
text in POSIX.1 subsection 2.3.2 with the following.

175
176
177

This standard defines discretionary file access control on the basis of file permission bits as described below. The additional provisions of section 2.3.2.2
apply only if {_POSIX_ACL} is defined.
c

178
179

The file permission bits of a file contain read, write, and execute/search permissions for the file owner class, file group class, and file other class.

180
181
182

These bits are set at file creation by open(), creat(), mkdir(), and mkfifo().
They are changed by chmod() and, if {_POSIX_ACL} is defined, acl_set_file()
and acl_set_fd(). These bits are read by stat(), and fstat().
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

8c

2 Revisions to Terminology and General Requirements

c

183
184
185
186
187

Implementations may provide additional or alternate file access control
mechanisms, or both. An additional access control mechanism shall only
further restrict the access permissions defined by the file access control
mechanisms described in this section. An alternate access control mechanism
shall:

188
189
190

(1) Specify file permission bits for the file owner class, file group class, andfile other class corresponding to the access permissions, to be returned bystat() or fstat().

191
192

(2) Be enabled only by explicit user action on a per file basis by the fileowner or a user with the appropriate privilege.

193
194
195

(3) Be disabled for a file after the file permission bits are changed for thatfile with chmod(). The disabling of the alternate mechanism need notdisable any additional mechanisms defined by an implementation.

196
197
198

Whenever a process requests file access permission for read, write, or
execute/search, if no additional mechanism denies access, access is determined asfollows:

199

If the process possesses appropriate privilege:

200
201

— If read, write, or directory search permission is requested, access isgranted.

202
203
204
205

— If execute permission is requested, access is granted if execute permission is granted to at least one user by the file access permission
bits or by an alternate access control mechanism; otherwise, access isdenied.

206
207
208
209
210
211
212
213
214
215

c

Otherwise:— Access is granted if an alternate access control mechanism is notenabled and the requested access permission bit is set for the class(file owner class, file group class, or file other class) to which the process belongs, or if an alternate access control mechanism is enabled
and it allows the requested access; otherwise, access is denied.
If {_POSIX_CAP} is defined, then appropriate privilege includes the following ccapabilities: CAP_DAC_WRITE for write access, CAP_DAC_EXECUTE for execute access, and CAP_DAC_READ_SEARCH for read and search access. See +Table 25-5.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
2 Revisions to Terminology and General Requirements

9

216

⇒ 2.3.2.2 access control lists: Add this as a new concept.

217
218
219
220
221
222

The {_POSIX_ACL} option provides an additional access control mechanism
by providing file access control based upon an access control list mechanism.
The provisions of this section apply only if {_POSIX_ACL} is defined. Theinteraction between file permission bits and the ACL mechanism is definedsuch that a correspondence is maintained between them. The ACL mechanism
therefore enhances access control based upon the file permission bits.

223
224

An ACL entry shall support at a minimum read, write, and execute/search permissions.

225
226
227
228
229
230
231
232
233
234

An ACL is set at file creation time by open(), creat(), mkdir(), and mkfifo().
An additional default ACL can be associated with a directory; the default ACL
is used in setting the ACL of any object created in that directory. An ACL ischanged by acl_set_fd() and acl_set_file(). A call to acl_set_fd() or acl_set_file()
may also result in a change to the file’s permission bits. A call to chmod() tochange a file’s permission bits will also result in a change to the correspondingc
entries in the ACL. The file’s ACL is read by either acl_get_fd() or
acl_get_file(). A process is granted discretionary access to a file only if all individual requested modes of access are granted by an ACL entry or the process +possesses appropriate privileges.

235
236
237

Whenever a process requests file access permission for read, write, or +execute/search, if no additional mechanism denies access, access is determined+
as follows:+

238

If the process possesses appropriate privilege:

239
240

— If read, write or directory search permission is requested, accessis granted.

241
242
243

— If execute permission is requested, access is granted if executepermission is specified in at least one ACL entry; otherwise,
access is denied.

244

Otherwise:

245
246
247
248
249

— access is granted if an alternate access control mechanism is notenabled and the requested access permissions are granted on thebasis of the evaluation of the ACL (see 23.1.5), or if an alternate
access control mechanism is enabled and it allows the requested
access; otherwise, access is denied.

250
251
252
253

If {_POSIX_CAP} is defined, then appropriate privileges includes the following ccapabilities: CAP_DAC_WRITE for write access, CAP_DAC_EXECUTE for
execute access, and CAP_DAC_READ_SEARCH for read and search access.
See Table 25-5.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

10c

2 Revisions to Terminology and General Requirements

c

254

⇒ 2.3.2.3 mandatory access control: Add this as a new concept.

255
256
257

The {_POSIX_MAC} option provides interfaces to an additional access control
mechanism based on the assignment of MAC labels to subjects and objects.
The provisions of this section only apply if {_POSIX_MAC} is defined.
c

258
259
260
261
262
263
264
265
266

The MAC mechanism permits or restricts access to an object by a process
based on a comparison of the MAC label of the process to the MAC label of theobject. A process can read an object only if the process’s MAC label dominates +the object’s MAC label, and write an object only if the process’s MAC label is +dominated by the object’s MAC label. However, an implementation may
impose further restrictions, permitting write access to objects only byprocesses with a MAC label equivalent to that of the object. The standard does
not define the dominance and equivalence relationships and, thus, does not cdefine a particular MAC policy.

267
268
269
270

MAC read access to an object by a process requires that the process’s MAC
label dominate the object’s MAC label or that the process possess appropriate
privilege. If {_POSIX_CAP} is defined, the appropriate privilege is
CAP_MAC_READ. See Table 25-6.

271
272
273
274

MAC write access to an object by a process requires that the process’s MAC
label be dominated by the object’s MAC label or that the process possess
appropriate privilege. If {_POSIX_CAP} is defined, the appropriate privilege isc
CAP_MAC_WRITE. See Table 25-6.

275

Execute/search file access requires MAC read access to the file.

276
277
278
279
280
281

The MAC label of an object (including a process object) is set at creation time
to dominate the MAC label of the creating process. Although this allows creation of upgraded objects, this standard provides only interfaces which will
create objects with MAC labels equivalent to that of the creating process.
However, interfaces are provided to allow an appropriately privileged process
to upgrade existing objects.

282
283
284
285
286
287
288

c

⇒ 2.3.2.4 evaluation of file access: Add this as a new concept.
Whenever a process requests file access, if an alternate access control mechanism is not enabled and all applicable POSIX.1 access control mechanisms
grant the requested access and all additional access control mechanisms grant c
the requested access or if an alternate access control mechanism is enabledand grants the requested access, then access is granted; otherwise, access isdenied.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
2 Revisions to Terminology and General Requirements

11

c

c

289
290

⇒ 2.3.5 file times update: (POSIX.1: line 475) Add the following paragraph tothe concept definition of file times update:

291
292
293

When {_POSIX_MAC} is defined and the object and process MAC labels are notc
equivalent, then the result of marking the file time attribute st_atime for
update shall be implementation-defined.

294
295

⇒ 2.4 Error Codes Add the following items to the error code definitions in alpha-−
betic order.

296[ENOTSUP] Operation is not supported.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

12

2 Revisions to Terminology and General Requirements

−

c

297
298
299
300
301
302
303
304
305
306
307
308
309
310
311

⇒ 2.7.2 POSIX.1 Symbols (POSIX.1: Table 2-2) Insert the following entries inalphabetical order in Table 2-2:
Reserved

Reserved

HeaderKey
PrefixSuffixiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii<sys/acl.h><sys/audit.h><sys/capability.h><sys/inf.h><sys/mac.h>

1
2
1
2
1
2
1
2
1
2

acl_
ACL_
aud_
AUD_
cap_
CAP_
inf_
INF_
mac_
MAC_

312
313

⇒ 2.7.3 Headers and Function Prototype (POSIX.1: line 910-927) Add thefollowing entries in alphabetical order:

314
315
316
317
318
319
320
321

<sys/acl.h> acl_add_perm(), acl_calc_mask(), acl_clear_perms(),
acl_copy_entry(), acl_copy_ext(), acl_copy_int(),
acl_create_entry(), acl_delete_def_file(), acl_delete_entry(),acl_delete_perm(), acl_dup(), acl_free(), acl_from_text(),
acl_get_entry(), acl_get_fd(), acl_get_file(), acl_get_permset(),acl_get_qualifier(), acl_get_tag_type(), acl_init(), acl_set_fd(),
acl_set_file(), acl_set_permset(), acl_set_qualifier(),
acl_set_tag_type(), acl_size(), acl_to_text(), acl_valid().

322
323
324
325
326
327
328
329
330
331
332
333
334
335

<sys/audit.h> aud_copy_ext(), aud_copy_int(), aud_delete_event(),
aud_delete_event_info(), aud_delete_hdr(), aud_delete_hdr_info(),c
aud_delete_obj(), aud_delete_obj_info(), aud_delete_subj(),
aud_delete_subj_info(), aud_dup_record (), aud_evid_from_text(),
aud_evid_to_text(), aud_free(), aud_get_all_evid(),
aud_get_event(), aud_get_event_info(), aud_get_hdr(),
aud_get_hdr_info(), aud_get_id(), aud_get_obj(),
aud_get_obj_info(), aud_get_subj(), aud_get_subj_info(),
aud_id_from_text(), aud_id_to_text(), aud_init_record(),aud_put_event (), aud_put_event_info(), aud_put_hdr (),aud_put_hdr_info(), aud_put_obj (), aud_put_obj_info(),
aud_put_subj (), aud_put_subj_info(), aud_read(),aud_rec_to_text(), aud_size(), aud_switch(), aud_valid(),
aud_write().

336
337
338
339
340

<sys/capability.h> cap_clear(), cap_copy_ext(), cap_copy_int(), cap_dup (),cap_free(), cap_from_text(), cap_get_fd(), cap_get_file(),cap_get_flag(), cap_get_proc(), cap_init(), cap_set_fd(),
cap_set_file(), cap_set_flag(), cap_set_proc(), cap_size(),
cap_to_text().
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

2 Revisions to Terminology and General Requirements

13

c

341
342
343
344

<sys/inf.h> inf_default(), inf_dominate(), inf_equal(), inf_float(), inf_free(),
inf_from_text(), inf_get_fd(), inf_get_file(), inf_get_proc(),
inf_set_fd(), inf_set_file(), inf_set_proc(), inf_size(), inf_to_text(),
inf_valid().

345
346
347
348

<sys/mac.h> mac_dominate(), mac_equal(), mac_free(), mac_from_text(),
mac_get_fd(), mac_get_file(), mac_get_proc(), mac_glb(),
mac_lub(), mac_set_fd(), mac_set_file(), mac_set_proc(),
mac_size(), mac_to_text(), mac_valid().

349
350

⇒ 2.8.2 Minimum Values (POSIX.1: line 983) Insert the following entry inTable 2-3 in alphabetical order:

351
352
353
359
354
355
356
357
358

Name
Description
Valueiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

360
361
362
363
364
365
367
366

{_POSIX_ACL_ENTRIES_MAX}⇒

The maximum number of entries
in an ACL for objects that support
ACLs.
c
Unspecified
if {_POSIX_ACL} is notdefined.
c

16

2.8.4 Run-Time
Invariant
Values(Possibly
Indeterminate)(POSIX.1: line 1023) Insert the following entry in Table 2-5 in alphabeticalorder:

Name
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii{_POSIX_ACL_MAX}

The maximum number of entries in an ACL for objects that support ACLs.c
Unspecified if {_POSIX_ACL} is not defined.−

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

14

2 Revisions to Terminology and General Requirements

{

368
369

⇒ 2.8.5 Pathname Variable Values (POSIX.1: line 1044) Insert the following
entries in alphabetical order in Table 2-6:

370

Table 2-6 - Pathname Variable Values

371
372
373
379
374
375
376
377
378
380
392
381
382
383
384
385
386
387
388
389
390
391
393
398
394
395
396
397
399
406
400
401
402
403
404
405
407
414
408
409
410
411
412
413

Name
Description
Minimum Valueiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii{_POSIX_ACL_EXTENDED}{_POSIX_ACL_PATH_MAX}{_POSIX_CAP_PRESENT}{_POSIX_INF_PRESENT}{_POSIX_MAC_PRESENT}A value greater than
zero
if
POSIX
extended Access Control Lists are supported on the object;otherwise zero.
Themaximum cnumberof
ACL centries permitted in c
the ACLs associated cwith the object. If c{_POSIX_ACL_EXTENDED}c
is greater than zero,then this value shallbe 16 or greater. If{_POSIX_ACL_EXTENDED}
is zero, then this value
shall be 3.
A value greater thanzero if POSIX FileCapability extensions
are supported on theobject; otherwise zero.
A value greater thanzero if POSIX Information Label functions that set theInformation Label aresupportedontheobject; otherwise zero.
A value greater thanzero if POSIX Mandatory Access Control
functions that set the
MAC label are supported on the object;otherwise zero.

Zero

3 or 16

Zero

Zero

Zero

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
2 Revisions to Terminology and General Requirements

15

415
416
417

⇒ 2.9.3 Compile-Time Symbolic Constants for Portability Specifications(POSIX.1: line 1122) Insert the following entries in Table 2-10 in alphabeticalc
order:

418

Table 2-10 - Compile-Time Symbolic Constants

419
420
421
425
422
423
424
426
430
427
428
429
431
435
432
433
434
436
440
437
438
439
441
445
442
443
444

Name
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii{_POSIX_ACL}{_POSIX_AUD}{_POSIX_CAP}{_POSIX_INF}{_POSIX_MAC}

If this symbol is defined, it
indicates that the implementation supports Access Control List extensions.
If this symbol is defined, it
indicates that the implementation
supports
Auditing
extensions.
If this symbol is defined, it
indicates that the implementation supports Capability
extensions.
If this symbol is defined, it
indicates that the implementation supports Information
Label extensions.
If this symbol is defined, it
indicates that the implementation supports Mandatory
Access Control extensions.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

16

2 Revisions to Terminology and General Requirementsc1Section 3: Revisions to Process Primitives

2
3⇒ 3.1.1.2 Process Creation — Description (POSIX.1: line 36) Insert the following lines after line 32 in Section 3.1.1.2:
c

4
5
6

(1) If {_POSIX_ACL} is defined, the child process shall have its own copy of
any ACL pointers and ACL entry descriptors in the parent, and any ACL
working storage to which they refer.
c

7
8
9
10
11
12

(2) If {_POSIX_AUD} is defined, the child process shall have its own copy of cany audit record descriptors in the parent, and any audit working
storage to which they refer. The audit state of the child, as set by
aud_switch(), shall initially be the same as that of the parent; subsequent calls to aud_switch() in either process shall not affect the audit
state of the other process.
c

13
14
15

⇒ 3.1.2.2 Execute a File — Description (POSIX.1: line 153) Insert the following at the end of the list of attributes inherited by the new process image onexec() following line 153 in Section 3.1.2.2:

16(15) If {_POSIX_MAC} is defined, the process MAC label (see 26.1.1)

%

17
18

⇒ 3.1.2.2 Execute a File — Description (POSIX.1: line 168) Insert the follow-c
ing paragraphs after line 168 in section 3.1.2.2:

19
20
21

If {_POSIX_ACL} is defined, the new process image created shall not inherit
any ACL pointers or ACL entry descriptions or any ACL working storage fromthe previous process image.

22
23
24
25
26

If {_POSIX_AUD} is defined, the new process image shall not inherit any auditc
record descriptors or audit record working storage from the previous process
image. Any incomplete audit records are discarded. The audit state of theprocess, as set by aud_switch() shall be the same as in the previous process
image.

27
28
29

If {_POSIX_CAP} is defined, the new process image shall not inherit any capa- cbility data objects nor any working storage associated with capabilities in theprevious process image.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

3 Revisions to Process Primitives

c

17

c

30
31
32
33
34
35
36
37
38

If {_POSIX_CAP} is defined, the exec() functions shall modify the state of each cof the capabilities of the process as follows, where I1, E1, and P1 are respec- ctively the inheritable, effective, and permitted flags of the new process image; c
I0 is the inheritable flags of the current process image; and If, Ef and Pf are crespectively the inheritable, effective, and permitted flags associated with thefile being executed:
I1 = I0
P1 = ( Pf && X ) || ( If && I0 )E1 = Ef && P1cc39

where X denotes possible additional implementation-defined restrictions.

40
41
42
43
44
45

If {_POSIX_INF} is defined and {_POSIX_INF_PRESENT} is in effect for the cfile being executed, the information label of the process shall automatically be
set to the same value as returned by inf_float(file information label, process
information label). If {_POSIX_INF} is defined but {_POSIX_INF_PRESENT} c
is not in effect for the file being executed, the information label of the process
shall be set in an implementation defined manner.

46
47

+

⇒ 3.3.1.3 Signal Actions — Description (POSIX.1: line 556) Insert the following section before line 556:
c

48
49

If {_POSIX_INF} is defined, the following functions shall also be %reentrant with respect to signals:

50
51

inf_dominate()
inf_equal()
inf_set_proc() inf_size()

52
53

If {_POSIX_MAC} is defined, the following functions shall also
be reentrant with respect to signals:

54
55

mac_dominate()
mac_equal()
mac_set_proc() mac_size()

inf_set_fd()

mac_set_fd()

inf_set_file()

mac_set_file()

56
57⇒ 3.3.2.2 Send a Signal to a Process — Description (POSIX.1: line 594)
Insert the following sentence after the word "privileges":58
59

If {_POSIX_CAP} is defined, then appropriate privilege shall include
CAP_KILL.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

18c

3 Revisions to Process Primitives

c

60
61

⇒ 3.3.2.2 Send a Signal to a Process — Description (POSIX.1: line 616)
Insert the following after line 616:

62
63
64
65

If {_POSIX_MAC} is defined, then in addition to the restrictions defined above,cthe following restrictions apply depending on the MAC labels of the sending
and receiving process. There are four cases to be considered for each potential
receiving process specified by pid:

6667(1) If the MAC label of the sending process is equivalent to the MAC label ofthe receiving process, then no additional restrictions are imposed.

68
69
70
71

(2) If the MAC label of the sending process dominates the MAC label of thereceiver (i.e., the signal is being written down), then the sending process
must have appropriate privilege. If {_POSIX_CAP} is defined, thenappropriate privilege shall include CAP_MAC_WRITE.

72
73
74
75
76

(3) If the MAC label of the receiving process dominates the MAC label of thesending process (i.e., the signal is being written up), then it is implementation defined whether the sending process requires appropriate
privilege. If {_POSIX_CAP} is defined and appropriate privilege isrequired, then appropriate privilege shall include CAP_MAC_READ.

77
78
79
80

(4) If neither of the MAC labels of the sender and receiver dominates the %other, then the sending process must have appropriate privilege. If{_POSIX_CAP} is defined, appropriate privilege shall include c
CAP_MAC_WRITE.

81
82

83
84

90
91
92

c

⇒ 3.3.2.4 Send a Signal to a Process — Errors (POSIX.1: line 625-628)
Replace lines 625-628 with the following:[EPERM]

85
86
87
88
89

c

The process does not have permission to send the signal to
any receiving process.
If {_POSIX_MAC} is defined, the process has appropriate
MAC access to a receiving process, but other access checks
have denied the request.

[ESRCH]No process or process group can be found corresponding tothat specified by pid.
If {_POSIX_MAC} is defined, a receiving process or processes c
may actually exist, but the sending process does not haveappropriate MAC access to any of the receiving processes.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
3 Revisions to Process Primitives

19

c

1

Section 4: Revisions to Process Environment2
3⇒ 4.2.2.2 Set User and Group IDs — Description (POSIX.1: line 48) Insert
the following after line 48 of Section 4.2.2.2:

4
5

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_SETUID capability.

67⇒ 4.2.2.2 Set User and Group IDs — Description (POSIX.1: line 52) Insert
the following after line 52 of Section 4.2.2.2:

8
9

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_SETUID capability.

10
11⇒ 4.2.2.2 Set User and Group IDs — Description (POSIX.1: line 54) Insert
the following after line 54 of Section 4.2.2.2:

12
13

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_SETGID capability.

14
15⇒ 4.2.2.2 Set User and Group IDs — Description (POSIX.1: line 58) Insert
the following after line 58 of Section 4.2.2.2:

16
17

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_SETGID capability.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
4 Revisions to Process Environment

21

18
19

⇒ 4.2.2.2 Set User and Group IDs — Description (POSIX.1: line 61) Insert
the following after line 61 of Section 4.2.2.2:

20
21

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_SETUID capability.

22
23⇒ 4.2.2.2 Set User and Group IDs — Description (POSIX.1: line 64) Insert
the following after line 64 of Section 4.2.2.2:

24
25

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_SETUID capability.

26
27⇒ 4.2.2.2 Set User and Group IDs — Description (POSIX.1: line 66) Insert
the following after line 66 of Section 4.2.2.2:

28
29

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_SETGID capability.

30
31⇒ 4.2.2.2 Set User and Group IDs — Description (POSIX.1: line 69) Insert
the following after line 69 of Section 4.2.2.2:

32
33

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_SETGID capability.

34
35⇒ 4.8.1.2 Get Configurable System Variables — Description (POSIX.1: line407) Insert the following entries in Table 4-2:

36
37
38
39
40
41
42
43

Variablename Valueiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii{_POSIX_ACL_MAX}{_POSIX_ACL}{_POSIX_AUD}{_POSIX_CAP}{_POSIX_INF}{_POSIX_MAC}{_SC_ACL_MAX}{_SC_ACCESS_CONTROL_LIST}{_SC_AUDIT}{_SC_CAPABILITIES}{_SC_INFORMATION_LABEL}{_SC_MANDATORY_ACCESS_CONTROL}WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

22

4 Revisions to Process Environmentc

1Section 5: Revisions to Files and Directories

23⇒ 5.3.1.2 Open a File — Description (POSIX.1: lines 192-194) Replace thesentence beginning ‘‘The file permission bits ...’’, with the following:

4
5
6

If {_POSIX_ACL} is defined and {_POSIX_ACL_EXTENDED} is in effect for c
the directory in which the file is being created (the "containing directory") and −said directory has a default ACL, the following actions shall be performed:

7
8

(1)

The default ACL of the containing directory is copied to the access
ACL of the new file.

9
10
11
12
13
14

(2)

Both the ACL_USER_OBJ ACL entry permission bits and the fileowner class permission bits of the access ACL are set to the intersec- +tion of the default ACL’s ACL_USER_OBJ permission bits and the fileowner class permission bits in mode. The action taken for any
implementation-defined permissions that may be in the
ACL_USER_OBJ entry shall be implementation-defined.

15
16
17
18
19
20
21

(3)

If the default ACL does not contain an ACL_MASK entry, both the
ACL_GROUP_OBJ ACL entry permission bits and the file group classpermission bits of the access ACL are set to the intersection of the +default ACL’s ACL_GROUP_OBJ permission bits and the file groupclass permission bits in mode. The action taken for any
implementation-defined permissions that may be in the
ACL_GROUP_OBJ entry shall be implementation-defined.

22
23
24
25
26
27
28

(4)

If the default ACL contains an ACL_MASK entry, both the
ACL_MASK ACL entry permission bits and the file group class permission bits of the access ACL are set to the intersection of the default+
ACL’s ACL_MASK permission bits and the file group class permission
bits in mode. The action taken for any implementation-defined permissions that may be in the ACL_MASK entry shall be
implementation-defined.

29
30
31
32
33
34

(5)

Both the ACL_OTHER ACL entry permission bits and the file otherclass permission bits of the access ACL are set to the intersection of +the default ACL’s ACL_OTHER permission bits and the file otherclass permission bits in mode. The action taken for any
implementation-defined permissions that may be in the ACL_OTHER
entry shall be implementation-defined.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
5 Revisions to Files and Directories

23

35
36
37
38
39
40
41

Implementation-defined default ACL entries may affect the above algorithm
but shall not alter the access permitted to any subject that does not match
those implementation-defined ACL entries. Implementations may provide an
additional default ACL mechanism that is applied if a default ACL as definedby this standard is not present. Such an implementation-defined default ACL cinterface may apply different access and/or default ACLs to created objects
based upon implementation-defined criteria.

42
43
44
45
46
47
48
49

If {_POSIX_ACL} is not defined, or {_POSIX_ACL_EXTENDED} is not in effectc
for the directory in which the file is being created (the "containing directory"), cor said directory does not have a default ACL, the file permission bits (see5.6.1) shall be set to the value of mode except those set in the file mode creation mask of the process (see 5.3.3). In any of these cases (default ACL,
implementation-defined default ACL, or file permission bits), access control
decisions shall not be made on the newly created file until all access control
information has been associated with the file.

50
51⇒ 5.3.1.2 Open a File — Description (POSIX.1: line 197) Insert the following
lines after line 197 in Section 5.3.1.2:

52
53
54
55
56
57

If {_POSIX_MAC} is defined and {_POSIX_MAC_PRESENT} is in effect for the ccontaining directory and the file is created, the MAC label of the newly createdfile shall be equivalent to the MAC label of the calling process. If{_POSIX_INF} is defined and the file is created, the information label of thefile shall automatically be set to a value which dominates the value returned
by inf_default().

58
59⇒ 5.3.1.2 Open a File — Description (POSIX.1: line 234) Insert the following
sentences after line 234 in Section 5.3.1.2:

60
61
62

If {_POSIX_INF} is defined and {_POSIX_INF_PRESENT} is in effect for the
file path, then the information label of the file shall automatically be set to avalue which dominates the value returned by inf_default().

63
64⇒ 5.3.1.2 Open a File — Description (POSIX.1: line 240) Insert the following
paragraph after line 240 in Section 5.3.1.2:

65
66
67
68

If {_POSIX_MAC} is defined and if the file exists and it is a FIFO special file,then the calling process shall have MAC write access to the file. If the file
exists and is a FIFO special file, and the value of oflag includes O_RDONLY or
O_RDWR then the calling process shall also have MAC read access to the file.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

24

5 Revisions to Files and Directories

c

c

c

69
70

⇒ 5.3.4.2 Link a File — Description (POSIX.1: line 331) Insert the following
sentence:

71
72

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_LINK_DIR capability.

73
74⇒ 5.3.4.2 Link a File — Description (POSIX.1: line 336) Insert the following
paragraph after line 336 in Section 5.3.4.2:

75
76
77

If {_POSIX_MAC} is defined, the calling process shall have MAC write accessto existing, MAC read access to the path to existing and new, and MAC readaccess to new.

78
79

If {_POSIX_MAC} is defined the calling process shall also have MAC write
access to the directory in which the new entry is to be created.
c

80
81

If {_POSIX_INF} is defined and {_POSIX_INF_PRESENT} is in effect for the
existing argument, the information label of existing remains unchanged.
c

82
83

⇒ 5.3.4.4 Link a File — Errors (POSIX.1: line 347) Insert the following after
the line:

84
85
86

or {_POSIX_MAC} is defined and MAC write access was denied to existing or toc
the directory in which new is to be created or MAC read access was denied tothe path to existing or to new.

87
88

⇒ 5.4.1.2 Make a Directory — Description (POSIX.1: lines 378-380) Replace
the second and third sentences of the paragraph with the following:

89
90
91
92

c

c

If {_POSIX_ACL} is defined and {_POSIX_ACL_EXTENDED} is in effect for c
the directory in which the new directory is being created (the "containing
directory") and said directory has a default ACL, the following actions shall be −performed:

93
94

(1)

The default ACL of the containing directory is copied to both theaccess ACL and the default ACL of the new directory.

95
96
97
98
99
100

(2)

Both the ACL_USER_OBJ ACL entry permission bits and the fileowner class permission bits of the access ACL are set to the intersec- +tion of the default ACL’s ACL_USER_OBJ permission bits and the fileowner class permission bits in mode. The action taken for any
implementation-defined permissions that may be in the
ACL_USER_OBJ entry shall be implementation-defined.

101
102
103

(3)

If the default ACL does not contain an ACL_MASK entry, both the
ACL_GROUP_OBJ ACL entry permission bits and the file group classpermission bits of the access ACL are set to the intersection of the +WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

5 Revisions to Files and Directories

25

104
105
106
107

default ACL’s ACL_GROUP_OBJ permission bits and the file groupclass permission bits in mode. The action taken for any
implementation-defined permissions that may be in the
ACL_GROUP_OBJ entry shall be implementation-defined.

108
109
110
111
112
113
114

(4)

If the default ACL contains an ACL_MASK entry, both the
ACL_MASK ACL entry permission bits and the file group class permission bits of the access ACL are set to the intersection of the default+
ACL’s ACL_MASK permission bits and the file group class permission
bits in mode. The action taken for any implementation-defined permissions that may be in the ACL_MASK entry shall be
implementation-defined.

115
116
117
118
119
120

(5)

Both the ACL_OTHER ACL entry permission bits and the file otherclass permission bits of the access ACL are set to the intersection of +the default ACL’s ACL_OTHER permission bits and the file otherclass permission bits in mode. The action taken for any
implementation-defined permissions that may be in the ACL_OTHER
entry shall be implementation-defined.

121
122
123
124
125
126
127

Implementation-defined default ACL entries may affect the above algorithm
but shall not alter the access permitted to any subject that does not match
those implementation-defined ACL entries. Implementations may provide an
additional default ACL mechanism that is applied if a default ACL as definedby this standard is not present. Such an implementation-defined default ACL cinterface may apply different access and/or default ACLs to created objects
based upon implementation-defined criteria.

128
129
130
131
132
133
134
135

If {_POSIX_ACL} is not defined or {_POSIX_ACL_EXTENDED} is not in effect c
for the directory in which the file is being created (the "containing directory"), cor said directory does not have a default ACL, the file permission bits of the
new directory shall be set to the value of mode except those set in the file mode
creation mask of the process (see 5.3.3). In any of these cases (default ACL,
implementation-defined default ACL, or file permission bits), access control
decisions shall not be made on the newly created directory until all access control information has been associated with the directory.

136
137

⇒ 5.4.1.2 Make a Directory — Description (POSIX.1: line 385) Insert the following paragraphs after line 385 in Section 5.4.1.2:

138
139
140

If {_POSIX_MAC} is defined and {_POSIX_MAC_PRESENT} is in effect for the ccontaining directory and the directory is created, the MAC label of the newly
created directory shall be equivalent to the MAC label of the calling process.

141
142

If {_POSIX_MAC} is defined, the calling process shall require MAC write
access to the containing directory.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

26

5 Revisions to Files and Directories

c

143
144
145
146
147

⇒ 5.4.2.2 Make a FIFO Special File — Description (POSIX.1: lines 426-428)
Replace the second and third sentences in the paragraph with the following:
If {_POSIX_ACL} is defined and {_POSIX_ACL_EXTENDED} is in effect for c
the directory in which the FIFO is being created (the "containing directory") −and said directory has a default ACL, the following actions shall be performed:

148
149

(1)

The default ACL of the containing directory is copied to the access
ACL of the new FIFO.

150
151
152
153
154
155

(2)

Both the ACL_USER_OBJ ACL entry permission bits and the fileowner class permission bits of the access ACL are set to the inter-+section of the default ACL’s ACL_USER_OBJ permission bits andthe file owner class permission bits in mode. The action taken for
any implementation-defined permissions that may be in the
ACL_USER_OBJ entry shall be implementation-defined.

156
157
158
159
160
161
162

(3)

If the default ACL does not contain an ACL_MASK entry, both
the ACL_GROUP_OBJ ACL entry permission bits and the filegroup class permission bits of the access ACL are set to the inter- +section of the default ACL’s ACL_GROUP_OBJ permission bits
and the file group class permission bits in mode. The action
taken for any implementation-defined permissions that may be in
the ACL_GROUP_OBJ entry shall be implementation-defined.

163
164
165
166
167
168
169

(4)

If the default ACL contains an ACL_MASK entry, both the
ACL_MASK ACL entry permission bits and the file group classpermission bits of the access ACL are set to the intersection of the+default ACL’s ACL_MASK permission bits and the file groupclass permission bits in mode. The action taken for any
implementation-defined permissions that may be in the
ACL_MASK entry shall be implementation-defined.

170
171
172
173
174
175

(5)

Both the ACL_OTHER ACL entry permission bits and the fileother class permission bits of the access ACL are set to the inter- +section of the default ACL’s ACL_OTHER permission bits and thefile other class permission bits in mode. The action taken for any
implementation-defined permissions that may be in the
ACL_OTHER entry shall be implementation-defined.

176
177
178
179
180
181
182

Implementation-defined default ACL entries may affect the above algorithm
but shall not alter the access permitted to any subject that does not match
those implementation-defined ACL entries. Implementations may provide an
additional default ACL mechanism that is applied if a default ACL as definedby this standard is not present. Such an implementation-defined default ACL cinterface may apply different access and/or default ACLs to created objects
based upon implementation-defined criteria.

183
184
185
186

If {_POSIX_ACL} is not defined or {_POSIX_ACL_EXTENDED} is not in effect c
for the directory in which the file is being created (the "containing directory"), cor said directory does not have a default ACL, the file permission bits of the cnew FIFO are initialized from mode. The file permission bits of the mode c
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

5 Revisions to Files and Directories

27

187

argument are modified by the file creation mask of the process (see 5.3.3).

188
189

⇒ 5.4.2.2 Make a FIFO Special File — Description (POSIX.1: lines 432)
Insert the following paragraphs after line 432 in Section 5.4.2.2:

190
191
192
193
194

If {_POSIX_MAC} is defined and {_POSIX_MAC_PRESENT} is in effect for the ccontaining directory and the special file is created, the MAC label of the newly
created special file shall be equivalent to the MAC label of the calling process
and the calling process shall have MAC write access to the parent directory of
the file to be created.

195
196
197
198

If {_POSIX_INF} is defined and {_POSIX_INF_PRESENT} is in effect for the %file path, and the special file is created, then the information label of the special file shall automatically be set to a value which dominates the value
returned by inf_default().

199
200

⇒ 5.5.1.2 Remove Directory Entries — Description (POSIX.1: line 474)
Insert the following paragraphs:

201
202

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_ADMIN capability.

203
204

If {_POSIX_MAC} is defined the calling process shall have MAC write access toc
the directory containing the link to be removed.

205
206

⇒ 5.5.1.4 Remove Directory Entries — Errors (POSIX.1: line 487) Insert
the following phrase at the end of the line:

207
208

or {_POSIX_MAC} is defined and MAC write access to the directory containing c
the link to be removed was denied.

209
210

⇒ 5.5.2.2 Remove a Directory — Description (POSIX.1: line 520) Insert thefollowing paragraph after line 520:

211
212
213
214

If {_POSIX_MAC} is defined, the calling process shall have MAC write accessto the parent directory of the directory being removed. If {_POSIX_MAC} isdefined, the calling process shall have MAC read access to the parent directoryof the directory being removed.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

28

5 Revisions to Files and Directories

c

c
c

215
216

⇒ 5.5.2.4 Remove a Directory — Errors (POSIX.1: line 532) Insert the following phrase at the end of the line:

217
218
219

or {_POSIX_MAC} is defined and MAC write access was denied to the parent
directory of the directory being removed or MAC read access was denied to thedirectory containing path.

220
221

⇒ 5.5.3.2 Rename a File — Description (POSIX.1: line 583) Insert the following paragraph after line 566:

222
223
224
225

If {_POSIX_MAC} is defined the calling process must have MAC write access toc
the directory containing old and to the directory that will contain new. If{_POSIX_MAC} is defined, and the link named by the new argument exists,
the calling process shall have MAC write access to new.

226
227

⇒ 5.6.2.2 Get File Status — Description (POSIX.1: line 726) Insert the following sentence:

228
229
230
231
232
233
234

If {_POSIX_ACL} is defined, and {_POSIX_ACL_EXTENDED} is in effect forthe pathname, and the access ACL contains an ACL_MASK entry, then the filec
group class permission bits represent the ACL_MASK access ACL entry filepermission bits. If {_POSIX_ACL} is defined, and {_POSIX_ACL_EXTENDED}c
is in effect for the pathname, and the access ACL does not contain an
ACL_MASK entry, then the file group class permission bits represent the
ACL_GROUP_OBJ access ACL entry file permission bits.

235
236

⇒ 5.6.2.2 Get File Status — Description (POSIX.1: line 727) Insert the following:

237
238
239

240
241
242

c

c

c
c
c
c

If {_POSIX_MAC} is defined stat() shall require the calling process have MAC cread access to the file. If {_POSIX_MAC} is defined fstat() shall require the ccalling process have the file open for read or have MAC read access to the file.

⇒ 5.6.2.4 Get File Status — Errors (POSIX.1: line 738) Insert the following
phrase at the end of this line:or {_POSIX_MAC} is defined and MAC read access is denied to the file.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
5 Revisions to Files and Directories

29

c

243
244

⇒ 5.6.4.2 Change File Modes — Description (POSIX.1: line 802) Insert thefollowing sentence in line 802 of Section 5.6.4.2:

245
246

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_FOWNER capability.

247
248

⇒ 5.6.4.2 Change File Modes — Description (POSIX.1: line 804) Insert thefollowing sentence in line 804:

249
250
251

If the process does not have appropriate privilege, then the S_ISUID bit in themode is ignored. If {_POSIX_CAP} is defined, then appropriate privilege shall c
include the CAP_FSETID capability.

252
253

⇒ 5.6.4.2 Change File Modes — Description (POSIX.1: line 805) Insert thefollowing paragraph after this line:

c

254
255

If {_POSIX_ACL} is defined and {_POSIX_ACL_EXTENDED} is in effect for −the pathname, then the following actions shall be performed.

256
257

(1) The ACL_USER_OBJ access ACL entry permission bits shall be set equal+
to the file owner class permission bits.

258
259
260
261
262
263

(2) If an ACL_MASK entry is not present in the access ACL, then the +ACL_GROUP_OBJ access ACL entry permission bits shall be set equal to+
the file group class permission bits. Otherwise, the ACL_MASK access +ACL entry permission bits shall be set equal to the file group class permission bits, and the ACL_GROUP_OBJ access ACL entry permission +bits shall remain unchanged.

264
265

(3) The ACL_OTHER access ACL entry permission bits shall be set equal to +the file other class permission bits.

266
267

⇒ 5.6.4.2 Change File Modes — Description (POSIX.1: line 809) Insert thefollowing sentence after this line:

268
269

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_FSETID capability.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

30

5 Revisions to Files and Directories

c

270
271

⇒ 5.6.4.2 Change File Modes — Description (POSIX.1: line 811) Insert thefollowing sentence after line 811 of Section 5.6.4.2:

272
273

If {_POSIX_MAC} is defined, the calling process shall have MAC write accessto the file.

274
275

⇒ 5.6.4.2 Change File Modes — Errors (POSIX.1: line 821) Insert the following phrase at the end of this line:276

or {_POSIX_MAC} is defined and MAC write access to the target file is denied. c

277
278

⇒ 5.6.5.2 Change Owner and Group of a File — Description (POSIX.1: line844) Insert the following sentence in this line:

279
280

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_FOWNER capability.

281
282

⇒ 5.6.5.2 Change Owner and Group of a File — Description (POSIX.1: line
847) Insert the following sentence after this line:

283
284

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_CHOWN capability.

285
286

⇒ 5.6.5.2 Change Owner and Group of a File — Description (POSIX.1: line856) Insert the following sentence after the word "altered":

287
288

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_FSETID capability.

289
290

⇒ 5.6.5.2 Change Owner and Group of a File — Description (POSIX.1: line858) Insert the following paragraph after line 858:

291
292

If {_POSIX_MAC} is defined, the calling process shall have MAC write accessto the file.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
5 Revisions to Files and Directories

31

c

c

c

c

c

293
294

⇒ 5.6.5.4 Change Owner and Group of a File — Errors (POSIX.1: line 868)
Insert the following phrase at the end of this line:295

or {_POSIX_MAC} is defined and MAC write access to the target file is denied. c

296
297

⇒ 5.6.5.4 Change Owner and Group of a File — Errors (POSIX.1: line 879) c
Insert the following sentences after this line:
c

298
299
300
301
302

If {_POSIX_CAP} is defined and {_POSIX_CHOWN_RESTRICTED} is defined, cand the effective user ID matches the owner of the file, then appropriate
privilege shall include the CAP_CHOWN capability. If {_POSIX_CAP} isdefined, and the effective user ID does not match the owner of the file, thenappropriate privilege shall include the CAP_FOWNER capability.

303
304

⇒ 5.6.6.2 Set File Access and Modification Times — Description(POSIX.1: line 899) Insert the following sentence after this line:

305
306

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_FOWNER capability.

307
308

⇒ 5.6.6.2 Set File Access and Modification Times — Description(POSIX.1: line 899) Insert the following paragraph after this:

309
310

If {_POSIX_MAC} is defined, then the process shall have MAC write access to c
the file.

311
312⇒ 5.6.6.2 Set File Access and Modification Times — Description(POSIX.1: line 903) Insert the following sentence after this line:

313
314

If {_POSIX_CAP} is defined, then appropriate privilege shall include the
CAP_FOWNER capability.

315
316

⇒ 5.6.6.4 Set File Access and Modification Times — Errors (POSIX.1: line
927) Insert the following phrase at the end of this line:317

or {_POSIX_MAC} is defined and MAC write access to the target file is denied. c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

32

5 Revisions to Files and Directories

c

c

c

c

c

318
319
320
321
322
323
324
325
326

⇒ 5.7.1.3 Get Configurable Pathname Variables — Returns (POSIX.1: line965) Add the following variables to Table 5-2:
Variablename Value
Notesiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii{_POSIX_ACL_EXTENDED}{_POSIX_ACL_PATH_MAX}{_POSIX_CAP_PRESENT}{_POSIX_MAC_PRESENT}{_POSIX_INF_PRESENT}{_PC_ACL_EXTENDED}{_PC_ACL_MAX}{_PC_CAP_PRESENT}{_PC_MAC_PRESENT}{_PC_INF_PRESENT}

(7)
(7)
(7)
(7)
(7)

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
5 Revisions to Files and Directories

33

c

1

Section 6: Revisions to Input and Output Primitives

2
3⇒ 6.1.1.2 Create an Inter-Process Channel — Description (POSIX.1: line21) Insert the following paragraphs after this line:

4
5
6
7

If {_POSIX_MAC} is defined, then the MAC label of a pipe shall be equivalent
to the MAC label of the process that created it. The MAC label is present for
return by mac_get_fd(). This standard does not define that any access control cdecisions are made using the label.

89

If {_POSIX_INF} is defined, the information label of the pipe shall automatically be set to a value which dominates the value returned by inf_default().

1011⇒ 6.4.1.2 Read from a File — Description (POSIX.1: line 158) Insert the following paragraph after this line:

12
13
14
15

If {_POSIX_INF} is defined and {_POSIX_INF_PRESENT} is in effect for the
file being read, then the information label of the process shall automatically be
set to an implementation-defined value that shall be the same as the value of
inf_float(file information label, process information label).

16
17⇒ 6.4.2.2 Write to a File — Description (POSIX.1: line 261) Insert the following paragraph after this line:

18
19
20
21

If {_POSIX_INF} is defined and {_POSIX_INF_PRESENT} is in effect for the
file being written, then the information label of the file shall automatically be
set to an implementation-defined value which shall be the same as the value of
inf_float(process information label, file information label).

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
6 Revisions to Input and Output Primitives

35

1

Section 8: Revisions to C Programming Language Specific Services23⇒ 8.2.3 Interactions of Other File Type C Functions (POSIX.1: line 345)
Insert the following sentence after line 345:

456

In particular, if an optional portion of this standard is present, the traits
specific to the option in the underlying function must be shared by the stream
function.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
8 Revisions to C Programming Language Specific Services

37

Section 23: Access Control Lists

1

2

23.1 General Overview

3
4
5
6

The POSIX.1e ACL facility defines an interface for manipulating Access Control
Lists. This interface is an extension of the POSIX.1 file permission bits. Support
for the interfaces defined in this section is optional but shall be provided if thesymbol {_POSIX_ACL} is defined.
c

7
8
9
10

The POSIX.1e ACL interface does not alter the syntax of existing POSIX.1 interfaces. However, the access control semantics associated with existing POSIX.1
interfaces are necessarily more complex as a result of ACLs. The POSIX.1e ACL
facility includes:

11(1) Definition and use of access and default ACLs

12(2) Definition of initial access permissions on object creation

13(3) Specification of the access check algorithm

14(4) Functions to manipulate ACLs.

15
16
17
18
19
20
21
22
23
24
25
26
27
28

Every object can be thought of as having associated with it an ACL that governs
the discretionary access to that object; this ACL is referred to as an access ACL.
In addition, a directory may have an associated ACL that governs the initialaccess ACL for objects created within that directory; this ACL is referred to as a +default ACL. Files, as defined by POSIX.1, are the only objects for which the
POSIX.1e ACL facility defines ACLs. For the purposes of this document, the
POSIX.1 file permission bits will be considered as a special case of an ACL. An
ACL consists of a set of ACL entries. An ACL entry specifies the access permissions on the associated object for an individual user or a group of users. The
POSIX.1e ACL facility does not dictate the actual implementation of ACLs or the
existing POSIX.1 file permission bits. The POSIX.1e ACL facility does not dictate
the specific internal representation of an ACL nor any ordering of entries within
an ACL. In particular, the order of internal storage of entries within an ACL does
not affect the order of evaluation.

29
30
31

In order to read an ACL from an object, a process must have read access to theobject’s attributes. In order to write (update) an ACL to an object, the process
must have write access to the object’s attributes.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.1 General Overview

39

32

23.1.1 ACL Entry Composition

33

An ACL entry contains, at a minimum, three distinct pieces of information:

34(1) tag type: specifies the type of ACL entry

35(2) qualifier: specifies an instance of an ACL entry tag type3637(3) permissions set: specifies the discretionary access rights for processes
identified by the tag type and qualifier

38
39

A conforming implementation may add implementation-defined pieces of information to an ACL entry.

40

A conforming ACL implementation shall define the following tag types:

41
42
43

— ACL_GROUP: an ACL entry of tag type ACL_GROUP denotes discretionary access rights for processes whose effective group ID or any supplemental group IDs match the ACL entry qualifier

44
45
46

— ACL_GROUP_OBJ: an ACL entry of tag type ACL_GROUP_OBJ denotes
discretionary access rights for processes whose effective group ID or any
supplemental group IDs match the group ID of the group of the file.

47
48
49

— ACL_MASK: an ACL entry of tag type ACL_MASK denotes the maximum
discretionary access rights that can be granted to a process in the file groupc
class.

50
51
52— ACL_OTHER: an ACL entry of tag type ACL_OTHER denotes discretionary
access rights for processes whose attributes do not match any other entry inc
the ACL

53
54
55— ACL_USER: an ACL entry of tag type ACL_USER denotes discretionary
access rights for processes whose effective user ID matches the ACL entry
qualifier

56
57
58

— ACL_USER_OBJ: an ACL entry of tag type ACL_USER_OBJ denotes discretionary access rights for processes whose effective user ID matches theuser ID of the owner of the file.

59

A conforming implementation may define additional tag types.

60
61
62
63

This standard extends the file group class, as defined in POSIX.1, to include
processes which are not in the file owner class and which match ACL entries with−the tag types ACL_GROUP, ACL_GROUP_OBJ, ACL_USER, or any
implementation-defined tag types that are not in the file owner class.

64
65
66
67
68

An ACL shall contain exactly one entry for each of ACL_USER_OBJ,
ACL_GROUP_OBJ, and ACL_OTHER tag types. ACL entries with ACL_GROUP
and ACL_USER tag types shall appear zero or more times in an ACL. A conform-c
ing implementation shall support the maximum number of entries in an ACL, as
defined by the value of {_POSIX_ACL_PATH_MAX}, on a non-empty set of objects.c

69
70
71

The three ACL entries of tag type ACL_USER_OBJ, ACL_GROUP_OBJ, and
ACL_OTHER are referred to as the required ACL entries. An ACL that contains
only the required ACL entries is called a minimum ACL. An ACL which is not a
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

40

23 Access Control Lists

c

c

72

minimum ACL is called an extended ACL.

73
74
75
76

An ACL that contains ACL_GROUP, ACL_USER, or implementation-defined ACL
entries in the file group class shall contain exactly one ACL_MASK entry. If an
ACL does not contain ACL_GROUP, ACL_USER, or implementation-defined ACL
entries in the file group class, then the ACL_MASK entry shall be optional.

77
78
79
80
81
82
83
84
85

The qualifier field associated with the POSIX.1e ACL facility defined tag types
shall not be extended to contain any implementation-defined information. The
qualifier field associated with implementation-defined tag types may contain fully
implementation-defined information. The qualifier field shall be unique among
all entries of the same POSIX.1e ACL facility defined tag type in a given ACL.
For entries of the ACL_USER and ACL_GROUP tag type, the qualifier field shallbe present and contain either a user ID or a group ID respectively. The value ofthe qualifier field in entries of tag types ACL_GROUP_OBJ, ACL_MASK,ACL_OTHER, and ACL_USER_OBJ shall be unspecified.
c

86
87
88

The set of discretionary access permissions shall, at a minimum, include: read,
write, and execute/search. Additional permissions may be added and shall be +implementation-defined.

89

23.1.2 Relationship with File Permission Bits

90
91
92
93
94

ACL interfaces extend the file permission bit interfaces to provide a finer granu- clarity of access control than is possible with permission bits alone. As a supersetof the file permission bit interface, the ACL functionality specified preserves com- cpatibility with applications using POSIX.1 interfaces to retrieve and manipulate
access permission bits, e.g., chmod(), creat(), and stat().

95
96
97
98
99
100
101
102

The file permission bits shall correspond to three entries in an ACL. The permis- csions specified by the file owner class permission bits correspond to the permissions associated with the ACL_USER_OBJ entry. The permissions specified by c
the file group class permission bits correspond to the permissions associated with
the ACL_GROUP_OBJ entry or the permissions associated with the ACL_MASK
entry if the ACL contains an ACL_MASK entry. The permissions specified by the cfile other class permission bits correspond to the permissions associated with the
ACL_OTHER entry.

103
104
105
106
107

The permissions associated with these ACL entries shall be identical to the permissions defined for the corresponding file permission bits. Modification of thepermissions associated with these ACL entries shall modify the corresponding filepermission bits and modification of the file permission bits shall modify the permissions of the corresponding ACL entries.

108
109

When the file permissions of an object are modified, e.g. using the chmod() function, then:

110
111

(1) the corresponding permissions associated with the ACL_USER_OBJ
entry shall be set equal to each of the file owner class permission bits

112
113

(2) if the ACL does not contain an ACL_MASK entry, then the corresponding
permissions associated with the ACL_GROUP_OBJ entry shall be set
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

23.1 General Overview

41

114

equal to each of the file group class permission bits

115
116
117
118

(3) if the ACL contains an ACL_MASK entry, then the corresponding permissions associated with the ACL_MASK entry shall be set equal to eachof the file group class permission bits and the permissions associatedwith the ACL_GROUP_OBJ entry shall not be modified.

119
120

(4) the corresponding permissions associated with the ACL_OTHER entry
shall be set equal to each of the file other class permission bits

121

23.1.3 Default ACLs

122
123
124
125
126
127
128
129
130
131
132

A default ACL is an additional ACL which may be associated with a directory, butc
which has no operational effect on the discretionary access on that directory. It
shall be possible to associate a default ACL with any directory for which{_POSIX_ACL_EXTENDED} is in effect. If there is a default ACL associated witha directory, then that default ACL shall be used, as specified in 23.1.4, to initialize the access ACL for any object created in that directory. If the newly createdobject is a directory and if the parent directory has a default ACL, then the new
directory inherits the parent’s default ACL as its default ACL. Entries within adefault ACL are manipulated using the same interfaces as those used for anaccess ACL. A default ACL has the same minimum required entries as an access
ACL as specified in 23.1.1.

133
134
135
136
137
138
139

Directories are not required to have a default ACL. While any particular directory for which {_POSIX_ACL_EXTENDED} is in effect may have a default ACL, aconforming implementation shall support the default ACL interface described
here. If a default ACL does not exist on a directory, then any implementationdefined default ACL(s) may be applied to the access or default ACLs of objects
created in that directory. If no default ACL is applied, the initial access control
information shall be obtained as specified in 5.3 and 5.4.
+

140

23.1.4 Associating an ACL with an Object at Object Creation Time

141
142
143

When an object is created, its access ACL is always initialized. If a default ACL is
associated with a directory, two components may be used to determine the initialaccess ACL for objects created within that directory:
−

144
145
146
147
148

(1) The mode parameter to functions which can create objects may be usedby an application to specify the maximum discretionary access permissions to be associated with the resulting object. There are four POSIX.1
functions which can be used to create objects: creat(), mkdir(), mkfifo(),and open() (with the O_CREAT flag).

149
150
151

(2) The default ACL may be used by the owner of a directory to specify the
maximum discretionary access permissions to be associated with objects
created within that directory.

152
153

The initial access control information is obtained as is specified in 5.3 and 5.4. −Implementations may provide an additional default ACL that is applied if a
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

42

23 Access Control Lists

c

154
155
156

default ACL as defined by this standard is not present. Such an implementationdefined default ACL interface may apply different access and/or default ACLs tocreated objects based upon implementation-defined criteria.

157
158

The physical ordering of the ACL entries of a newly created object shall beunspecified.

159

23.1.5 ACL Access Check Algorithm

160
161
162
163
164

A process may request discretionary read, write, execute/search or any
implementation-defined access mode of an object protected by an access ACL. The
algorithm below matches specific attributes of the process to ACL entries. The
process’s request is granted only if a matching ACL entry grants all of therequested access modes.

165
166

The access check algorithm shall check the ACL entries in the following relative
order:

167(1) the ACL_USER_OBJ entry

168(2) any ACL_USER entries

169(3) the ACL_GROUP_OBJ entry as well as any ACL_GROUP entries

170(4) the ACL_OTHER entry
Implementation-defined entries may be checked at any implementation-defined
points in the access check algorithm, as long as the above relative ordering ismaintained. Implementation-defined entries may grant or deny access but shallnot alter the access permitted to any process that does not match those implementation entries.

176
177
178

If no ACL_USER_OBJ, ACL_USER, ACL_GROUP_OBJ, or ACL_GROUP entries c
apply and no implementation-defined entries apply, the permissions in the
ACL_OTHER entry shall be used to determine access.

179
180

Note, the algorithm presented is a logical description of the access check. The
physical code sequence may be different.

181
182
183
184

(1) If the effective user ID of the process matches the user ID of theobject owner
then
set matched entry to ACL_USER_OBJ entry

185
186
187
188

(2) else if the effective user ID of the process matches the user ID
specified in any ACL_USER tag type ACL entry,
then
set matched entry to the matching ACL_USER entry

189
190
191
192
193

(3) else if the effective group ID or any of the supplementary group IDsof the process match the group ID of the object or match the group ID
specified in any ACL_GROUP or ACL_GROUP_OBJ tag type ACL +
entry
then

23.1 General Overview

43

c

c

c

171
172
173
174
175

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

c

c

194
195
196
197
198
199
200
201

if the requested access modes are granted by at least one entry
matched by the effective group ID or any of the supplementarygroup IDs of the processthen
set matched entry to a granting entry
else
access is denied
endif

202
203
204
205
206

(4) else if the requested access modes are granted by the ACL_OTHER c
entry of the ACL,
then
set matched entry to the ACL_OTHER entry
endif

207
208
209
210
211
212

(5) If the requested access modes are granted by the matched entry
then
if the matched entry is an ACL_USER_OBJ or ACL_OTHER
entry
then
access is granted

213
214
215
216
217
218
219
220
221
222

else if the requested access modes are also granted by the
ACL_MASK entry or no ACL_MASK entry exists in the ACL
thenaccess is granted
else
access is denied
endif
else
access is denied
endif

223

23.1.6 ACL Functions

224
225
226

Functional interfaces are defined to manipulate ACLs and ACL entries. The functions provide a portable interface for editing and manipulating the entries within
an ACL and the fields within an ACL entry.

227

Four groups of functions are defined to:228(1) manage the ACL working storage area229(2) manipulate ACL entries

230(3) manipulate an ACL on an object

231(4) translate an ACL into different formats.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

44

23 Access Control Lists

232

23.1.6.1 ACL Storage Management

233
234
235

These functions manage the storage areas used to contain working copies of
ACLs. An ACL in working storage shall not be used in any access control decisions.

236

acl_dup()

Duplicates an ACL in a working storage area

237
238

acl_free()Release the working storage area allocated to an ACL data
object239

acl_init()

Allocates and initializes an ACL working storage area

240

23.1.6.2 ACL Entry Manipulation

241
242

These functions manipulate ACL entries in working storage. The functions are
divided into several groups:

243(1) Functions that manipulate complete entries in an ACL:244

acl_copy_entry()245

acl_create_entry() Creates a new entry in an ACL

246

acl_delete_entry() Deletes an entry from an ACL247

acl_get_entry()

Returns a descriptor to an ACL entry

248
249

acl_valid()

Validates an ACL by checking for duplicate, missing, and ill-formed entries

250

Copies an ACL entry to another ACL entry(2) Functions that manipulate permissions within an ACL entry:251

acl_add_perm()

Adds a permission to a given permission set

252
253
254
255

acl_calc_mask()

Sets the permission granted by the ACL_MASK
entry to the maximum permissions granted by the
ACL_GROUP, ACL_GROUP_OBJ, ACL_USER and
implementation-defined ACL entries

256

acl_clear_perms() Clears all permissions from a given permission set257

acl_delete_perm() Deletes a permission from a given permission set

258

acl_get_permset() Returns the permissions in a given ACL entry259

acl_set_permset() Sets the permissions in a given ACL entry

260(3) Functions that manipulate the tag type and qualifier in an ACL entry:261

acl_get_qualifier() Returns the qualifier in a given ACL entry262

acl_get_tag_type() Returns the tag type in a given ACL entry263

acl_set_qualifier() Sets the qualifier in a given ACL entry264

acl_set_tag_type() Sets the tag type in a given ACL entry

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.1 General Overview

45

265

23.1.6.3 ACL Manipulation on an Object

266
267
268

These functions read the contents of an access ACL or a default ACL into working
storage and write an ACL in working storage to an object’s access ACL or default
ACL. The functions also delete a default ACL from an object:269

acl_delete_def_file() Deletes the default ACL associated with an object

270
271

acl_get_fd()

Reads the contents of an access ACL associated with a filedescriptor into working storage

272
273

acl_get_file()

Reads the contents of an access ACL or default ACL associated with an object into working storage

274
275

acl_set_fd()

Writes the ACL in working storage to the object associated with a file descriptor as an access ACL

276
277

acl_set_file()

Writes the ACL in working storage to an object as anaccess ACL or default ACL

278

23.1.6.4 ACL Format Translation

279

The standard defines three different representations for ACLs:

280
281

external form

The exportable, contiguous, persistent representation of an
ACL in user-managed space

282

internal form

The internal representation of an ACL in working storage

283

text form

The structured text representation of an ACL

284

These functions translate an ACL from one representation into another.

285
286

acl_copy_ext()

Translates an internal form of an ACL to an external form ofan ACL287
288

acl_copy_int()

Translates an external form of an ACL to an internal form ofan ACL289
290

acl_from_text()

Translates a text form of an ACL to an internal form of an
ACL

291
292

acl_size()

Returns the size in bytes required to store the external formof an ACL that is the result of an acl_copy_ext()

293
294

acl_to_text()

Translates an internal form of an ACL to a text form of an
ACL

295

23.1.7 POSIX.1 Functions Covered by ACLs

296
297

The following table lists the POSIX.1 interfaces that are changed to reflect AccessControl Lists. There are no changes to the syntax of these interfaces.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

46

23 Access Control Lists

298
299
300
301
302
303
304
305
306
307
308

Existing
POSIX.1
Function
Sectioni
iiiiiiiiiiiiiiiiiii
access()5.6.3
chmod()
5.6.4
creat()
5.3.2
fstat()
5.6.2
mkdir()
5.4.1
mkfifo()5.4.2
open()
5.3.1
stat()
5.6.2

309

23.2 Header

310

The header <sys/acl.h> defines the symbols used in the ACL interfaces.

311
312
313
314

Some of the data types used by the ACL functions are not defined as part of thisstandard but shall be implementation-defined. If {_POSIX_ACL} is defined, thesetypes shall be defined in the header <sys/acl.h>, which contains definitions forat least the types shown in Table 23-1.
c

315
316
317
318
320
319
321
323
322
324
326
325
327
329
328
330
332
331
333
335
334

DefinedType
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
acl_entry_t
Used as a descriptor for a specific ACL entry in ACL working
storage. This data type is non-exportable data.
acl_perm_t
Used for individual object access permissions. This data typeis exportable data.
acl_permset_t
Used for the set of object access permissions. This data type
is non-exportable data.
acl_t
Used as a pointer to an ACL in ACL working storage. Thisdata type is non-exportable data.
acl_tag_t
Used to distinguish different types of ACL entries. This data
type is exportable data.
acl_type_t
Used to distinguish different types of ACLs (e.g., access,default). This data type is exportable data.

336
337

The symbolic constants defined in Table 23-2, Table 23-3, Table 23-4, Table 23-5, +Table 23-6, shall be defined in the header <sys/acl.h>.

338

23.2.1 acl_entry_t

339
340

This typedef shall define an opaque, implementation-defined descriptor for an
ACL entry. The internal structure of an acl_entry_t is unspecified.

Table 23-1 − ACL Data Types

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.2 Header

47

341

23.2.2 acl_perm_t

342
343

This typedef shall define a data type capable of storing an individual object accesspermission.

344
345

Table 23-2 contains acl_perm_t values for acl_add_perm(), acl_clear_perms(), and
acl_delete_perm().

346

Table 23-2 − acl_perm_t Values

347
348
349
350
351

Constant
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
ACL_EXECUTE
ACL_READ
ACL_WRITEACL execute permission
ACL read permission
ACL write permission

352

These constants shall be implementation-defined unique values.

353

23.2.3 acl_permset_t

354
355
356

This typedef shall define the opaque, implementation-defined descriptor for a setof object access permissions. The internal structure of an acl_permset_t isunspecified.

357

23.2.4 acl_t

358
359

This typedef shall define a pointer to an opaque, implementation-defined ACL in
ACL working storage, the internal structure of which is unspecified.

360

23.2.5 acl_tag_t

361
362

This typedef shall define a data type capable of storing an individual ACL entry
tag type.

363

Table 23-3 contains acl_tag_t values for acl_get_tag_type() and acl_set_tag_type().

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

48

23 Access Control Lists

Table 23-3 − acl_tag_t Values

364
365
366
367
368
369
376
370
371
372
373
374
375
377
380
378
379
381
382
383

Constant
Description
i iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
ACL_GROUP
ACL_GROUP_OBJ
ACL_MASK

ACL_OTHER

ACL_UNDEFINED_TAG
ACL_USER
ACL_USER_OBJ

ACL entry for a specific group
ACL entry for the owning group
ACL entry that denotes the
maximum permissions allowedon all other ACL entry types
except for ACL_USER_OBJ
and ACL_OTHER (including
implementation-defined types +in the file group class )ACL entry for users whose process attributes are not matchedin any other ACL entry
Undefined ACL entry
ACL entry for a specific user
ACL entry for the object owner

384

These constants shall be implementation-defined unique values.

385

23.2.6 acl_type_t

386This typedef shall define a data type capable of storing an individual ACL type.

387

Table 23-4 contains acl_type_t values for acl_get_file() and acl_set_file().
Table 23-4 − acl_type_t Values

388
389
390
391
392

Constant
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
ACL_TYPE_ACCESS
Indicates an access ACL
ACL_TYPE_DEFAULT Indicates a default ACL

393

These constants shall be implementation-defined unique values.

394

23.2.7 ACL Qualifier

395
396

Table 23-5 contains the value of undefined user IDs or group IDs for the ACL
qualifier.

397
398
399
400

Table 23-5 − ACL Qualifier Constants

401

Constant
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
cc

ACL_UNDEFINED_IDc

Undefined ID

These constants shall be implementation-defined values.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.2 Header

c

49

402

23.2.8 ACL Entry

403
404

Table 23-6 contains the values used to denote ACL entries to be retrieved by theacl_get_entry() function.
c

405
406
407
408
409

Constant
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
ACL_FIRST_ENTRY Return the first ACL entry in the ACL.
ACL_NEXT_ENTRY
Return the next ACL entry in the ACL.

Table 23-6 − ACL Entry Constants

410

These constants shall be implementation-defined values.

411

23.3 Text Form Representation

412
413
414
415

This section defines the long and short text forms of ACLs. The long text form isdefined first in order to give a complete specification with no exceptions. The
short text form is defined second because it is specified relative to the long text
form.

416

23.3.1 Long Text Form for ACLs

417
418

The long text form is used for either input or output of ACLs and is defined as follows:

419
420

<acl_entry>[<acl_entry>] ...

421
422
423
424
425
426

Each <acl_entry> line shall contain one ACL entry with three required colonseparated fields: an ACL entry tag type, an ACL entry qualifier, and the discretionary access permissions. An implementation may define additional colonseparated fields after the required fields. Comments may be included on any<acl_entry> line. If a comment starts at the beginning of a line, then the entire
line shall be interpreted as a comment.

427
428

The first field contains the ACL entry tag type. This standard defines the following ACL entry tag type keywords, one of which shall appear in the first field:

429
430

user

A user ACL entry specifies the access granted to either the fileowner or a specified user.

431
432

group

An group ACL entry specifies the access granted to either the fileowning group or a specified group.

433
434
435

other

An other ACL entry specifies the access granted to any processthat does not match any user, group, or implementation-defined
ACL entries.

436
437
438

mask

A mask ACL entry specifies the maximum access which can be
granted by any ACL entry except the user entry for the file ownerand the other entry.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

50

23 Access Control Lists

c

c

c

c

cc

439

An implementation may define additional ACL entry types.

440
441

The second field contains the ACL entry qualifier (referred to in the remainder ofthis section as qualifier). This standard defines the following qualifiers:
c

442

uid

This qualifier specifies a user name or a user ID number.

443

gid

This qualifier specifies a group name or a group ID number.

444
445
446

empty

This qualifier specifies that no uid or gid information is to be applied
to the ACL entry. An empty qualifier shall be represented by an
empty string or by white space.

447

An implementation may define additional qualifiers.

448
449

The third field contains the discretionary access permissions. This standard
defines the following symbolic discretionary access permissions:

450r

Read access451

w

Write access

452

x

Execute/search access453−

No access by this ACL entry.

454
455
456
457
458

The discretionary access permissions field shall contain exactly one each of thefollowing characters in the following order: r, w, and x. Each of these may bereplaced by the ‘‘-’’ character to indicate no access. An implementation may definec
additional characters following the required characters that represent
implementation-defined permissions.

459
460
461
462
463

A user entry with an empty qualifier shall specify the access granted to the fileowner. A user entry with a uid qualifier shall specify the access permissions
granted to the user name matching the uid value. If the uid value does not matcha user name, then the ACL entry shall specify the access permissions granted tothe user ID matching the numeric uid value.
+

464
465
466
467
468

A group entry with an empty qualifier shall specify the access granted to the fileowning group. A group entry with a gid qualifier shall specify the access permissions granted to the group name matching the gid value. If the gid value does notmatch a group name, then the ACL entry shall specify the access permissions
granted to the group ID matching the numeric gid value.
+

469
470

The mask and other entries shall contain an empty qualifier. An implementation may define additional ACL entry types that use the empty qualifier.

471
472
473
474

A number-sign (#) starts a comment on an <acl_entry> line. A comment may startat the beginning of a line, after the required fields and after any implementationdefined, colon-separated fields. The end of the line denotes the end of the comment.
−

475
476
477
478

If an ACL entry contains permissions that are not also contained in the mask
entry, then the output text form for that <acl_entry> line shall be displayed as
described above followed by a number-sign (#), the string "effective: ", and theeffective access permissions for that ACL entry.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

23.3 Text Form Representation

51

c

479
480
481

White space is permitted in <acl_entry> lines as follows: at the start of the line; −immediately before and after a ‘‘:’’ separator; immediately before the firstnumber-sign (#) character; at any point after the first number-sign (#) character.

482
483
484

Comments shall have no effect on the discretionary access check of the object withwhich they are associated. An implementation shall define whether or not comments are stored with an ACL.

485
486
487
488

If an implementation allows the colon character ‘‘:’’ to be present in an ACL entry
qualifier, then that implementation shall provide a method for distinguishing
between a colon character as a field separator in an ACL entry definition and acolon character as a component of the ACL entry qualifier value.
−

489

23.3.2 Short Text Form for ACLs

490

The short text form is used only for input of ACLs and is defined as follows:

491<acl_entry>[,<acl_entry>]...

492
493

Each <acl_entry> shall contain one ACL entry, as defined in 23.3.1, with two
exceptions.

494
495
496
497
498

The ACL entry tag type keyword shall appear in the first field in either its fullunabbreviated form or its single letter abbreviated form. The abbreviation foruser is ‘‘uu’’, the abbreviation for group is ‘‘gg’’, the abbreviation for other is ‘‘oo’’,
and the abbreviation for mask is ‘‘mm’’. An implementation may define additional
ACL entry tag type abbreviations.

499

There are no exceptions for the second field in the short text form for ACLs.

500
501
502
503

The discretionary access permissions shall appear in the third field. The symbolic−string shall contain at most one each of the following characters in any order: r,
w, and x; implementations may define additional characters that may appear inany order within the string.
%504

23.4 Functions

505
506
507
508
509

Support for the ACL facility functions described in this section is optional. If thesymbol {_POSIX_ACL} is defined, the implementation supports the ACL option cand all of the ACL functions shall be implemented as described in this section. If c{_POSIX_ACL} is not defined, the result of calling any of these functions is c
unspecified.

510
511
512

The error [ENOTSUP] shall be returned in those cases where the system supports
the ACL facility but the particular ACL operation cannot be applied because ofrestrictions imposed by the implementation.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

52

23 Access Control Lists

c

513

23.4.1 Add a Permission to an ACL Permission Set

514

Function: acl_add_perm()

515

23.4.1.1 Synopsis

516#include <sys/acl.h>c517

int acl_add_perm (acl_permset_t permset_d,, acl_perm_t perm)
);
c

518

23.4.1.2 Description

519
520
521
522

The acl_add_perm() function shall add the permission contained in argument
perm to the permission set referred to by argument permset_d. An attempt to add
a permission that is already granted by the permission set shall not be considered
an error.
−

523
524

Any existing descriptors that refer to permset_d shall continue to refer to that permission set.

525

23.4.1.3 Returns

526
527

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

528

23.4.1.4 Errors

529
530

If any of the following conditions occur, the acl_add_perm() function shall return−1 and set errno to the corresponding value:

531
532

[EINVAL]

533

Argument permset_d is not a valid descriptor for a permission
set within an ACL entry.
Argument perm does not contain a valid acl_perm_t value.

−

534

23.4.1.5 Cross-References

535
536

acl_clear_perms(), 23.4.3; acl_delete_perm(), 23.4.10; acl_get_permset(), 23.4.17;
acl_set_permset(), 23.4.23.

537

23.4.2 Calculate the File Group Class Mask

538

Function: acl_calc_mask()

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.4 Functions

53

539

23.4.2.1 Synopsis

540#include <sys/acl.h>c541

int acl_calc_mask (acl_t ∗acl_p)
);
c

542

23.4.2.2 Description

543
544
545
546
547
548
549
550
551
552
553
554

The acl_calc_mask() function shall calculate and set the permissions associatedwith the ACL_MASK ACL entry of the ACL referred to by acl_p. The value of the
new permissions shall be the union of the permissions granted by the
ACL_GROUP, ACL_GROUP_OBJ, ACL_USER, and any implementation-defined
tag types which match processes in the file group class contained in the ACL
referred to by acl_p. If the ACL referred to by acl_p already contains an
ACL_MASK entry, its permissions shall be overwritten; if it does not contain an
ACL_MASK entry, one shall be added. If the ACL referred to by acl_p does notcontain enough space for the new ACL entry, then additional working storage
may be allocated. If the working storage cannot be increased in the current location, then it may be relocated and the previous working storage shall be released
and a pointer to the new working storage shall be returned via acl_p.

555

The order of existing entries in the ACL is undefined after this function.

556
557
558

Any existing ACL entry descriptors that refer to entries in the ACL shall continue
to refer to those entries. Any existing ACL pointers that refer to the ACL referred
to by acl_p shall continue to refer to the ACL.

559

23.4.2.3 Returns

560
561

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

562

23.4.2.4 Errors

563
564

If any of the following conditions occur, the acl_calc_mask() function shall return−1 and set errno to the corresponding value:

565[EINVAL]

Argument acl_p does not point to a pointer to a valid ACL.

566
567

[ENOMEM] The acl_calc_mask() function is unable to allocate the memory
required for an ACL_MASK ACL entry.
−

568

23.4.2.5 Cross-References569

acl_get_entry(), 23.4.14; acl_valid(), 23.4.28.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

54

23 Access Control Lists

c
c

570

23.4.3 Clear All Permissions from an ACL Permission Set

571

Function: acl_clear_perms()572

23.4.3.1 Synopsis

573#include <sys/acl.h>c574

int acl_clear_perms (acl_permset_t permset_d)
);
c

575

23.4.3.2 Description

576
577

The acl_clear_perms() function shall clear all permissions from the permission set
referred to by argument permset_d.
−

578
579

Any existing descriptors that refer to permset_d shall continue to refer to that permission set.

580

23.4.3.3 Returns

581
582

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

583

23.4.3.4 Errors

584
585

If any of the following conditions occur, the acl_clear_perms() function shallreturn −1 and set errno to the corresponding value:

586
587

[EINVAL]

Argument permset_d is not a valid descriptor for a permission
set within an ACL entry.
−

588

23.4.3.5 Cross-References

589
590

acl_add_perm(), 23.4.1; acl_delete_perm(), 23.4.10; acl_get_permset(), 23.4.17;
acl_set_permset(), 23.4.23.

591

23.4.4 Copy an ACL Entry

592

Function: acl_copy_entry()593

23.4.4.1 Synopsis

594#include <sys/acl.h>c595

int acl_copy_entry (acl_entry_t dest_d,, acl_entry_t src_d));c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.4 Functions

55

596

23.4.4.2 Description

597
598
599

The acl_copy_entry() function shall copy the contents of the ACL entry indicatedby the src_d descriptor to the existing ACL entry indicated by the dest_d descriptor. The src_d and dest_d descriptors may refer to entries in different ACLs.

600
601
602

The src_d, dest_d and any other ACL entry descriptors that refer to entries in +either ACL shall continue to refer to those entries. The order of all existing
entries in both ACLs shall remain unchanged.

603

23.4.4.3 Returns

604
605

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

606

23.4.4.4 Errors

607
608

If any of the following conditions occur, the acl_copy_entry() function shall return−1 and set errno to the corresponding value:

609
610
611

[EINVAL]

Argument src_d or dest_d is not a valid descriptor for an ACL
entry.
Arguments src_d and dest_d reference the same ACL entry.

−

612

23.4.4.5 Cross-References613

acl_get_entry(), 23.4.14.

614

23.4.5 Copy an ACL From System to User Space

615

Function: acl_copy_ext()

616

23.4.5.1 Synopsis

617#include <sys/acl.h>c618

ssize_t acl_copy_ext (void ∗buf_p,, acl_t acl,, ssize_t size)
);
c

619

23.4.5.2 Description

620
621
622
623
624
625
626
627

The acl_copy_ext() function shall copy an ACL, pointed to by acl, from systemmanaged space to the user managed space pointed to by buf_p. The size parame- cter represents the size in bytes of the buffer pointed to by buf_p. The format of the
ACL placed in the user-managed space pointed to by buf_p shall be a contiguous,persistent data item, the format of which is unspecified. It is the responsibility of
the invoker to allocate an area large enough to hold the copied ACL. The size ofthe exportable, contiguous, persistent form of the ACL may be obtained by invoking the acl_size() function.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

56

23 Access Control Lists

628
629
630

Any ACL entry descriptors that refer to an entry in the ACL referenced by acl
shall continue to refer to those entries. Any existing ACL pointers that refer tothe ACL referenced by acl shall continue to refer to the ACL.

631

23.4.5.3 Returns

632
633
634

Upon successful completion, the acl_copy_ext() function shall return the numberof bytes placed in the user-managed space pointed to by buf_p. Otherwise, a valueof (ssize_t) −1 shall be returned and errno shall be set to indicate the error.
c635

23.4.5.4 Errors

636
637

If any of the following conditions occur, the acl_copy_ext() function shall return avalue of (ssize_t) −1 and set errno to the corresponding value:c638[EINVAL]

The size parameter is zero or negative.

639

Argument acl does not point to a valid ACL.

640
641
642

The ACL referenced by acl contains one or more improperly
formed ACL entries, or for some other reason cannot betranslated into the external form ACL.
−

643
644

[ERANGE]

The size parameter is greater than zero but smaller than thelength of the contiguous, persistent form of the ACL.

645

23.4.5.5 Cross-References646

acl_copy_int(), 23.4.6; acl_size(), 23.4.26.

647

23.4.6 Copy an ACL From User to System Space

648

Function: acl_copy_int()

649

23.4.6.1 Synopsis

650#include <sys/acl.h>c651

acl_t acl_copy_int (const void ∗buf_p)
);
c

652

23.4.6.2 Description

653
654
655

The acl_copy_int() function shall copy an exportable, contiguous, persistent formof an ACL, pointed to by buf_p, from user-managed space to system-managed
space.

656
657
658

This function may cause memory to be allocated. The caller should free any
releaseable memory, when the new ACL is no longer required, by calling
acl_free() with the (void ∗)acl_t as an argument.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

23.4 Functions

57

659
660

Upon successful completion, this function shall return a pointer that references
the ACL in ACL working storage.

661

23.4.6.3 Returns

662
663
664

Upon successful completion, the acl_copy_int() function shall return a pointerreferencing the ACL in ACL working storage. Otherwise, a value of (acl_t)NULL
shall be returned, and errno shall be set to indicate the error.

665

23.4.6.4 Errors

666
667

If any of the following conditions occur, the acl_copy_int() function shall return avalue of (acl_t)NULL and set errno to the corresponding value:

668
669

[EINVAL]

The buffer pointed to by argument buf_p does not contain a validc
external form ACL.

670
671
672

[ENOMEM] The ACL working storage requires more memory than is allowedby the hardware or system-imposed memory management constraints.
−

673

23.4.6.5 Cross-References674

acl_copy_ext(), 23.4.5; acl_get_entry(), 23.4.14; acl_free(), 23.4.12.

675

23.4.7 Create a New ACL Entry

676

Function: acl_create_entry()

677

23.4.7.1 Synopsis

678#include <sys/acl.h>c679

int acl_create_entry (acl_t ∗acl_p,, acl_entry_t ∗entry_p)
);
c

680

23.4.7.2 Description

681
682

The acl_create_entry() function creates a new ACL entry in the ACL pointed to by
the contents of the pointer argument acl_p.

683
684
685

This function may cause memory to be allocated. The caller should free any
releaseable memory, when the ACL is no longer required, by calling acl_free()with (void ∗)acl_t as an argument.

686
687
688
689
690

If the ACL working storage cannot be increased in the current location, then theworking storage for the ACL pointed to by acl_p may be relocated and the previous working storage shall be released. A pointer to the new working storage shallbe returned via acl_p. Upon successful completion, the acl_create_entry() function
shall return a descriptor for the new ACL entry via entry_p.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

58

23 Access Control Lists

691
692
693
694
695
696

The components of the new ACL entry are initialized in the following ways: the
ACL tag type component shall contain ACL_UNDEFINED_TAG, the qualifiercomponent shall contain ACL_UNDEFINED_ID, and the set of permissions shallhave no permissions enabled. Other features of a newly created ACL entry shallbe implementation-defined. Any existing ACL entry descriptors that refer toentries in the ACL shall continue to refer to those entries.

697

23.4.7.3 Returns

698
699

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

700

23.4.7.4 Errors

701
702

If any of the following conditions occur, the acl_create_entry() function shallreturn −1 and set errno to the corresponding value:703[EINVAL]

Argument acl_p does not point to a pointer to a valid ACL.

704
705
706

[ENOMEM] The ACL working storage requires more memory than is allowedby the hardware or system-imposed memory management constraints.
−

707

23.4.7.5 Cross-References708

acl_delete_entry(), 23.4.9; acl_get_entry(), 23.4.14.

709

23.4.8 Delete a Default ACL by Filename

710

Function: acl_delete_def_file()

711

23.4.8.1 Synopsis

712#include <sys/acl.h>c713

int acl_delete_def_file (const char ∗path_p)
);
c

714

23.4.8.2 Description

715
716
717
718
719
720
721

The acl_delete_def_file() function deletes a default ACL from the directory whose
pathname is pointed to by the argument path_p. The effective user ID of the pro- ccess must match the owner of the directory or the process must have appropriate
privilege to delete the default ACL from path_p. If {_POSIX_CAP} is defined, thenc
appropriate privilege shall include CAP_FOWNER.
In addition, if{_POSIX_MAC} is defined, then the process must have MAC write access to the cdirectory.

722
723

If the argument path_p is not a directory, then the function shall fail. It shall not c
be considered
an error if path_p is a directory and either
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

23.4 Functions

59

c

724
725

{_POSIX_ACL_EXTENDED} is not in effect for path_p, or path_p does not have a c
default ACL.

726
727
728

Upon successful completion, acl_delete_def_file() shall delete the default ACL
associated with the argument path_p. If acl_delete_def_file() is unsuccessful, thedefault ACL associated with the argument path_p shall not be changed.

729

23.4.8.3 Returns

730
731

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

732

23.4.8.4 Errors

733
734

If any of the following conditions occur, the acl_delete_def_file() function shallreturn −1 and set errno to the corresponding value:

735
736
737

[EACCES]

Search permission is denied for a component of the path prefixor the object exists and the process does not have appropriate
access rights.

738
739

If {_POSIX_MAC} is defined, MAC write access to path_p isdenied.

740
741
742
743

[ENAMETOOLONG]
The length of the path_p argument exceeds {PATH_MAX}, or apathname component is longer than {NAME_MAX} while{POSIX_NO_TRUNC} is in effect.

744
745

[ENOENT]746[ENOTDIR] A component of the path prefix is not a directory.

747

The named object does not exist or the path_p argument points
to an empty string.
−Argument path_p does not refer to a directory.

748
749

[EPERM]

The process does not have appropriate privilege to perform theoperation to delete the default ACL.

750
751

[EROFS]This function requires modification of a file system which iscurrently read-only.

752

23.4.8.5 Cross-References753

acl_get_file(), 23.4.16; acl_set_file(), 23.4.22.

−

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

60

23 Access Control Lists

c

754

23.4.9 Delete an ACL Entry

755

Function: acl_delete_entry()756

23.4.9.1 Synopsis

757#include <sys/acl.h>c758

int acl_delete_entry (acl_t acl,
, acl_entry_t entry_d)
);
c

759

23.4.9.2 Description

760
761

The acl_delete_entry() function shall remove the ACL entry indicated by theentry_d descriptor from the ACL pointed to by acl.

762
763
764
765
766

Any existing ACL entry descriptors that refer to entries in acl other than thatreferred to by entry_d shall continue to refer to the same entries. The argument
entry_d and any other ACL entry descriptors that refer to the same ACL entry are
undefined after this function completes. Any existing ACL pointers that refer tothe ACL referred to by acl shall continue to refer to the ACL.

767

23.4.9.3 Returns

768
769

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

770

23.4.9.4 Errors

771
772

If any of the following conditions occur, the acl_delete_entry() function shallreturn −1 and set errno to the corresponding value:

773
774

[EINVAL]

Argument acl does not point to a valid ACL. Argument entry_d +is not a valid descriptor for an ACL entry in acl.

775

[ENOSYS]This function is not supported by the implementation.

776

23.4.9.5 Cross-References

777

acl_copy_entry(), 23.4.4; acl_create_entry(), 23.4.7; acl_get_entry(), 23.4.14.

778

23.4.10 Delete Permissions from an ACL Permission Set

779

Function: acl_delete_perm()

780

23.4.10.1 Synopsis

781#include <sys/acl.h>c782

int acl_delete_perm (acl_permset_t permset_d,, acl_perm_t perm));c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.4 Functions

61

783

23.4.10.2 Description

784
785
786
787

The acl_delete_perm() function shall delete the permission contained in argument
perm from the permission set referred to by argument permset_d. An attempt todelete a permission that is not granted by the ACL entry shall not be considered
an error.
−

788
789

Any existing descriptors that refer to permset_d shall continue to refer to that permission set.

790

23.4.10.3 Returns

791
792

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

793

23.4.10.4 Errors

794
795

If any of the following conditions occur, the acl_delete_perm() function shallreturn −1 and set errno to the corresponding value:

796
797

[EINVAL]

798
799

Argument permset_d is not a valid descriptor for a permission
set within an ACL entry.
Argument perm does not contain a valid acl_perm_t value.

[ENOSYS]This function is not supported by the implementation.

800

23.4.10.5 Cross-References

801
802

acl_add_perm(), 23.4.1; acl_clear_perms(), 23.4.3; acl_get_permset(), 23.4.17;
acl_set_permset(), 23.4.23.

803

23.4.11 Duplicate an ACL

804

Function: acl_dup()

805

23.4.11.1 Synopsis

806#include <sys/acl.h>c807

acl_t acl_dup (acl_t acl)
);
c

808

23.4.11.2 Description

809
810

The acl_dup() function returns a pointer to a copy of the ACL pointed to by argument acl.

811
812
813

This function may cause memory to be allocated. When the new ACL is no longer c
required, the caller should free any releaseable memory by calling acl_free() withthe (void ∗)acl_t as an argument.
c
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

62

23 Access Control Lists

814
815

Any existing ACL pointers that refer to the ACL referred to by acl shall continue
to refer to the ACL.

816

23.4.11.3 Returns

817
818
819

Upon successful completion, the function shall return a pointer to the duplicate
ACL. Otherwise, a value of (acl_t)NULL shall be returned and errno shall be set
to indicate the error.

820

23.4.11.4 Errors

821
822

If any of the following conditions occur, the acl_dup() function shall return avalue of (acl_t)NULL and set errno to the corresponding value:823[EINVAL]

Argument acl does not point to a valid ACL.

824
825
826

[ENOMEM] The ACL working storage requires more memory than is allowedby the hardware or system-imposed memory management constraints.
−

827

23.4.11.5 Cross-References828

acl_free(), 23.4.12; acl_get_entry(), 23.4.14.

829

23.4.12 Release Memory Allocated to an ACL Data Object

830

Function: acl_free()831

23.4.12.1 Synopsis

832#include <sys/acl.h>c833

int acl_free (void ∗obj_p)
);
c

834

23.4.12.2 Description

835
836
837

The acl_free() function shall free any releasable memory currently allocated to the
ACL data object identified by obj_p. The argument obj_p may identify an ACL, an
ACL entry qualifier, or a pointer to a string allocated by one of the ACL functions.

838
839
840
841
842

If the item identified by obj_p is an acl_t, the acl_t and any existing descriptors
that refer to parts of the ACL shall become undefined. If the item identified by
obj_p is a string (char∗), then use of the char∗ shall become undefined. If the item
identified by obj_p is an ACL entry qualifier (void∗), then use of the void∗ shallbecome undefined.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.4 Functions

63

843

23.4.12.3 Returns

844
845

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

846

23.4.12.4 Errors

847
848

If any of the following conditions occur, the acl_free() function shall return −1 andset errno to the corresponding value:

849[EINVAL]−

The value of the obj_p argument is invalid.

850

23.4.12.5 Cross-References

851
852
853

acl_copy_int(),
23.4.6;
acl_create_entry(),
23.4.7;
acl_dup(),acl_from_text(),
23.4.13;acl_get_fd(),
23.4.15;
acl_get_file(),acl_get_permset(), 23.4.17; acl_init(), 23.4.20.

854

23.4.13 Create an ACL from Text

855

Function: acl_from_text()

856

23.4.13.1 Synopsis

857#include <sys/acl.h>c858

acl_t acl_from_text (const char ∗buf_p)
);
c

859

23.4.13.2 Description

860
861
862
863
864

The acl_from_text() function converts the text form of the ACL referred to by c
buf_p into the internal form of an ACL and returns a pointer to the working
storage that contains the ACL. The acl_from_text() function shall accept as input +the long text form and short text form of an ACL as described in sections 23.3.1. +and 23.3.2.

865
866
867

This function may cause memory to be allocated. The caller should free any
releaseable memory, when the new ACL is no longer required, by calling
acl_free() with the (void ∗)acl_t as an argument.

868
869

Permissions within each ACL entry within the short text form of the ACL shall be−
specified only as absolute values.

870

23.4.13.3 Returns

871
872
873

Upon successful completion, the function shall return a pointer to the internal
representation of the ACL in working storage. Otherwise, a value of (acl_t)NULL
shall be returned and errno shall be set to indicate the error.

23.4.11;23.4.16;

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

64

23 Access Control Lists

c

874

23.4.13.4 Errors

875
876

If any of the following conditions occur, the acl_from_text() function shall return avalue of (acl_t)NULL and set errno to the corresponding value:877[EINVAL]

Argument buf_p cannot be translated into an ACL.

878
879
880

[ENOMEM] The ACL working storage requires more memory than is allowedby the hardware or system-imposed memory management constraints.
−

881

23.4.13.5 Cross-References882

acl_free(), 23.4.12; acl_get_entry(), 23.4.14; acl_to_text(), 23.4.27.

883

23.4.14 Get an ACL Entry

884

Function: acl_get_entry()885

23.4.14.1 Synopsis

886#include <sys/acl.h>

c

887
888
889

int acl_get_entry (acl_t acl,,
int entry_id,,
acl_entry_t ∗entry_p)
);
c

890

23.4.14.2 Description

891
892
893
894
895
896
897
898
899
900

The acl_get_entry() function shall obtain a descriptor for an ACL entry as
specified by entry_id within the ACL indicated by argument acl. If the value ofentry_id is ACL_FIRST_ENTRY, then the function shall return in entry_p a +descriptor for the first ACL entry within acl. If a call is made to acl_get_entry() cwith entry_id set to ACL_NEXT_ENTRY when there has not been either an ini- ctial successful call to acl_get_entry(), or a previous successful call to
acl_get_entry()
followingacallto
acl_calc_mask(),
acl_copy_int(),
acl_create_entry(), acl_delete_entry(), acl_dup(), acl_from_text(), acl_get_fd(),
acl_get_file(), acl_set_fd(), acl_set_file(), or acl_valid(), then the effect isunspecified.

901
902

Upon successful execution, the acl_get_entry() function shall return a descriptor
for the ACL entry via entry_p.

903
904
905
906
907
908
909

Calls to acl_get_entry() shall not modify any ACL entries. Subsequent operations
using the returned ACL entry descriptor shall operate on the ACL entry within
the ACL in ACL working storage. The order of all existing entries in the ACL
shall remain unchanged. Any existing ACL entry descriptors that refer to entries
within the ACL shall continue to refer to those entries. Any existing ACL
pointers that refer to the ACL referred to by acl shall continue to refer to the
ACL.

c
c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.4 Functions

65

910

23.4.14.3 Returns

911
912
913
914
915
916
917

If the function successfully obtains an ACL entry, the function shall return avalue of 1. If the ACL has no ACL entries, the function shall return a value of czero. If the value of entry_id is ACL_NEXT_ENTRY and the last ACL entry in
the ACL has already been returned by a previous call to acl_get_entry(), the function shall return a value of zero until a successful call with entry_id of +ACL_FIRST_ENTRY is made. Otherwise, a value of −1 shall be returned anderrno shall be set to indicate the error.

918

23.4.14.4 Errors

919
920

If any of the following conditions occur, the acl_get_entry() function shall return−1 and set errno to the corresponding value:

921
922

[EINVAL]

Argument acl does not point to a valid ACL. Argument entry_id +is neither ACL_NEXT_ENTRY nor ACL_FIRST_ENTRY.
−

923

23.4.14.5 Cross-References

924
925
926
927

acl_calc_mask(), 23.4.2; acl_copy_int(), 23.4.6; acl_create_entry(), 23.4.7;
acl_delete_entry(), 23.4.9; acl_dup(), 23.4.11;
acl_from_text(), 23.4.13;
acl_get_fd(), 23.4.15; acl_get_file(), 23.4.16; acl_init(), 23.4.20; acl_set_fd(),
23.4.21; acl_set_file(), 23.4.22; acl_valid(), 23.4.28.

928

23.4.15 Get an ACL by File Descriptor

929

Function: acl_get_fd()930

23.4.15.1 Synopsis

931#include <sys/acl.h>c932

acl_t acl_get_fd (int fd)
);
c

933

23.4.15.2 Description

934
935
936
937

The acl_get_fd() function retrieves the access ACL for the object associated with c
the file descriptor, fd. If {_POSIX_MAC} is defined, then the process must have c
MAC read access to the object associated with fd. The ACL shall be placed into +working storage and acl_get_fd() shall return a pointer to that storage.

938
939
940

This function may cause memory to be allocated. The caller should free any
releaseable memory, when the new ACL is no longer required, by calling
acl_free() with the (void ∗)acl_t as an argument.

941
942
943

The ACL in the working storage is an independent copy of the ACL associatedwith the object referred to by fd. The ACL in the working storage shall not participate in any access control decisions.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

66

23 Access Control Lists

944

23.4.15.3 Returns

945
946
947

Upon successful completion, the function shall return a pointer to the ACL thatwas retrieved. Otherwise, a value of (acl_t)NULL shall be returned and errno
shall be set to indicate the error.

948

23.4.15.4 Errors

949
950

If any of the following conditions occur, the acl_get_fd() function shall return avalue of (acl_t)NULL and set errno to the corresponding value:

951
952

[EACCES]If {_POSIX_MAC} is defined, MAC read access to the object isdenied.

953[EBADF]The fd argument is not a valid file descriptor.

954
955
956

[ENOMEM] The ACL working storage requires more memory than is allowedby the hardware or system-imposed memory management constraints.
−

c

957

23.4.15.5 Cross-References

958
959

acl_free(), 23.4.12; acl_get_entry(), 23.4.14; acl_get_file(), 23.4.16; acl_set_fd(), +23.4.21.

960

23.4.16 Get an ACL by Filename

961

Function: acl_get_file()

962

23.4.16.1 Synopsis

963#include <sys/acl.h>c964

acl_t acl_get_file (const char ∗path_p,, acl_type_t type)
);
c

965

23.4.16.2 Description

966
967
968
969
970

The acl_get_file() function retrieves the access ACL associated with an object or −the default ACL associated with a directory. The pathname for the object ordirectory is pointed to by the argument path_p. If {_POSIX_MAC} is defined, then cthe process must have MAC read access to path_p. The ACL shall be placed into +working storage and acl_get_file() shall return a pointer to that storage.

971
972
973

This function may cause memory to be allocated. The caller should free any
releaseable memory, when the new ACL is no longer required, by calling
acl_free() with the (void ∗)acl_t as an argument.

974
975
976
977

The value of the argument type is used to indicate whether the access ACL or thedefault ACL associated with path_p is returned. If type is ACL_TYPE_ACCESS,
then the access ACL shall be returned. If type is ACL_TYPE_DEFAULT, then thedefault ACL shall be returned. If type is ACL_TYPE_DEFAULT and no default
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

23.4 Functions

67

978
979
980

ACL is associated with path_p, then an ACL containing zero ACL entries shall be
returned. If the argument type specifies a type of ACL that cannot be associatedwith path_p, then the function shall fail.

981
982
983

The ACL in the working storage is an independent copy of the ACL associatedwith the object referred to by path_p. The ACL in the working storage shall notparticipate in any access control decisions.

984

23.4.16.3 Returns

985
986
987

Upon successful completion, the function shall return a pointer to the ACL thatwas retrieved. Otherwise, a value of (acl_t)NULL shall be returned and errno
shall be set to indicate the error.

988

23.4.16.4 Errors

989
990

If any of the following conditions occur, the acl_get_file() function shall return avalue of (acl_t)NULL and set errno to the corresponding value:

991
992
993

[EACCES]

Search permission is denied for a component of the path prefixor the object exists and the process does not have appropriate
access rights.

994
995

If {_POSIX_MAC} is defined, MAC read access to the object isdenied.

996
997

Argument type specifies a type of ACL that cannot be associatedwith path_p.

998
999
1000

[EINVAL]

Argument
type
is
ACL_TYPE_DEFAULT, or
value.

nota valid

ACL_TYPE_ACCESS,
implementation-defined

1001
1002
1003
1004

[ENAMETOOLONG]
The length of the path_p argument exceeds {PATH_MAX}, or apathname component is longer than {NAME_MAX} while{POSIX_NO_TRUNC} is in effect.

1005
1006

[ENOENT]

1007
1008
1009

[ENOMEM] The ACL working storage requires more memory than is allowedby the hardware or system-imposed memory management constraints.
−

1010[ENOTDIR] A component of the path prefix is not a directory.

The named object does not exist or the path_p argument points
to an empty string.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

68

23 Access Control Lists

c

1011

23.4.16.5 Cross-References

1012
1013

acl_delete_def_file(), 23.4.8; acl_free(),
acl_get_fd(), 23.4.15; acl_set_file(), 23.4.22.

1014

23.4.17 Retrieve the Permission Set from an ACL Entry

1015

Function: acl_get_permset()1016

23.4.17.1 Synopsis

1017#include <sys/acl.h>

c

1018

int acl_get_permset (acl_entry_t entry_d,, acl_permset_t ∗permset_p)
);
c

1019

23.4.17.2 Description

1020
1021
1022
1023

The acl_get_permset() function returns via permset_p a descriptor to the permission set in the ACL entry indicated by entry_d. Subsequent operations using the −returned permission set descriptor operate on the permission set within the ACL
entry.
+

1024
1025

Any ACL entry descriptors that refer to the entry referred to by entry_d shall continue to refer to those entries.

1026

23.4.17.3 Returns

1027
1028

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

1029

23.4.17.4 Errors

1030
1031

If any of the following conditions occur, the acl_get_permset() function shallreturn −1 and set errno to the corresponding value:1032[EINVAL]

23.4.12;acl_get_entry(),

23.4.14; +Argument entry_d is not a valid descriptor for an ACL entry.

−

1033

23.4.17.5 Cross-References

1034
1035

acl_add_perm(), 23.4.1; acl_clear_perms(), 23.4.3; acl_delete_perm(), 23.4.10;
acl_set_permset(), 23.4.23.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.4 Functions

69

1036

23.4.18 Get ACL Entry Qualifier

1037

Function: acl_get_qualifier()

1038

23.4.18.1 Synopsis

1039#include <sys/acl.h>

c

1040

void ∗acl_get_qualifier (acl_entry_t entry_d)
);
c

1041

23.4.18.2 Description

1042
1043
1044

The acl_get_qualifier() function retrieves the qualifier of the tag for the ACL entry
indicated by the argument entry_d into working storage and returns a pointer tothat storage.
−

1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057

If the value of the tag type in the ACL entry referred to by entry_d is ACL_USER,
then the value returned by acl_get_qualifier() shall be a pointer to type uid_t. If
the value of the tag type in the ACL entry referred to by entry_d is ACL_GROUP,
then the value returned by acl_get_qualifier() shall be a pointer to type gid_t. If
the value of the tag type in the ACL entry referred to by entry_d isimplementation-defined, then the value returned by acl_get_qualifier() shall be apointer to an implementation-defined type. If the value of the tag type in the ACL
entry referred to by entry_d is ACL_UNDEFINED_TAG, ACL_USER_OBJ,
ACL_GROUP_OBJ, ACL_OTHER, ACL_MASK, or an implementation-definedvalue for which a qualifier is not supported, then acl_get_qualifier() shall return avalue of (void ∗)NULL and the function shall fail. Subsequent operations using
the returned pointer shall operate on an independent copy of the qualifier inworking storage.

1058
1059
1060

This function may cause memory to be allocated. The caller should free any
releaseable memory, when the new qualifier is no longer required, by calling
acl_free() with the void∗ as an argument.

1061
1062
1063
1064

The argument entry_d and any other ACL entry descriptors that refer to entries
within the ACL containing the entry referred to by entry_d shall continue to referto those entries. The order of all existing entries in the ACL containing the entry
referred to by entry_d shall remain unchanged.

1065

23.4.18.3 Returns

1066
1067
1068

Upon successful completion, the function shall return a pointer to the tag qualifierthat was retrieved into ACL working storage. Otherwise, a value of (void ∗)NULL
shall be returned and errno shall be set to indicate the error.

1069

23.4.18.4 Errors

1070
1071

If any of the following conditions occur, the acl_get_qualifier() function shallreturn a value of (void ∗)NULL and set errno to the corresponding value:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

70

23 Access Control Lists

c

c

c

1072

[EINVAL]

Argument entry_d is not a valid descriptor for an ACL entry.

1073
1074
1075

The value of the tag type in the ACL entry referenced by argument entry_d is not ACL_USER, ACL_GROUP, nor a valid
implementation-defined value.

1076
1077
1078

[ENOMEM] The value to be returned requires more memory than is allowedby the hardware or system-imposed memory management constraints.
−

1079

23.4.18.5 Cross-References

1080
1081

acl_create_entry(),
23.4.7;
acl_free(),
23.4.12;acl_get_entry(),
23.4.14;acl_get_tag_type(), 23.4.19; acl_set_qualifier(), 23.4.24; acl_set_tag_type(), 23.4.25.

1082

23.4.19 Get ACL Entry Tag Type1083

Function: acl_get_tag_type()1084

23.4.19.1 Synopsis

1085#include <sys/acl.h>

c

1086

int acl_get_tag_type (acl_entry_t entry_d,, acl_tag_t ∗tag_type_p)
);
c

1087

23.4.19.2 Description

1088
1089
1090
1091

The acl_get_tag_type() function returns the tag type for the ACL entry indicatedby the argument entry_d. Upon successful completion, the location referred to by −the argument tag_type_p shall be set to the tag type of the ACL entry referred toby entry_d.

1092
1093
1094

The argument entry_d and any other ACL entry descriptors that refer to entries
in the same ACL shall continue to refer to those entries. The order of all existing
entries in the ACL shall remain unchanged.

1095

23.4.19.3 Returns

1096
1097
1098
1099

Upon successful completion, the function shall set the location referred to by
tag_type_p to the tag type that was retrieved and shall return a value of zero.
Otherwise, a value of −1 shall be returned, the location referred to by tag_type_p, cshall not be changed, and errno shall be set to indicate the error.

1100

23.4.19.4 Errors

1101
1102

If any of the following conditions occur, the acl_get_tag_type() function shallreturn −1 and set errno to the corresponding value:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.4 Functions

71

1103

[EINVAL]

Argument entry_d is not a valid descriptor for an ACL entry.

−

1104

23.4.19.5 Cross-References

1105
1106

acl_create_entry(), 23.4.7; acl_get_entry(), 23.4.14; acl_get_qualifier(), 23.4.18;
acl_set_qualifier(), 23.4.24; acl_set_tag_type(), 23.4.25.

1107

23.4.20 Initialize ACL Working Storage

1108

Function: acl_init()

1109

23.4.20.1 Synopsis

1110#include <sys/acl.h>

c

1111

acl_t acl_init (int count)
);
c

1112

23.4.20.2 Description

1113
1114
1115
1116
1117
1118

The acl_init() function allocates and initializes working storage for an ACL of atleast count ACL entries. A pointer to the working storage is returned. The working storage allocated to contain the ACL is freed by a call to acl_free(). When the −area is first allocated, it shall contain an ACL that contains no ACL entries. The
initial state of any implementation-defined attributes of the ACL shall be
implementation-defined.

1119
1120
1121

This function may cause memory to be allocated. The caller should free any
releaseable memory, when the new ACL is no longer required, by calling
acl_free() with the (void ∗)acl_t as an argument.

1122

23.4.20.3 Returns

1123
1124
1125

Upon successful completion, this function shall return a pointer to the working
storage. Otherwise, a value of (acl_t)NULL shall be returned and errno shall be
set to indicate the error.

1126

23.4.20.4 Errors

1127
1128

If any of the following conditions occur, the acl_init() function shall return a valueof (acl_t)NULL and set errno to the corresponding value:1129[EINVAL]

The value of count is less than zero.

1130
1131
1132

[ENOMEM] The acl_t to be returned requires more memory than is allowedby the hardware or system-imposed memory management constraints.
−

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

72

23 Access Control Lists

1133

23.4.20.5 Cross-References1134

acl_free(), 23.4.12.

1135

23.4.21 Set an ACL by File Descriptor

1136

Function: acl_set_fd()1137

23.4.21.1 Synopsis

1138#include <sys/acl.h>

c

1139

int acl_set_fd (int fd,, acl_t acl)
);
c

1140

23.4.21.2 Description

1141
1142
1143
1144
1145
1146

The acl_set_fd() function associates an access ACL with the object referred to by
fd. The effective user ID of the process must match the owner of the object or the cprocess must have appropriate privilege to set the access ACL on the object. If{_POSIX_CAP} is defined, then appropriate privilege shall include c
CAP_FOWNER. In addition, if {_POSIX_MAC} is defined, then the process must chave MAC write access to the object.

1147
1148

The acl_set_fd() function will succeed only if the ACL referred to by acl is valid as+
defined by the acl_valid() function.

1149
1150
1151
1152
1153
1154

Upon successful completion, acl_set_fd() shall set the access ACL of the object −referred to by argument fd to the ACL contained in the argument acl. The object’s
previous access ACL shall no longer be in effect. The invocation of this function
may result in changes to the object’s file permission bits. If acl_set_fd() is unsuc- +cessful, the access ACL and the file permission bits of the object referred to by +argument fd shall not be changed.

1155
1156

The ordering of entries within the ACL referred to by acl may be changed in some
implementation-defined manner.

1157
1158
1159

Existing ACL entry descriptors that refer to entries within the ACL referred to byacl shall continue to refer to those entries. Existing ACL pointers that refer to the
ACL referred to by acl shall continue to refer to the ACL.

1160

23.4.21.3 Returns

1161
1162

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

1163

23.4.21.4 Errors

1164
1165

If any of the following conditions occur, the acl_set_fd() function shall return −1
and set errno to the corresponding value:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.4 Functions

73

1166
1167

[EACCES]If {_POSIX_MAC} is defined, MAC write access to the object is cdenied.
−1168[EBADF]The fd argument is not a valid file descriptor.

1169
1170
1171

[EINVAL]

Argument acl does not point to a valid ACL. The function
acl_valid() may be used to determine what errors are in the
ACL.
+

1172
1173
1174
1175

fpathconf() indicates that {_POSIX_ACL_EXTENDED} is in +effect for the object referenced by the argument fd, but the ACL +has more entries than the value returned by fpathconf() for +{_POSIX_ACL_PATH_MAX} for the object.

1176
1177
1178

[ENOSPC]

The directory or file system that would contain the new ACL
cannot be extended or the file system is out of file allocation
resources.
−

1179
1180

[EPERM]

The process does not have appropriate privilege to perform theoperation to set the ACL.

1181
1182

[EROFS]This function requires modification of a file system which iscurrently read-only.

1183

23.4.21.5 Cross-References

1184
1185

acl_delete_def_file(), 23.4.8; acl_get_entry(), 23.4.14; acl_get_fd(),
acl_get_file(), 23.4.16; acl_set_file(), 23.4.22; acl_valid(), 23.4.28.

1186

23.4.22 Set an ACL by Filename

1187

Function: acl_set_file()

1188

23.4.22.1 Synopsis

1189#include <sys/acl.h>

c

1190

int acl_set_file (const char ∗path_p,, acl_type_t type,, acl_t acl)
);
c

1191

23.4.22.2 Description

1192
1193
1194
1195
1196
1197
1198
1199

The acl_set_file() function associates an access ACL with an object or associates adefault ACL with a directory. The pathname for the object or directory is pointed
to by the argument path_p. The effective user ID of the process must match theowner of the object or the process must have appropriate privilege to set theaccess ACL or the default ACL on path_p. If {_POSIX_CAP} is defined, thenappropriate privilege shall include CAP_FOWNER.
In addition, if{_POSIX_MAC} is defined, then the process must have MAC write access to theobject.

23.4.15;

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

74

23 Access Control Lists

c

c

c

1200
1201
1202
1203
1204

The value of the argument type is used to indicate whether the access ACL or thedefault ACL associated with path_p is being set. If type is ACL_TYPE_ACCESS,
then the access ACL shall be set. If type is ACL_TYPE_DEFAULT, then thedefault ACL shall be set. If the argument type specifies a type of ACL that cannot
be associated with path_p, then the function shall fail.

1205
1206

The acl_set_file() function will succeed only if the access or default ACL is valid asdefined by the acl_valid() function.

1207
1208

If {_POSIX_ACL_EXTENDED} is not in effect for path_p, then the function shall
fail if:

1209(1) the value of type is ACL_TYPE_DEFAULT, or

1210(2) the value of type is ACL_TYPE_ACCESS and acl is not a minimum ACL.

1211
1212
1213

If the value of type is ACL_TYPE_ACCESS or ACL_TYPE_DEFAULT, then thefunction shall fail if the number of entries in acl is greater than the value pathconf() returns for {_POSIX_ACL_PATH_MAX} for path_p.
c

1214
1215
1216
1217
1218
1219
1220

Upon successful completion, acl_set_file() shall set the access ACL or the default −ACL, as indicated by type_d, of the object path_p to the ACL contained in theargument acl. The object’s previous access ACL or default ACL, as indicated by
type_d, shall no longer be in effect. The invocation of this function may result inchanges to the object’s file permission bits. If acl_set_file() is unsuccessful, the +access ACL, the default ACL, and the file permission bits of the object referred to +by argument path_p shall not be changed.

1221
1222

The ordering of entries within the ACL referred to by acl may be changed in some
implementation-defined manner.

1223
1224
1225

Existing ACL entry descriptors that refer to entries within the ACL referred to byacl shall continue to refer to those entries. Existing ACL pointers that refer to the
ACL referred to by acl shall continue to refer to the ACL.

1226

23.4.22.3 Returns

1227
1228

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

1229

23.4.22.4 Errors

1230
1231

If any of the following conditions occur, the acl_set_file() function shall return −1
and set errno to the corresponding value:

1232
1233
1234

[EACCES]

1235
1236

Search permission is denied for a component of the path prefixor the object exists and the process does not have appropriate
access rights.
If {_POSIX_MAC} is defined, MAC write access to path_p isdenied.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.4 Functions

75

c

1237
1238
1239
1240
1241

Argument type specifies a type of ACL that cannot be associatedwith path_p.
−[EINVAL]

Argument acl does not point to a valid ACL. The function
acl_valid() may be used to determine what errors are in the
ACL.

1242
1243
1244

Argument
type
is
ACL_TYPE_DEFAULT, or
value.

1245
1246
1247
1248

pathconf() indicates that {_POSIX_ACL_EXTENDED} is in +effect for the object referenced by the argument path_p, but the +ACL has more entries than the value returned by pathconf() for +{_POSIX_ACL_PATH_MAX} for the object.

a

not
valid

ACL_TYPE_ACCESS,
implementation-defined
+

1249
1250
1251
1252

[ENAMETOOLONG]
The length of the path_p argument exceeds {PATH_MAX}, or apathname component is longer than {NAME_MAX} while{POSIX_NO_TRUNC} is in effect.

1253
1254

[ENOENT]The named object does not exist or the path_p argument points
to an empty string.

1255
1256
1257

[ENOSPC]

The directory or file system that would contain the new ACL
cannot be extended or the file system is out of file allocation
resources.
−

1258[ENOTDIR] A component of the path prefix is not a directory.

1259
1260

[EPERM]

The process does not have appropriate privilege to perform theoperation to set the ACL.

1261
1262

[EROFS]This function requires modification of a file system which iscurrently read-only.

1263

23.4.22.5 Cross-References

1264
1265

acl_delete_def_file(), 23.4.8; acl_get_entry(), 23.4.14; acl_get_fd(),
acl_get_file(), 23.4.16; acl_set_fd(), 23.4.21; acl_valid(), 23.4.28.

1266

23.4.23 Set the Permissions in an ACL Entry

1267

Function: acl_set_permset()1268

23.4.23.1 Synopsis

1269#include <sys/acl.h>

c

1270

int acl_set_permset (acl_entry_t entry_d,, acl_permset_t permset_d));c23.4.15;

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

76

23 Access Control Lists

1271

23.4.23.2 Description

1272
1273
1274

The acl_set_permset() function shall set the permissions of the ACL entry indicated by argument entry_d to the permissions contained in the argument
permset_d.
−

1275
1276
1277
1278

Any ACL entry descriptors that refer to the entry containing the permission set
referred to by permset_d shall continue to refer to those entries. Any ACL entry
descriptors that refer to the entry referred to by entry_d shall continue to refer tothat entry.

1279

23.4.23.3 Returns

1280
1281

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

1282

23.4.23.4 Errors

1283
1284

If any of the following conditions occur, the acl_set_permset() function shall return−1 and set errno to the corresponding value:

1285[EINVAL]

Argument entry_d is not a valid descriptor for an ACL entry.

1286
1287

Argument permset_d is not a valid descriptor for a permission
set within an ACL entry.

1288
1289

Argument permset_d contains values which are not valid
acl_permset_t values.
−

1290

23.4.23.5 Cross-References

1291
1292

acl_add_perm(), 23.4.1; acl_clear_perms(), 23.4.3; acl_delete_perm(), 23.4.10;
acl_get_permset(), 23.4.17.

1293

23.4.24 Set ACL Entry Tag Qualifier

1294

Function: acl_set_qualifier()

1295

23.4.24.1 Synopsis

1296#include <sys/acl.h>

c

1297
1298

int acl_set_qualifier (acl_entry_t entry_d,,
const void ∗tag_qualifier_p)
);
c

1299

23.4.24.2 Description

1300
1301
1302

The acl_set_qualifier() function shall set the qualifier of the tag for the ACL entry
indicated by the argument entry_d to the value referred to by the argument
tag_qualifier_p.
+c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
23.4 Functions

77

1303
1304
1305
1306
1307
1308
1309
1310
1311

If the value of the tag type in the ACL entry referred to by entry_d is ACL_USER,
then the value referred to by tag_qualifier_p shall be of type uid_t. If the value ofthe tag type in the ACL entry referred to by entry_d is ACL_GROUP, then thevalue referred to by tag_qualifier_p shall be of type gid_t. If the value of the tag
type in the ACL entry referred to by entry_d is ACL_UNDEFINED_TAG,
ACL_USER_OBJ, ACL_GROUP_OBJ, ACL_OTHER or ACL_MASK, thenacl_set_qualifier() shall return an error. If the value of the tag type in the ACL
entry referred to by entry_d is an implementation-defined value, then the valuereferred to by tag_qualifier_p shall be implementation-defined.

1312
1313
1314
1315

Any ACL entry descriptors that refer to the entry referred to by entry_d shall con-−tinue to refer to that entry. This function may cause memory to be allocated. The
caller should free any releaseable memory, when the ACL is no longer required,by calling acl_free() with a pointer to the ACL as an argument.

1316

23.4.24.3 Returns

1317
1318

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

1319

23.4.24.4 Errors

1320
1321

If any of the following conditions occur, the acl_set_qualifier() function shallreturn −1 and set errno to the corresponding value:1322[EINVAL]

Argument entry_d is not a valid descriptor for an ACL entry.

1323
1324
1325

The tag type of the ACL entry referred to by the argument
entry_d is not ACL_USER, ACL_GROUP, nor a valid
implementation-defined value.

1326
1327

The value pointed to by the argument tag_qualifier_p is not
valid.

1328
1329[ENOMEM] The acl_set_qualifier() function is unable to allocate the memory
required for an ACL tag qualifier.
−1330

23.4.24.5 Cross-References1331

acl_get_qualifier(), 23.4.18.

1332

23.4.25 Set ACL Entry Tag Type

1333

Function: acl_set_tag_type()

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

78

23 Access Control Lists

c

1334

23.4.25.1 Synopsis

1335#include <sys/acl.h>

c

1336

int acl_set_tag_type (acl_entry_t entry_d,, acl_tag_t tag_type)
);
c

1337

23.4.25.2 Description

1338
1339

The acl_set_tag_type() function shall set the tag type for the ACL entry referred toby the argument entry_d to the value of the argument tag_type.
−

1340
1341

Any ACL entry descriptors that refer to the entry referred to by entry_d shall continue to refer to that entry.

1342

23.4.25.3 Returns

1343
1344

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

1345

23.4.25.4 Errors

1346
1347

If any of the following conditions occur, the acl_set_tag_type() function shallreturn −1 and set errno to the corresponding value:

1348[EINVAL]

1349

Argument entry_d is not a valid descriptor for an ACL entry.
−

Argument tag_type is not a valid tag type.

1350

23.4.25.5 Cross-References1351

acl_get_tag_type(), 23.4.19.

1352

23.4.26 Get the Size of an ACL

1353

Function: acl_size()1354

23.4.26.1 Synopsis

1355#include <sys/acl.h>

c

1356

ssize_t acl_size (acl_t acl)
);
c

1357

23.4.26.2 Description

1358
1359
1360

The acl_size() function shall return the size, in bytes, of the buffer required tohold the exportable, contiguous, persistent form of the ACL pointed to by argument acl, when converted by acl_copy_ext().

1361
1362

Any existing ACL entry descriptors that refer to entries in acl shall continue to −refer to the same entries. Any existing ACL pointers that refer to the ACL
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

23.4 Functions

79

1363
1364

referred to by acl shall continue to refer to the ACL. The order of ACL entries
within acl shall remain unchanged.

1365

23.4.26.3 Returns

1366
1367
1368

Upon successful completion, the acl_size() function shall return the size in bytesof the contiguous, persistent form of the ACL. Otherwise, a value of (ssize_t) −1
shall be returned and errno shall be set to indicate the error.

1369

23.4.26.4 Errors

1370
1371

If any of the following conditions occur, the acl_size() function shall return(ssize_t) −1 and set errno to the corresponding value:

1372[EINVAL]

Argument acl does not point to a valid ACL.

−

1373

23.4.26.5 Cross-References1374

acl_copy_ext(), 23.4.5.

1375

23.4.27 Convert an ACL to Text

1376

Function: acl_to_text()

1377

23.4.27.1 Synopsis

1378#include <sys/acl.h>

c

1379

char ∗acl_to_text (acl_t acl,, ssize_t ∗len_p)
);
c

1380

23.4.27.2 Description

1381
1382
1383
1384
1385

The acl_to_text() function translates the ACL pointed to by argument acl into a

NULL terminated character string. If the pointer len_p is not NULL, then the −function shall return the length of the string (not including the NULL terminator)

in the location pointed to by len_p. The format of the text string returned by −acl_to_text() shall be the long text form defined in 23.3.1.
c

1386
1387
1388
1389

This function allocates any memory necessary to contain the string and returns a +pointer to the string. The caller should free any releaseable memory, when the +new string is no longer required, by calling acl_free() with the (void ∗)char as an +argument.
+

1390
1391
1392
1393

Any existing ACL entry descriptors that refer to entries in acl shall continue torefer to the same entries. Any existing ACL pointers that refer to the ACL
referred to by acl shall continue to refer to the ACL. The order of ACL entries
within acl shall remain unchanged.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

80

23 Access Control Lists

1394

23.4.27.3 Returns

1395
1396
1397

Upon successful completion, the function shall return a pointer to the long text
form of an ACL. Otherwise, a value of (char ∗)NULL shall be returned and errno
shall be set to indicate the error.

1398

23.4.27.4 Errors

1399
1400

If any of the following conditions occur, the acl_to_text() function shall return avalue of (char ∗)NULL and set errno to the corresponding value:1401[EINVAL]

Argument acl does not point to a valid ACL.

1402
1403
1404

The ACL denoted by acl contains one or more improperly formed
ACL entries, or for some other reason cannot be translated into atext form of an ACL.

1405
1406
1407

[ENOMEM] The character string to be returned requires more memory thanis allowed by the hardware or system-imposed memory management constraints.
−

1408

23.4.27.5 Cross-References1409

acl_free(), 23.4.12; acl_from_text(). 23.4.13.

1410

23.4.28 Validate an ACL

1411

Function: acl_valid()1412

23.4.28.1 Synopsis

1413#include <sys/acl.h>

c

1414

int acl_valid (acl_t acl)
);
c

1415

23.4.28.2 Description

1416
1417

The acl_valid() function checks the ACL referred to by the argument acl for validity.

1418
1419
1420
1421
1422

The three required entries (ACL_USER_OBJ, ACL_GROUP_OBJ, and
ACL_OTHER) shall exist exactly once in the ACL. If the ACL contains any
ACL_USER, ACL_GROUP, or any implementation-defined entries in the filegroup class, then one ACL_MASK entry shall also be required. The ACL shallcontain at most one ACL_MASK entry.

1423
1424
1425
1426

The qualifier field shall be unique among all entries of the same POSIX.1e ACL
facility defined tag type. The tag type field shall contain valid values including
any implementation-defined values. Validation of the values of the qualifier field
is implementation-defined.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

23.4 Functions

81

1427
1428

The ordering of entries within the ACL referred to by acl may be changed in some
implementation-defined manner.

1429
1430
1431

Existing ACL entry descriptors that refer to entries within the ACL referred to byacl shall continue to refer to those entries. Existing ACL pointers that refer to the
ACL referred to by acl shall continue to refer to the ACL.

1432
1433
1434

If multiple errors occur in the ACL, the order of detection of the errors and, as aresult, the ACL entry descriptor returned by acl_valid() shall be implementationdefined.

1435

23.4.28.3 Returns

1436
1437

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

1438

23.4.28.4 Errors

1439
1440

If any of the following conditions occur, the acl_valid() function shall return −1
and set errno to the corresponding value:

1441[EINVAL]

Argument acl does not point to a valid ACL.

1442

One or more of the required ACL entries is not present in acl.

1443

The ACL contains entries that are not unique.

−

1444

23.4.28.5 Cross-References

1445
1446

acl_get_entry(), 23.4.14; acl_get_fd(), 23.4.15; acl_get_file(), 23.4.16; acl_init(),23.4.20; acl_set_fd(), 23.4.21; acl_set_file(), 23.4.22.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

82

23 Access Control Lists

Section 24: Audit1

2

24.1 General Overview

3
4

There are four major functional components of the POSIX.1 audit interface
specification:56(1) Interfaces for a conforming application to construct and write records toan audit log and control the auditing of the current process

7(2) Interfaces for reading an audit log and manipulating audit records

89(3) The definition of a standard set of events, based on the POSIX.1 function
interfaces, that shall be reportable in conforming implementations

10(4) The definition of the contents of audit records.

11
12This standard defines which interfaces require an appropriate privilege, and therelevant capabilities if the POSIX capability option is in use.

13
14

Support for the interfaces defined in this section is optional but shall be provided
if the symbol {_POSIX_AUD} is defined.

15

24.1.1 Audit Logs

16
17
18
19
20

The standard views the destination of audit records that are recorded, and thesource of records read by an audit post-processing application, as an ‘‘audit log’’.
Audit logs map to the POSIX abstraction of a ‘‘file’’: that is, POSIX file interfaces
such as open() can generally be used to gain access to audit logs, subject to theaccess controls of the system.

21
22

As viewed at the POSIX interface, a log contains a sequence of audit records;
interfaces are provided to write records to a log, and to read records from it.

23
24
25
26
27
28
29
30
31

A conforming implementation shall support a ‘‘system audit log’’: that is, a log
that is the destination of system-generated audit records (e.g. reporting on use of csecurity-relevant POSIX.1 interfaces), and of application-generated records thatan application sends to that log. The system audit log may correspond to different
files at different times. An application that sends records to the system audit log
does not have to be able to open() the corresponding file; instead an appropriate
privilege is required. This protects the integrity of the system audit log. A postprocessing application that reads records from the system audit log can gain
access to the log through open() of the file that currently corresponds to it.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.1 General Overview

83

32
33
34

The internal format of audit logs, and of the records within them, is unspecified(because of this, the POSIX read() and write() interfaces should not generally be
used to access audit logs).

35

24.1.2 Audit Records

36
37
38
39

Audit records describe events; that is, there is a correspondence between someactual event that occurred and the audit record reporting it. An audit record provides a description of one event. With an audit record, a report is given of what
happened, who will be held accountable for it, what it affected, and when.

40

Audit records are generated in two ways:

41
42
43

g

By a system conforming to the POSIX.1 audit option, to report on use of its
security relevant interfaces. This is known as system auditing, and therecords are known as system-generated records.

44
45

g

By an application with the appropriate privilege, to report on its own activities. These are known as application-generated records.

46
47
48
49
50

This standard does not specify the method by which audit records are written to
the audit log nor does it specify the internal format in which audit records are
stored. The standard specifies only the interfaces by which application-generated
records are delivered to the system and by which system- and applicationgenerated records are reported to a conforming application.

51
52

Note that the standard does not specify the manner by which system-generated
records are delivered to the system audit log; this is left up to the implementation.

53
54
55
56
57
58
59
60
61
62

An audit record that is generated by an application, or an auditable event that
occurs in a system conforming to the POSIX.1 audit option, may or may not actually be reported to a conforming application. This standard specifies that these
events shall be reportable on a conforming implementation, but not that they
always be reported. The record will be reported only if {_POSIX_AUD} was
defined at the time the event occurred and was defined at the time the event completed. The results are indeterminate if {_POSIX_AUD} was not defined throughthe lifetime of the event. There may also be other implementation-specific controls on the events that are actually reported (in particular, a conforming implementation may have some configurable selectivity of the events that are reported).

63

24.1.2.1 Audit Record Contents

64
65
66

Although there is no requirement on how the system stores an audit record, logically it appears to the post-processing application, and to a self-auditing application constructing a record, to have several parts:

67g

one or more headers, see below

68
69

g

one or more sets of subject attributes, describing the process(es) thatcaused the event to be reported

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

84

24 Audit70gzero or more sets of event-specific data

71
72

g

zero or more sets of object attributes, describing objects affected by theevent.

73
74
75

Records are required to have at least one header and set of subject attributes.
Conforming implementations and self-auditing applications may add further
parts, of any type; the contents of each of the required parts is also extensible.

76
77
78
79
80
81
82
83

A post-processing application can obtain a descriptor to each of the parts, andusing these descriptors can then obtain the contents of each part. An audit record
header contains, amongst other things, the event type, time and result. There isalso a record format indicator, currently limited to defining that the data in therecord is in the format used by the current system. The header also contains a
version number, identifying the version of this standard to which the record content conforms. Post-processing applications should examine this value to ensurethat the version is one for which they can process the information in the record.

84
85
86
87
88
89
90
91

The event type in the header defines the minimum set of information found in therecord. This standard specifies the required content for POSIX.1 events that are
required to be auditable: that is, the content of the event-specific and object partsof the record; the event type for these system-generated events is an integer.
Implementations may define additional content for such events, and additional
events and their content. Self-auditing applications may add further events, withapplication-specific types and contents; the event type for these applicationgenerated events is a text string.

92
93
94
95
96
97
98

To ensure that users can be made individually accountable for their securityrelevant actions, an ‘‘audit identifier’’, or audit ID, that an implementation can
use to uniquely identify each accountable user, is included in the header of eachrecord. If the record is related to an event that is not associated with any individual user (e.g., events recorded before a user has completed authentication, or
events from daemons), the implementation may report a null audit ID for thatrecord.

99

24.1.3 Audit Interfaces

100
101
102
103
104

Self-auditing applications need a standard means of constructing records andadding them into an audit log. Additionally, applications having the appropriate
privilege may need to suspend system auditing of their actions. However, therequest to suspend system auditing is advisory and may be rejected by the implementation.

105
106

Portable audit post-processing utilities need a standard means to access records
in an audit log and a standard means to analyze the content of the records.

107
108

Several groups of functions are defined for use by portable applications. These
functions are used to:109(1) Construct audit records

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.1 General Overview

85

110

(2) Write audit records

111(3) Control system auditing of the current process

112(4) Read audit records

113(5) Analyze an audit record

114
115

(6) Save audit records in user-managed store and return them to systemmanaged store.

116

The following sections provide an overview of those functions.

117

24.1.3.1 Accessing an Audit Log

118
119

Audit logs are accessed via the POSIX.1 open() and close() functions. The system
audit log is also written directly by the aud_write() function (see below).

120

24.1.3.2 Constructing Audit Records

121
122

Functions are provided to get access to an unused audit record in working store,
and to duplicate an existing record:123

aud_init_record() Get access to an unused audit record in working store.

124
125

aud_dup_record() Create a duplicate of an existing audit record in working
store.

126
127

Various other functions manipulate audit records. New sections can be added toan audit record:128

aud_put_hdr()

Add an empty header to an audit record

129

aud_put_subj()

Add an empty set of subject attributes to an audit record

130

aud_put_event()

Add an empty set of event-specific data to an audit record

131

aud_put_obj()

Add an empty set of object attributes to an audit record

132

And data can be added to each type of section:133

aud_put_hdr_info() Add a data item to a header in an audit record

134
135

aud_put_subj_info() Add a data item to a set of subject attributes in an audit
record136137

aud_put_event_info() Add a data item to a set of event-specific data in an audit
record138
139

aud_put_obj_info() Add a data item to a set of object attributes in an audit
record.

140

Data items can also be deleted from each type of section:141

aud_delete_hdr_info() Delete a data item from a header in an audit record

142
143

aud_delete_subj_info() Delete a data item from a set of subject attributes in anaudit record
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

86

24 Audit144
145

aud_delete_event_info() Delete a data item from a set of event-specific data in
an audit record

146
147

aud_delete_obj_info() Delete a data item from a set of object attributes in anaudit record.

148

And whole sections can be deleted too:149

aud_delete_hdr() Delete a header from an audit record

150

aud_delete_subj() Delete a set of subject attributes from an audit record

151

aud_delete_event()Delete a set of event-specific data from an audit record

152

aud_delete_obj()

153
154
155
156
157
158
159
160

Delete a set of object attributes from an audit record.

A function is provided to obtain the audit ID of the user accountable for theactions of a specified process:aud_get_id()

Get the audit ID of a process with a specified process ID.
This allows, for example, a server process to include theaudit ID of a client in a record it generates.

A function is provided to check the validity of an audit record:
aud_valid()

Validates an audit record by checking for, at least, a valid
header.

161

24.1.3.3 Writing Audit Records

162

A single function is provided to write a record to an audit log:

163
164
165
166
167
168
169
170

aud_write()

When a program wants to write a record to an audit log, itcalls aud_write(). The system then adds the record to thelog. This could be used by a self-auditing application thathas constructed the record, or by an audit post-processing
application that has read the record from an audit log and
now wants to preserve it in another log for later processing. −Appropriate privilege is required to use this interface towrite to the system audit log.

171

24.1.3.4 Controlling System Auditing

172
173

A single function is provided to allow a self-auditing application to control system
auditing of its operations:

174
175
176
177
178
179
180

aud_switch()

Suspend or resume system auditing of the current process,or query the current state of system auditing for the current
process. The system may or may not actually suspend(either partially or completely) its auditing of the process,depending on the implementation-specific audit policy
currently in use. Appropriate privilege is required to use −this interface.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.1 General Overview

87

181

24.1.3.5 Reading Audit Records

182
183

A single function is provided to read an audit record from an audit log into systemmanaged store.

184
185
186
187

aud_read()

Read the next record from the audit log and return adescriptor to it in working store. The descriptor can then be
used as an argument to any of the audit functions thatmanipulate audit records.

188

24.1.3.6 Analyzing an Audit Record

189
190

Functions are provided to get descriptors for the various sections of an audit
record, and to get data items from within each type of section:191

aud_get_hdr()

Get the descriptor for a header from an audit record.

192

aud_get_hdr_info()

Get an item from within a header of an audit record.

193
194

aud_get_subj()

Get the descriptor for a subject attribute set from anaudit record.

195
196

aud_get_subj_info()

Get an item from within a subject attribute set from anaudit record.

197
198

aud_get_event()Get the descriptor for a set of event-specific data froman audit record.

199
200

aud_get_event_info()

Get an item from within a set of event-specific datafrom an audit record.

201
202

aud_get_obj()

Get a descriptor for an object attribute set from anaudit record.

203
204

aud_get_obj_info()

Get an item from within an object attribute set in anaudit record.

205
206
207
208
209

To allow a post-processing application to interact with an audit administrator,
either to display records or to obtain record selection criteria from the administrator, interfaces are provided to convert a record to text, to convert between theinternal and human-readable forms of event types and audit IDs, and to find out
all the system event types reportable in the audit log:210

aud_rec_to_text()

Convert an entire audit record into human-readable text.

211
212

aud_evid_to_text()

Map a numeric identifier for a system audit event to a text
string.

213
214

aud_evid_from_text() Map a text string, representing an system audit event type,to a numeric audit event.

215

aud_id_to_text()

Map an audit ID to text identifying an individual user.

216

aud_id_from_text()

Map text identifying an individual user to an audit ID.

217
218

aud_get_all_evid()

Get a list of all system generated audit event types currently
reportable on the system. This interface retrieves both

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

88

24 Audit

219

POSIX.1 and implementation-specific event types.

220

24.1.3.7 Storing Audit Records

221
222
223
224
225

A pair of functions are provided for placing audit records in user-managed spaceand conversely, returning audit records to system-managed space; for the former,
a function is provided that determines how much space is needed. This facility
provides applications with the ability to save selected records outside an audit log
for later processing.

226
227

aud_copy_ext()

The aud_copy_ext() function is provided to convert therecord to a ‘‘byte-copyable’’ format in user-managed space.

228
229
230
231

aud_copy_int()

The aud_copy_int() function is provided to convert therecord from a ‘‘byte-copyable’’ format in user-managed space
into system-dependent, internal format in system-managed
space.

232
233

aud_size()

Return the size of user-managed space needed to hold arecord.

234
235

Note that it is also possible to transfer an audit record from one log to another,
without using user-managed space, by use of aud_read() and aud_write().

236
237

Finally, an interface is provided to allow an application to free any memory allocated by the various audit functions:

238
239

aud_free()Many of the above interfaces may allocate memory space.
The aud_free() interface frees all the releasable space.

240

24.1.4 Summary of POSIX.1 System Interface Impact

241
242
243
244

When {_POSIX_AUD} is defined, there is no impact on the interface syntax of any
POSIX.1 function, nor on the function semantics defined by POSIX.1. However,use of some POSIX.1 functions may cause audit records to be reported, see section
24.2.1.1, below.

245

24.2 Audit Record Content

246
247
248
249
250
251

Section 24.1.2.1, defines the overall structure of an audit record, viewed throughthese interfaces, as consisting of headers, subject attribute sets, sets of eventspecific data items, and object attribute sets. This section specifies the minimum
set of event types which shall be reportable in a conforming implementation, andfor each of these event types defines the minimum required contents of the set of
event-specific items for the event and the minimum required object attribute sets.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.2 Audit Record Content

89

252

24.2.1 Auditable Interfaces and Event Types

253
254

This section defines the minimum set of audit event types that shall be reportable
by a conforming system.

255
256
257

Two kinds of auditing are defined. First there is auditing, by the system, ofoperations performed by programs at the system interface level. Second there is
auditing by applications of their own operations.

258

24.2.1.1 Auditing at the System Interface

259
260
261
262
263
264
265

The following interfaces, which are derived from POSIX.1 and the POSIX.1e
options, are defined as the minimum set of system interface functions that shallbe reportable on a conforming implementation. For each interface, a corresponding POSIX.1e audit event is defined. For each defined event, a numeric constantuniquely identifying the audit event is defined in the <sys/audit.h> header.
For all the interfaces except fork(), a single audit record shall be reportable foreach occasion that the interface is used.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

90

24 Audit266

If {_POSIX_AUD} is defined, the following interfaces shall be auditable:

267

Table 24-1 − Interfaces and Corresponding Audit Events

268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299

Interfacehhhhhhhhhhhh
aud_switch()
aud_write()chdir()
chmod()
chown()
creat()dup()
dup2()
exec()
execl()
execlp()execv()
execvp()execle()execve()_exit()
fork()
kill()link()
mkdir()
mkfifo()open()
opendir()pipe()
rename()rmdir()
setgid()setuid()unlink()utime()

cc

Event Typehhhhhhhhhhhhhhhhhhhhhhhhh
AUD_AET_AUD_SWITCH
AUD_AET_AUD_WRITE
AUD_AET_CHDIR
AUD_AET_CHMOD
AUD_AET_CHOWN
AUD_AET_CREAT
AUD_AET_DUP
AUD_AET_DUP
AUD_AET_EXEC
AUD_AET_EXEC
AUD_AET_EXEC
AUD_AET_EXEC
AUD_AET_EXEC
AUD_AET_EXEC
AUD_AET_EXEC
AUD_AET_EXIT
AUD_AET_FORK
AUD_AET_KILL
AUD_AET_LINK
AUD_AET_MKDIR
AUD_AET_MKFIFO
AUD_AET_OPEN
AUD_AET_OPEN
AUD_AET_PIPE
AUD_AET_RENAME
AUD_AET_RMDIR
AUD_AET_SETGID
AUD_AET_SETUID
AUD_AET_UNLINKAUD_AET_UTIME
cc
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c

300
301

The aud_write() function is auditable only when an attempt to write to the system audit log fails.

302
303

The fcntl() function when used with command F_DUPFD also generates audit
events of type AUD_AET_DUP.

304

If {_POSIX_ACL} is defined, the following interfaces shall be auditable:

305
306
307
308
309
310

c

Interfaceh hhhhhhhhhhhhhhhhh

Event Typehhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhcc

acl_delete_def_file()
acl_set_fd()
acl_set_file()

AUD_AET_ACL_DELETE_DEF_FILE
AUD_AET_ACL_SET_FD
AUD_AET_ACL_SET_FILEccc

If {_POSIX_CAP} is defined, the following interfaces shall be auditable:c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.2 Audit Record Content

91

311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327

Interfacehhhhhhhhhhhhh

Event Typehhhhhhhhhhhhhhhhhhhhhhhhhhhcc

cap_set_fd()
cap_set_file()
cap_set_proc()

AUD_AET_CAP_SET_FD
AUD_AET_CAP_SET_FILE
AUD_AET_CAP_SET_PROCccc

If {_POSIX_INF} is defined, the following interfaces shall be auditable:cInterfacehhhhhhhhhhhhh

Event Typehhhhhhhhhhhhhhhhhhhhhhhhhhhcc

inf_set_fd()
inf_set_file()
inf_set_proc()

AUD_AET_INF_SET_FD
AUD_AET_INF_SET_FILE
AUD_AET_INF_SET_PROCccc

If {_POSIX_MAC} is defined, the following interfaces shall be auditable:cInterfacehhhhhhhhhhhhhh

Event Typehhhhhhhhhhhhhhhhhhhhhhhhhhhhcc

mac_set_fd()
mac_set_file()
mac_set_proc()

AUD_AET_MAC_SET_FD
AUD_AET_MAC_SET_FILE
AUD_AET_MAC_SET_PROC
c
c
c

328
329
330

Event types recording use of other system interfaces shall be implementationdefined; a complete set of such events shall be obtainable through the
aud_get_all_evid() interface.

331

24.2.1.2 Auditing by Applications

332
333
334
335
336
337

No specific types are defined for auditing by applications. The event types usedby applications are character strings (to reduce the chances of different applications using the same types and ensure they do not clash with the integer event
types used for system-generated events) and applications are free to add theirown audit event types. Applications which generate their own audit records will
use the aud_write() function passing the event type in the record header.

338

24.2.2 Audit Event Types and Record Content

339
340
341
342
343
344
345
346
347
348
349

This clause defines the minimum required content of audit records for each of thestandard event types. The required contents of the header is the same for all
records, and is defined in aud_get_hdr_info(); the required content of the set of
subject attributes is similar for all records, and is defined in aud_get_subj_info();the required contents of a set of object attributes is defined in aud_get_obj_info().
This section defines the required minimum content for the set of items specific toeach event, and the required minimum object attribute sets for each event. A conforming implementation may include additional items in the required header, setof subject attributes, set of event-specific items, and object attribute sets, or may
add additional sets, but the required content must be reported before these
implementation-specific additions.

350
351
352
353
354

A header, subject attribute set, set of event-specific items, and object attribute set
from an audit record are not C-language structures; each is a separate logical section within the record, with components accessed using the aud_get_∗_info()
interfaces described below. An argument item_id of these interfaces identifies thecomponent to access; a value for this argument for each component is defined in
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

92

24 Audit355

the tables below.

356
357
358
359
360
361
362

Unless otherwise specified, event-specific data contains the argument values
requested for the operation. If the argument is not available (for example, if thecaller supplied a NULL or invalid pointer for a pathname), theaud_get_event_info() function shall return an aud_info_t structure with a zero len
member. Pathname values reported as arguments may be the exact values
passed as arguments, or may be expanded by the implementation to full pathnames.

363

24.2.2.1 AUD_AET_ACL_DELETE_DEF_FILE

364
365

This event will be encountered only if {_POSIX_ACL} was defined when the audit clog was generated.

366
367
368

Calls
on
aud_get_event_info()
for
the
audit
recordofan
AUD_AET_ACL_DELETE_DEF_FILE event shall return aud_info_t structures
for the following event-specific items, with aud_info_type members as specified:

369
370
371

Type
h hhhhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING

Pathname

AUD_PATHNAME
c

372
373

The Pathname contains theacl_delete_def_file() function.

374
375
376
377
378
379
380

If the call succeeded a set of object attributes shall also be available from therecord, describing the object affected; if an ACL is reported in the set of object
attributes it shall contain the ACL before the event. If the call failed due toaccess controls, and a set of object attributes is still available from the record, it
shall describe the object at which the failure occurred. Otherwise it is unspecified
whether a set of object attributes is available, or what object is defined by such a
set.

381

24.2.2.2 AUD_AET_ACL_SET_FD

382
383

This event will be encountered only if {_POSIX_ACL} was defined when the audit clog was generated.

384
385
386

Calls on aud_get_event_info() for the audit record of an AUD_AET_ACL_SET_FD
event shall return aud_info_t structures for the following event-specific items,with aud_info_type members as specified:

387
388
389
390
391

Type
hhhhhhhhhhhhhhhhhhhhhhh
AUD_TYPE_INT
AUD_TYPE_ACL_TYPE
AUD_TYPE_ACL

value

passedDescriptionhhhhhhhhhhhhh
File desc
ACL type
ACL

as

an

argumenttotheitem_idhhhhhhhhhhhhhhhhhcc

AUD_FILE_ID
AUD_ACL_TYPE
AUD_ACL
c
c
c

392
393

The File desc, ACL type, and ACL contain the values passed as arguments to theacl_set_fd() function.

394
395
396

If the call succeeded a set of object attributes shall also be available from therecord, describing the object affected; if an ACL is reported in the set of object
attributes it shall contain the ACL before the event. If the call failed due to
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

24.2 Audit Record Content

93

397
398
399
400

access controls, and a set of object attributes is still available from the record, it
shall describe the object at which the failure occurred. Otherwise it is unspecified
whether a set of object attributes is available, or what object is defined by such a
set.

401

24.2.2.3 AUD_AET_ACL_SET_FILE

402
403

This event will be encountered only if {_POSIX_ACL} was defined when the audit clog was generated.

404
405
406

Calls
on
aud_get_event_info()
for
the
audit
recordofan
AUD_AET_ACL_SET_FILE event shall return aud_info_t structures for the following event-specific items, with aud_info_type members as specified:

407
408
409
410
411

Type
hhhhhhhhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh
Pathname
ACL type
ACL

AUD_TYPE_STRING
AUD_TYPE_ACL_TYPE
AUD_TYPE_ACL

item_idhhhhhhhhhhhhhhhhhh
AUD_PATHNAMEAUD_ACL_TYPE
AUD_ACL

412
413

The Pathname, ACL type, and ACL contain the values passed as arguments tothe acl_set_file() function.

414
415
416
417
418
419
420

If the call succeeded a set of object attributes shall also be available from therecord, describing the object affected; if an ACL is reported in the set of object
attributes it shall contain the ACL before the event. If the call failed due toaccess controls, and a set of object attributes is still available from the record, it
shall describe the object at which the failure occurred. Otherwise it is unspecified
whether a set of object attributes is available, or what object is defined by such a
set.

421

24.2.2.4 AUD_AET_AUD_SWITCH

422
423
424

Calls
on
aud_get_event_info()
for
the
audit
recordofan
AUD_AET_AUD_SWITCH event shall return aud_info_t structures for the following event-specific items, with aud_info_type members as specified:

425
426
427

Type
hhhhhhhhhhhhhhhhhhhhhhhhh
AUD_TYPE_AUD_STATE

Descriptionhhhhhhhhhhhhh
Audit state

c
c

cc

AUD_AUDIT_STATEccitem_idhhhhhhhhhhhhhhhhhhhhh

428
429

The Audit state contains the value passed as an argument to the aud_switch()function: AUD_STATE_ON, AUD_STATE_OFF or AUD_STATE_QUERY.

430

24.2.2.5 AUD_AET_AUD_WRITE

431
432
433
434
435
436
437

Calls on aud_get_event_info() for the audit record of an AUD_AET_AUD_WRITE
event are not required to report any event-specific data. This event is required tobe reportable only if an attempt to use aud_write(), to write a record to the system audit log, fails (e.g. due to lack of appropriate privilege). The header of therecord shall give details of the attempt to use aud_write(), and the set of subject
attributes shall relate to the caller of aud_write(); that is, the record is not
required to contain data from the record that the application tried to write to the
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

94

cc

24 Auditc438

system audit log.

439

24.2.2.6 AUD_AET_CAP_SET_FD

440
441

This event will be encountered only if {_POSIX_CAP} was defined when the audit clog was generated.

442
443
444

Calls on aud_get_event_info() for the audit record of an AUD_AET_CAP_SET_FD
event shall return aud_info_t structures for the following event-specific items,with aud_info_type members as specified:

445
446
447
448

Type
hhhhhhhhhhhhhhhhh

Description
hhhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhh
cc

AUD_TYPE_INT
AUD_TYPE_CAP

File desc
Capability state

AUD_FILE_ID
AUD_CAP
c
c

449
450

The File desc and Capability state contain the values passed as arguments to the
cap_set_fd() function.

451
452
453
454
455
456
457

If the call succeeded a set of object attributes shall also be available from therecord, describing the object affected; if a file capability state is reported in the setof object attributes it shall contain the file capability state before the event. If thecall failed due to access controls, and a set of object attributes is still available
from the record, it shall describe the object at which the failure occurred. Otherwise it is unspecified whether a set of object attributes is available, or what object
is defined by such a set.

458

24.2.2.7 AUD_AET_CAP_SET_FILE

459
460

This event will be encountered only if {_POSIX_CAP} was defined when the audit clog was generated.

461
462
463

Calls
on
aud_get_event_info()
for
the
audit
recordofan
AUD_AET_CAP_SET_FILE event shall return aud_info_t structures for the following event-specific items, with aud_info_type members as specified:

464
465
466
467

Type
h hhhhhhhhhhhhhhhhhhh
AUD_TYPE_STRING
AUD_TYPE_CAP

Description
hhhhhhhhhhhhhhh
Pathname
Capability state

item_idhhhhhhhhhhhhhhhhhh
AUD_PATHNAMEAUD_CAP
cc
c
c

468
469

The Pathname and Capability state contain the values passed as arguments to the
cap_set_file() function.

470
471
472
473
474
475
476

If the call succeeded a set of object attributes shall also be available from therecord, describing the object affected. If a file capability state is reported in theset of object attributes it shall contain the file capability state before the event. If
the call failed due to access controls, and a set of object attributes is still available
from the record, it shall describe the object at which the failure occurred. Otherwise it is unspecified whether a set of object attributes is available, or what object
is defined by such a set.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.2 Audit Record Content

95

477

24.2.2.8 AUD_AET_CAP_SET_PROC

478
479

This event will be encountered only if {_POSIX_CAP} was defined when the audit clog was generated.

480
481
482

Calls
on
aud_get_event_info()
for
the
audit
recordofan
AUD_AET_CAP_SET_PROC event shall return aud_info_t structures for the following event-specific items, with aud_info_type members as specified:

483
484
485

Type
hhhhhhhhhhhhhhhhh

Description
hhhhhhhhhhhhhhh

item_idhhhhhhhhhh
cc

AUD_TYPE_CAP

Capability state

AUD_CAP
c

486
487
488
489

The Capability state records the value passed as an argument to the
cap_set_proc() function. If a capability state is reported in the set of subject attributes in the record, this shall record the process capability state of the process
before the event.

490

24.2.2.9 AUD_AET_CHDIR

491
492
493

Calls on aud_get_event_info() for the audit record of an AUD_AET_CHDIR event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

494
495
496

Type
h hhhhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING

Pathname

AUD_PATHNAME
c497

The Pathname contains the value passed as an argument to the chdir() function.

498

24.2.2.10 AUD_AET_CHMOD

499
500
501

Calls on aud_get_event_info() for the audit record of an AUD_AET_CHMOD event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

502
503
504
505

Type
h hhhhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING
AUD_TYPE_MODE

Pathname
Mode

AUD_PATHNAME
AUD_MODE
c

506
507

The Pathname and Mode contain the values passed as arguments to the chmod()function.

508
509
510
511
512
513
514

If the call succeeded a set of object attributes shall also be available from therecord, describing the object affected; if a mode is reported in the set of object
attributes it shall contain the mode before the event. If the call failed due toaccess controls, and a set of object attributes is still available from the record, it
shall describe the object at which the failure occurred. Otherwise it is unspecified
whether a set of object attributes is available, or what object is defined by such a
set.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

96

24 Auditc515

24.2.2.11 AUD_AET_CHOWN

516
517
518

Calls on aud_get_event_info() for the audit record of an AUD_AET_CHOWN event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

519
520
521
522
523

Type
h hhhhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING
AUD_TYPE_UID
AUD_TYPE_GID

Pathname
Owner
Group

AUD_PATHNAMEAUD_UID
AUD_GID
c
c
c

524
525

The Pathname, Owner, and Group contain the values passed as arguments to thechown() function.

526
527
528
529
530
531
532

If the call succeeded a set of object attributes shall also be available from therecord, describing the object affected; if an owner and group are reported in theset of object attributes they shall contain the object owner and group before theevent. If the call failed due to access controls, and a set of object attributes is stillavailable from the record, it shall describe the object at which the failure
occurred. Otherwise it is unspecified whether a set of object attributes is available, or what object is defined by such a set.

533

24.2.2.12 AUD_AET_CREAT

534
535
536

Calls on aud_get_event_info() for the audit record of an AUD_AET_CREAT event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

537
538
539
540
541

Type
h hhhhhhhhhhhhhhhhhhh

Description
hhhhhhhhhhhhhhhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING
AUD_TYPE_MODE
AUD_TYPE_INT

Pathname
Mode
Return value (file descriptor)

AUD_PATHNAME
AUD_MODEAUD_RETURN_ID
c

542
543

The Pathname and Mode contain the values passed as arguments to the creat()function.

544
545
546
547
548

If the call succeeded a set of object attributes shall also be available from therecord, describing the object created. If the call failed due to access controls, anda set of object attributes is still available from the record, it shall describe theobject at which the failure occurred. Otherwise it is unspecified whether a set ofobject attributes is available, or what object is defined by such a set.

549

24.2.2.13 AUD_AET_DUP

550
551
552

Calls on aud_get_event_info() for the audit record of an AUD_AET_DUP event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

553
554
555
556

Type
hhhhhhhhhhhhhhhh

Description
hhhhhhhhhhhhhhhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_INT
AUD_TYPE_INTFile descriptor
Return value (file descriptor)

AUD_FILE_ID
AUD_RETURN_ID
c

c

c

c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.2 Audit Record Content

97

557
558

This event is recorded for any of the functions dup(), dup2(), or fcntl() with command F_DUPFD.

559
560

The File descriptor contains the value passed as the first argument to the function.

561

24.2.2.14 AUD_AET_EXEC

562
563
564

Calls on aud_get_event_info() for the audit record of an AUD_AET_EXEC event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

565
566
567
568
569
570
571
572
573

Type
hhhhhhhhhhhhhhhhhhhhhhhhhhhhh

Description
hhhhhhhhhhhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING
AUD_TYPE_STRING_ARRAY

Pathname
Command-args(Records arg0...argn)
Env_args (Records envp)
Effective UID
Effective GID
Process capability state

AUD_PATHNAMEAUD_CMD_ARGSc

AUD_TYPE_STRING_ARRAY
AUD_TYPE_UID
AUD_TYPE_GID
AUD_TYPE_CAPc

AUD_ENVP
AUD_UID_ID
AUD_GID_ID
AUD_CAP574
575

This event is recorded for any of the functions exec(), execl(), execlp(), execv(),
execvp(), execle(), or execve().

576

The Pathname contains the value passed as an argument to the function.

577
578
579
580

An implementation may choose not to report the value of Command_args. If thisis the case, or the arrays pointed to by the argument contained any invalid
pointers, the aud_get_event_info() function shall return an aud_info_t with a zero
aud_info_length member.

581
582
583
584
585
586

For calls other than execle() and execve(), the aud_get_event_info() function may
return an aud_info_t with a zero aud_info_length member for Env_args. For execle() and execve() an implementation may choose not to report the value of
Env_args. If this is the case, or the arrays pointed to by the arguments contained
any invalid pointers, the aud_get_event_info() function shall return an aud_info_t
with a zero aud_info_length member.

587
588
589
590
591

The Effective UID and GID are those in effect after the call to exec(). The values
previous to the call to exec() are reportable in the record’s subject attributes. The
aud_info_length member of the aud_info_t reporting these values may be zero
length if the effective UID and GID of the process are the same before and after
the exec().

592
593
594
595
596
597
598

If {_POSIX_CAP} was in effect when the record was generated, then the processcapability state in the event-specific data shall record the state at the end of thecall, and if a process capability state is reported in the subject attributes in theaudit record, it shall be that at the start of the call. If {_POSIX_CAP} was not in
effect when the record was generated, the aud_get_event_info() function shallreturn an aud_info_t with a zero aud_info_length member for the process capability state.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

98c

24 Audit

c

c

c

c

599
600
601
602
603

If the call succeeded a set of object attributes shall also be available from therecord, describing the object executed. If the call failed due to access controls, anda set of object attributes is still available from the record, it shall describe theobject at which the failure occurred. Otherwise it is unspecified whether a set ofobject attributes is available, or what object is defined by such a set.

604

24.2.2.15 AUD_AET_EXIT

605
606
607

Calls on aud_get_event_info() for the audit record of an AUD_AET_EXIT event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

608
609
610

Type
hhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_INTExit code

AUD_EXIT_CODEc611

The Exit code contains the value passed as an argument to the _exit() function.

612

24.2.2.16 AUD_AET_FORK

613
614
615

Calls on aud_get_event_info() for the audit record of an AUD_AET_FORK event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

616
617
618

Type
hhhhhhhhhhhhhhhh
AUD_TYPE_PID

Descriptionhhhhhhhhhhhhh
Return value

item_idhhhhhhhhhhhhhhhhhhcc

AUD_RETURN_ID
c

619
620
621
622
623
624

The audit record shall be reportable on behalf of the parent, when the Return
value shall be the child’s process ID, thus the parent’s process ID is recorded in
the record header, and the child’s is the return value. A conforming implementation may also report a record for the child process; in this case the Return value
shall be zero. No events that are reported for the child shall be reported before
the parent’s AUD_AET_FORK record.

625

24.2.2.17 AUD_AET_INF_SET_FD

626
627

This event will be encountered only if {_POSIX_INF} was defined when the audit clog was generated.

628
629
630

Calls on aud_get_event_info() for the audit record of an AUD_AET_INF_SET_FD
event shall return aud_info_t structures for the following event-specific items,with aud_info_type members as specified:

631
632
633
634

Type
hhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhh
cc

AUD_TYPE_INT
AUD_TYPE_INF

File desc
Label

AUD_FILE_ID
AUD_INF_LBL
c
c

635
636

The File desc and Label contain the values passed as arguments to the
inf_set_fd() function.

637
638
639

If the call succeeded a set of object attributes shall also be available from therecord, describing the object affected; if an information label is reported in the setof object attributes it shall contain the information label before the event. If the
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

24.2 Audit Record Content

99

640
641
642
643

call failed due to access controls, and a set of object attributes is still available
from the record, it shall describe the object at which the failure occurred. Otherwise it is unspecified whether a set of object attributes is available, or what object
is defined by such a set.

644

24.2.2.18 AUD_AET_INF_SET_FILE

645
646

This event will be encountered only if {_POSIX_INF} was defined when the audit clog was generated.

647
648
649

Calls
on
aud_get_event_info()
for
the
audit
recordofan
AUD_AET_INF_SET_FILE event shall return aud_info_t structures for the following event-specific items, with aud_info_type members as specified:

650
651
652
653

Type
h hhhhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING
AUD_TYPE_INF

PathnameLabel

AUD_PATHNAME
AUD_INF_LBL
c

654
655

The Pathname and Label contain the values passed as arguments to the
inf_set_file() function.

656
657
658
659
660
661
662

If the call succeeded a set of object attributes shall also be available from therecord, describing the object affected; if an information label is reported in the setof object attributes it shall contain the information label before the event. If thecall failed due to access controls, and a set of object attributes is still available
from the record, it shall describe the object at which the failure occurred. Otherwise it is unspecified whether a set of object attributes is available, or what object
is defined by such a set.

663

24.2.2.19 AUD_AET_INF_SET_PROC

664
665

This event will be encountered only if {_POSIX_INF} was defined when the audit clog was generated.

666
667
668

Calls
on
aud_get_event_info()
for
the
audit
recordofan
AUD_AET_INF_SET_PROC event shall return aud_info_t structures for the following event-specific items, with aud_info_type members as specified:

669
670
671

Type
hhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhh
cc

AUD_TYPE_INF

Label

AUD_INF_LBL
c

672
673
674

The Label contains the value passed as an argument to the inf_set_proc() function. If an information label is reported in the record header it shall contain theprocess’s information label before the event.

675

24.2.2.20 AUD_AET_KILL

676
677
678

Calls on aud_get_event_info() for the audit record of an AUD_AET_KILL event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

100c

24 Audit

679
680
681
682

Type
hhhhhhhhhhhhhhhh

hDescription
hhhhhhhhhhhhh

item_idhhhhhhhhhh
cc

AUD_TYPE_PID
AUD_TYPE_INT

Pid
Signal Number

AUD_PID
AUD_SIG
c
c

683
684

The Pid and Signal Number shall record the values passed as arguments to thekill() function.

685
686
687
688
689

If the call succeeded, or if the call failed because of access control restrictions, setsof object attributes shall also be available from the record, one describing eachobject to which the signal was directed. In addition, following the content normally required from each set of object attributes, there shall also be available
from each an item:

690
691
692

Type
Description
item_id
iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
cc

AUD_TYPE_AUD_STATUS

c

693
694
695

recording whether the signal was successfully sent to that object. If the call failed
for reasons other than access control, it is not defined whether any sets of object
attributes are available.

696

24.2.2.21 AUD_AET_LINK

697
698
699

Calls on aud_get_event_info() for the audit record of an AUD_AET_LINK event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

700
701
702
703

The audit status of the event

AUD_STATUS

Type
h hhhhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING
AUD_TYPE_STRING

Path1
Path2

AUD_PATHNAMEAUD_LINKNAME
c
c

704
705
706

The Path1 and Path2 contain the values passed as arguments to the link() function. Path1 contains the pathname of the existing file, Path2 contains the pathname of the new directory entry to be created.

707
708
709
710
711
712

If the call succeeded a set of object attributes shall also be available from therecord, describing the file to which the link is made. If the call failed due toaccess controls, and a set of object attributes is still available from the record, it
shall describe the object at which the failure occurred. Otherwise it is unspecified
whether a set of object attributes is available, or what object is defined by such a
set.

713

24.2.2.22 AUD_AET_MAC_SET_FD

714
715

This event will be encountered only if {_POSIX_MAC} was defined when the auditc
log was generated.

716
717
718

Calls on aud_get_event_info() for the audit record of an AUD_AET_MAC_SET_FD
event shall return aud_info_t structures for the following event-specific items,with aud_info_type members as specified:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.2 Audit Record Content

101

719
720
721
722

Type
hhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhh
cc

AUD_TYPE_INT
AUD_TYPE_MAC

File desc
Label

AUD_FILE_ID
AUD_MAC_LBL
c
c

723
724

The File desc and Label contain the values passed as arguments to themac_set_fd() call.

725
726
727
728
729
730
731

If the call succeeded a set of object attributes shall also be available from therecord, describing the object affected; if a MAC label is reported in the set of object
attributes it shall contain the MAC label before the event. If the call failed due toaccess controls, and a set of object attributes is still available from the record, it
shall describe the object at which the failure occurred. Otherwise it is unspecified
whether a set of object attributes is available, or what object is defined by such a
set.

732

24.2.2.23 AUD_AET_MAC_SET_FILE

733
734

This event will be encountered only if {_POSIX_MAC} was defined when the auditc
log was generated.

735
736
737

Calls
on
aud_get_event_info()
for
the
audit
recordofan
AUD_AET_MAC_SET_FILE event shall return aud_info_t structures for the following event-specific items, with aud_info_type members as specified:

738
739
740
741

Type
h hhhhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING
AUD_TYPE_MAC

PathnameLabel

AUD_PATHNAME
AUD_MAC_LBL
c

742
743

The Pathname and Label contain the values passed as arguments to themac_set_file() call.

744
745
746
747
748
749
750

If the call succeeded a set of object attributes shall also be available from therecord, describing the object affected; if a MAC label is reported in the set of object
attributes it shall contain the MAC label before the event. If the call failed due toaccess controls, and a set of object attributes is still available from the record, it
shall describe the object at which the failure occurred. Otherwise it is unspecified
whether a set of object attributes is available, or what object is defined by such a
set.

751

24.2.2.24 AUD_AET_MAC_SET_PROC

752
753

This event will be encountered only if {_POSIX_MAC} was defined when the auditc
log was generated.

754
755
756

Calls
on
aud_get_event_info()
for
the
audit
recordofan
AUD_AET_MAC_SET_PROC event shall return aud_info_t structures for the following event-specific items, with aud_info_type members as specified:

757
758
759
760
761

Type
hhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhh
cc

AUD_TYPE_MAC

Label

AUD_MAC_LBL
c

The Label contains the value passed as an argument to the mac_set_proc() function. If a MAC label is reported in the record header it shall contain the process
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

102c

24 Audit

762

MAC label before the event.

763

24.2.2.25 AUD_AET_MKDIR

764
765
766

Calls on aud_get_event_info() for the audit record of an AUD_AET_MKDIR event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

767
768
769
770

Type
h hhhhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING
AUD_TYPE_MODE

Pathname
Mode

AUD_PATHNAME
AUD_MODE
c
c

771
772

The Pathname and Mode contain the values passed as arguments to the mkdir()function.

773
774
775
776
777

If the call succeeded a set of object attributes shall also be available from therecord, describing the object created. If the call failed due to access controls, anda set of object attributes is still available from the record, it shall describe theobject at which the failure occurred. Otherwise it is unspecified whether a set ofobject attributes is available, or what object is defined by such a set.

778

24.2.2.26 AUD_AET_MKFIFO

779
780
781

Calls on aud_get_event_info() for the audit record of an AUD_AET_MKFIFO
event shall return aud_info_t structures for the following event-specific items,with aud_info_type members as specified:

782
783
784
785

Type
h hhhhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING
AUD_TYPE_MODE

Pathname
Mode

AUD_PATHNAME
AUD_MODE
c
c

786
787

The Pathname and Mode contain the values passed as arguments to the mkfifo()
function.

788
789
790
791
792

If the call succeeded a set of object attributes shall also be available from therecord, describing the object created. If the call failed due to access controls, anda set of object attributes is still available from the record, it shall describe theobject at which the failure occurred. Otherwise it is unspecified whether a set ofobject attributes is available, or what object is defined by such a set.

793

24.2.2.27 AUD_AET_OPEN

794
795
796

Calls on aud_get_event_info() for the audit record of an AUD_AET_OPEN event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

797
798
799
800
801
802

Type
h hhhhhhhhhhhhhhhhhhh

Description
hhhhhhhhhhhhhhhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING
AUD_TYPE_INT
AUD_TYPE_MODE
AUD_TYPE_INT

Pathname
Oflag
Mode
Return value (file descriptor)

AUD_PATHNAMEAUD_OFLAG
AUD_MODEAUD_RETURN_ID
c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.2 Audit Record Content

103

c

c

c

803
804
805
806

The Pathname, Oflag and Mode contain the values passed as arguments to theopen() function. If the O_CREAT flag is not set in Oflag, the aud_get_event_info()
function shall return an aud_info_t with a zero aud_info_length field if an attempt
is made to read Mode.

807
808
809
810
811

If the call succeeded a set of object attributes shall also be available from therecord, describing the object opened. If the call failed due to access controls, and aset of object attributes is still available from the record, it shall describe the object
at which the failure occurred. Otherwise it is unspecified whether a set of object
attributes is available, or what object is defined by such a set.

812

24.2.2.28 AUD_AET_PIPE

813
814
815

Calls on aud_get_event_info() for the audit record of an AUD_AET_PIPE event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

816
817
818
819

Type
hhhhhhhhhhhhhhhh

Description
hhhhhhhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_INT
AUD_TYPE_INTRead file descriptor
Write file descriptor

AUD_RD_FILE_ID
AUD_WR_FILE_ID
c

820
821
822

If the call succeeded, the File descriptors shall contain the values returned to thecaller. Otherwise, the aud_get_event_info() function shall return aud_info_t
structures with zero aud_info_length members for these items.

823

24.2.2.29 AUD_AET_RENAME

824
825
826

Calls on aud_get_event_info() for the audit record of an AUD_AET_RENAME
event shall return aud_info_t structures for the following event-specific items,with aud_info_type members as specified:

827
828
829
830

Type
h hhhhhhhhhhhhhhhhhhh
AUD_TYPE_STRING
AUD_TYPE_STRING

hDescription
hhhhhhhhhhhhh
Old pathname
New pathname

item_idhhhhhhhhhhhhhhhhhhhhhhhh
AUD_OLD_PATHNAMEAUD_NEW_PATHNAME

831

The pathnames contain the values passed as arguments to the rename() call.

832
833
834
835
836
837
838

If the call succeeded a set of object attributes shall also be available from therecord, describing the object renamed; the name reported in the set of object attributes shall contain the name before the event. If the call failed due to access controls, and a set of object attributes is still available from the record, it shalldescribe the object at which the failure occurred. Otherwise it is unspecified
whether a set of object attributes is available, or what object is defined by such a
set.

839

24.2.2.30 AUD_AET_RMDIR

840
841
842

Calls on aud_get_event_info() for the audit record of an AUD_AET_RMDIR event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

104

24 Audit

c

c

cc

c

843
844
845

Type
h hhhhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING

Pathname

AUD_PATHNAME
c

846

The pathname contains the value passed as an argument to the rmdir() call.

847
848
849
850
851

If the call succeeded a set of object attributes shall also be available from therecord, describing the object removed. If the call failed due to access controls, anda set of object attributes is still available from the record, it shall describe theobject at which the failure occurred. Otherwise it is unspecified whether a set ofobject attributes is available, or what object is defined by such a set.

852

24.2.2.31 AUD_AET_SETGID

853
854
855

Calls on aud_get_event_info() for the audit record of an AUD_AET_SETGID event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

856
857
858

Type
hhhhhhhhhhhhhhhh
AUD_TYPE_GID

Descriptionhhhhhhhhhhhhh
gid

item_idhhhhhhhhhhcc

AUD_GIDc

859
860

The gid contains the value passed as an argument. The value before the call isreportable in the subject attributes.

861

24.2.2.32 AUD_AET_SETUID

862
863
864

Calls on aud_get_event_info() for the audit record of an AUD_AET_SETUID event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

865
866
867

Type
h hhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhh
cc

AUD_TYPE_UID

uid

AUD_UIDc

868
869

The uid contains the value passed as an argument. The value before the call isreportable in the subject attributes.

870

24.2.2.33 AUD_AET_UNLINK

871
872
873

Calls on aud_get_event_info() for the audit record of an AUD_AET_UNLINK
event shall return aud_info_t structures for the following event-specific items,with aud_info_type members as specified:

874
875
876

Type
h hhhhhhhhhhhhhhhhhhh

Descriptionhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING

Pathname

AUD_PATHNAME
c877

The Pathname contains the value passed as an argument to the unlink() function.

878
879
880
881
882

If the call succeeded a set of object attributes shall also be available from therecord, describing the object unlinked. If the call failed due to access controls,
and a set of object attributes is still available from the record, it shall describe theobject at which the failure occurred. Otherwise it is unspecified whether a set ofobject attributes is available, or what object is defined by such a set.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.2 Audit Record Content

105

883

24.2.2.34 AUD_AET_UTIME

884
885
886

Calls on aud_get_event_info() for the audit record of an AUD_AET_UTIME event
shall return aud_info_t structures for the following event-specific items, with
aud_info_type members as specified:

887
888
889
890
891

Type
h hhhhhhhhhhhhhhhhhhh

Description
hhhhhhhhhhhhhhhhh

item_idhhhhhhhhhhhhhhhhhh
cc

AUD_TYPE_STRING
AUD_TYPE_TIME
AUD_TYPE_TIME

Pathname
Access time
Modification time

AUD_PATHNAMEAUD_ATIME
AUD_MTIME
c

892
893
894

The Pathname contains the value passed as an argument to the utime() function.
The Access time and Modification time contain the values from the timebuf structure passed as an argument.

895
896
897
898
899

If the call succeeded a set of object attributes shall also be available from therecord, describing the object affected. If the call failed due to access controls, anda set of object attributes is still available from the record, it shall describe theobject at which the failure occurred. Otherwise it is unspecified whether a set ofobject attributes is available, or what object is defined by such a set.

900

24.3 Header

901
902
903
904

Some of the data types used by the audit functions are not defined as part of thisstandard, but shall be implementation-defined. If {_POSIX_AUD} is defined,
these types shall be defined in the header <sys/audit.h>, which contains
definitions for at least the types shown in the following table.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

106

24 Audit

c

c

c

905

Table 24-2 − Audit Data Types

906
907
910
908
909
913
911
912
917
914
915
916
920
918
919
923
921
922
926
924
925
929
927
928
932
930
931
935
933
934
938
936
937
940
939

Defined Type
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
aud_evinfo_t
aud_hdr_t
aud_id_t

aud_info_t
aud_obj_t
aud_obj_type_t
aud_rec_t
aud_state_t
aud_status_t
aud_subj_t
aud_time_tcUsed to access the set of event-specific data within an audit
record. This data type is non-exportable data.
Used to access the header of an audit record. This data type
is non-exportable data.
Item in an audit record header used to provide individual
accountability for the audit event. This data type is exportable data.
Defines the type, size and location of various items from anaudit record. This data type is non-exportable data.
Used to access an object attribute set within an audit record.
This data type is non-exportable data.
Item in an object attribute set that defines the type of theobject. This data type is exportable data.
A pointer to an opaque audit record. This data type is nonexportable data.
Controls whether system-generated records are auditable fora process. This data type is exportable data.
Item in an audit record header giving the success/failure
status of the audit event. This data type is exportable data.
Used to access the subject attribute set within an audit
record. This data type is non-exportable data.
The time of an audit event. This data type is exportable data.

941

Further details of these types are given below.

942

In addition, the header <sys/audit.h> shall define the following constants:

cc
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c
c

c

943
944

g

All the AUD_AET_∗ constants defined in section 24.2.2, for the POSIXdefined event types

945
946
947

g

All the constants defined in sections 24.2.2, 24.4.17, 24.4.19, 24.4.22, and24.4.24, (including AUD_FIRST_ITEM and AUD_NEXT_ITEM) for theitem_id arguments that can be supplied to the aud_get_∗_info() functions

948

g

The following miscellaneous constants:
Table 24-3 − Other Constants

949

c

950
951
952
953
954
955
956
957

Constant
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

958
959
960

The NNNN_N in AUD_STD_NNNN_N is merely a placeholder for the year c(e.g., 1997) this standard is approved and standard (e.g., _1 implying
POSIX.1) it is placed into.

AUD_SYSTEM_LOG
AUD_NATIVE
AUD_LAST_ITEM
AUD_STD_NNNN_Nof the version item in a record header.

Value of the filedes argument for aud_write().
Value of the format item in a record header.
Value of the position argument for the
aud_put_∗_info() functions.
Value

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.3 Header

107

961

Further constants are identified in the rest of this section.

962

24.3.1 aud_evinfo_t

963
964
965

This typedef shall define an opaque, implementation-defined descriptor for the setof event-specific data in an audit record. The internal structure of an
aud_evinfo_t is unspecified.

966

24.3.2 aud_hdr_t

967
968

This typedef shall define an opaque, implementation-defined descriptor for an
audit record header. The internal structure of an aud_hdr_t is unspecified.

969

24.3.3 aud_id_t

970
971

The aud_id_t obtainable from an audit record header is an implementationdefined typedef for holding a value which uniquely identifies a user.

972

24.3.4 aud_info_t

973
974
975

The aud_info_t structure defines the type, length and location of some data froman audit record. The aud_info_t structure shall contain at least the following
members:976

Table 24-4 − aud_info_t members

977
978
979
980
981

DefinedType
Name
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
int
aud_info_type
The type of the data
size_taud_info_length
The length of the data
void ∗
aud_info_p
Pointer to the data

982
983
984
985

The aud_info_type member may be used to interpret the data referenced by the
aud_info_p member. Values for aud_info_type shall be defined in the header<sys/audit.h>. At least the following values of aud_info_type shall be defined,
and shall have the specified interpretation:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

108

24 Audit986

Table 24-5 − Values for aud_info_type Member

987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011

Value
of aud_info_type
Interpretation of aud_info_piiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

1012
1013
1014
1015
1016

With the exception of AUD_TYPE_STRING and AUD_TYPE_OPAQUE,
aud_info_p should be interpreted as a pointer to zero or more items of the typespecified. In the case of AUD_TYPE_STRING, aud_info_p should interpreted asa (char ∗) value. For AUD_TYPE_OPAQUE aud_info_p is interpreted as apointer to zero or more bytes of opaque data.

1017
1018

A conforming implementation may define further values for aud_info_type, thatcan be treated in the same way as AUD_TYPE_OPAQUE.

1019
1020

In all cases, the aud_info_length member gives the length, in bytes, of the data towhich aud_info_p points.

1021

24.3.5 aud_obj_t

1022
1023
1024

This typedef shall define an opaque, implementation-defined descriptor for a setof object attributes in an audit record. The internal structure of an aud_obj_t isunspecified.

AUD_TYPE_ACL
AUD_TYPE_ACL_TYPE
AUD_TYPE_AUD_ID
AUD_TYPE_AUD_OBJ_TYPE
AUD_TYPE_AUD_STATEAUD_TYPE_AUD_STATUS
AUD_TYPE_AUD_TIME
AUD_TYPE_CAP
AUD_TYPE_CHAR
AUD_TYPE_GID
AUD_TYPE_INF
AUD_TYPE_INT
AUD_TYPE_LONG
AUD_TYPE_MAC
AUD_TYPE_MODE
AUD_TYPE_OPAQUE
AUD_TYPE_PID
AUD_TYPE_SHORTAUD_TYPE_STRING
AUD_TYPE_STRING_ARRAY
AUD_TYPE_TIME
AUD_TYPE_UID

acl_t∗
acl_type_t∗
aud_id_t∗
aud_obj_type_t∗
aud_state_t∗
aud_status_t∗
aud_time_t∗
cap_t∗
char∗
gid_t∗
inf_t∗
int∗
long∗
mac_t∗
mode_t∗void∗
pid_t∗
short∗
char∗, pointing to a null terminatedcharacter stringchar∗∗
time_t∗uid_t∗WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.3 Header

109

1025

24.3.6 aud_obj_type_t

1026
1027
1028
1029

The aud_obj_type_t obtainable from an object attribute set indicates the object
type. This data type shall support a unique value for each of the object types forwhich object attribute sets can be generated in the implementation. The implementation shall define in <sys/audit.h> at least the following unique values:

1030

Table 24-6 − aud_obj_type_t Values

1031
1032
1033
1034
1035
1036
1037
1038

DefinedType
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
AUD_OBJ_BLOCK_DEV
AUD_OBJ_CHAR_DEV
AUD_OBJ_DIR
AUD_OBJ_FIFO
AUD_OBJ_FILE
AUD_OBJ_PROC

Block device
Character device
Directory
FIFO object
Regular file
Process object

1039

24.3.7 aud_rec_t

1040
1041
1042
1043

This typedef shall define a pointer to an opaque data item capable of holding a
specific audit record, the format and storage of which are unspecified. Thus, anapplication cannot depend on performing normal byte-copy operations on the data
item to which an aud_rec_t points.

1044

24.3.8 aud_state_t

1045
1046
1047

An aud_state_t describes whether system events are being audited for a process.
An implementation shall define in <sys/audit.h> at least the following uniquevalues for this type:

1048

Table 24-7 − aud_state_t Values

1049
1050
1051
1052
1053

DefinedType
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
AUD_STATE_OFF
AUD_STATE_ON
AUD_STATE_QUERY

System events not audited
System events audited
Enquiry value for aud_switch()1054

24.3.9 aud_status_t

1055
1056
1057

The aud_status_t item obtainable from an audit record header indicates thestatus of the event. This data type shall define in <sys/audit.h> at least thefollowing unique values for this type:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

110

24 Audit1058

Table 24-8 − aud_status_t Values

1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069

Defined Type
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

1070
1071

The value AUD_PRIV_USED indicates that the operation succeeded, but would
not have done so if the process had not had appropriate privilege.
−

1072
1073
1074
1075

If the process fails a DAC or MAC access check, and does not have appropriate
privilege to override this check, and does not fail any other checks for appropriate
privilege, then the AUD_FAIL_DAC or AUD_FAIL_MAC status, respectively,
shall be reported in preference to the AUD_FAIL_PRIV one.

1076

A conforming implementation may add additional status values.

1077

24.3.10 aud_subj_t

1078
1079
1080

This typedef shall define an opaque, implementation-defined descriptor for the setof subject attributes in an audit record. The internal structure of an aud_subj_t isunspecified.

1081

24.3.11 aud_time_t

1082
1083

An aud_time_t structure specifies a single time value and shall include at least
the following members:

1084

Table 24-9 − aud_time_t Members

1085
1086
1087
1088

DefinedType
Name
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
time_tsec
Secondslongnsec
Nanoseconds

1089
1090
1091
1092

The nsec member specifies the subsecond portion of time; it is valid only if greaterthan or equal to zero, and less than the number of nanoseconds in a second (1000
million). A conforming implementation shall provide the subsecond portion oftime to a resolution of at least 20 milliseconds (1/50 of a second).

AUD_FAIL_PRIV
AUD_FAIL_DAC
AUD_FAIL_MAC
AUD_FAIL_OTHER
AUD_PRIV_USED
AUD_SUCCESSThe event failed because the process did not have appropriate
privilege (see below).
The event failed because of DAC access checks.
The event failed because of MAC access checks.
The event failed for some reason not included inother AUD_FAIL_∗ values.
The event completed successfully; appropriate privilege wasused (see below).
The event completed successfully.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.3 Header

111

c

1093

24.4 Functions

1094
1095
1096
1097
1098
1099

The functions in this section comprise the set of services that permit a process toconstruct, write, read and analyze audit records. Support for the audit facility
functions described in this section is optional. If the symbol {_POSIX_AUD} isdefined the implementation supports the audit option and all of the audit functions shall be implemented as described in this section. If {_POSIX_AUD} is notdefined, the result of calling any of these functions is unspecified.
c

1100
1101
1102

The error [ENOTSUP] shall be returned in those cases where the system supports
the audit facility but the particular audit operation cannot be applied because ofrestrictions imposed by the implementation.

1103

24.4.1 Copy an Audit Record From System to User Space

1104

Function: aud_copy_ext()

1105

24.4.1.1 Synopsis

1106#include <sys/audit.h>

1107
1108

ssize_t aud_copy_ext (void ∗aud_rec_ext_p,, aud_rec_t aud_rec_int,,
ssize_t size)
);

1109

24.4.1.2 Description

1110
1111
1112
1113

The aud_copy_ext() function shall copy an audit record, pointed to by aud_rec_int,
from system-managed space to user-managed space (pointed to by aud_rec_ext_p).
The size argument represents the size in bytes of the buffer pointed to by the
aud_rec_ext_p argument.

1114
1115
1116
1117
1118

The aud_copy_ext() function will do any conversions necessary to convert therecord from internal format. The audit record returned by aud_copy_ext() will bea contiguous, persistent data item. It is the responsibility of the user to allocate arecord buffer large enough to hold the copied record. The size of the buffer needed
can be obtained by a call to the aud_size() function.

1119

The aud_copy_ext() call shall not affect the record pointed to by aud_rec_int.

1120
1121

It is the responsibility of the user to release any space required to store the converted record.

1122

24.4.1.3 Returns

1123
1124
1125

Upon successful completion, the aud_copy_ext() function returns the size of theconverted record placed in aud_rec_ext_p. Otherwise, a value of ((ssize_t)−1) shallbe returned and errno shall be set to indicate the error.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

112

24 Audit

c
c
c

1126

24.4.1.4 Errors

1127
1128

If any of the following conditions occur, the aud_copy_ext() function shall return((ssize_t)−1) and set errno to the corresponding value:1129[EINVAL]

1130
1131
1132

The value for the aud_rec_int argument is invalid.
−

The size argument is zero or negative.
[ERANGE]

The size argument is greater than zero but smaller than thelength of the audit record.

1133

24.4.1.5 Cross-References1134

aud_copy_int(), 24.4.2; aud_size(), 24.4.38; aud_valid(), 24.4.40.

1135

24.4.2 Copy an Audit Record From User to System Space

1136

Function: aud_copy_int()

1137

24.4.2.1 Synopsis

1138#include <sys/audit.h>1139

aud_rec_t aud_copy_int (const void ∗aud_rec_ext_p)
);

1140

24.4.2.2 Description

1141
1142
1143
1144

The aud_copy_int() function shall copy an audit record, pointed to by
aud_rec_ext_p, from user-managed space to system-managed space. Upon successful completion, the function shall return an aud_rec_t pointing to the internal version of the audit record.

1145
1146

Once copied to system-managed space, the record can be manipulated by the
aud_get_∗() functions, and other functions that manipulate audit records.

1147
1148

The record pointed to by aud_rec_ext_p must have been obtained from a previous,
successful call to aud_copy_ext() for this function to work successfully.

1149
1150
1151

This function may cause memory to be allocated. The caller should free any
releasable memory, when the new record is no longer required, by calling
aud_free() with the (void∗)aud_rec_t as an argument.

1152

The aud_copy_int() call shall not affect the record pointed to by aud_rec_ext_p.

1153

24.4.2.3 Returns

1154
1155
1156
1157

Upon successful completion, the aud_copy_int() function returns an audit record
pointer set to point to the internal version of the audit record. Otherwise, a valueof (aud_rec_t)NULL shall be returned, the caller shall not have to free any releasable memory, and errno shall be set to indicate the error.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

113

1158

24.4.2.4 Errors

1159
1160

If any of the following conditions occur, the aud_copy_int() function shall return(aud_rec_t)NULL and set errno to the corresponding value:1161[EINVAL]

The value of the aud_rec_ext_p argument is invalid.

1162
1163

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −1164

24.4.2.5 Cross-References

1165
1166

aud_copy_ext(),
24.4.1;
aud_free(),
24.4.14;aud_get_event(),
aud_get_hdr(), 24.4.18; aud_get_obj(), 24.4.21; aud_get_subj(). 24.4.23.

1167

24.4.3 Delete Set of Event-specific Data from a Record

1168

Function: aud_delete_event()

1169

24.4.3.1 Synopsis

1170#include <sys/audit.h>1171

int aud_delete_event (aud_evinfo_t aud_event_d)
);

1172

24.4.3.2 Description

1173
1174
1175
1176
1177

The aud_delete_event() function deletes a set of event-specific data from an audit
record, including any data items within the set. The set to be deleted is definedby the aud_event_d descriptor. Upon successful execution, the set of event-specificdata shall no longer be accessible, and the aud_event_d descriptor shall become
undefined.

1178
1179

Calls to this function shall not affect the status of descriptors for any other set ofdata in this or any other audit record.

1180

24.4.3.3 Returns

1181
1182
1183

Upon successful completion, the aud_delete_event() function returns 0. Otherwise, it returns a value of −1 and errno is set to indicate the error. The audit
record shall not be changed if the return value is −1.

1184

24.4.3.4 Errors

1185
1186

If any of the following conditions occur, the aud_delete_event() function shallreturn -1 and set errno to the corresponding value:

1187
1188

[EINVAL]

24.4.16;

Argument aud_event_d is not a valid descriptor for a set of
event-specific data within an audit record.
−

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

114

24 Audit1189

24.4.3.5 Cross-References

1190
1191

aud_delete_event_info(), 24.4.4; aud_init_record(),24.4.28; aud_valid(), 24.4.40; aud_write(), 24.4.41.

1192

24.4.4 Delete Item from Set of Event-specific Data

1193

Function: aud_delete_event_info()1194

24.4.4.1 Synopsis

1195#include <sys/audit.h>

1196
1197

int aud_delete_event_info (aud_evinfo_t aud_event_d,,
int item_id)
);

1198

24.4.4.2 Description

1199
1200
1201
1202

The aud_delete_event_info() function deletes a data item from a set of eventspecific data in an audit record.
Upon successful execution of
aud_delete_event_info(), the item defined by item_id shall no longer be accessible
in the set of event-specific data defined by aud_event_d.

1203
1204
1205
1206
1207
1208
1209

The value of item_id specifies an item within the set of event-specific data. For
system-generated records, the items available are dependent upon the event typeof the audit record being examined; for each POSIX-defined event type theminimum set of items that shall be available, together with values of item_id toaccess them, are specified in section 24.2.2. For application-generated records,
the values of item_id match the calls on aud_put_event_info() that put the items
into the set of event-specific data.

1210
1211

Calls to this function shall not affect the status of descriptors for any other data
item in this or any other audit record.

1212

24.4.4.3 Returns

1213
1214
1215

Upon successful completion, the aud_delete_event_info() function returns 0. Otherwise, it returns a value of −1 and errno is set to indicate the error. The audit
record shall not be changed if the return value is −1.

1216

24.4.4.4 Errors

1217
1218

If any of the following conditions occur, the aud_delete_event_info() function shallreturn −1 and set errno to the corresponding value:

1219
1220

[EINVAL]

1221
1222

24.4.27;

aud_put_event (),Argument aud_event_d is not a valid descriptor for a set of
event-specific data within an audit record.
Argument item_id does not reference a valid data item within
aud_event_d.
−

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

115

1223

24.4.4.5 Cross-References

1224
1225

aud_delete_event(), 24.4.3; aud_init_record(), 24.4.27; aud_put_event (), 24.4.28;
aud_put_event_info(), 24.4.29; aud_valid(), 24.4.40; aud_write(), 24.4.41.

1226

24.4.5 Delete Header from an Audit Record

1227

Function: aud_delete_hdr()

1228

24.4.5.1 Synopsis

1229#include <sys/audit.h>1230

int aud_delete_hdr (aud_hdr_t aud_hdr_d)
);

1231

24.4.5.2 Description

1232
1233
1234
1235

The aud_delete_hdr() function deletes a header from an audit record, including
any data items within the header. The header to be deleted is defined by the
aud_hdr_d descriptor. Upon successful execution, the header shall no longer beaccessible in the record, and the aud_hdr_d descriptor shall become undefined.

1236
1237

Calls to this function shall not affect the status of descriptors for any other set ofdata in this or any other audit record.

1238

24.4.5.3 Returns

1239
1240
1241

Upon successful completion, the aud_delete_hdr() function returns 0. Otherwise,
it returns a value of −1 and errno is set to indicate the error. The audit record
shall not be changed if the return value is −1.

1242

24.4.5.4 Errors

1243
1244

If any of the following conditions occur, the aud_delete_hdr() function shall return-1 and set errno to the corresponding value:

1245
1246

[EINVAL]

Argument aud_hdr_d is not a valid descriptor for a header
within an audit record.
−

1247

24.4.5.5 Cross-References

1248
1249

aud_delete_hdr_info(), 24.4.6; aud_init_record(), 24.4.27; aud_put_hdr (), 24.4.30;
aud_valid(), 24.4.40; aud_write(), 24.4.41.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

116

24 Audit

1250

24.4.6 Delete Item from Audit Record Header

1251

Function: aud_delete_hdr_info()1252

24.4.6.1 Synopsis

1253#include <sys/audit.h>

1254
1255

int aud_delete_hdr_info (aud_hdr_t aud_hdr_d,,
int item_id)
);

1256

24.4.6.2 Description

1257
1258
1259

The aud_delete_hdr_info() function deletes a data item from a header in an audit
record. Upon successful execution of aud_delete_hdr_info(), the item defined by
item_id shall no longer be accessible in the header defined by aud_hdr_d.

1260
1261
1262
1263
1264

The value of item_id specifies an item within the audit record header. For records
read from an audit log, the minimum set of items that shall be available from thefirst header, together with values of item_id to access them, are specified in section 24.4.19. For application-generated records the values of item_id match thecalls on aud_put_hdr_info() that put the items into the header.

1265
1266

Calls to this function shall not affect the status of descriptors for any other data
item in this or any other audit record.

1267

24.4.6.3 Returns

1268
1269
1270

Upon successful completion, the aud_delete_hdr_info() function returns 0. Otherwise, it returns a value of −1 and errno is set to indicate the error. The audit
record shall not be changed if the return value is −1.

1271

24.4.6.4 Errors

1272
1273

If any of the following conditions occur, the aud_delete_hdr_info() function shallreturn −1 and set errno to the corresponding value:

1274
1275

[EINVAL]

1276
1277

Argument aud_hdr_d is not a valid descriptor for a header
within an audit record.
Argument item_id does not reference a valid data item within
aud_hdr_d.
−1278

24.4.6.5 Cross-References

1279
1280

aud_delete_hdr(), 24.4.5; aud_init_record(), 24.4.27; aud_put_hdr (), 24.4.30;
aud_put_hdr_info(), 24.4.31; aud_valid(), 24.4.40; aud_write(), 24.4.41.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

117

1281

24.4.7 Delete Set of Object Attributes from a Record

1282

Function: aud_delete_obj()

1283

24.4.7.1 Synopsis

1284#include <sys/audit.h>1285

int aud_delete_obj (aud_obj_t aud_obj_d)
);

1286

24.4.7.2 Description

1287
1288
1289
1290
1291

The aud_delete_obj() function deletes a set of object attributes from an audit
record, including any data items within the set. The set to be deleted is definedby the aud_obj_d descriptor. Upon successful execution, the set of object attributes shall no longer be accessible in the record, and the aud_obj_d descriptor
shall become undefined.

1292
1293

Calls to this function shall not affect the status of descriptors for any other set ofdata in this or any other audit record.

1294

24.4.7.3 Returns

1295
1296
1297

Upon successful completion, the aud_delete_obj() function returns 0. Otherwise,
it returns a value of −1 and errno is set to indicate the error. The audit record
shall not be changed if the return value is −1.

1298

24.4.7.4 Errors

1299
1300

If any of the following conditions occur, the aud_delete_obj() function shall return-1 and set errno to the corresponding value:

1301
1302

[EINVAL]

Argument aud_obj_d is not a valid descriptor for a set of object
attributes within an audit record.
−

1303

24.4.7.5 Cross-References

1304
1305

aud_delete_obj_info(), 24.4.8; aud_init_record(), 24.4.27; aud_put_obj (), 24.4.32;
aud_valid(), 24.4.40; aud_write(), 24.4.41.

1306

24.4.8 Delete Item from Set of Object Attributes

1307

Function: aud_delete_obj_info()1308

24.4.8.1 Synopsis

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

118

24 Audit1309#include <sys/audit.h>

1310
1311

int aud_delete_obj_info (aud_obj_t aud_obj_d,,
int item_id)
);

1312

24.4.8.2 Description

1313
1314
1315
1316

The aud_delete_obj_info() function deletes a data item from a set of object attributes in an audit record. Upon successful execution of aud_delete_obj_info(), theitem defined by item_id shall no longer be accessible in the set of object attributes
defined by aud_obj_d.

1317
1318
1319
1320
1321

The value of item_id specifies an item within the set of object attributes. For
system-generated records, the minimum set of items that shall be available,
together with values of item_id to access them, are specified in section 24.4.22.
For application-generated records, the values of item_id match the calls on
aud_put_obj_info() that put the items into the set of object attributes.

1322
1323

Calls to this function shall not affect the status of descriptors for any other data
item in this or any other audit record.

1324

24.4.8.3 Returns

1325
1326
1327

Upon successful completion, the aud_delete_obj_info() function returns 0. Otherwise, it returns a value of −1 and errno is set to indicate the error. The audit
record shall not be changed if the return value is −1.

1328

24.4.8.4 Errors

1329
1330

If any of the following conditions occur, the aud_delete_obj_info() function shallreturn −1 and set errno to the corresponding value:

1331
1332

[EINVAL]

1333
1334

Argument aud_obj_d is not a valid descriptor for a set of object
attributes within an audit record.
Argument item_id does not reference a valid data item within
aud_obj_d.
−

1335

24.4.8.5 Cross-References

1336
1337

aud_delete_obj(), 24.4.7; aud_init_record(), 24.4.27; aud_put_obj (), 24.4.32;
aud_put_obj_info(), 24.4.33; aud_valid(), 24.4.40; aud_write(), 24.4.41.

1338

24.4.9 Delete Set of Subject Attributes from a Record

1339

Function: aud_delete_subj()

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

119

1340

24.4.9.1 Synopsis

1341#include <sys/audit.h>1342

int aud_delete_subj (aud_subj_t aud_subj_d)
);

1343

24.4.9.2 Description

1344
1345
1346
1347
1348

The aud_delete_subj() function deletes a set of subject attributes from an audit
record, including any data items within the set. The set to be deleted is definedby the aud_subj_d descriptor. Upon successful execution, the set of subject attributes shall no longer be accessible in the record, and the aud_subj_d descriptor
shall become undefined.

1349
1350

Calls to this function shall not affect the status of descriptors for any other set ofdata in this or any other audit record.

1351

24.4.9.3 Returns

1352
1353
1354

Upon successful completion, the aud_delete_subj() function returns 0. Otherwise,
it returns a value of −1 and errno is set to indicate the error. The audit record
shall not be changed if the return value is −1.

1355

24.4.9.4 Errors

1356
1357

If any of the following conditions occur, the aud_delete_subj() function shallreturn -1 and set errno to the corresponding value:

1358
1359

[EINVAL]

Argument aud_subj_d is not a valid descriptor for a set of subject attributes within an audit record.
−

1360

24.4.9.5 Cross-References

1361
1362

aud_delete_subj_info(), 24.4.10; aud_init_record(),24.4.34; aud_valid(), 24.4.40; aud_write(), 24.4.41.

1363

24.4.10 Delete Item from Set of Subject Attributes

1364

Function: aud_delete_subj_info()1365

24.4.10.1 Synopsis

1366#include <sys/audit.h>

1367
1368

int aud_delete_subj_info (aud_subj_t aud_subj_d,,
int item_id));

24.4.27;

aud_put_subj (),WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

120

24 Audit

1369

24.4.10.2 Description

1370
1371
1372
1373

The aud_delete_subj_info() function deletes a data item from a set of subject attributes in an audit record. Upon successful execution of aud_delete_subj_info(), theitem defined by item_id shall no longer be accessible in the set of subject attributes defined by aud_subj_d.

1374
1375
1376
1377
1378

The value of item_id specifies an item within the set of subject attributes. For
system-generated records, the minimum set of items that shall be available,
together with values of item_id to access them, are specified in section 24.4.24.
For application-generated records, the values of item_id match the calls on
aud_put_subj_info() that put the items into the set of subject attributes.

1379
1380

Calls to this function shall not affect the status of descriptors for any other data
item in this or any other audit record.

1381

24.4.10.3 Returns

1382
1383
1384

Upon successful completion, the aud_delete_subj_info() function returns 0. Otherwise, it returns a value of −1 and errno is set to indicate the error. The audit
record shall not be changed if the return value is −1.

1385

24.4.10.4 Errors

1386
1387

If any of the following conditions occur, the aud_delete_subj_info() function shallreturn −1 and set errno to the corresponding value:

1388
1389

[EINVAL]

1390
1391

Argument aud_subj_d is not a valid descriptor for a set of subject attributes within an audit record.
Argument item_id does not reference a valid data item within
aud_subj_d.
−1392

24.4.10.5 Cross-References

1393
1394

aud_delete_subj(), 24.4.9; aud_init_record(), 24.4.27; aud_put_subj (), 24.4.34;
aud_put_subj_info(), 24.4.35; aud_valid(), 24.4.40; aud_write(), 24.4.41.

1395

24.4.11 Duplicate an Audit Record

1396

Function: aud_dup_record ()1397

24.4.11.1 Synopsis

1398#include <sys/audit.h>1399

aud_rec_t aud_dup_record (aud_rec_t ar));

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

121

1400

24.4.11.2 Description

1401
1402
1403
1404

The aud_dup_record () function creates a duplicate of the audit record pointed toby argument ar. The duplicate shall be independent of the original record; subsequent operations on either shall not affect the other. Upon successful execution,
the aud_dup_record () function returns a pointer to the duplicate record.

1405
1406

Any existing descriptors that refer to ar shall continue to refer to that record.
Calls to aud_dup_record () shall not affect the status of any existing records.

1407
1408
1409

This function may cause memory to be allocated. The caller should free any
releasable memory, when the new record is no longer required, by calling
aud_free() with the (void∗)aud_rec_t as an argument.

1410

24.4.11.3 Returns

1411
1412
1413
1414

Upon successful completion, the aud_dup_record () function returns an aud_rec_t
pointing to the new record. Otherwise, a value of (aud_rec_t)NULL shall be
returned, the caller shall not have to free any releasable memory, and errno is set
to indicate the error.

1415

24.4.11.4 Errors

1416
1417

If any of the following conditions occur, the aud_dup_record () function shallreturn (aud_rec_t)NULL and set errno to the corresponding value:1418[EINVAL]

Argument ar does not point to a valid audit record.

1419
1420

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −1421

24.4.11.5 Cross-References

1422
1423

aud_free(), 24.4.14; aud_init_record(), 24.4.27; aud_valid(), 24.4.40; aud_write(),24.4.41.

1424

24.4.12 Map Text to Event Type

1425

Function: aud_evid_from_text()

1426

24.4.12.1 Synopsis

1427#include <sys/audit.h>1428

int aud_evid_from_text(const char ∗text));

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

122

24 Audit1429

24.4.12.2 Description

1430
1431
1432

The aud_evid_from_text() function returns the audit event type of the system
audit event identified by the string pointed to by text. The means by which thisinformation is obtained is unspecified.

1433

24.4.12.3 Returns

1434
1435
1436

Upon successful completion, the aud_evid_from_text() function returns the event
type associated with text. On error, or if the requested entry is not found a valueof -1 is returned and errno is set to indicate the error.

1437

24.4.12.4 Errors

1438
1439

If any of the following conditions occur, the aud_evid_from_text() function shallreturn a value of -1 and set errno to the corresponding value:

1440
1441

[EINVAL]

The text argument does not identify a valid system audit event
type.
−

1442

24.4.12.5 Cross-References

1443
1444

aud_evid_to_text(), 24.4.13; aud_get_hdr_info(), 24.4.19; aud_put_hdr_info(),
24.4.31.

1445

24.4.13 Map Event Type to Text

1446

Function: aud_evid_to_text()

1447

24.4.13.1 Synopsis

1448#include <sys/audit.h>1449

char ∗aud_evid_to_text (int event_type,, ssize_t ∗aud_info_length)
);

1450

24.4.13.2 Description

1451
1452
1453
1454
1455

The aud_evid_to_text() function shall transform the system audit event_type intoa human-readable, null terminated character string identifying an event type.
The means by which this information is obtained is unspecified. The function
shall return the address of the string, and set the location pointed to by
aud_info_length to the length of the string (not including the null terminator).

1456
1457
1458

This function may cause memory to be allocated. The caller should free any
releasable memory when the string is no longer required, by calling the aud_free()function with the string address (cast to a (void∗)) as an argument.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

123

1459

24.4.13.3 Returns

1460
1461
1462
1463

Upon successful completion, the aud_evid_to_text() function returns a pointer to astring containing the event name associated with event_type. On error, or if therequested entry is not found, (char ∗)NULL is returned, the caller shall not haveto free any releasable memory, and errno is set to indicate the error.

1464

24.4.13.4 Errors

1465
1466

If any of the following conditions occur, the aud_evid_to_text() function shallreturn (char ∗)NULL and set errno to the corresponding value:

1467
1468

[EINVAL]

The event_type argument does not contain a valid system audit
event type.

1469
1470
1471

[ENOMEM] The string to be returned requires more memory than is allowedby the hardware or system-imposed memory management constraints.
−

1472

24.4.13.5 Cross-References

1473
1474

aud_evid_from_text(); 24.4.12. aud_get_hdr_info(), 24.4.19; aud_put_hdr_info(),
24.4.31.

1475

24.4.14 Release Memory Allocated to an Audit Data Object

1476

Function: aud_free()1477

24.4.14.1 Synopsis

1478#include <sys/audit.h>1479

int aud_free (void ∗obj_p)
);

1480

24.4.14.2 Description

1481
1482
1483
1484

The function aud_free() shall free any releasable memory currently allocated tothe item identified by obj_p. This may identify an audit record (i.e., be a(void∗)aud_rec_t) or a pointer to a string or event list allocated by one of the audit
functions.

1485
1486
1487
1488

If the item identified by obj_p is an aud_rec_t, the aud_rec_t and any existing
descriptors and aud_info_t items that refer to parts of the audit record shallbecome undefined. If it is a string (char∗), then use of the char∗ shall become
undefined.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

124

24 Audit1489

24.4.14.3 Returns

1490
1491
1492

Upon successful completion, the aud_free() function returns 0. Otherwise, avalue of −1 shall be returned and errno shall be set to indicate the error, and thememory shall not be freed.

1493

24.4.14.4 Errors

1494
1495

If any of the following conditions occur, the aud_free() function shall return −1
and set errno to the corresponding value:

1496
1497

[EINVAL]

The obj_p argument does not identify an audit record, string or
event list allocated by one of the audit functions.
−1498

24.4.14.5 Cross-References

1499
1500
1501
1502
1503
1504

aud_copy_int(), 24.4.2; aud_dup_record (), 24.4.11; aud_get_all_evid(), 24.4.15;
aud_get_event(), 24.4.16; aud_get_event_info(), 24.4.17; aud_get_hdr(), 24.4.18;
aud_get_hdr_info(), 24.4.19; aud_get_obj(), 24.4.21; aud_get_obj_info(), 24.4.22;
aud_get_subj(), 24.4.23; aud_get_subj_info(), 24.4.24; aud_id_to_text(), 24.4.26;
aud_init_record(), 24.4.27; aud_read(), 24.4.36; aud_rec_to_text(), 24.4.37;
aud_valid(), 24.4.40.

1505

24.4.15 Get All Audit Event Types

1506

Function: aud_get_all_evid()

1507

24.4.15.1 Synopsis

1508#include <sys/audit.h>1509

int ∗aud_get_all_evid (void)1510

24.4.15.2 Description

1511
1512
1513
1514
1515

The aud_get_all_evid() function returns the list of event types for systemgenerated events currently reportable on a conforming implementation. Each
event type is a non-negative integer; the list is terminated by a negative value.
The means by which this information is obtained is unspecified. These event
types can be converted into textual format by the aud_evid_to_text() function.

1516
1517
1518

This function may cause memory to be allocated. The caller should free any
releasable memory when the event list is no longer required, by calling the
aud_free() function with the event list address (cast to a void∗) as an argument.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

125

1519

24.4.15.3 Returns

1520
1521
1522
1523

Upon successful completion, the aud_get_all_evid() function returns a pointer to alist of the system-generated event types currently reportable on a conforming
implementation. Otherwise, (int ∗)NULL is returned, the caller shall not have tofree any releasable memory, and errno is set to indicate the error.

1524

24.4.15.4 Errors

1525
1526

If any of the following conditions occur, the aud_get_all_evid() function shallreturn (int ∗)NULL and set errno to the corresponding value:

1527
1528
1529

[ENOMEM] The event types to be returned require more memory than isallowed by the hardware or system-imposed memory management constraints.
−

1530

24.4.15.5 Cross-References1531

aud_free(), 24.4.14; aud_evid_from_text(), 24.4.12; aud_evid_to_text(), 24.4.13.

1532

24.4.16 Get Audit Record Event-specific Data Descriptor

1533

Function: aud_get_event()

1534

24.4.16.1 Synopsis

1535#include <sys/audit.h>

1536
1537
1538

int aud_get_event (aud_rec_t ar,,
int index,,
aud_evinfo_t ∗aud_event_p)
);

1539

24.4.16.2 Description

1540
1541
1542
1543
1544
1545
1546
1547
1548
1549

The aud_get_event() function returns a descriptor to a set of event-specific datafrom an audit record. The function accepts an audit record pointer ar returned
from a previously successful call to aud_read(), aud_init_record() or
aud_dup_record (). If aud_event_p is not NULL, then upon successful execution
the aud_get_event() function shall return a descriptor via aud_event_p for the setof event-specific data identified by index. The descriptor returned by this call canthen be used in subsequent calls on aud_get_event_info() to extract the data items
from the set of event-specific data from the audit record. If aud_event_p is NULL,
then the value of the index argument is ignored and the function just returns avalue as described below.

1550
1551
1552

Calls to aud_get_event() shall not affect the status of any other existing descriptors. Calls on the various aud_get_∗() functions can be interleaved without affecting each other.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

126

24 Audit

1553
1554
1555

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record is no longer required, by calling aud_free()with the (void∗)aud_rec_t as an argument.

1556
1557
1558
1559
1560

A descriptor for the first set of event-specific data in the record is obtained by supplying an index of 1. While the standard does not require more than one set of
event-specific data to be present in a record, an implementation or application
may add additional sets that can be read by supplying values of index that are
greater than 1.

1561

24.4.16.3 Returns

1562
1563

Upon successful completion, the aud_get_event() function returns a non-negativevalue. This value indicates the number of sets of event-specific data in the record.

1564
1565
1566
1567

In the event of failure the aud_get_event() function returns a value of −1, thecaller shall not have to free any releasable memory, and errno is set to indicate
the error. The aud_evinfo_t referenced by aud_event_p shall not be affected if the
return value is -1.

1568

24.4.16.4 Errors

1569
1570

If any of the following conditions occur, the aud_get_event() function shall return-1 and set errno to the corresponding value:

1571[EINVAL]

Argument ar does not point to a valid audit record.

1572
1573

Argument index does not identify a valid set of event-specificdata in the record.

1574
1575

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −1576

24.4.16.5 Cross-References

1577
1578

aud_free(), 24.4.14; aud_get_event_info(), 24.4.17; aud_put_event (), 24.4.28;
aud_read(), 24.4.36; aud_valid(), 24.4.40.

1579

24.4.17 Examine Audit Record Event-specific Data

1580

Function: aud_get_event_info()1581

24.4.17.1 Synopsis

1582#include <sys/audit.h>

1583
1584
1585

int aud_get_event_info (aud_evinfo_t aud_event_d,,
int item_id,,
aud_info_t ∗aud_event_info_p));

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

127

1586

24.4.17.2 Description

1587
1588
1589
1590
1591
1592
1593
1594

The aud_get_event_info() function returns a data item from within a set of eventspecific data. The set of event-specific data within an audit record to be examined
is identified by aud_event_d which was obtained from a previous successful call to
aud_get_event() or aud_put_event (). If aud_event_info_p is not NULL, then uponsuccessful execution the aud_get_event_info() function shall return via
aud_event_info_p an aud_info_t for the data identified by item_id. If
aud_event_info_p is NULL, then the value of the item_id argument is ignored, andthe function just returns a value as described in the Returns section below.

1595
1596
1597
1598
1599

The value of item_id may specify a named item within the set of event-specificdata, or may specify the ‘first’ item or the ‘next’ item. The named items available
are dependent upon the event type of the audit record being examined; for each
POSIX-defined event type the minimum set of items that shall be available,
together with values of item_id to access them, are specified in section 24.2.2.

1600
1601
1602
1603
1604
1605
1606
1607

If item_id is AUD_FIRST_ITEM, then this specifies the first item of event-specificdata in the set. A call of aud_get_event_info() with item_id set to
AUD_NEXT_ITEM shall return the item that follows the previous one read; for
POSIX-defined events, the required items are returned in the order they aredefined for each event type in section 24.2.2; implementations may report additional items after the required items. If AUD_NEXT_ITEM is used when there
has not been a previous successful call of this function for this set of event information, the effect is unspecified.

1608
1609

Any existing descriptors shall not be affected by use of this function. Calls on thevarious aud_get_∗() functions can be interleaved without affecting each other.

1610
1611
1612
1613

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record containing aud_event_d is no longer
required, by calling aud_free() with the aud_rec_t for the record (cast to a (void∗))
as an argument.

1614

24.4.17.3 Returns

1615
1616
1617

Upon successful completion, the aud_get_event_info() function returns a nonnegative value. This value indicates the number of items of event-specific data inthe set.

1618
1619
1620
1621

In the event of failure the aud_get_event_info() function returns a value of −1, thecaller shall not have to free any releasable memory, and errno is set to indicate
the error. The aud_info_t referenced by aud_event_info_p shall not be affected if
the return value is -1.

1622

24.4.17.4 Errors

1623
1624

If any of the following conditions occur, the aud_get_event_info() function shallreturn -1 and set errno to the corresponding value:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

128

24 Audit

1625
1626

[EINVAL]

Argument aud_event_d is not a valid descriptor for a set of
event-specific data within an audit record.

1627
1628

Argument item_id does not identify a valid item from the set of
event-specific data.

1629
1630

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −1631

24.4.17.5 Cross-References

1632
1633

aud_free(), 24.4.14; aud_get_event(), 24.4.16; aud_put_event_info(), 24.4.29;
aud_read(), 24.4.36; aud_valid(), 24.4.40.

1634

24.4.18 Get an Audit Record Header Descriptor

1635

Function: aud_get_hdr()

1636

24.4.18.1 Synopsis

1637#include <sys/audit.h>

1638
1639
1640

int aud_get_hdr (aud_rec_t ar,,
int index,,
aud_hdr_t ∗aud_hdr_p)
);

1641

24.4.18.2 Description

1642
1643
1644
1645
1646
1647
1648
1649
1650

The aud_get_hdr() function returns a descriptor to the header of an audit record.
The function accepts an audit record pointer ar returned from a previously successful call to aud_read(), aud_init_record() or aud_dup_record (). If aud_hdr_p
is not NULL, then upon successful execution the aud_get_hdr() function shallreturn a descriptor via aud_hdr_p for the header identified by index. The descriptor returned by this call can then be used in subsequent calls to
aud_get_hdr_info() to extract the data from the audit record header. If
aud_hdr_p is NULL, then the value of the index argument is ignored, and thefunction just returns a value as described below.

1651
1652
1653

Calls to aud_get_hdr() shall not affect the status of any other existing descriptors.
Calls on the various aud_get_∗() functions can be interleaved without affecting
each other.

1654
1655
1656

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record is no longer required, by calling aud_free()with the (void∗)aud_rec_t as an argument.

1657
1658
1659
1660

A descriptor for the first header in the record is obtained by supplying an index of
1. While the standard does not require more than one header to be present in arecord, an implementation or application may add additional headers that can beread by supplying values of index that are greater than 1.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

129

1661

24.4.18.3 Returns

1662
1663

Upon successful completion, the aud_get_hdr() function returns a non-negativevalue. This value indicates the number of headers in the record.

1664
1665
1666
1667

In the event of failure the aud_get_hdr() function returns a value of −1, the caller
shall not have to free any releasable memory, and errno is set to indicate theerror. The aud_hdr_t referenced by aud_hdr_p shall not be affected if the return
value is -1.

1668

24.4.18.4 Errors

1669
1670

If any of the following conditions occur, the aud_get_hdr() function shall return -1
and set errno to the corresponding value:

1671
1672
1673
1674

[EINVAL]

Argument ar does not point to a valid audit record.
Argument index does not identify a valid header in the record.

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −1675

24.4.18.5 Cross-References

1676
1677

aud_free(), 24.4.14; aud_get_hdr_info(),
aud_read(), 24.4.36; aud_valid(), 24.4.40.

1678

24.4.19 Examine an Audit Record Header

1679

Function: aud_get_hdr_info()1680

24.4.19.1 Synopsis

1681#include <sys/audit.h>

1682
1683
1684

int aud_get_hdr_info (aud_hdr_t aud_hdr_d,,
int item_id,,
aud_info_t ∗aud_hdr_info_p)
);

1685

24.4.19.2 Description

1686
1687
1688
1689
1690
1691
1692
1693

The aud_get_hdr_info() function returns a data item from within a header of anaudit record. The audit record header to be examined is identified by aud_hdr_dwhich was obtained from a previous successful call to aud_get_hdr() or
aud_put_hdr (). If aud_hdr_info_p is not NULL, then upon successful execution
the aud_get_hdr_info() function shall return via aud_hdr_info_p an aud_info_t for
the item of event-specific data identified by item_id. If aud_hdr_info_p is NULL,
then the value of the item_id argument is ignored, and the function just returns avalue as described in the Returns section below.

24.4.19;

aud_put_hdr (),24.4.30;WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

130

24 Audit

1694
1695

The value of item_id may specify a named item within the set of header data, or
may specify the ‘first’ item or the ‘next’ item.

1696
1697
1698
1699

The minimum set of named items to be available from the first header of an audit
record is specified in the table below, together with values of item_id to access theitems. If a record contains more than one header, the contents of the second andsubsequent headers is not specified by this standard.

1700

Table 24-10 − aud_hdr_info_p Values

1701
1702
1703
1704
1705
1706
1707
1708
1709
1710

Type
Description
item_idNotes
iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

1711

Notes on the table:

AUD_TYPE_SHORTAUD_TYPE_SHORTAUD_TYPE_AUD_ID
AUD_TYPE_INT or
AUD_TYPE_STRING
AUD_TYPE_AUD_TIME
AUD_TYPE_AUD_STATUS
AUD_TYPE_INT

The format of the audit record
The version number of the record
The audit ID of the process
The event type of the record

AUD_FORMAT
AUD_VERSIONAUD_AUD_ID
AUD_EVENT_TYPE

(1)
(2)
(3)
(4)

The time the event occurred
The audit status of the event
Value returned for event (errno)

AUD_TIMEAUD_STATUS
AUD_ERRNO

(5)

1712
1713

(1) Only one value is currently defined for the format item: AUD_NATIVE.
All data in any given record shall be in the same format.

1714
1715
1716
1717

(2) The version item provides a means of identifying the version of the
POSIX.1e audit option to which the audit record conforms. Conforming
applications can make use of the version to provide for backward compatibility or to ignore records which they are not prepared to handle.

1718
1719
1720
1721
1722
1723

Currently only one value for version is defined: AUD_STD_NNNN_N.
This identifies records which conform to the initial version of this standard. Further revisions of this standard may define additional values forthe header version. The NNNN_N is merely a placeholder for the year
(e.g., 1997) this standard is approved and standard (e.g., _1 implying
POSIX.1) it is placed into.

1724
1725
1726
1727

(3) If the record is not associated with any accountable user (e.g., it wasrecorded before a user had completed authentication), then the
aud_get_hdr_info() function shall return an aud_info_t with a zero
aud_info_length member.

1728
1729

(4) The event type is an integer if this is a system-generated event, or astring if it is an application-generated event.

1730
1731
1732
1733

(5) For system-generated events, the return value reported contains theerrno on return from the function audited; if the operation succeeded (asshown by the status), this value is undefined. For application-generated
records there may be no errno reported.

1734
1735
1736
1737

If item_id is AUD_FIRST_ITEM, then this specifies the first of the items of information from the header. A call of aud_get_hdr_info() with item_id set to
AUD_NEXT_ITEM shall return the item that follows the previous one read; for
the POSIX-defined header, the required items are returned in the order they are
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

24.4 Functions

131

c

c

1738
1739
1740

defined in the table above; implementations may report additional items after therequired items. If AUD_NEXT_ITEM is used when there has not been a previous
successful call of this function for this header, the effect is unspecified.

1741
1742
1743
1744

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record containing aud_hdr_d is no longer required,by calling aud_free() with the aud_rec_t for the record (cast to a (void∗)) as anargument.

1745
1746

Any existing descriptors shall not be affected by use of this function. Calls on thevarious aud_get_∗() functions can be interleaved without affecting each other.

1747

24.4.19.3 Returns

1748
1749
1750

Upon successful completion, the aud_get_hdr_info() function returns a nonnegative value. This value indicates the number of items of header information in
the set.

1751
1752
1753
1754

In the event of failure the aud_get_hdr_info() function returns a value of −1, thecaller shall not have to free any releasable memory, and errno is set to indicate
the error. The aud_info_t referenced by aud_hdr_info_p shall not be affected if
the return value is -1.

1755

24.4.19.4 Errors

1756
1757

If any of the following conditions occur, the aud_get_hdr_info() function shallreturn -1 and set errno to the corresponding value:

1758
1759

[EINVAL]

Argument aud_hdr_d is not a valid descriptor for an audit
record header within an audit record.

1760
1761

Argument item_id does not identify a valid item from theheader.

1762
1763[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −1764

24.4.19.5 Cross-References

1765
1766

aud_free(), 24.4.14; aud_get_hdr(), 24.4.18;
aud_read(), 24.4.36; aud_valid(), 24.4.40.

1767

24.4.20 Get a Process Audit ID

1768

Function: aud_get_id()

aud_put_hdr_info(),

24.4.31;

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

132

24 Audit1769

24.4.20.1 Synopsis

1770
1771

#include <sys/audit.h>#include <sys/types.h>

1772

aud_id_t aud_get_id (pid_t pid)
);

1773

24.4.20.2 Description

1774
1775

The aud_get_id() function returns the audit ID of the user who is accountable for
auditable actions of the existing process identified by pid.

1776

It is unspecified whether appropriate privilege is required to use this function.

1777

24.4.20.3 Returns

1778
1779
1780

Upon successful completion, the aud_get_id() function returns the audit ID of thenominated process. Otherwise, a value of ((aud_id_t)−1) is returned and errno is
set to indicate the error.

1781

24.4.20.4 Errors

1782
1783

If any of the following conditions occur, the aud_get_id() function shall return avalue of ((aud_id_t)−1) and set errno to the corresponding value:

1784[EINVAL]−

The value of the pid_t argument is invalid.

1785

24.4.20.5 Cross-References1786

aud_id_to_text(), 24.4.26; aud_put_hdr_info(), 24.4.31; aud_write(), 24.4.41.

1787

24.4.21 Get an Audit Record Object Descriptor

1788

Function: aud_get_obj()

1789

24.4.21.1 Synopsis

1790#include <sys/audit.h>

1791
1792
1793

int aud_get_obj (aud_rec_t ar,,
int index,,
aud_obj_t ∗aud_obj_p)
);

1794

24.4.21.2 Description

1795
1796
1797
1798
1799

The aud_get_obj() function returns a descriptor to a set of object attributes froman audit record. The function accepts an audit record pointer ar returned from apreviously successful call to aud_read(), aud_init_record() or aud_dup_record ().
If aud_obj_p is not NULL, then upon successful execution the aud_get_obj() function shall return a descriptor via aud_obj_p for the set of object data identified by
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

24.4 Functions

133

1800
1801
1802

index. The descriptor returned by this call can then be used in subsequent calls
to aud_get_obj_info() to extract the object data for that object. If aud_obj_p is
NULL, then the function just returns a value as described below.

1803
1804
1805

Calls to aud_get_obj() shall not affect the status of any other existing descriptors.
Calls on the various aud_get_∗() functions can be interleaved without affecting
each other.

1806
1807
1808

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record is no longer required, by calling aud_free()with the (void∗)aud_rec_t as an argument.

1809
1810
1811

A descriptor for the first set of object attributes in the record is obtained by supplying an index of 1. Any additional sets can be read by supplying values of index
that are greater than 1.

1812

24.4.21.3 Returns

1813
1814

Upon successful completion, the aud_get_obj() function returns a non-negativevalue. This value indicates the number of sets of object attributes in the record.

1815
1816
1817
1818

In the event of failure the aud_get_obj() function returns a value of −1, the caller
shall not have to free any releasable memory, and errno is set to indicate theerror. The aud_obj_t referenced by aud_obj_p shall not be affected if the return
value is -1.

1819

24.4.21.4 Errors

1820
1821

If any of the following conditions occur, the aud_get_obj() function shall return -1
and set errno to the corresponding value:

1822[EINVAL]

Argument ar does not point to a valid audit record.

1823
1824

Argument index does not identify a valid set of object attributes
in the record.

1825
1826

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −1827

24.4.21.5 Cross-References

1828
1829

aud_free(), 24.4.14; aud_get_obj_info(),
aud_read(), 24.4.36; aud_valid(), 24.4.40.

1830

24.4.22 Examine Audit Record Object Data

1831

Function: aud_get_obj_info()

24.4.22;

aud_put_obj (),24.4.32;

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

134

24 Audit1832

24.4.22.1 Synopsis

1833#include <sys/audit.h>

1834
1835
1836

int aud_get_obj_info (aud_obj_t aud_obj_d,,
int item_id,,
aud_info_t ∗aud_obj_info_p)
);

1837

24.4.22.2 Description

1838
1839
1840
1841
1842
1843
1844
1845
1846
1847

The aud_get_obj_info() function returns a data item from within a set of object
data. For system-generated events recording use of an interface that changes
object attributes, the attributes reported are those at the start of the event. The
set of object data to be examined is identified by aud_obj_d which was obtained
from a previous successful call to aud_get_obj() or aud_put_obj (). If
aud_obj_info_p is not NULL, then upon successful execution the
aud_get_obj_info() function shall return via aud_obj_info_p an aud_info_t for theobject attribute identified by item_id. If aud_obj_info_p is NULL, then the valueof the item_id argument is ignored, and the function just returns a value as
described in the Returns section below.

1848
1849

The value of item_id may specify a named item within the set of object data or
may specify the ‘first’ item or the ‘next’ item.

1850
1851
1852

The minimum set of named items that shall be available for system generated
events that are required to report object attributes is specified in the table below,
together with values of item_id to access them:

1853

Table 24-11 − aud_obj_info_p Values

1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864

Type
Description
item_id
Notes
iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

1865

Notes on the table:

AUD_TYPE_AUD_OBJ_TYPE
AUD_TYPE_UID
AUD_TYPE_GID
AUD_TYPE_MODE
AUD_TYPE_STRING
AUD_TYPE_ACL
AUD_TYPE_MAC
AUD_TYPE_INF
AUD_TYPE_CAP

The type of the object
The user ID of the object owner
The group ID of the object owner
The mode bits of the object
The name of the object
The ACL of the object
The MAC label of the object
The information label of the object
The capability set of the object

AUD_TYPE
AUD_UID
AUD_GID
AUD_MODEAUD_NAME
AUD_ACL
AUD_MAC_LBL
AUD_INF_LBL
AUD_CAP

1866(1) For a process object, the object owner is the effective UID of the process.

1867(2) For a process object, the object group is the effective GID of the process.

1868
1869

(3) For a process object, the aud_get_obj_info() function may return an
aud_info_t with a zero aud_info_length member for the mode bits.

1870
1871

(4) This item contains the name of the object, which shall provide sufficient
information to identify the object.

1872
1873

(5) This item contains an acl_t recording the ACL of the object at the start ofthe event. If {_POSIX_ACL} was not defined at that time, or the object
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

24.4 Functions

135

(1)
(2)
(3)
(4)
(5)
(6)
(7)

c

+

1874
1875

does not have a POSIX.1e conformant ACL, the aud_get_obj_info() function shall return an aud_info_t with a zero aud_info_length member.

1876
1877
1878
1879

(6) This item contains a mac_t recording the MAC label of the object at thestart of the event. If {_POSIX_MAC} was not defined at that time, theaud_get_obj_info() function shall return an aud_info_t with a zero
aud_info_length member.

1880
1881
1882
1883

(7) This item contains an inf_t recording the information label of the object
at the start of the event. If {_POSIX_INF} was not defined at that time, cthe aud_get_obj_info() function shall return an aud_info_t with a zero
aud_info_length member.
+

1884
1885
1886
1887
1888

(8) This item contains a cap_t recording the capability set of the object at the+start of the event. If {_POSIX_CAP} was not in effect at that time or if the+object does not have a POSIX.1e conformant capability set, the +aud_get_obj_info() function shall return an aud_info_t with a zero +aud_info_length member.

1889
1890
1891
1892
1893
1894
1895
1896

If item_id is AUD_FIRST_ITEM, this specifies the first of the items of informationfrom the set. A call of aud_get_obj_info() with item_id set to AUD_NEXT_ITEM
shall return the item that follows the previous one read; for system-generated
events that are required to report object attributes, the required items are
returned in the order they are defined in the table above; implementations mayreport additional items after the required items. If AUD_NEXT_ITEM is used
when there has not been a previous successful call of this function for this set ofobject attributes, the effect is unspecified.

1897
1898
1899

Only the object type and object owner items are required. The other specified
items are optional. If an item is not available, the function aud_get_obj_info()shall return a aud_info_t with a zero aud_info_length member.

1900
1901

Any existing descriptors shall not be affected by use of this function. Calls on thevarious aud_get_∗() functions can be interleaved without affecting each other.

1902
1903
1904
1905

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record containing aud_obj_d is no longer required,by calling aud_free() with the aud_rec_t for the record (cast to a (void∗)) as anargument.

1906

24.4.22.3 Returns

1907
1908
1909

Upon successful completion, the aud_get_obj_info() function returns a nonnegative value. This value indicates the number of items of object attributes inthe set.

1910
1911
1912
1913

In the event of failure the aud_get_obj_info() function returns a value of −1, thecaller shall not have to free any releasable memory, and errno is set to indicate
the error. The aud_info_t referenced by aud_obj_info_p shall not be affected if the
return value is -1.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

136

24 Auditc

1914

24.4.22.4 Errors

1915
1916
1917

If any of the following conditions occur, the aud_get_obj_info() function shallreturn -1 and set errno to the corresponding value: If any of the following conditions occur, this function will fail and set errno to one of the following values:

1918
1919

[EINVAL]

Argument aud_obj_d is not a valid descriptor for a set of object
attributes within an audit record.

1920
1921

Argument item_id does not identify a valid item from the set ofobject attributes.

1922
1923

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −1924

24.4.22.5 Cross-References

1925
1926

aud_free(), 24.4.14; aud_get_obj(), 24.4.21;
aud_read(), 24.4.36; aud_valid(), 24.4.40.

1927

24.4.23 Get an Audit Record Subject Descriptor

1928

Function: aud_get_subj()

1929

24.4.23.1 Synopsis

1930#include <sys/audit.h>

1931
1932
1933

int aud_get_subj (aud_rec_t ar,,
int index,,
aud_subj_t ∗aud_subj_p)
);

1934

24.4.23.2 Description

1935
1936
1937
1938
1939
1940
1941
1942
1943

The aud_get_subj() function returns a descriptor to a set of subject attributes
from an audit record. The function accepts an audit record pointer ar returned
from a previously successful call to aud_read(), aud_init_record() or
aud_dup_record (). If aud_subj_p is not NULL, then upon successful execution the
aud_get_subj() function shall return a descriptor via aud_subj_p for the set of
subject attributes identified by index. The descriptor returned by this call canthen be used in subsequent calls to aud_get_subj_info() to extract the attributes
for that process. If aud_subj_p is NULL, then the function just returns a value as
described below.

1944
1945
1946

Calls to aud_get_subj() shall not affect the status of any other existing descriptors. Calls on the various aud_get_∗() functions can be interleaved without affecting each other.

1947
1948
1949

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record is no longer required, by calling aud_free()with the (void∗)aud_rec_t as an argument.

aud_put_obj_info(),

24.4.33;

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

137

1950
1951
1952
1953
1954

A descriptor for the first set of subject attributes in the record is obtained by supplying an index of 1. While the standard does not require more than one set of
subject attributes to be present in a record, an implementation or application may
add additional sets that can be read by supplying values of index that are greaterthan 1.

1955

24.4.23.3 Returns

1956
1957

Upon successful completion, the aud_get_subj() function returns a non-negativevalue. This value indicates the number of sets of subject attributes in the record.

1958
1959
1960
1961

In the event of failure the aud_get_subj() function returns a value of −1, the caller
shall not have to free any releasable memory, and errno is set to indicate theerror. The aud_subj_t referenced by aud_subj_p shall not be affected if the return
value is -1.

1962

24.4.23.4 Errors

1963
1964

If any of the following conditions occur, the aud_get_subj() function shall return-1 and set errno to the corresponding value:

1965[EINVAL]

Argument ar does not point to a valid audit record.

1966
1967

Argument index does not identify a valid set of subject attributes
in the record.

1968
1969

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −1970

24.4.23.5 Cross-References

1971
1972

aud_free(), 24.4.14; aud_get_subj_info(),
aud_read(), 24.4.36; aud_valid(), 24.4.40.

1973

24.4.24 Examine Audit Record Subject Data

1974

Function: aud_get_subj_info()

1975

24.4.24.1 Synopsis

1976#include <sys/audit.h>

1977
1978
1979

int aud_get_subj_info (aud_subj_t aud_subj_d,,
int item_id,,
aud_info_t ∗aud_subj_info_p));24.4.24;

aud_put_subj ()24.4.34;

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

138

24 Audit1980

24.4.24.2 Description

1981
1982
1983
1984
1985
1986
1987
1988
1989
1990

The aud_get_subj_info() function returns a data item from within a set of subject
attributes in an audit record. For system-generated events recording use of aninterface that changes subject attributes, the attributes reported are those at thestart of the event. The set of attributes to be examined is identified by
aud_subj_d which was obtained from a previous successful call to aud_get_subj()
or aud_put_subj (). If aud_subj_info_p is not NULL, then upon successful execution the aud_get_subj_info() function shall return via aud_subj_info_p an
aud_info_t for the attribute identified by item_id. If aud_subj_info_p is NULL,
then the value of the item_id argument is ignored, and the function just returns avalue as described in the Returns section below.

1991
1992
1993
1994

The value of item_id may specify a named item within the set of subject attributes, or may specify the ‘first’ item or the ‘next’ item. The minimum set ofnamed items that shall be available from system-generated records is specified in
the table below, together with values of item_id to access them:

1995

Table 24-12 − aud_subj_info_p Values

1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006

Type
Description
item_id
Notes
iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
AUD_TYPE_PID
The process ID
AUD_PID
AUD_TYPE_UID
The effective user ID
AUD_EUID
AUD_TYPE_GID
The effective group ID
AUD_EGID
AUD_TYPE_GID
The supplementary group IDs AUD_SGIDS(1)
AUD_TYPE_UID
The real user ID
AUD_RUID
AUD_TYPE_GID
The real group ID
AUD_RGID
AUD_TYPE_MAC
The process MAC label
AUD_MAC_LBL(2)
AUD_TYPE_INF
The process information label
AUD_INF_LBL(3)
AUD_TYPE_CAP
The process capability state
AUD_CAP(4)

2007

Notes on the table:

2008
2009

(1) The number of supplementary groups can be calculated from the
aud_info_length member of the aud_info_t.

2010
2011

(2) If {_POSIX_MAC} was not defined at that time, the aud_get_subj_info()
function shall return an aud_info_t with a zero aud_info_length member.

2012
2013

(3) If {_POSIX_INF} was not defined at that time, the aud_get_subj_info()
function shall return an aud_info_t with a zero aud_info_length member.

2014
2015

(4) If {_POSIX_CAP} was not defined at that time, the aud_get_subj_info()
function shall return an aud_info_t with a zero aud_info_length member.

2016
2017
2018
2019
2020
2021
2022
2023

If item_id is AUD_FIRST_ITEM, then this specifies the first of the items from theset of subject attributes. A call of aud_get_subj_info() with item_id set to
AUD_NEXT_ITEM shall return the item that follows the previous one read; forsystem-generated records, the required items are returned in the order they aredefined in the table above; implementations may report additional items after therequired items. If AUD_NEXT_ITEM is used when there has not been a previous
successful call of this function for this set of subject attributes, the effect isunspecified.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

24.4 Functions

139

c

c

c

2024
2025
2026
2027
2028

For system-generated records, the first three items are required; the MAC label,information label and capability state are required if the relevant POSIX options
are in effect; the other specified items are optional. If an item is not available, thefunction aud_get_subj_info() shall return an aud_info_t with a zero
aud_info_length member.

2029
2030

Any existing descriptors shall not be affected by use of this function. Calls on thevarious aud_get_∗() functions can be interleaved without affecting each other.

2031
2032
2033
2034

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record containing aud_subj_d is no longer required,by calling aud_free() with the aud_rec_t for the record (cast to a (char∗)) as anargument.

2035

24.4.24.3 Returns

2036
2037
2038

Upon successful completion, the aud_get_subj_info() function returns a nonnegative value. This value indicates the number of items of subject attributes inthe set.

2039
2040
2041
2042

In the event of failure the aud_get_subj_info() function returns a value of −1, thecaller shall not have to free any releasable memory, and errno is set to indicate
the error. The aud_info_t referenced by aud_subj_info_p shall not be affected if
the return value is -1.

2043

24.4.24.4 Errors

2044
2045

If any of the following conditions occur, the aud_get_subj_info() function shallreturn −1 and set errno to the corresponding value:

2046
2047

[EINVAL]

Argument aud_subj_d is not a valid descriptor for a set of subject attributes within an audit record.

2048
2049

Argument item_id does not identify a valid item from the set of
subject attributes.

2050
2051

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −2052

24.4.24.5 Cross-References

2053
2054

aud_free(), 24.4.14; aud_get_subj(), 24.4.23;
aud_read(), 24.4.36; aud_valid(), 24.4.40.

aud_put_subj_info(),

24.4.35;

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

140

24 Audit

2055

24.4.25 Map Text to Audit ID

2056

Function: aud_id_from_text()

2057

24.4.25.1 Synopsis

2058#include <sys/audit.h>2059

aud_id_t aud_id_from_text

2060

24.4.25.2 Description

2061
2062
2063

The aud_id_from_text() function returns the audit ID identified by the string
pointed to by text_p. The means by which this information is obtained isunspecified.

2064

24.4.25.3 Returns

2065
2066
2067

Upon successful completion, the aud_id_from_text() function returns the audit ID
associated with text_p. On error, or if the requested entry is not found, a value of((aud_id_t)−1) is returned and errno is set to indicate the error.

2068

24.4.25.4 Errors

2069
2070

If any of the following conditions occur, the aud_id_from_text() function shallreturn a value of ((aud_id_t)−1) and set errno to the corresponding value:

2071[EINVAL](const char ∗text_p));−

The text_p argument does not identify a valid user.

2072

24.4.25.5 Cross-References

2073
2074

aud_get_hdr_info(),
24.4.31.

2075

24.4.26 Map Audit ID to Text

2076

Function: aud_id_to_text()

2077

24.4.26.1 Synopsis

2078#include <sys/audit.h>2079

char ∗aud_id_to_text (aud_id_t audit_ID,, ssize_t ∗len_p)
);

2080

24.4.26.2 Description

2081
2082
2083

The aud_id_to_text() function transforms the audit_ID into a human-readable,
null terminated character string. The means by which this information is
obtained is unspecified. Upon successful completion, the function shall return the

24.4.19;

aud_id_to_text(),

24.4.26;

aud_put_hdr_info(),

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

141

2084
2085

address of the string, and set the location pointed to by len_p to the length of thestring (not including the null terminator).

2086
2087
2088

This function may cause memory to be allocated. The caller should free any
releasable memory when the text form of audit_ID is no longer required, by calling aud_free() with the string address (cast to a (void∗)) as an argument.

2089

24.4.26.3 Returns

2090
2091
2092
2093
2094

Upon successful completion, the aud_id_to_text() function returns a pointer to astring identifying the user associated with audit_ID. On error, or if the requested
entry is not found, the caller shall not have to free any releasable memory,(char∗)NULL is returned, the location pointed to by len_p is not changed, anderrno is set to indicate the error.

2095

24.4.26.4 Errors

2096
2097

If any of the following conditions occur, the aud_id_to_text() function shall return(char ∗)NULL and set errno to the corresponding value:

2098[EINVAL]

The audit_ID argument does not contain a valid audit identifier.

2099
2100

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −2101

24.4.26.5 Cross-References

2102
2103

aud_free(), 24.4.14; aud_get_hdr_info(), 24.4.19; aud_id_from_text(), 24.4.25;
aud_put_hdr_info(), 24.4.31.

2104

24.4.27 Create a New Audit Record

2105

Function: aud_init_record()

2106

24.4.27.1 Synopsis

2107#include <sys/audit.h>2108

aud_rec_t aud_init_record (void);

2109

24.4.27.2 Description

2110
2111
2112

The aud_init_record() function returns a pointer to an audit record that is otherwise not in use. The record shall contain no headers or sets of subject, eventspecific, or object information.

2113
2114
2115
2116

Upon successful execution of the aud_init_record() function, the pointer returned
can be used in subsequent calls to the aud_put_∗() functions to add information to
the record, and in other functions that manipulate audit records, and the record
can be written to an audit log by a call of aud_write().
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

142

24 Audit2117

Calls to aud_init_record() shall not affect the status of any existing records.

2118
2119
2120

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record is no longer required, by calling aud_free()with the (void∗)aud_rec_t as an argument.

2121

24.4.27.3 Returns

2122
2123
2124
2125

Upon successful completion, the aud_init_record() function returns an aud_rec_t
pointing to the new record. Otherwise, a value of (aud_rec_t)NULL shall be
returned, the caller shall not have to free any releasable memory, and errno is set
to indicate the error.

2126

24.4.27.4 Errors

2127
2128

If any of the following conditions occur, the aud_init_record() function shallreturn (aud_rec_t)NULL and set errno to the corresponding value:

2129
2130

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −2131

24.4.27.5 Cross-References

2132
2133
2134

aud_dup_record (), 24.4.11; aud_free(), 24.4.14; aud_put_event (),aud_put_hdr (), 24.4.30; aud_put_obj (), 24.4.32; aud_put_subj (),aud_write(), 24.4.41.

2135

24.4.28 Add Set of Event-specific Data to Audit Record

2136

Function: aud_put_event ()2137

24.4.28.1 Synopsis

2138#include <sys/audit.h>

2139
2140
2141

int aud_put_event (aud_rec_t ar,,const aud_evinfo_t ∗next_p,,
aud_evinfo_t ∗new_p)
);

2142

24.4.28.2 Description

2143
2144
2145
2146
2147

The aud_put_event () function creates a new set of event-specific data, containing
no data items, in an audit record, and returns a descriptor to the set. The function accepts an audit record pointer ar, and puts the new set of event-specific datalogically before the existing set next_p in the record. If next_p is NULL, then the
new set shall be logically the last in the record.

2148
2149
2150

Upon successful execution the aud_put_event () function shall return via new_p a
descriptor for the new set of event-specific data. The descriptor returned by thiscall can then be used in subsequent calls to aud_put_event_info() to add data to

24.4.28;
24.4.34;

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

143

2151

this set of event-specific data in the audit record.

2152
2153
2154

Calls to aud_put_event () shall not affect the status of any existing descriptors forthis or any other audit record. Calls on the various aud_put_∗() functions can beinterleaved without affecting each other.

2155
2156
2157

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record is no longer required, by calling aud_free()with the (void∗)aud_rec_t as an argument.

2158

24.4.28.3 Returns

2159
2160
2161
2162

Upon successful completion, the aud_put_event () function returns 0. Otherwise, avalue of −1 shall be returned, the caller shall not have to free any releasable
memory, and errno is set to indicate the error. The audit record referenced by arshall not be affected if the return value is -1.

2163

24.4.28.4 Errors

2164
2165

If any of the following conditions occur, the aud_put_event () function shall return-1 and set errno to the corresponding value:

2166[EINVAL]

Argument ar does not point to a valid audit record.

2167
2168

Argument next_p is neither NULL nor does it indicate an existing set of event-specific data in record ar.

2169
2170

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −2171

24.4.28.5 Cross-References

2172
2173
2174

aud_free(), 24.4.14; aud_delete_event(), 24.4.3; aud_get_event(), 24.4.16;
aud_init_record(), 24.4.27; aud_put_event_info(), 24.4.29; aud_valid(), 24.4.40;
aud_write(), 24.4.41.

2175

24.4.29 Add Item to Set of Event-specific Data

2176

Function: aud_put_event_info()2177

24.4.29.1 Synopsis

2178#include <sys/audit.h>

2179
2180
2181
2182

int aud_put_event_info (aud_evinfo_t aud_event_d,,
int position,,
int item_id,,
const aud_info_t ∗aud_event_info_p));

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

144

24 Audit

2183

24.4.29.2 Description

2184
2185
2186
2187
2188
2189
2190
2191

The aud_put_event_info() function adds a data item to a set of event-specific data
within an audit record. The function accepts a descriptor for a set of eventspecific data aud_event_d in an audit record, and puts into the set of eventspecific data the item with type, size and address defined in the structure referenced by aud_event_info_p. The item shall subsequently be identifiable byitem_id in calls to functions as the record is manipulated, including after being
written to and read back from an audit log; no item identifiable by item_id shallalready exist in the set of event-specific information.

2192

The position argument shall specify either

2193
2194
2195

— the item_id of an item that already exists in the set of event-specific data;in this case the new data item shall be placed logically before the existing
item

2196
2197

— AUD_LAST_ITEM; in this case the new item shall be logically the last in
the set.

2198
2199
2200
2201

After the call of aud_put_event_info(), the caller can continue to manipulate thedata item indicated by the aud_info_t, and the aud_info_t itself, and changes tothem shall not affect the record unless they are used in a further call to
aud_put_∗_info().

2202
2203
2204

Calls to aud_put_event_info() shall not affect the status of any other existing
descriptors for this or any other audit record. Calls on the various
aud_put_∗_info() functions can be interleaved without affecting each other.

2205
2206
2207

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record is no longer required, by calling aud_free()with the (void∗)aud_rec_t as an argument.

2208

24.4.29.3 Returns

2209
2210
2211
2212

Upon successful completion, the aud_put_event_info() function returns 0. Otherwise, it returns a value of −1, the caller shall not have to free any releasable
memory, and errno is set to indicate the error. The set of event-specific data referenced by aud_event_d shall not be affected if the return value is -1.

2213

24.4.29.4 Errors

2214
2215

If any of the following conditions occur, the aud_put_event_info() function shallreturn -1 and set errno to the corresponding value:

2216
2217

[EINVAL]

Argument aud_event_d is not a valid descriptor for a set of
event-specific data within an audit record.

2218
2219

Argument position is not AUD_LAST_ITEM and does not identify a valid item from the set of event-specific data.

2220
2221

The value of the aud_info_type field of the structure referenced
by aud_event_info_p is invalid.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

24.4 Functions

145

2222
2223

An item with identifier item_id already exists in the set of
event-specific data.

2224
2225

The argument item_id is equal to AUD_FIRST_ITEM,
AUD_NEXT_ITEM, or AUD_LAST_ITEM.

2226
2227

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −2228

24.4.29.5 Cross-References

2229
2230

aud_delete_event_info(), 24.4.4; aud_free(), 24.4.14; aud_get_event_info(), 24.4.17;
aud_put_event (), 24.4.28; aud_valid(), 24.4.40; aud_write(), 24.4.41.

2231

24.4.30 Add Header to Audit Record

2232

Function: aud_put_hdr ()2233

24.4.30.1 Synopsis

2234#include <sys/audit.h>

2235
2236
2237

int aud_put_hdr (aud_rec_t ar,,const aud_hdr_t ∗next_p,,
aud_hdr_t ∗new_p)
);

2238

24.4.30.2 Description

2239
2240
2241
2242
2243

The aud_put_hdr () function creates a new header, containing no data items, in anaudit record, and returns a descriptor to the header. The function accepts anaudit record pointer ar, and puts the new header logically before the existingheader next_p in the record. If next_p is NULL, then the new header shall be logically the last in the record.

2244
2245
2246
2247

Upon successful execution the aud_put_hdr () function shall return via new_p a
descriptor for the new header. The descriptor returned by this call can then be
used in subsequent calls to aud_put_hdr_info() to add data to this header in theaudit record.

2248
2249
2250

Calls to aud_put_hdr () shall not affect the status of any existing descriptors forthis or any other audit record. Calls on the various aud_put_∗() functions can beinterleaved without affecting each other.

2251
2252
2253

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record is no longer required, by calling aud_free()with the (void∗)aud_rec_t as an argument.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

146

24 Audit

2254

24.4.30.3 Returns

2255
2256
2257
2258

Upon successful completion, the aud_put_hdr () function returns 0. Otherwise, avalue of −1 shall be returned, the caller shall not have to free any releasable
memory, and errno is set to indicate the error. The audit record referenced by arshall not be affected if the return value is -1.

2259

24.4.30.4 Errors

2260
2261

If any of the following conditions occur, the aud_put_hdr () function shall return -1
and set errno to the corresponding value:

2262[EINVAL]

Argument ar does not point to a valid audit record.

2263
2264

Argument next_p is neither NULL nor does it indicate an existing header in record ar.

2265
2266

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −2267

24.4.30.5 Cross-References

2268
2269
2270

aud_delete_hdr(),24.4.5;
aud_free(),
24.4.14;aud_get_hdr(),24.4.18;
aud_init_record(), 24.4.27; aud_put_hdr_info(), 24.4.31; aud_valid(), 24.4.40;
aud_write(), 24.4.41.

2271

24.4.31 Add Item to Audit Record Header

2272

Function: aud_put_hdr_info()2273

24.4.31.1 Synopsis

2274#include <sys/audit.h>

2275
2276
2277
2278

int aud_put_hdr_info (aud_hdr_t aud_hdr_d,,
int position,,
int item_id,,
const aud_info_t ∗aud_hdr_info_p)
);

2279

24.4.31.2 Description

2280
2281
2282
2283
2284
2285
2286

The aud_put_hdr_info() function adds a data item to a header within an audit
record. The function accepts a descriptor for a header aud_hdr_d in an audit
record, and puts into the header the item with type, size and address defined in
the structure referenced by aud_hdr_info_p. The item shall subsequently be
identifiable by item_id in calls to functions as the record is manipulated, including
after being written to and read back from an audit log; no item identifiable byitem_id shall already exist in the header.

2287

The position argument shall specify either

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

147

2288
2289

— the item_id of an item that already exists in the header; in this case thenew data item shall be placed logically before the existing item

2290
2291

— AUD_LAST_ITEM; in this case the new item shall be logically the last in
the header.

2292
2293
2294
2295

After the call of aud_put_hdr_info(), the caller can continue to manipulate thedata item indicated by the aud_info_t, and the aud_info_t, and changes to themshall not affect the record unless they are used in a further call to
aud_put_∗_info().

2296
2297
2298

Calls to aud_put_hdr_info() shall not affect the status of any other existing
descriptors for this or any other audit record. Calls on the various
aud_put_∗_info() functions can be interleaved without affecting each other.

2299
2300
2301

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record is no longer required, by calling aud_free()with the (void∗)aud_rec_t as an argument.

2302

24.4.31.3 Returns

2303
2304
2305
2306

Upon successful completion, the aud_put_hdr_info() function returns 0. Otherwise, it returns a value of −1, the caller shall not have to free any releasable
memory, and errno is set to indicate the error. The header referenced by
aud_hdr_d shall not be affected if the return value is -1.

2307

24.4.31.4 Errors

2308
2309

If any of the following conditions occur, the aud_put_hdr_info() function shallreturn -1 and set errno to the corresponding value:

2310
2311

[EINVAL]

Argument aud_hdr_d is not a valid descriptor for a header
within an audit record.

2312
2313

Argument position is not AUD_LAST_ITEM and does not identify a valid item from the header.

2314
2315

The value of the aud_info_type field of the structure referenced
by aud_hdr_info_p is invalid.

2316

An item with identifier item_id already exists in the header.

2317
2318

The argument item_id is equal to AUD_FIRST_ITEM,
AUD_NEXT_ITEM, or AUD_LAST_ITEM.

2319
2320

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −2321

24.4.31.5 Cross-References

2322
2323

aud_delete_hdr_info(), 24.4.6; aud_free(), 24.4.14; aud_get_hdr_info(), 24.4.20;
aud_put_hdr (), 24.4.30; aud_valid(), 24.4.40; aud_write(), 24.4.41.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

148

24 Audit

2324

24.4.32 Add Set of Object Attributes to Audit Record

2325

Function: aud_put_obj ()2326

24.4.32.1 Synopsis

2327#include <sys/audit.h>

2328
2329
2330

int aud_put_obj (aud_rec_t ar,,const aud_obj_t ∗next_p,,
aud_obj_t ∗new_p)
);

2331

24.4.32.2 Description

2332
2333
2334
2335
2336

The aud_put_obj () function creates a new set of object attributes, containing nodata items, in an audit record, and returns a descriptor to the set. The function
accepts an audit record pointer ar, and puts the new set of object attributes logically before the existing set next_p in the record. If next_p is NULL, then the new
set shall be logically the last in the record.

2337
2338
2339
2340

Upon successful execution the aud_put_obj () function shall return via new_p a
descriptor for the new set of object attributes. The descriptor returned by this call
can then be used in subsequent calls to aud_put_obj_info() to add data to this setof object attributes in the audit record.

2341
2342
2343

Calls to aud_put_obj () shall not affect the status of any existing descriptors forthis or any other audit record. Calls on the various aud_put_∗() functions can beinterleaved without affecting each other.

2344
2345
2346

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record is no longer required, by calling aud_free()with the (void∗)aud_rec_t as an argument.

2347

24.4.32.3 Returns

2348
2349
2350
2351

Upon successful completion, the aud_put_obj () function returns 0. Otherwise, avalue of −1 shall be returned, the caller shall not have to free any releasable
memory, and errno is set to indicate the error. The audit record referenced by arshall not be affected if the return value is -1.

2352

24.4.32.4 Errors

2353
2354

If any of the following conditions occur, the aud_put_obj () function shall return -1
and set errno to the corresponding value:

2355[EINVAL]

Argument ar does not point to a valid audit record.

2356
2357

Argument next_p is neither NULL nor does it indicate an existing set of object attributes in record ar.

2358
2359

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

24.4 Functions

149

2360

24.4.32.5 Cross-References

2361
2362
2363

aud_delete_obj(),
24.4.8;aud_free(),
24.4.14;aud_get_obj(),
24.4.21;
aud_init_record(), 24.4.27; aud_put_obj_info(), 24.4.33; aud_valid(), 24.4.40;
aud_write(), 24.4.41.

2364

24.4.33 Add Item to Set of Object Attributes

2365

Function: aud_put_obj_info()

2366

24.4.33.1 Synopsis

2367#include <sys/audit.h>

2368
2369
2370
2371

int aud_put_obj_info (aud_obj_t aud_obj_d,,
int position,,
int item_id,,
const aud_info_t ∗aud_obj_info_p)
);

2372

24.4.33.2 Description

2373
2374
2375
2376
2377
2378
2379
2380

The aud_put_obj_info() function adds a data item to a set of object attributes
within an audit record. The function accepts a descriptor for a set of object attributes aud_obj_d in an audit record, and puts into the set of object attributes theitem with type, size and address defined in the structure referenced by
aud_obj_info_p. The item shall subsequently be identifiable by item_id in calls tofunctions as the record is manipulated, including after being written to and readback from an audit log; no item identifiable by item_id shall already exist in theset of object attributes.

2381

The position argument shall specify either

2382
2383
2384

— the item_id of an item that already exists in the set of object attributes; inthis case the new data item shall be placed logically before the existing
item

2385
2386

— AUD_LAST_ITEM; in this case the new item shall be logically the last in
the set.

2387
2388
2389
2390

After the call of aud_put_obj_info(), the caller can continue to manipulate thedata item indicated by the aud_info_t, and the aud_info_t, and changes to themshall not affect the record unless they are used in a further call to
aud_put_∗_info().

2391
2392
2393

Calls to aud_put_obj_info() shall not affect the status of any other existing
descriptors for this or any other audit record. Calls on the various
aud_put_∗_info() functions can be interleaved without affecting each other.

2394
2395
2396

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record is no longer required, by calling aud_free()with the (void∗)aud_rec_t as an argument.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

150

24 Audit

2397

24.4.33.3 Returns

2398
2399
2400
2401

Upon successful completion, the aud_put_obj_info() function returns 0. Otherwise, it returns a value of −1, the caller shall not have to free any releasable
memory, and errno is set to indicate the error. The set of object attributes referenced by aud_obj_d shall not be affected if the return value is -1.

2402

24.4.33.4 Errors

2403
2404

If any of the following conditions occur, the aud_put_obj_info() function shallreturn -1 and set errno to the corresponding value:

2405
2406

[EINVAL]

Argument aud_obj_d is not a valid descriptor for a set of object
attributes within an audit record.

2407
2408

Argument position is not AUD_LAST_ITEM and does not identify a valid item from the set of object attributes.

2409
2410

The value of the aud_info_type field of the structure referenced
by aud_obj_info_p is invalid.

2411
2412

An item with identifier item_id already exists in the set of object
attributes.

2413
2414

The argument item_id is equal to AUD_FIRST_ITEM,
AUD_NEXT_ITEM, or AUD_LAST_ITEM.

2415
2416

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −2417

24.4.33.5 Cross-References

2418
2419

aud_delete_obj_info(), 24.4.8; aud_free(), 24.4.14; aud_get_obj_info(), 24.4.22;
aud_put_obj (), 24.4.32; aud_valid(), 24.4.40; aud_write(), 24.4.41.

2420

24.4.34 Add Set of Subject Attributes to Audit Record

2421

Function: aud_put_subj ()2422

24.4.34.1 Synopsis

2423#include <sys/audit.h>

2424
2425
2426

int aud_put_subj (aud_rec_t ar,,const aud_subj_t ∗next_p,,
aud_subj_t ∗new_p));

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

151

2427

24.4.34.2 Description

2428
2429
2430
2431
2432

The aud_put_subj () function creates a new set of subject attributes, containing nodata items, in an audit record, and returns a descriptor to the set. The function
accepts an audit record pointer ar, and puts the new set of subject attributes logically before the existing set next_p in the record. If next_p is NULL, then the new
set shall be logically the last in the record.

2433
2434
2435
2436

Upon successful execution the aud_put_subj () function shall return via new_p a
descriptor for the new set of subject attributes. The descriptor returned by thiscall can then be used in subsequent calls to aud_put_subj_info() to add data tothis set of subject attributes in the audit record.

2437
2438
2439

Calls to aud_put_subj () shall not affect the status of any existing descriptors forthis or any other audit record. Calls on the various aud_put_∗() functions can beinterleaved without affecting each other.

2440
2441
2442

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record is no longer required, by calling aud_free()with the (void∗)aud_rec_t as an argument.

2443

24.4.34.3 Returns

2444
2445
2446
2447

Upon successful completion, the aud_put_subj () function returns 0. Otherwise, avalue of −1 shall be returned, the caller shall not have to free any releasable
memory, and errno is set to indicate the error. The audit record referenced by arshall not be affected if the return value is -1.

2448

24.4.34.4 Errors

2449
2450

If any of the following conditions occur, the aud_put_subj () function shall return-1 and set errno to the corresponding value:

2451[EINVAL]

Argument ar does not point to a valid audit record.

2452
2453

Argument next_p is neither NULL nor does it indicate an existing set of subject attributes in record ar.

2454
2455

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −2456

24.4.34.5 Cross-References

2457
2458
2459

aud_delete_subj(), 24.4.9; aud_free(), 24.4.14; aud_get_subj(), 24.4.23;
aud_init_record(), 24.4.27; aud_put_subj_info(), 24.4.35; aud_valid(), 24.4.40;
aud_write(), 24.4.41.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

152

24 Audit

2460

24.4.35 Add Item to Set of Subject Attributes

2461

Function: aud_put_subj_info()2462

24.4.35.1 Synopsis

2463#include <sys/audit.h>

2464
2465
2466
2467

int aud_put_subj_info (aud_subj_t aud_subj_d,,
int position,,
int item_id,,
const aud_info_t ∗aud_subj_info_p)
);

2468

24.4.35.2 Description

2469
2470
2471
2472
2473
2474
2475
2476

The aud_put_subj_info() function adds a data item to a set of subject attributes
within an audit record. The function accepts a descriptor for a set of subject attributes aud_subj_d in an audit record, and puts into the set of subject attributes
the item with type, size and address defined in the structure referenced by
aud_subj_info_p. The item shall subsequently be identifiable by item_id in calls
to functions as the record is manipulated, including after being written to andread back from an audit log; no item identifiable by item_id shall already exist in
the set of subject attributes.

2477

The position argument shall specify either

2478
2479
2480

— the item_id of an item that already exists in the set of subject attributes; inthis case the new data item shall be placed logically before the existing
item

2481
2482

— AUD_LAST_ITEM; in this case the new item shall be logically the last in
the set.

2483
2484
2485
2486

After the call of aud_put_subj_info(), the caller can continue to manipulate thedata item indicated by the aud_info_t, and the aud_info_t, and changes to themshall not affect the record unless they are used in a further call to
aud_put_∗_info().

2487
2488
2489

Calls to aud_put_subj_info() shall not affect the status of any other existing
descriptors for this or any other audit record. Calls on the various
aud_put_∗_info() functions can be interleaved without affecting each other.

2490
2491
2492

This function may cause memory to be allocated. The caller should free any
releasable memory, when the record is no longer required, by calling aud_free()with the (void∗)aud_rec_t as an argument.

2493

24.4.35.3 Returns

2494
2495
2496
2497

Upon successful completion, the aud_put_subj_info() function returns 0. Otherwise, it returns a value of −1, the caller shall not have to free any releasable
memory, and errno is set to indicate the error. The set of subject attributes referenced by aud_subj_d shall not be affected if the return value is -1.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

24.4 Functions

153

2498

24.4.35.4 Errors

2499
2500

If any of the following conditions occur, the aud_put_subj_info() function shallreturn -1 and set errno to the corresponding value:

2501
2502

[EINVAL]

Argument aud_subj_d is not a valid descriptor for a set of subject attributes within an audit record.

2503
2504

Argument position is not AUD_LAST_ITEM and does not identify a valid item from the set of subject attributes.

2505
2506

The value of the aud_info_type field of the structure referenced
by aud_subj_info_p is invalid.

2507
2508

An item with identifier item_id already exists in the set of subject attributes.

2509
2510

The argument item_id is equal to AUD_FIRST_ITEM,
AUD_NEXT_ITEM, or AUD_LAST_ITEM.

2511
2512

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −2513

24.4.35.5 Cross-References

2514
2515

aud_delete_subj_info(), 24.4.10; aud_free(), 24.4.14; aud_get_subj_info(), 24.4.24;
aud_put_subj (), 24.4.34; aud_valid(), 24.4.40; aud_write(), 24.4.41.

2516

24.4.36 Read an Audit Record

2517

Function: aud_read()2518

24.4.36.1 Synopsis

2519#include <sys/audit.h>2520

aud_rec_t aud_read (int filedes)
);

2521

24.4.36.2 Description

2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532

This function attempts to read an audit record from the current file offset of thefile identified by filedes. If the function successfully reads an audit record, the fileoffset shall be incremented such that a further call of the function will operate on
the next audit record in the log. If the file contains records that were written to
the system audit log, it is left to the implementation to provide any sequencing
information required to ensure that successive calls of aud_read() each obtain the‘‘next’’ available record that was written to the log. If the file contains records
that were written to a file, the ordering of the records depends on the position of
the file offset at the time aud_write() was called. If no more records are in thefile, a value of zero is returned. In other cases, if a call is unsuccessful, the effectof further calls is unspecified.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

154

24 Audit

2533
2534
2535
2536

Upon successful completion, the function returns an audit record pointer,aud_rec_t, identifying the audit record. The format of the audit record isunspecified, but the aud_rec_t can be supplied as an input argument to functions
such as the aud_get_∗() functions .

2537
2538

Any existing audit record pointers that refer to records from the audit log shallcontinue to refer to those records.

2539
2540
2541
2542

This function may cause memory to be allocated. The caller should free any
releasable memory allocated by this function (and by other functions that areused to process the record), when the caller is finished with the record, by a call to
aud_free() with the (void∗)aud_rec_t as an argument.

2543
2544
2545
2546

If {_POSIX_INF} is defined, and {_POSIX_INF_PRESENT} is in effect for the file cdesignated by filedes, then the information label of the process shall automatically be set to an implementation-defined value which shall be the same as thevalue returned by inf_float(file information label, process information label).

2547

24.4.36.3 Returns

2548
2549
2550
2551
2552

Upon successful completion, the aud_read() function returns an aud_rec_t pointing to the record. If there are no more records in the audit log, the caller shall nothave to free any releasable memory, and the function returns a value of(aud_rec_t) 0. Otherwise, a value of (aud_rec_t) −1 is returned, the caller shall nothave to free any releasable memory, and errno is set to indicate the error.

2553

24.4.36.4 Errors

2554
2555

If any of the following conditions occur, the aud_read() function shall return avalue of −1 and set errno to the corresponding value:

2556
2557

[EAGAIN]The O_NONBLOCK flag is set for the file descriptor filedes andthe process would be delayed in the read operation.

2558
2559

[EBADF]The filedes argument is not a valid file descriptor open for reading.

2560
2561

[EINTR]

The operation was interrupted by a signal, and no data wastransferred.

2562
2563

[EINVAL]

The value of the filedes argument does not identify an audit log
positioned at a valid audit record.

2564
2565
2566

The header of the next record in the audit log identified by
filedes indicates the record has an AUD_FORMAT or
AUD_VERSION that is not supported by the implementation.

2567
2568

[ENOMEM] The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

155

2569

24.4.36.5 Cross-References

2570
2571

aud_free(),
24.4.14;aud_get_event(),
24.4.16;
aud_get_hdr(),24.4.18;
aud_get_obj(), 24.4.21; aud_get_subj(), 24.4.23; aud_rec_to_text(), 24.4.37.

2572

24.4.37 Convert an Audit Record to Text

2573

Function: aud_rec_to_text()

2574

24.4.37.1 Synopsis

2575#include <sys/audit.h>2576

char ∗aud_rec_to_text (aud_rec_t ar,, ssize_t ∗len_p)
);

2577

24.4.37.2 Description

2578
2579
2580
2581

The aud_rec_to_text() function transforms the audit record identified by ar into ahuman-readable, null terminated character string. The function shall return theaddress of the string and, if len_p is not NULL, set the location pointed to by len_p
to the length of the string (not including the null terminator).

2582
2583
2584
2585
2586
2587

The text string produced by aud_rec_to_text() shall contain a text form of the various sections of the audit record; the record header(s) shall be given first, followedby any set(s) of subject attributes, followed by any set(s) of event specific information, followed by any set(s) of object attributes. Items within each section shall begiven in the order they would be returned by the aud_get_∗() functions. Other
than this, the form of the text string is unspecified by this standard.

2588
2589
2590

This function may cause memory to be allocated. The caller should free any
releasable memory when the text form of the record is no longer required, by calling aud_free() with the string address (cast to a (void∗)) as an argument.

2591

24.4.37.3 Returns

2592
2593
2594

Upon successful completion, the aud_rec_to_text() function returns a pointer tothe text record. Otherwise, a value of NULL shall be returned, the caller shall nothave to free any releasable memory, and errno shall be set to indicate the error.

2595

24.4.37.4 Errors

2596
2597

If any of the following conditions occur, the aud_rec_to_text() function shall return
a value of NULL and set errno to the corresponding value:

2598
2599

[EINVAL]

The value of the ar argument does not identify a valid audit
record.

2600
2601
2602

[ENOMEM] The text to be returned requires more memory than is allowedby the hardware or system-imposed memory management constraints.
−
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

156

24 Audit

2603

24.4.37.5 Cross-References2604

aud_free(), 24.4.14; aud_read(), 24.4.36; aud_valid(), 24.4.40.

2605

24.4.38 Get the Size of an Audit Record

2606

Function: aud_size()

2607

24.4.38.1 Synopsis

2608#include <sys/audit.h>2609

ssize_t aud_size (aud_rec_t ar)
);

2610

24.4.38.2 Description

2611
2612
2613
2614
2615
2616

The aud_size() function returns the total length (in bytes) that the audit record
identified by ar would use when converted by aud_copy_ext(). The audit record ar
will have been obtained by a previous, successful call to the aud_read(),aud_init_record() or aud_dup_record () function. The aud_size() function is used
to ascertain the buffer size required to copy an audit record (via aud_copy_ext())
into user-allocated space.

2617

24.4.38.3 Returns

2618
2619

Upon successful completion, the aud_size() function returns the length of theaudit record.

2620
2621

In the event of failure the aud_size() function returns a value of −1 and errno is
set to indicate the error.

2622

24.4.38.4 Errors

2623
2624

If any of the following conditions occur, the aud_size() function shall return −1
and set errno to the corresponding value:

2625
2626

[EINVAL]

The value of the ar argument does not identify a valid audit
record.
−2627

24.4.38.5 Cross-References

2628
2629

aud_copy_ext(), 24.4.1; aud_dup_record (), 24.4.11; aud_init_record(), 24.4.27;
aud_read(), 24.4.36; aud_valid(), 24.4.40.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

157

2630

24.4.39 Control the Generation of Audit Records

2631

Function: aud_switch()2632

24.4.39.1 Synopsis

2633#include <sys/audit.h>2634

aud_state_t aud_switch (aud_state_t aud_state)
);

2635

24.4.39.2 Description

2636
2637
2638
2639
2640
2641
2642

The aud_switch() function requests that recording of system-generated audit
records for the current process be suspended (using AUD_STATE_OFF) or
resumed (using AUD_STATE_ON), or enquires about the current state (using
AUD_STATE_QUERY). A request to set the state is advisory and may be ignored
either wholly or partially if the auditing policy of the system prohibits the suspension of process auditing. A request to suspend auditing does not affect auditing
performed by the aud_write() function.

2643
2644

The current state of this switch is inherited by a child if the process calls thefork() function.

2645
2646

Appropriate privilege is required to use this function. If {_POSIX_CAP} is defined,cthen appropriate privilege is provided by the CAP_AUDIT_CONTROL capability.

2647

24.4.39.3 Returns

2648
2649
2650
2651

Upon successful completion, the aud_switch() function returns the value of theaudit state for the calling process at the start of the call. Otherwise, a value of((aud_state_t)−1) is returned and no change shall be made to the calling process’s
audit state.

2652

24.4.39.4 Errors

2653
2654

If any of the following conditions occur, the aud_switch() function shall return avalue of ((aud_state_t)−1) and set errno to the corresponding value:−

2655[EINVAL]

The value of the aud_state argument is invalid.

2656
2657

[EPERM]

The process does not have appropriate privileges to call thisfunction.

2658

24.4.39.5 Cross-References2659

aud_write(), 24.4.41.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

158

24 Audit2660

24.4.40 Validate an Audit Record

2661

Function: aud_valid()

2662

24.4.40.1 Synopsis

2663#include <sys/audit.h>2664

int aud_valid (aud_rec_t ar)
);

2665

24.4.40.2 Description

2666
2667

The aud_valid() function checks the audit record referred to by the argument arfor validity.

2668
2669
2670
2671

The audit record ar shall have been created by a previous call to
aud_init_record(), aud_copy_int() or aud_dup_record (), or shall have been readfrom an audit log by aud_read(). The record shall contain at least one header,
and the first or only header shall contain at least the following items:

2672
2673
2674

g

The event type for the event (identified by a item_id of
AUD_EVENT_TYPE_ID). The corresponding aud_info_t shall have its
aud_info_type member equal to AUD_TYPE_STRING or AUD_TYPE_INT.

2675
2676
2677

g

The audit status for the event (identified by a item_id of
AUD_STATUS_ID). The corresponding aud_info_t shall have its
aud_info_type member equal to AUD_TYPE_AUD_STATUS.

2678
2679

Calls to aud_valid() shall not affect the status of any existing descriptors for thisor any other audit record.

2680

24.4.40.3 Returns

2681
2682

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

2683

24.4.40.4 Errors

2684
2685

If any of the following conditions occur, the aud_valid() function shall return −1
and set errno to the corresponding value:

2686
2687

[EINVAL]

2688

Argument ar does not point to an aud_rec_t structure as recognized by the implementation.
−

One or more of the required entries is not present.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

159

2689

24.4.41 Write an Audit Record

2690

Function: aud_write()

2691

24.4.41.1 Synopsis

2692#include <sys/audit.h>2693

int aud_write (int filedes,, aud_rec_t ar)
);

2694

24.4.41.2 Description

2695
2696
2697
2698
2699
2700

The aud_write() function writes an application-specific audit record to an audit
log. Upon successful completion the audit record identified by aud_rec_t shall be
written into the audit log file identified by filedes; if filedes is equal to
AUD_SYSTEM_LOG then the record shall be written to the system audit log. If
filedes is not equal to AUD_SYSTEM_LOG then the record shall be written at theposition in the file defined for the POSIX write() interface.

2701
2702
2703
2704

The record ar shall be a valid audit record, as defined by the aud_valid() function.
The aud_write() call shall not alter the record ar; after the call of aud_write(), thecaller can continue to manipulate the record, and changes to it shall not affect therecord reportable from this call of aud_write().

2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715

If the first or only header in the record does not contain an item with item_id set
to AUD_TIME_ID, then the time reported by a later call on aud_get_hdr_info()
for the AUD_TIME_ID field of this header shall be the time at which the
aud_write() function was executed. If the header does not contain items with
item_ids set to AUD_FORMAT_ID and AUD_VERSION_ID, then the values ofthese fields reported for this record shall be the same as those that would bereported for records generated by the system at the time the aud_write() function
was called. If the header does not contain an item with item_id set to
AUD_AUD_ID, then the audit ID reported by a later call on aud_get_hdr_info()
for the AUD_AUD_ID field of this header shall be the audit ID of the user
accountable for the current process.

2716
2717
2718
2719
2720
2721
2722
2723
2724
2725

The application may include in the record one or more sets of subject attributes. If
the application is auditing an action performed on behalf of a client process, thefirst set of subject attributes should describe the client, and the header should
include the client’s audit ID in an item with item_id set to AUD_AUD_ID and
aud_info_type field AUD_TYPE_AUD_ID. If the application is writing a recordthat was read from another log, the record will already contain one or more sets ofsubject attributes. If the record does not contain any sets of subject attributes,
then later calls to aud_get_subj() and aud_get_subj_info() for this record shallreport one set of subject attributes, containing details of the process that invoked
aud_write().

2726
2727
2728
2729

If the record has been constructed by the application, later reading of the record
using aud_read(), aud_get_∗() and the aud_get_∗_info() functions shall report theitems from the record ar in the logical order specified by the aud_put_∗() and
aud_put_∗_info() calls used to construct the record. The content of the record,
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

160

24 Audit

2730
2731

reported by calls to the aud_read(), aud_get_∗() and the aud_get_∗_info() functions, shall be the content at the time aud_write() was invoked.

2732
2733
2734
2735

If {_POSIX_INF} is defined, and {_POSIX_INF_PRESENT} is in effect for the log cdesignated by filedes, then the information label of the log shall automatically be
set to an implementation-defined value which should be the same as the value
returned by inf_float(process information label, log information label).

2736
2737
2738

Appropriate privilege is required to use aud_write() to write to the system audit
log. If {_POSIX_CAP} is defined then appropriate privilege is provided by the
CAP_AUDIT_WRITE capability.

2739

24.4.41.3 Returns

2740
2741
2742
2743

Upon successful completion, the aud_write() function returns a value of 0 and thespecified record is written to the specified audit log. Otherwise, a value of −1 isreturned and errno is set to indicate the error, and the specified record is not written to the specified audit log.

2744

24.4.41.4 Errors

2745
2746

If any of the following conditions occur, the aud_write() function shall return −1
and set errno to the corresponding value:

2747
2748

[EBADF]The value of the filedes argument is not a valid file descriptor
open for writing and is not AUD_SYSTEM_LOG.

2749
2750

[EINTR]

The operation was interrupted by a signal, and no data wastransferred.

2751
2752

[EINVAL]

The value of the ar argument does not identify a valid audit
record.

2753
2754
2755
2756

The audit record identified by ar does not contain the required
header data.
−[EPERM]

The process does not have appropriate privilege to perform therequested operation.

2757

24.4.41.5 Cross-References

2758
2759

aud_dup_record (), 24.4.11; aud_get_id(), 24.4.20; aud_init_record(), 24.4.27;
aud_read(), 24.4.36; aud_switch(), 24.4.39; aud_valid(), 24.4.40.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
24.4 Functions

161cSection 25: Capabilities12

25.1 General Overview

3
4
5
6
7
8
9
10

This section defines a set of portable interfaces that permit one or more capabilities to be associated with a process or file, for the capabilities associated with aprocess to be enabled or disabled, and for a set of these capabilities to be passed
on to the next program associated with a process. This specification also
identifies a minimum set of capabilities required for the support of portablesecurity-relevant programs, and specifies the circumstances in POSIX.1 underwhich these capabilities shall be used. Support for the interfaces defined in thissection is optional, but shall be provided if the symbol {_POSIX_CAP} is defined. c

11
12
13
14

POSIX.1 specifies that certain actions require a process to possess appropriate
privilege in order to complete those actions. This section specifies the names of
the capabilities which constitute appropriate privilege to perform those actions onc
a system that supports the POSIX Capability Option.
c

15
16
17
18
19
20

This section describes a set of interfaces by which capabilities may be associatedwith a process and the method by which a process’s capabilities are derived.
Specific capabilities of a process that exec’s a particular file may be revoked,
inherited from the previous process image, or granted to the process, dependingon the value(s) of the file capability state of the file and the process capability
state of the previous process image.

21
22
23
24
25
26
27
28
29
30
31

The set of interfaces defined by this standard provide the means to support the
principle of least privilege. Note, however, it does not require that a conforming
implementation actually enforce a least privilege (least capability) security policy.
The capability related interfaces and semantics specified in this standard permit
individual capabilities to be defined down to a per-function level and permit them
to be granted or denied to the granularity of an individual process image. They
also permit a process image to control the effectiveness of the capabilities
assigned to it during its execution. These capabilities are necessary, but not
sufficient, for the implementation of a least privilege security policy. Implementa-−
tions may extend the capability interfaces such that use of and/or access to capabilities by programs are further constrained.

32
33
34

This section also defines a minimal number of capabilities that shall be supported
by conforming implementations. Implementations may define additional capabilities that affect the behavior of POSIX defined and/or other system functions.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.1 General Overview

163

c
c

c

c

35

25.1.1 Major Features36

25.1.1.1 Task Bounding of Capability

37
38
39
40
41

Another major characteristic of the capability interfaces is that capabilities may
be bounded in the extent of code they are effective over. That is, they can be
enabled for only as long as they are actually needed to perform a task (or tasks),
and then disabled. The extent of code that could exercise a particular capability
can be bounded both at the program level and within a particular program.

42
43
44
45
46
47
48

At the program level, a process may be assigned or denied specific capabilities by
setting the capability flags and attributes associated with the program file. Whenthe file is executed, these flags and attributes are examined by exec(). The exec()
function then modifies the capability state of the process in a specific manneraccording to those flags and attributes. In this way, a process may gain additional
capabilities by executing certain programs, or it may lose capabilities it currently
possesses.

49
50
51
52
53
54
55

Within itself, a process image may enable, disable, or permanently revoke its
capabilities. For example, a process modifies the effective flag of a given capabilityc
to either enable or disable that capability. This flag shall be set in order for thecapability to be available for use. A process image permanently, i.e., for the duration of that process image, revokes a given capability by resetting both the effec- ctive and permitted flags for that capability. More information on these two flags c
is provided in section 25.1.1.4 below.
c56

25.1.1.2 Capability Inheritance

57
58
59
60
61

Following the exec() of a program, the capabilities that have their permitted flags c
set in the new process image depend on the capability states of both the previous
process image and the exec’d program file. Each capability marked as permitted c
may have been forced to be set by the program file or inherited from the previous
image (if the capability attributes of the program file allow the inheritance).

62
63
64
65
66
67

Inheritance permits a process image to request that all, some or none of its capabilities be passed to the next process image, subject to restrictions set by the system security policy. For example, a backup program may exec() the pax utility,
granting it the capabilities required to read all files in a file system (providing it
is allowed to inherit those capabilities). However, the same backup utility may
exec() other utilities to which it does not pass any capabilities.

68

25.1.1.3 Capability Flags

69
70
71
72
73
74

The capability flags defined by this standard are permitted, effective, and inherit- cable. These flags apply to each capability separately, and together their values
determine a capability state. Capability states shall be assignable to at least two
entities: processes and files. Implementations may define additional flags forcapabilities and may provide for the assignment of capability states to additional
entities.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

164

25 Capabilities

75

25.1.1.4 Capability Flags and Processes

76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

The capability state is the attribute of a process which contains the value of all of
the process’s capability flags. A conforming implementation shall support the cassignment of a capability state to processes. When the process permitted flag forc
a capability is set, a process shall be able to set all its flags defined by this standard for that capability. A process shall be able to clear any flag for any of its
capabilities regardless of the state of the permitted flags. A process can exercise ac
particular capability only when that capability’s process effective flag is set. The cprocess effective flag shall be the only flag considered by system functions when cdetermining if the process possesses appropriate privilege. The process inherit- cable flag is used by the exec() function when determining the capability flags ofthe new process image. A capability may be passed from one process image to thenext through an exec() only if the inheritable flag of that capability is set. This cinheritance may or may not actually occur, depending on the capability state of
the file as described in the next section. The new process image may also acquirecapabilities based upon the capability state of the file used to create the new process image, as defined in section 3.1.2.2.

92

25.1.1.5 Capability Flags and Files

93
94
95
96
97
98

The capability state is the attribute of a file which contains the value of all of the
file’s capability flags. A conforming implementation shall support the assignmentof capability states to files. The purpose of assigning capability states to files is toprovide the exec() function with information regarding the capabilities that any
process image created with the program in the file is capable of dealing with andhave been granted by some authority to use.

99
100

If pathconf() indicates that {_POSIX_CAP_PRESENT} is not in effect for a file,then the capability state of that file shall be implementation-defined.
c101

25.1.1.6 File System Support of Capability

102
103
104

The capability state of a process after an exec() of a file for which the value of the −pathname variable {_POSIX_CAP_PRESENT} is zero shall be implementation- cdefined.

105

25.1.1.7 Application

106
107

The POSIX.1 functions listed in Table 25-1 are affected by the capability functionality defined in this standard.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.1 General Overview

165

108

Table 25-1 − POSIX.1 Functions Covered by Capability Policies

109
110
111

Existing
POSIX.1
Function
Sectioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

chmod
chown
creat
exec
fpathconf
fstat
kill
link
mkdir
mkfifoopen
pathconf
read
renamermdir
setgidsetuidstat
unlink
utime
write

133
134
135

New
POSIX.1eFunction
Synopsisiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

acl_delete_def_fd
acl_delete_def_file
acl_get_fd
acl_get_file
acl_set_fd
acl_set_file
aud_switch
aud_write
inf_get_fd
inf_get_file
inf_set_fd
inf_set_file
inf_set_proc
mac_get_fd
mac_get_file
mac_set_fd
mac_set_file
mac_set_proc
cap_get_fd
cap_get_file
cap_set_fd
cap_set_file

5.6.4
5.6.5
5.3.2
3.1.2
5.7.1
5.6.2
3.3.2
5.3.4
5.4.1
5.4.2
5.3.1
5.7.1
6.4.1
5.5.3
5.5.2
4.2.2
4.2.2
5.6.2
5.5.1
5.6.6
6.4.2

Delete a Default ACL by File Descriptor
Delete a Default ACL by Filename
Get an ACL by File Descriptor
Get an ACL by Filename
Set an ACL by File Descriptor
Set an ACL Filename
Control the Generation of Audit Records
write an application-generated record to an audit log
Get the Information Label of a File Identified by File Descriptor
Get the Information Label of a File Identified by File Pathname
Set the Information Label of a File Identified by File Descriptor
Set the Information Label of a File Identified by File Pathname
Set the Process Information LabelGet the Label of a File Designated by File Descriptor
Get the Label of a File Designated by File Pathname
Set the Label of a File Designated by File Descriptor
Set the Label of a File
Set the Process LabelGet the Capability State of an Open File
Read the Capability State of a File
Set the Capability State of an Open File
Write the Capability State of a File

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

166

25 Capabilities

158

25.1.2 Capability Functions

159
160
161
162
163

Functional interfaces are defined to manipulate capability states, to assign themto files and processes and to obtain them for files and processes. These functions
comprise a set of interfaces that permit portable programs to manipulate theirown capability state and a minimal set of interfaces to manipulate the capability
state of files.

164

Four groups of functions are defined to:165(1) manage the working storage area used by capability states

166(2) manipulate the capability flags within a capability state

167(3) manipulate (read and write) a capability state on a file or process

168(4) translate a capability state into different formats.

169

25.1.2.1 Capability Data Object Storage Management

170
171
172
173
174
175

The capabilities associated with a file or process are never edited directly.
Rather, a working storage area is allocated to contain a representation of thecapability state. Capabilities are edited and manipulated only within this working
storage area. Once the editing of the capability state is completed, the updated
capability state is used to replace the capability state associated with the file orprocess.

176
177
178
179
180

Working storage is allocated as needed by the capability manipulation functions.
The cap_init() and cap_dup () functions also allow the application to allocate
working storage for the creation of a new capability state. The working storage
area may be released by the application once the capability state is no longer
needed by use of the cap_free() function.

c181

cap_dup()

Duplicates a capability state in a working storage area

182
183

cap_free()Releases working storage area previously allocated by capability
manipulation functions

184
185

cap_init()

Allocates and initializes working storage area for a capability
state.

186

25.1.2.2 Capability Data Object Manipulation

187
188

These functions manipulate capability state only in working storage not associated with file or process.

189

cap_get_flag()Obtain the value of a specific flag for a specific capability.

190

cap_set_flag()

Sets the value of a specific flag for a specific capability.

191
192

cap_clear()

Initializes or resets a capability state such that all flags for
all capabilities are cleared.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.1 General Overview

167

193

25.1.2.3 Capability Manipulation on an Object

194
195

These functions read the capability state of a file or process into working storage
and write the capability state in working storage to a file or process.

196
197

cap_get_fd()

Reads the capability state associated with a file descriptor
into working storage.

198
199

cap_get_file()

Reads the capability state associated with a file into working storage.

200
201

cap_get_proc()

Reads the capability state associated with the calling process into working storage.

202
203

cap_set_fd()

Writes the capability state in working storage to the object
associated with a file descriptor.

204

cap_set_file()

Writes the capability state in working storage to a file.

205
206

cap_set_proc()

Sets the process capability state of the calling process to acapability state in working storage.

207

25.1.2.4 Capability State Format Translation

208

This standard defines three different representations for a capability state:

−

209
210

external form

The exportable, contiguous, persistent representation of acapability state in user-managed space.

211
212

internal form

The internal representation of a capability state in working
storage managed by the capability functions.

213

text form

The structured text representation of a capability state.

214

These functions translate a capability state from one representation into another. +

215
216

cap_copy_ext()

Translates an internal form of a capability state to the external form of a capability state.

217
218

cap_copy_int()

Translates the external form of a capability state to the internal form of a capability state.

219
220

cap_from_text() Translates a text form of a capability state to the internal
form of a capability state.

221
222

cap_size()

Returns the size in bytes required to store the external formof a capability state that is the result of an cap_copy_ext().

223
224

cap_to_text()

Translates an internal form of a capability state to the text
form of a capability state.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

168

25 Capabilities

225

25.2 Header

226
227
228
229

Some of the data types used by the capability functions are not defined as part ofthis standard, but shall be implementation-defined. These types shall be definedin the header <sys/capability.h>, which contains definitions for at least thetypes shown in the following table.

230

Table 25-2 − Capability Data Types

231
232
233
235
234
236
239
237
238
240
242
241
243
245
244

Defined Type
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

246
247

The symbolic constants specified in the remainder of this section shall be definedin the header <sys/capability.h>.

248
249

Table 25-3 contains cap_flag_t values for the cap_get_flag() and cap_set_flag()
functions.

cap_flag_t
cap_t

cap_flag_value_t
cap_value_t

Used to identify capability flags. This data type is exportable
data.
Used as a pointer to an opaque data object that is used ascapability state working storage. This data type is nonexportable data.
Used to specify the value of capability flags. This data type isexportable data.
Used to identify capabilities. This data type is exportable
data.

250

Table 25-3 − cap_flag_t Values

251
252
253
254
255
256
257
258

Constant
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

259
260

CAP_EFFECTIVE
CAP_INHERITABLE
CAP_PERMITTED

Specifies the effective flag.
Specifies the inheritable flag.
Specifies the permitted flag.

Table 25-4 contains cap_flag_value_t
cap_set_flag() functions.

valuesforthecap_get_flag()

and

261

Table 25-4 − cap_flag_value_t Values

262
263
264
265
266
267

Constant
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

268
269
270
271
272
273
274
275

Table 25-5 through Table 25-8 contains cap_value_t values for cap_get_flag() and
cap_set_flag(). Note that the description of each capability specifies exactly what
restriction the capability is intended to affect. Possession of a capability that
overrides one restriction should not imply that any other restrictions are overridden. For example, possession of the CAP_DAC_OVERRIDE capability should not
imply that a process can read files with MAC labels that dominate that of the process, nor should it override any restrictions that the file owner ID match the user
ID of the process.

276

If the {_POSIX_CAP} system configuration option is defined, the implementation

CAP_CLEAR
CAP_SETThe flag is cleared/disabled.
The flag is set/enabled.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.2 Header

169

277

278
279
280
281
294
282
283
284
285
286
287
288
289
290
291
292
293
295
304
296
297
298
299
300
301
302
303
305
314
306
307
308
309
310
311
312
313
315
324
316
317
318
319
320
321
322
323

shall define at least the following set of cap_value_t values:
Table 25-5 − cap_value_t Values
Constant
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
CAP_CHOWN
In a system in which the{_POSIX_CHOWN_RESTRICTED}
option is defined, this capability shall override the restriction that a process cannotchange the user ID of a file itowns and the restriction thatthe group ID supplied to thechown() function shall beequal to either the group ID
or one of the supplementarygroup IDs of the calling process.
CAP_DAC_EXECUTE
This capability shall override
file mode execute access restrictions when accessing an
object,and,
if
the{_POSIX_ACL}
optionisdefined, this capability shalloverride the ACL executeaccessrestrictions
when
accessing an object.
CAP_DAC_WRITE
This capability shall override
file mode write access restrictions when accessing an
object,and,
if
the{_POSIX_ACL}
optionisdefined, this capability shalloverride the ACL write access
restrictions when accessing
an object.
CAP_DAC_READ_SEARCHThis capability shall override
file mode read and searchaccessrestrictions
when
accessing an object, and, if the{_POSIX_ACL}
optionisdefined, this capability shalloverride the ACL read andsearch access restrictions
when accessing an object.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

170

25 Capabilities

325

326
338
327
328
329
330
331
332
333
334
335
336
337
339
358
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
359
365
360
361
362
363
364
366
370
367
368
369

CAP_FOWNERCAP_FSETID

CAP_KILLCAP_LINK_DIR

This capability overrides therequirement that the user ID
associated with a process beequal to the file owner ID,
except in the cases where the
CAP_FSETID
capability isapplicable. In general, thiscapability, when effective, will
permit a process to perform
all the functions that any fileowner would have for theirfiles.
This capability shall override
the following restrictions:that the effective user ID of
the calling process shallmatch the file owner whensettingthe
set-user-ID(S_ISUID) and set-group-ID(S_ISGID) bits on that file;that the effective group ID or
one of the supplementarygroup IDs of the calling process shall match the group ID
of the file when setting theset-group-ID bit of that file;and that the set-user-ID and
set-group-ID bits of the filemode shall be cleared uponsuccessful
returnfromchown().
This capability shall override
the restriction that the real oreffective user ID of a process
sending a signal must matchthe real or effective user ID of
the receiving process.
This capability overrides the
restriction that a process cannot create or delete a hard
link to a directory.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.2 Header

171

371

372
376
373
374
375
377
391
378
379
380
381
382
383
384
385
386
387
388
389
390
392
404
393
394
395
396
397
398
399
400
401
402
403
405
406

CAP_SETFCAP

CAP_SETGID

CAP_SETUIDThis capability shall override
the restriction that a process
cannot set the file capability
state of a file.
This capability shall override
the restriction in the setgid()function that a process cannotchange its real group ID orchange its effective group ID
to a value other than its real
group
ID.
If
{_POSIX_SAVED_IDS}
isdefined, then this capability
also overrides any restrictions
on setting the saved setgroup-ID to a value otherthan the current real or saved
set-group ID.
This capability shall override
the restriction in the setuid()function that a process cannotchange its real user ID orchange its effective user ID toa value other than thecurrent real user ID. If{_POSIX_SAVED_IDS}
isdefined, then this capability
also overrides any restrictions
on setting the saved set-userID.

If the {_POSIX_MAC} system configuration option is defined, the implementation −shall define at least the following set of cap_value_t values:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

172

25 Capabilities

407
408
409
410
414
411
412
413
415
419
416
417
418
420
424
421
422
423
425
429
426
427
428
430
434
431
432
433

Table 25-6 − cap_value_t Values for Mandatory Access Controls

435
436

If the {_POSIX_INF} system configuration option is defined, the implementation
shall define at least the following set of cap_value_t values:

Constant
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
CAP_MAC_DOWNGRADE

CAP_MAC_READ

CAP_MAC_RELABEL_SUBJ

CAP_MAC_UPGRADE

CAP_MAC_WRITE

This capability shall override
the restriction that no process
may downgrade the MAC
label of a file.
This capability shall override
mandatory read access restrictions
when
accessingobjects.
This capability shall override
the restriction that a process
may not modify its own MAC
label.
This capability shall override
the restriction that no process
may upgrade the MAC labelof a file.
This capability shall override
mandatory write access restrictions
when
accessingobjects.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.2 Header

173

437
438
439
440
446
441
442
443
444
445
447
453
448
449
450
451
452
454
458
455
456
457
459
465
460
461
462
463
464
466
467

468
469
470
471
475
472
473
474
476
480
477
478
479
481
482

Table 25-7 − cap_value_t Values for Information Labels
Constant
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
CAP_INF_NOFLOAT_OBJ

CAP_INF_NOFLOAT_SUBJ

CAP_INF_RELABEL_OBJ

CAP_INF_RELABEL_SUBJ

This capability shall override
the requirement that an
object’s information label
shall automatically float whena write operation is performed by a process.
This capability shall override
the requirement that a process’ information label shall
automatically float when aread or execute operation is
performed on an object.
This capability shall override
the restriction against changing the information label ofan object.
This capability shall override
the restriction that a process
may not modify its own information label in violation of
the information labeling policy.

If the {_POSIX_AUD} system configuration option is defined, the implementation
shall define at least the following set of cap_value_t values:
Table 25-8 − cap_value_t Values for Audit
Constant
Descriptioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
CAP_AUDIT_CONTROLCAP_AUDIT_WRITE

This capability shall override
the restriction that a process
cannot modify audit control
parameters.
This capability shall override
the restriction that a process
cannot write data into thesystem audit trail.

The symbolic constants defined in this section shall be implementation-defined
unique values.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

174

25 Capabilities

483

25.3 Text Form Representation

484
485
486
487
488

The text form of a capability state shall consist of one or more clauses contained within a single, NULL-terminated character string. Clauses are
separated by whitespace characters. Each valid clause identifies a capability or aset of capabilities, an op (operation), and one or more flags that the operation
applies to:

489
490

clause [SEP clause]...
where clause has the following format:

491[caplist] actionlist

492

and SEP is ‘‘:’’ or any whitespace character.

493

caplist has the following format:

494
495

c

capability_name[,capability_name]... .
actionlist has the following format:

496

op [flags] [op [flags]]...

497

op is one of ‘‘==’’, ‘‘−−’’, or ‘‘+
+’’.

498

flags is a token consisting of one or more alphabetic characters.

499
500
501

The string shall be interpreted in order, e.g., the op specified in a later clause shall supplant or modify op that apply to the same capabilities in an earlier clause.

502
503
504
505
506
507
508
509

The capability_name symbols shall specify which capability or capabilities theclause is to operate on. The symbols to be used are those defined in thecapability.h header file for each capability, e.g., ‘‘CAP_FOWNER’’,‘‘CAP_SETUID’’, etc. More than one capability_name may be specified in aclause by separating them with a comma. A capability_name consisting of thestring ‘‘aall’’ shall be equivalent to a list containing every capability defined by
the implementation. Capability_names are case insensitive on input, and thecase used for output shall be implementation defined.

510
511
512
513
514

The flags symbols e, i and p shall represent the effective, inheritable and permitted capability flags, respectively. All lowercase characters for use as flags
symbols are reserved for use by future versions of this standard. Implementations
may define uppercase characters for flags to represent implementation-defined
flags.

515
516
517

If multiple actionlists are grouped with a single caplist in the grammar, eachactionlist shall be applied in the order specified with that caplist. The op symbols
shall represent the operation performed, as follows:
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

25.3 Text Form Representation

175

518
519

+

If flags is not specified and caplist contains one or more capability
names, the + operation shall not change the capability state; else,

520

if caplist is not specified, this shall be considered an error; otherwise

521
522
523

if caplist is specified as ‘‘aall’’, the capability flags represented by flags
for all capabilities defined for the target by the implementation shall beset; otherwise,

524
525

the flags specified in flags for all the capabilities specified in caplist
shall be set.

526
527
528

−

If flags is not specified and caplist contains one or more capability
names, the − operation shall not change the target capability state;
else,

529
530
531

if caplist is not specified or is specified as ‘‘aall’’, the capability flags
represented by flags for all capabilities defined by the implementation
shall be cleared; otherwise,

532
533

the capability flags specified in flags for all the capabilities specified incaplist shall be cleared.

534
535
536

=

Clear all the capability flags for the capabilities specified in caplist, or,if no caplist is specified, clear all capability flags for all capabilities
defined by the implementation, then:

537
538

if flags is not specified, the = operation shall make no further
modification to the target capability state; else,

539
540
541

if caplist is not specified or is specified as ‘‘aall’’, the capability flags
represented by flags shall be set for all capabilities defined for the target by the implementation; otherwise,

542
543

the capability flags represented by flags shall be set for all the capabilities specified in caplist in the target capability state.

544

25.3.1 Grammar

545
546
547
548
549
550

The grammar and lexical conventions in this subclause describe the syntax for the
textual representation of capability state. The general conventions for this style ofgrammar are described in POSIX.2, "Grammar Conventions", 2.1.2. A valid capability state can be represented as the nonterminal symbol capability state in thegrammar. The formal syntax description in this grammar shall take precedence
over the textual descriptions in this clause.

551
552
553

The lexical processing shall be based on single characters except for capability
name recognition. Implementations need not allow whitespace characters within
the single argument being processed.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

176

25 Capabilities

554
555
556
557
558

%startcapability_state%%
capability_state : clause| capability_state clause
;

559
560
561

clause: actionlist| caplist actionlist
;

562
563
564

caplist: capability_name| caplist ’,’ capability_name
;

565
566
567

actionlist: action| actionlist action
;

568
569
570

action: op| op flaglist
;

571
572
573
574

op

: ‘‘+’’| ‘‘−’’| ‘‘=’’
;

575
576
577

flaglist

578
579
580
581

flag

582

25.4 Functions

583
584
585
586
587
588
589

The functions in this section comprise the set of services that permit a process
image to acquire, manipulate, and pass capabilities on to new process images theycreate. Support for the capability facility functions identified in this section is
optional. If the symbol {_POSIX_CAP} is defined, the implementation supports
the capability option and all of the capability functions shall be implemented as
described in this section. If {_POSIX_CAP} is not defined, the result of calling anycof these functions is unspecified.

590
591
592

The error [ENOTSUP] shall be returned in those cases where the system supports
the capability facility but the particular capability operation cannot be applied
because of restrictions imposed by the implementation.
−: flag| flaglist flag;: ‘‘e’’| ‘‘i’’| ‘‘p’’;WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.4 Functions

177

c

593

25.4.1 Initialize a Capability State in Working Storage

594

Function: cap_clear()595

25.4.1.1 Synopsis

596#include <sys/capability.h>597

int cap_clear (cap_t cap_p));598

25.4.1.2 Description

599
600
601

The function cap_clear() shall initialize the capability state in working storage
identified by cap_p so that all capability flags for all capabilities defined in theimplementation shall be cleared.

602

25.4.1.3 Returns

603
604

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

605

25.4.1.4 Errors

606
607

If any of the following conditions occur, the cap_clear() function shall return −1
and set errno to the corresponding value:

608
609

[EINVAL]

The value of the cap_p argument does not refer to a capability state in working storage.
−

610

25.4.1.5 Cross-References611

cap_init(), 25.4.11; cap_set_flag(), 25.4.14.

612

25.4.2 Copy a Capability State From System to User Space

613

Function: cap_copy_ext()

614

25.4.2.1 Synopsis

615#include <sys/capability.h>616

ssize_t cap_copy_ext (void ∗ext_p,, cap_t cap_p,, ssize_t size))

617

25.4.2.2 Description

618
619
620
621

The cap_copy_ext() function shall copy a capability state in working storage,
identified by cap_p, from system managed space to user-managed space (pointed
to by ext_p) and returns the length of the resulting data record. The size parameter represents the maximum size, in bytes, of the resulting data record. Thec

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

178

25 Capabilities

c

622
623
624
625
626

cap_copy_ext() function will do any conversions necessary to convert the capability state from the unspecified internal format to an exportable, contiguous, persistent data record. It is the responsibility of the user to allocate a buffer large
enough to hold the copied data. The buffer length required to hold the copied
data may be obtained by a call to the cap_size() function.

627

25.4.2.3 Returns

628
629
630

Upon successful completion, the function shall return the number of bytes placedin the user managed space pointed to by ext_p. Otherwise, a value of (ssize_t)−1
shall be returned and errno shall be set to indicate the error.

631

25.4.2.4 Errors

632
633

If any of the following conditions occur, the cap_copy_ext() function shall return(ssize_t)−1 and set errno to the corresponding value:

c

c

c

634
635
636

[EINVAL] The value of the cap_p argument does not refer to a capability state
in working storage or the value of the size argument is zero or nega- −
tive.

637
638

[ERANGE] The size parameter is greater than zero, but smaller than thelength of the contiguous, persistent form of the capability state.
−

639

25.4.2.5 Cross-References

640

cap_copy_int() 25.4.3.

641

25.4.3 Copy a Capability State From User to System Space

642

Function: cap_copy_int()

643

25.4.3.1 Synopsis

644#include <sys/capability.h>645

cap_t cap_copy_int (const void ∗ext_p))

646

25.4.3.2 Description

647
648
649
650
651
652
653
654

The cap_copy_int() function shall copy a capability state from a capability data
record in user-managed space to a new capability state in working storage, allocating any memory necessary, and returning a pointer to the newly created capability state. The function shall initialize the capability state and then copy thecapability state from the record pointed to by ext_p into the capability state, converting, if necessary, the data from a contiguous, persistent format to anunspecified internal format. Once copied into internal format, the object can be
manipulated by the capability state manipulation functions.

cc

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.4 Functions

179

c

655
656

Note that the record pointed to by ext_p must have been obtained from a previous,
successful call to cap_copy_ext() for this function to work successfully.

657
658
659

This function may cause memory to be allocated. The caller should free any
releasable memory, when the capability state in working storage is no longer
required, by calling cap_free() with the cap_t as an argument.

660

25.4.3.3 Returns

661
662
663

Upon successful completion, the cap_copy_int() function returns a pointer to the
newly created capability state in working storage. Otherwise, a value of(cap_t)NULL shall be returned and errno shall be set to indicate the error.

664

25.4.3.4 Errors

665
666

If any of the following conditions occur, the cap_copy_int() function shall return(cap_t)NULL and set errno to the corresponding value:

667
668

[EINVAL]

The value of the ext_p argument does not refer to a capability
data record as defined in section 25.3.

669
670
671

[ENOMEM] The capability state to be returned requires more memory thanis allowed by the hardware or system-imposed memory management constraints.
−

672

25.4.3.5 Cross-References673

cap_copy_ext(), 25.4.2; cap_free(), 25.4.5; cap_init(), 25.4.11.

674

25.4.4 Duplicate a Capability State in Working Storage

675

Function: cap_dup ()676

25.4.4.1 Synopsis

677#include <sys/capability.h>678

cap_t cap_dup (cap_t cap_p));679

25.4.4.2 Description

680
681
682
683

The cap_dup () function returns a duplicate capability state in working storage
given the source object cap_p, allocating any memory necessary, and returning apointer to the newly created capability state. Once duplicated, no operations oneither capability state shall affect the other in any way.

684
685
686

This function may cause memory to be allocated. The caller should free any
releasable memory, when the capability state in working storage is no longer
required, by calling cap_free() with the cap_t as an argument.

c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

180

25 Capabilities

c

c

687

25.4.4.3 Returns

688
689
690

Upon successful completion, the cap_dup () function returns a pointer to the newly
created capability state in working storage. Otherwise, a value of (cap_t)NULL
shall be returned and errno shall be set to indicate the error.

691

25.4.4.4 Errors

692
693

If any of the following conditions occur, the cap_dup () function shall return(cap_t)NULL and set errno to the corresponding value:

694
695

[EINVAL]

The value of the cap_p argument does not refer to a capability state in working storage.
−

696
697
698

[ENOMEM]

The capability state to be returned requires more memory
than is allowed by the hardware or system-imposed memory
management constraints.
−

c

c

699

25.4.4.5 Cross-References

700

cap_free(), 25.4.5.

701
702

25.4.5 Release Memory Allocated to a Capability State in Working
Storage703

Function: cap_free()704

25.4.5.1 Synopsis

705#include <sys/capability.h>706

int cap_free (void ∗obj_d));

707

25.4.5.2 Description

708
709
710
711

The function cap_free() shall free any releasable memory currently allocated tothe capability state in working storage identified by obj_d. The obj_d argument %may identify either a cap_t entity, or a char ∗ entity allocated by the cap_to_text()
function.

712

25.4.5.3 Returns

713
714

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

cc

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.4 Functions

181

715

25.4.5.4 Errors

716
717

If any of the following conditions occur, the cap_free() function shall return −1 andset errno to the corresponding value:

718
719

[EINVAL]

The value of the obj_d argument does not refer to memory
recognized as releasable by the implementation.
−

720

25.4.5.5 References

721
722
723

cap_copy_int(), 25.4.3; cap_dup (), 25.4.4; cap_from_text(), 25.4.6; cap_get_fd(), %25.4.7; cap_get_file(), 25.4.8; cap_get_proc(), 25.4.10; cap_init(), 25.4.11; %cap_to_text(), 25.4.17.
c724

25.4.6 Convert Text to a Capability State in Working Storage

725

Function: cap_from_text()

726

25.4.6.1 Synopsis

727#include <sys/capability.h>728

cap_t cap_from_text (const char ∗buf_p));729

25.4.6.2 Description

730
731
732
733

This function shall allocate and initialize a capability state in working storage. It
shall then set the contents of this newly-created capability state to the state
represented by the human−readable, null terminated character string pointed toby buf_p. It shall then return a pointer to the newly created capability state.

734
735
736

This function may cause memory to be allocated. The caller should free any
releasable memory, when the capability state in working storage is no longer
required, by calling cap_free() with the cap_t as an argument.

737
738
739
740
741

The function shall recognize and correctly parse any string that meets the
specification in 25.3. The function shall return an error if the implementation canc
not parse the contents of the string pointed to by buf_p or does not recognize any
capability_name or flag character as valid. The function shall also return an error
if any flag is both set and cleared within a single clause.

742

25.4.6.3 Returns

743
744

Upon successful completion, a non-NULL value is returned. Otherwise, a value ofc(cap_t)NULL shall be returned and errno shall be set to indicate the error.

c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

182

25 Capabilities

745

25.4.6.4 Errors

746
747

If any of the following conditions occur, the cap_from_text() function shall return c(cap_t)NULL and set errno to the corresponding value:

748
749
750
751
752

[EINVAL]

The buf_p argument does not refer to a character string as
defined in section 25.3, the string pointed to by buf_p is notparseable by the function, the text string contains acapability_name or a flag character that the implementation
does not recognize as valid.

753
754
755

[ENOMEM]

The capability state to be returned requires more memory
than is allowed by the hardware or system-imposed memory
management constraints.
−

756

25.4.6.5 Cross-References

757
758

cap_to_text(), 25.4.17; cap_free(), 25.4.5; cap_init(), 25.4.11; cap_set_flag(),
25.4.14.

759

25.4.7 Get the Capability State of an Open File760

Function: cap_get_fd()761

25.4.7.1 Synopsis

762#include <sys/capability.h>763

cap_t cap_get_fd (int fd));

764

25.4.7.2 Description

765
766
767

The function cap_get_fd() shall allocate a capability state in working storage andset it to represent the capability state of the file open on the descriptor fd, thenreturn a pointer to the newly created capability state.

768
769
770
771

A process can get the capability state of any regular file for which the process has ca valid file descriptor. If the file open on the descriptor fd is not a regular file, cthen cap_get_fd() shall return an error. If {_POSIX_CAP_PRESENT} is not in ceffect for the file, then the results of cap_get_fd() shall be implementation-defined.c

772
773

If {_POSIX_MAC} is defined, the process must also have mandatory access control
read access to the file.
−

774
775
776

This function may cause memory to be allocated. The caller should free any
releasable memory, when the capability state in working storage is no longer
required, by calling cap_free() with the cap_t as an argument.

c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.4 Functions

c

183

777

25.4.7.3 Returns

778
779
780

Upon successful completion, this function returns a non-NULL value. Otherwise,a value of (cap_t)NULL shall be returned and errno shall be set to indicate theerror.

781

25.4.7.4 Errors

782
783

If any of the following conditions occur, the cap_get_fd() function shall return(cap_t)NULL and set errno to the corresponding value:

784
785

[EACCES]If the {_POSIX_MAC} system configuration option isenabled, MAC read access to the file is denied.

786[EBADF]The fd argument is not a valid open file descriptor.

787[EINVAL]

The file open on fd is not a regular file.

788
789
790

[ENOMEM]

The capability state to be returned requires more memory
than is allowed by the hardware or system-imposed memory
management constraints.
−

c

c

+

791

25.4.7.5 Cross-References792

cap_init(), 25.4.11; cap_free(), 25.4.5; cap_get_file(), 25.4.8; cap_set_fd(), 25.4.12. c

793

25.4.8 Get the Capability State of a File794

Function: cap_get_file()

795

25.4.8.1 Synopsis

796#include <sys/capability.h>797

cap_t cap_get_file (const char ∗path_p));798

25.4.8.2 Description

799
800
801

The function cap_get_file() shall allocate a capability state in working storage andset it to be equal to the capability state of the pathname pointed to by path_p,then return a pointer for the newly created capability state in working storage.

802
803
804
805
806

A process can get the capability state of any regular file for which the process has +search access to the path specified. If the file pointed to by path_p is not a regular+
file, then cap_get_file() shall return an error. If {_POSIX_CAP_PRESENT} is not +in effect for the file, then the results of cap_get_file() shall be implementation- +defined.
+

807
808

If {_POSIX_MAC} is defined, the process must also have MAC read access to the
file.
−

c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

184

25 Capabilities

c

809
810
811

This function may cause memory to be allocated. The caller should free any
releasable memory, when the capability state in working storage is no longer
required, by calling cap_free() with the cap_t as an argument.

812

25.4.8.3 Returns

813
814
815

Upon successful completion, this function returns a non-NULL value. Otherwise,a value of (cap_t)NULL shall be returned and errno shall be set to indicate theerror.

816

25.4.8.4 Errors

817
818

If any of the following conditions occur, the cap_get_file() function shall return(cap_t)NULL and set errno to the corresponding value:

819
820
821

[EACCES]

Search permission is denied for a component of the path
prefix, or, if {_POSIX_MAC} is defined, MAC read access tothe file path_p is denied.
c822[EINVAL]

The file pointed to by path_p is not a regular file.

823
824
825

[ENAMETOOLONG] The length of the path_p argument exceeds{PATH_MAX}, or a pathname component is longer than
{NAME_MAX} while {POSIX_NO_TRUNC} is in effect.

826
827

[ENOENT]The named file does not exist or the path_p argument pointsc
to an empty string.

828
829
830

[ENOMEM]

The capability state to be returned requires more memory
than is allowed by the hardware or system-imposed memory
management constraints.
−

831[ENOTDIR]

A component of the path prefix is not a directory.

832

25.4.8.5 Cross-References833

cap_free(), 25.4.5; cap_init(), 25.4.11; cap_set_file(), 25.4.13; cap_get_fd(), 25.4.7. c834

25.4.9 Get the Value of a Capability Flag

835

Function: cap_get_flag()836

25.4.9.1 Synopsis

837#include <sys/capability.h>

838
839
840
841

int cap_get_flag (cap_t cap_p,,
cap_value_t cap,,
cap_flag_t flag,,
cap_flag_value_t ∗value_p)
);

c

c

c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.4 Functions

c

185

842

25.4.9.2 Description

843
844
845

The function cap_get_flag() shall obtain the current value of the capability flag
flag of the capability cap from the capability state in working storage identified by
cap_p and place it into the location pointed to by value_p.

846

25.4.9.3 Returns

847
848

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

849

25.4.9.4 Errors

850
851

If any of the following conditions occur, the cap_get_flag() function shall return −1
and set errno to the corresponding value:

852
853

[EINVAL]At least one of the values of the cap_p, cap, flag and value_p
arguments does not refer to the corresponding entity.
−854

25.4.9.5 Cross-References855

cap_set_flag(), 25.4.14.

856

25.4.10 Obtain the Current Process Capability State

857

Function: cap_get_proc()858

25.4.10.1 Synopsis

859#include <sys/capability.h>860

cap_t cap_get_proc (void);

861

25.4.10.2 Description

862
863
864

The function cap_get_proc() shall allocate a capability state in working storage,
set its state to that of the calling process, and return a pointer to the newly
created capability state.

865
866
867

This function may cause memory to be allocated. The caller should free any
releasable memory, when the capability state in working storage is no longer
required, by calling cap_free() with the cap_t as an argument.

868

25.4.10.3 Returns

869
870
871

Upon successful completion, this function shall return a cap_t value. Otherwise,a value of (cap_t)NULL shall be returned and errno shall be set to indicate theerror.

cc

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

186

25 Capabilities

c

872

25.4.10.4 Errors

873
874

If any of the following conditions occur, the cap_get_proc() function shall return(cap_t)NULL and set errno to the corresponding value:

875
876
877

[ENOMEM]

The capability state to be returned requires more memory
than is allowed by the hardware or system-imposed memory
management constraints.
−

878

25.4.10.5 Cross-References

879
880

cap_free(), 25.4.5; cap_init(), 25.4.11; cap_get_flag(), 25.4.9; cap_set_proc(),
25.4.15.

881

25.4.11 Allocate and Initialize a Capability State in Working Storage

882

Function: cap_init()883

25.4.11.1 Synopsis

884#include <sys/capability.h>885

cap_t cap_init (void);

886

25.4.11.2 Description

887
888
889

The function cap_init() shall create a capability state in working storage andreturn a pointer to the capability state. The initial value of all flags for all capabilities defined by the implementation shall be cleared.

890
891
892

This function may cause memory to be allocated. The caller should free any
releasable memory, when the capability state in working storage is no longer
required, by calling cap_free() with the cap_t as an argument.

893

25.4.11.3 Returns

894
895
896

Upon successful completion, this function returns a non-NULL cap_t value. Otherwise, a value of (cap_t)NULL shall be returned and errno shall be set to indicatec
the error.

897

25.4.11.4 Errors

898
899

If any of the following conditions occur, the cap_init() function shall return(cap_t)NULL and set errno to the corresponding value:

900
901
902

[ENOMEM]cc

The capability state to be returned requires more memory
than is allowed by the hardware or system-imposed memory
management constraints.
−

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.4 Functions

c

187

c

903

25.4.11.5 Cross-References904

cap_free(), 25.4.5.

905

25.4.12 Set the Capability State of an Open File906

Function: cap_set_fd()907

25.4.12.1 Synopsis

908#include <sys/capability.h>909

int cap_set_fd (int fd,, cap_t cap_p));910

25.4.12.2 Description

911
912
913
914

The function cap_set_fd() shall set the values for all capability flags for all capabilities defined in the implementation for the file opened on descriptor fd with thecapability state identified by cap_p. The new capability state of the file identified
by fd shall be completely determined by the contents of cap_p.
+

915
916
917
918
919
920

For this function to succeed, the process calling it must have the CAP_SETFCAP
capability enabled and either the effective user ID of the process must match thefile owner or the calling process must have the effective CAP_FOWNER capability
flag set. In addition, if {_POSIX_MAC} is defined, then the process must have
MAC write access to the file. Implementations may place additional restrictions
on setting the capability state of a file.
c

921
922

If the file open on the descriptor fd is not a regular file, then cap_set_fd() shallreturn an error.

923

25.4.12.3 Returns

924
925
926

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error. The
capability state of the file shall not be affected if the return value is −1.

927

25.4.12.4 Errors

928
929

If any of the following conditions occur, the cap_set_fd() function shall return −1
and set errno to the corresponding value:

c

c

930
931
932
933

[EACCES]The requested access to the file specified is denied,or the {_POSIX_MAC} system configuration option isenabled and MAC write access to the file opened on descriptor fd is denied.

934[EBADF]The fd argument is not a valid open file descriptor.

935
936

[EINVAL]

The value of the cap_p argument does not refer to a capability state in working storage.
+

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

188

25 Capabilities

c

937

The file open on fd is not a regular file.

938
939
940

[EPERM]

The process does not have appropriate privilege or does notmeet other restrictions imposed by the implementation to
perform the operation.

941
942

[EROFS]This function requires modification of a file resident on a filesystem which is currently read-only.

943

25.4.12.5 Cross-References944

cap_get_fd(), 25.4.7; cap_set_file(), 25.4.13.

945

25.4.13 Set the Capability State of a File946

Function: cap_set_file()

947

25.4.13.1 Synopsis

948#include <sys/capability.h>949

int cap_set_file (const char ∗path_p,, cap_t cap_p));

95025.4.13.2 Description

951
952
953
954

The function cap_set_file() shall set the values for all capability flags for all capabilities defined in the implementation for the pathname pointed to by path_p withc
the capability state identified by cap_p. The new capability state of the file
identified by path_p shall be completely determined by the contents of cap_p.
c

955
956
957
958
959
960

For this function to succeed, the process must have the CAP_SETFCAP capability
enabled and either the effective user ID of the process must match the file owneror the calling process must have the effective flag of the CAP_FOWNER capability
set. In addition, if {_POSIX_MAC} is defined, then the process must have MAC
write access to the file. Implementations may place additional restrictions on setting the capability state of a file.

961
962
963

If the file pointed to by path_p is not a regular file, then cap_set_file() shall return
an error. The effects of writing capability state to any file type other than a regular file are undefined.
−

964

25.4.13.3 Returns

965
966
967

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error. The
capability state of the file shall not be affected if the return value is −1.

cc

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.4 Functions

189

c

968

25.4.13.4 Errors

969
970

If any of the following conditions occur, the cap_set_file() function shall return −1
and set errno to the corresponding value:

971
972
973
974

[EACCES]

Search/read permission is denied for a component of thepath prefix, or the {_POSIX_MAC} system configuration −option is enabled and MAC write access to the file referred
to by path_p is denied.
c

975
976
977

[EINVAL]

The value of the cap_p argument does not refer to a capabil- c
ity state in working storage or the capability state specified
is not permitted for a file on the implementation.
+

978

The file pointed to by path_p is not a regular file.

979
980
981

[ENAMETOOLONG] The length of the path_p argument exceeds{PATH_MAX}, or a pathname component is longer than
{NAME_MAX} while {POSIX_NO_TRUNC} is in effect.

982
983

[ENOENT]The named file/directory does not exist or the path_p argu- cment points to an empty string.
−

984[ENOTDIR]

A component of the path prefix is not a directory.

985
986
987

[EPERM]

The process does not have appropriate privilege or does notmeet other restrictions imposed by the implementation to
perform the operation.

988
989

[EROFS]This function requires modification of a file resident on a filesystem which is currently read-only.

990

25.4.13.5 Cross-References

991

cap_get_file(), 25.4.8; cap_set_fd(), 25.4.12.

992

25.4.14 Set the Value of a Capability Flag

993

Function: cap_set_flag()994

25.4.14.1 Synopsis

995#include <sys/capability.h>c996 int cap_set_flag (cap_t cap_p,,997
cap_flag_t flag,,
998
int ncap,,999
cap_value_t caps[],,1000
cap_flag_value_t value));

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

190

25 Capabilities

c

1001

25.4.14.2 Description

1002
1003
1004
1005

This function shall set the flag flag of each capability in the array caps in thecapability state in working storage identified by cap_p to value. The argument
ncap is used to specify the number of capabilities in the array caps. Implementations may place restrictions on the setting of the flags in a capability state.

1006

25.4.14.3 Returns

1007
1008
1009

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error. The
capability state identified by cap_p shall not be affected if the return value is −1.

1010

25.4.14.4 Errors

1011
1012

If any of the following conditions occur, the cap_set_flag() function shall return −1
and set errno to the corresponding value:

1013
1014
1015

[EINVAL]

1016
1017

At least one of the values of cap_p, ncap, flag and value, orat least one of the first ncap elements in caps, does not referto the corresponding entity.
−
The resulting capability state identified by cap_p violates %one or more implementation restrictions.
−1018

25.4.14.5 Cross-References1019

cap_get_flag(), 25.4.16.

1020

25.4.15 Set the Process Capability State

1021

Function: cap_set_proc()1022

25.4.15.1 Synopsis

1023#include <sys/capability.h>1024

int cap_set_proc (cap_t cap_p)
);

1025

25.4.15.2 Description

1026
1027
1028
1029
1030
1031

The function cap_set_proc() shall set the values for all capability flags for all capabilities defined in the implementation with the capability state identified by
cap_p. The new capability state of the process shall be completely determined by
the contents of cap_p upon successful return from this function. If any flag in
cap_p is set for any capability not currently permitted for the calling process, thefunction shall fail, and the capability state of the process shall remain unchanged.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.4 Functions

191

1032

25.4.15.3 Returns

1033
1034
1035
1036

Upon successful completion, the function shall return a value of zero. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error. Neither
the state represented in the object identified by cap_p nor the capability state of
the calling process shall be affected if the return value is −1.

1037

25.4.15.4 Errors

1038
1039

If any of the following conditions occur, cap_set_proc() shall return −1 and set
errno to the corresponding value:

1040
1041

[EINVAL]

The value of the cap_p argument does not refer to a capability state in working storage.
−

1042
1043

[EPERM]

The caller attempted to set a capability flag of a capability
that was not permitted to the invoking process.

1044
1045
1046

[ENOMEM]

The function requires more memory than is allowed by the
hardware or system-imposed memory management constraints.

1047

25.4.15.5 Cross-References1048

cap_get_proc(), 25.4.10.

1049

25.4.16 Get the Size of a Capability Data Record

1050

Function: cap_size()

1051

25.4.16.1 Synopsis

1052#include <sys/capability.h>1053

ssize_t cap_size (cap_t cap_p))1054

25.4.16.2 Description

1055
1056
1057
1058
1059

The cap_size() function returns the total length (in bytes) that the capability state
in working storage identified by cap_p would require when converted by
cap_copy_ext(). This function is used primarily to determine the amount of buffer
space that must be provided to the cap_copy_ext() function in order to hold thecapability data record created from cap_p.

1060

25.4.16.3 Returns

1061
1062
1063

Upon successful completion, the cap_size() function returns the length required tohold a capability data record. Otherwise, a value of (ssize_t)−1 shall be returnedand errno shall be set to indicate the error.

c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

192

25 Capabilities

c

1064

25.4.16.4 Errors

1065
1066

If any of the following conditions occur, cap_size() shall return −1 and set errno to
one of the following values:

1067
1068

[EINVAL]

The value of the cap_p argument does not refer to a capability state in working storage.
−1069

25.4.16.5 Cross-References1070

cap_copy_ext(), 25.4.2.

1071

25.4.17 Convert a Capability State in Working Storage to Text

1072

Function: cap_to_text()

1073

25.4.17.1 Synopsis

1074#include <sys/capability.h>1075char ∗cap_to_text (cap_t cap_p,, size_t ∗len_p)
);

1076

25.4.17.2 Description

1077
1078
1079
1080
1081
1082
1083

This function shall convert the capability state in working storage identified by
cap_p into a null terminated human-readable string. This function allocates any
memory necessary to contain the string, and returns a pointer to the string. If thepointer len_p is not (size_t)NULL, the function shall also return the full length of cthe string (not including the null terminator) in the location pointed to by len_p.
The capability state in working storage identified by cap_p shall be completely
represented in the returned character string.

1084
1085

The format of the string pointed to by the returned pointer shall comply with the cspecification in 25.3.

1086
1087
1088

This function may cause memory to be allocated. The caller should free any
releasable memory, when the capability state in working storage is no longer
required, by calling cap_free() with the cap_t as an argument.

1089

25.4.17.3 Returns

1090
1091

Upon successful completion, a non-NULL value is returned. Otherwise, a value ofc(char ∗)NULL shall be returned and errno shall be set to indicate the error.

1092

25.4.17.4 Errors

1093
1094

If any of the following conditions occur, cap_to_text() shall return (char ∗)NULL
and set errno to the corresponding value:cc

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
25.4 Functions

193

c

1095
1096
1097

[EINVAL]

Either the cap_p argument does not refer to a capability
state in working storage or the len_p argument is invalid, or−
both.

1098
1099
1100

[ENOMEM]

The string to be returned requires more memory than isallowed by the hardware or system-imposed memory
management constraints.
−

1101

25.4.17.5 Cross-References1102

cap_free(), 25.4.5; cap_get_flag(), 25.4.16; cap_from_text(), 25.4.6.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

194

25 CapabilitiescSection 26: Mandatory Access Control

1

2

26.1 General Overview

3
4
5
6
7

This section describes the Mandatory Access Control Option. The section definesand discusses MAC concepts, outlines the MAC policy adopted in this standard
and the impact of MAC on existing POSIX.1 functions. Support for the interfaces
defined in this section is optional but shall be provided if the symbol{_POSIX_MAC} is defined.

8

26.1.1 MAC Concepts

9

MAC Labels

10
11
12
13

MAC labels form the basis for mandatory access control decisions. In order topromote flexibility in which conforming implementations may define a MAC policy, specific components of MAC labels and their textual representations are
implementation-defined.

14

Label Relationships

15
16
17
18
19

Two relationships are defined between MAC labels: equivalence, and dominance.
The details of dominance are left to the definition of the conforming implementation, however the dominance relation shall constitute a partial order on MAC
labels. Equivalence is defined relative to dominance. If two MAC labels areequivalent, then each dominates the other.

20

MAC Objects

21
22

MAC objects are the interface-visible data containers, i.e., entities that receive orcontain data, to which MAC is applied. In POSIX.1, these include the following:

23

Files

24
25

This includes regular files, directories, FIFO-special files, and (unnamed)
pipes.

26

Processes

27
28

In cases where a process is the target of some request by another process,that target process shall be considered an object.

29

MAC Subjects

30
31

A subject is an active entity that can cause information to flow between controlled
objects. Since processes are the only such interface-visible element of POSIX.1
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

26.1 General Overview

195

32

they are the only subjects treated in this document.

33

26.1.2 MAC Policy

34
35

The MAC policy presented below is logically structured into the following named
policies:

36

P:

37

FP.∗: The refinements of P that apply to file objects (FP.1, FP.2, etc.)

38

PP.∗: The refinements of P that apply to process objects

39

The fundamental statement of mandatory access control policy

The following labeling requirement shall be imposed:40
41

Each subject and each object shall have a MAC label associated with it at all
times.

42
43
44
45

A physically unique MAC label is not required to be associated with each subject
and object. The requirement is only that a MAC label shall always be associatedwith each subject and object. For example, all files in a file system could share asingle MAC label.

46
47

Policies for initial assignment and constraints on the changing of MAC labels are
given in the refining policies below.

48

The fundamental MAC restriction P is simply stated:

49
50

P:

Subjects cannot cause information labeled at some MAC label L1 tobecome accessible to subjects at L2 unless L2 dominates L1 .

51
52
53
54

This covers all data entities visible at the POSIX.1e interface, and includes restrictions on re-labeling data, i.e., changing the label of an object, as well as movement of that data between objects. P covers all forms of data transmission visible
through the POSIX interface.

55
56

There are several important exceptions or limitations to the application of P and
its refinements to POSIX.1 functions:57

Covert Channel Exceptions

58
59
60
61
62

Policy statement P strictly requires that there be no covert channels. Consistent with this policy statement the new POSIX.1e functions and thechanges to existing POSIX.1 functions have been specified such that covert
channels are not inherent in their definition. This standard does not require
conforming implementations to be free of covert channels.

63

Processes Possessing Appropriate Privileges

64
65
66
67
68

Implicit in the statement of P is the assumption that none of the policies need
necessarily apply to processes possessing appropriate privilege unless explicitly stated. If {_POSIX_CAP} is defined, the list of capabilities that satisfy
the appropriate privilege requirements are defined in this standard in section
25.2.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

196

26 Mandatory Access Control

69

Devices

70
71

The MAC policy on devices may have additional restrictions or refinements
not addressed here. The MAC policy on devices is unspecified.

72

Additional Implementation Restrictions

73
74

It is understood that a conforming implementation may enforce additional
security restrictions consistent with these policies.

75

26.1.2.1 FP: File Function Policies

76
77
78
79
80
81

Mandatory access control for files results from the application of basic policies(FP.∗) to a simple assumption of the file data object. The straightforward application of these rules to the object model determines the specific MAC restrictions
for a large number of file-related interfaces. The object that encompasses a
POSIX.1 file shall be defined to consist of a data portion and an attribute portion.
For the purposes of mandatory access control, the following assumption is made:

82
83
84

Both the data and attribute portion of a file are considered a single MAClabeled data container. Note that the MAC label shall be considered to be in
the attribute portion.

85
86
87
88

Note that, within this standard, and as a basis for defining interface behavior,link names are considered as the contents of directories, and are not a property of
the file that they indicate. They are protected by and considered labeled at the
MAC label of their containing directory.

89

The following policy rules apply:

90
91

FP.1: The MAC label of a file shall be dominated by the MAC label of a subject for the subject to read the data or attributes of a file.

92
93

FP.2: The MAC label of a file shall dominate the MAC label of a subject forthe subject to write the data or attributes of a file.

94
95
96
97
98
99

The general POSIX.1e mandatory access control policy shall be that
subjects may write objects if the MAC label of the subject is dominatedby the object’s MAC label. In accordance with the policy in 2.3.2 thatfurther restrictions may be placed on a policy, an implementation could
choose to be more restrictive by allowing a subject to write to a file only
when the MAC labels are equivalent.

100
101

FP.3: If reading from a FIFO-special file changes either the attributes or thedata of the FIFO object, both FP.1 and FP.2 shall be satisfied.

102
103

FP.4: A newly created object shall be assigned a MAC label which dominates
the MAC label of the creating subject.

104
105

The general POSIX.1e mandatory access control policy shall be that
newly created objects shall be assigned a MAC label which dominates
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

26.1 General Overview

197

106
107
108
109

the MAC label of the creating subject. Although this policy statement
allows creation of upgraded objects, this standard only provides interfaces which will create objects with equivalent MAC labels to the MAC
label of the creating subject.

110
111
112

The MAC label of a file object cannot be modified in violation of P, e.g., processes
which do not possess appropriate privilege cannot downgrade the label of a fileobject.

113
114(Unnamed) pipes are considered objects, although they are not addressable bypathname.

115

26.1.2.1.1 Summary of POSIX.1 System Interface Impact

116

This policy shall be applied to the POSIX.1 functions listed in Table 26-1.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

198

26 Mandatory Access Control

117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

Table 26-1 − POSIX.1 Functions Covered by MAC File Policies

145
146
147

New
POSIX.1eFunction
Synopsisi iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

149
148
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181

acl_delete_def_file
acl_get_fd
acl_get_file
acl_set_fd
acl_set_file
inf_get_fd
inf_get_file
inf_set_fd
inf_set_file
mac_get_fd
mac_get_file
mac_set_fd
mac_set_file
cap_get_fd
cap_get_file
cap_set_fd
cap_set_file

Existing
POSIX.1
Function
Sectioni iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
access
5.6.3
chdir
5.2.1
chmod
5.6.4
chown
5.6.5
creat
5.3.2
execl
3.1.2
execv
3.1.2
execle3.1.2
execve3.1.2
execlp3.1.2
execvp
3.1.2
fcntl
6.5.2
getcwd
5.2.2
link
5.3.4
mkdir
5.4.1
mkfifo
5.4.2
open
5.3.1
opendir
5.1.2
pipe
6.1.1
rename
5.5.3
rmdir
5.5.2
stat
5.6.2
unlink
5.5.1
utime
5.6.6

Delete a Default ACL of a FileGet an ACL of an Open FileGet an ACL of a File
Set an ACL of an Open File
Set an ACL of a FileGet the Information Label of an Open FileGet the Information Label of a File
Set the Information Label of an Open File
Set the Information Label of a FileGet the MAC Label of an Open FileGet the MAC Label of a File
Set the MAC Label of an Open File
Set the MAC Label of a FileGet the Capability State of an Open FileGet the Capability State of a File
Set the Capability State of an Open File
Set the Capability State of a File+

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
26.1 General Overview

199

182

26.1.2.2 PP: Process Function Policies

183
184
185
186

Mandatory access control for processes stems from the application of the basic
MAC restriction to the affected POSIX.1 functions. When treated as an object,
the process shall consist of its internal data (including the environment data), its
executable image, and its status information.

187

The following policy rules apply:

188
189

PP.1: No process at MAC label L1 may write to a process at label L2 unless L2
dominates L1 .

190
191

PP.2: A newly created process shall be assigned a MAC label which dominates
the MAC label of the creating process.

192
193
194
195
196
197

The general POSIX.1 mandatory access control policy shall be that newly
created processes shall be assigned a MAC label which dominates the
MAC label of the creating process. Although this policy statement allows
creation of upgraded processes, this standard only provides interfaces
which create processes with equivalent MAC labels as the creating process.

198
199

The MAC label of a process cannot be altered in violation of P, e.g., a process
which do not possess appropriate privilege cannot downgrade its own MAC label.

200

26.1.2.2.1 POSIX.1 Functions Covered by MAC Process Policies

201

This policy shall be applied to the POSIX.1 functions listed in Table 26-2.

202
203
204
205
206
207

Table 26-2 − POSIX.1 Functions Covered by MAC Process Policies

208
209
210
211
212

New
POSIX.1eFunction
Synopsisiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
mac_set_proc
Set the Process Label

Existing
POSIX.1
Function
Sectioniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
fork
3.1.1
kill
3.3.2

213

26.2 Header

214
215
216
217

Some of the data types used by the MAC label functions are not defined as part ofthis standard, but shall be implementation-defined. If {_POSIX_MAC} is defined,
these types shall be defined in the header <sys/mac.h>, which contains
definitions for at least the following type: mac_t.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

200

26 Mandatory Access Control

218

26.2.1 mac_t

219
220
221
222
223
224
225
226

This type defines a pointer to an "exportable" object capable of holding a MAC
label. The object is opaque, persistent, and self-contained. It shall be possible tocreate an independent copy of the entire MAC label in a user-defined location
using normal byte-copy of mac_size() bytes starting at the location pointed to by
the mac_t. It shall be possible to byte-copy the copy back into system-managed
space, and recommence processing of it there, even if the copy has been stored ina file or elsewhere, or moved to a different process. The internal structure of the
MAC label is otherwise unspecified.

227

26.3 Functions

228
229
230
231
232
233
234

The functions in this section comprise the set of services that permit processes toretrieve, compare, set, and convert MAC labels. Support for the functions andpolicy described in this section is optional. If the symbol {_POSIX_MAC} is cdefined, the implementation supports the Mandatory Access Control (MAC) labelsc
option and all of the MAC functions shall be implemented as described in this sec-ction. If {_POSIX_MAC} is not defined, the result of calling any of these functions cis unspecified.

235
236
237

The error [ENOTSUP] shall be returned in those cases where the system supports
MAC labeling but the particular MAC label operation cannot be applied becauseof restrictions imposed by the implementation.
−

238

26.3.1 Test MAC Labels for Dominance239

Function: mac_dominate()

24026.3.1.1 Synopsis

241#include <sys/mac.h>242

int mac_dominate (mac_t labela,, mac_t labelb));

243

26.3.1.2 Description

244
245

The function mac_dominate() determines whether labela dominates labelb. The
precise method for determining domination is implementation-defined.

246
247

This function is provided to allow conforming applications to test for dominancesince a comparison of the labels themselves may yield an indeterminate result.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
26.3 Functions

201

248

26.3.1.3 Returns

249
250
251
252

If an error occurs, the mac_dominate() function shall return a value of −1 anderrno shall be set to indicate the error. Otherwise, a value of 1 shall be returned
if label labela dominates labelb, and a value of 0 shall be returned if labela does
not dominate labelb.

253

26.3.1.4 Errors

254
255

If any of the following conditions occur, the mac_dominate() function shall return−1 and set errno to the corresponding value:

256
257

[EINVAL]At least one of the labels is not a valid MAC label as defined by −mac_valid().
−258

26.3.1.5 Cross-References259

mac_equal(), 26.3.2; mac_valid(), 26.3.15.

260

26.3.2 Test MAC Labels for Equivalence

261

Function: mac_equal()

262

26.3.2.1 Synopsis

263#include <sys/mac.h>264

int mac_equal (mac_t labela,, mac_t labelb));

265

26.3.2.2 Description

266
267

The function mac_equal() determines whether labela is equivalent to labelb. The
precise method for determining equivalence is implementation-defined.

268
269

This function is provided to allow conforming applications to test for equivalencesince a comparison of the labels themselves may yield an indeterminate result.

270

26.3.2.3 Returns

271
272
273

If an error occurs, a value of −1 shall be returned and errno shall be set to indicate
the error. Otherwise, the mac_equal() function returns 1 if labela is equivalent toc
labelb, and a value of 0 shall be returned if labela is not equivalent to labelb.
c274

26.3.2.4 Errors

275
276

If any of the following conditions occur, the mac_equal() function shall return −1
and set errno to the corresponding value:c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

202

26 Mandatory Access Control

277
278

[EINVAL]At least one of the labels is not a valid MAC label as defined by −mac_valid().
−279

26.3.2.5 Cross-References280

mac_dominate(), 26.3.1; mac_valid(), 26.3.15.

281

26.3.3 Free MAC Label Storage Space

282

Function: mac_free()283

26.3.3.1 Synopsis

284#include <sys/mac.h>285

int mac_free (void ∗buf_p));286

26.3.3.2 Description

287
288
289

The function mac_free() shall free any releasable memory currently allocated tothe buffer identified by buf_p. The buf_p argument may be either a (void∗)mac_t, cor a (void∗)char∗ allocated by the mac_to_text() function.
c

290

26.3.3.3 Returns

291
292

Upon successful completion, the function mac_free() returns a value of 0. Otherwise, a value of −1 is returned and errno is set to indicate the error.

293

26.3.3.4 Errors

294
295
296

This standard does not specify any error conditions that are required to be
detected for the mac_free() function. Some errors may be detected under conditions that are unspecified by this part of the standard.

297

26.3.3.5 Cross-References

298
299

mac_from_text(),
26.3.4;
mac_get_fd(),
26.3.5;
mac_get_file(),mac_get_proc(), 26.3.7; mac_glb(), 26.3.8; mac_lub(), 26.3.9.

300

26.3.4 Convert Text MAC Label to Internal Representation

301

Function: mac_from_text()c26.3.6;c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
26.3 Functions

203

c

c

c

c

302

26.3.4.1 Synopsis

303#include <sys/mac.h>304

mac_t mac_from_text (const char ∗text_p));305

26.3.4.2 Description

306
307

The function mac_from_text() converts the text representation of a MAC label
text_p into its internal representation.

308
309
310
311

This function may cause memory to be allocated. The caller should free any
releasable memory, when the MAC label is no longer required, by calling
mac_free() with the mac_t as an argument. In event an error occurs, no memory
shall be allocated and NULL shall be returned.

312

26.3.4.3 Returns

313
314
315

Upon successful completion, the function mac_from_text() shall return a pointerto the MAC label. Otherwise, no space shall be allocated, a (mac_t) NULL pointerc
shall be returned, and errno shall be set to indicate the error.

316

26.3.4.4 Errors

317
318

If any of the following conditions occur, the mac_from_text() function shall return
a NULL pointer and set errno to the corresponding value:

319
320

[EINVAL]

The string text_p is not a valid textual representation of a MAC
label as defined by mac_valid().
−

321
322

[ENOMEM] The MAC label requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −323

26.3.4.5 Cross-References324

mac_free(), 26.3.3; mac_valid(), 26.3.15.

325

26.3.5 Get the Label of a File Designated by a File Descriptor

326

Function: mac_get_fd()327

26.3.5.1 Synopsis

328#include <sys/mac.h>329

mac_t mac_get_fd (int fildes))c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

204

26 Mandatory Access Control

c

330

26.3.5.2 Description

331
332
333
334

The mac_get_fd() function returns the MAC label associated with an open file.
The function accepts a valid file descriptor to the file, allocates memory in whichto store the MAC label to be returned and copies the file MAC label into the allocated memory.

335
336

A process can get the MAC label for any file for which the process has a valid filedescriptor and MAC read access.

337
338
339
340

This function may cause memory to be allocated. The caller should free any
releasable memory, when the MAC label is no longer required, by calling
mac_free() with the mac_t as an argument. In event an error occurs, no memory
shall be allocated and NULL shall be returned.

341

26.3.5.3 Returns

342
343
344

Upon successful completion, the function shall return a pointer to the MAC label. cOtherwise, no space shall be allocated, a (mac_t)NULL pointer shall be returned cand errno shall be set to indicate the error.

345

26.3.5.4 Errors

346
347

If any of the following conditions occur, the mac_get_fd() function shall return a(mac_t)NULL and set errno to the corresponding value:

348[EACCES]MAC read access is denied to the file referred to by fildes.

349[EBADF]The fildes argument is not a valid file descriptor.

350
351

[ENOMEM] The MAC label requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −352

26.3.5.5 Cross-References

353
354

mac_free(), 26.3.3; mac_get_file(), 26.3.6; mac_set_fd(), 26.3.10; mac_set_file(),26.3.11.

355

26.3.6 Get the Label of a File Designated by a Pathname356

Function: mac_get_file()357

26.3.6.1 Synopsis

358#include <sys/mac.h>359

mac_t mac_get_file (const char ∗path_p));

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
26.3 Functions

205

c

c

360

26.3.6.2 Description

361
362
363

The mac_get_file() function returns the MAC label associated with the pathname
pointed to by path_p. The function allocates memory in which to store the MAC
label to be returned and copies the file MAC label into the allocated memory.

364
365

A process can get the MAC label for any file for which the process has searchaccess to the path specified and MAC read access to the file.

366
367
368
369

This function may cause memory to be allocated. The caller should free any
releasable memory, when the MAC label is no longer required, by calling
mac_free() with the mac_t as an argument. In event an error occurs, no memory
shall be allocated and NULL shall be returned.

370

26.3.6.3 Returns

371
372
373

Upon successful completion, the function shall return a pointer to the MAC label. cOtherwise, no space shall be allocated, a (mac_t)NULL pointer shall be returned cand errno shall be set to indicate the error.

374

26.3.6.4 Errors

375
376

If any of the following conditions occur, the mac_get_file() function shall return a c(mac_t)NULL and set errno to the corresponding value:

377
378

[EACCES]

Search permission is denied for a component of the path prefix
or MAC read access to the file is denied.

379
380
381
382

[ENAMETOOLONG]
The length of the path_p argument exceeds {PATH_MAX} or apathname component is longer than {NAME_MAX} while{POSIX_NO_TRUNC} is in effect.

383
384

[ENOENT]

385
386[ENOMEM] The MAC label requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −387[ENOTDIR] A component of the path prefix is not a directory.

The named file/directory does not exist, or the path_p argument
points to an empty string.

388

26.3.6.5 Cross-References

389
390

mac_free(), 26.3.3; mac_get_fd(), 26.3.5; mac_set_fd(), 26.3.10; mac_set_file(),26.3.11.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

206

26 Mandatory Access Control

c

391

26.3.7 Get the Process Label

392

Function: mac_get_proc()393

26.3.7.1 Synopsis

394#include <sys/mac.h>395

mac_t mac_get_proc (void);

396

26.3.7.2 Description

397
398
399

The mac_get_proc() function returns the MAC label associated with the requesting process. The function allocates memory in which to store the MAC label to be
returned and copies the process MAC label into the allocated memory.

400

Any process may so query its MAC label.

401
402
403
404

This function may cause memory to be allocated. The caller should free any
releasable memory, when the MAC label is no longer required, by calling
mac_free() with the mac_t as an argument. In event an error occurs, no memory
shall be allocated and NULL shall be returned.

405

26.3.7.3 Returns

406
407
408

Upon successful completion, mac_get_proc() returns a pointer to the MAC label of+the process. Otherwise, no space shall be allocated, a (mac_t)NULL pointer shall cbe returned and errno shall be set to indicate the error.

409

26.3.7.4 Errors

410
411

If any of the following conditions occur, the mac_get_proc() function shall return ac(mac_t)NULL and set errno to the corresponding value:

412
413

[ENOMEM] The MAC label requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −414

26.3.7.5 Cross-References415

mac_free(), 26.3.3; mac_set_proc(), 26.3.12.

416

26.3.8 Compute the Greatest Lower Bound

417

Function: mac_glb()

cc

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
26.3 Functions

207

418

26.3.8.1 Synopsis

419#include <sys/mac.h>420

mac_t mac_glb (mac_t labela,, mac_t labelb));

421

26.3.8.2 Description

422
423
424
425

The function mac_glb() returns a pointer to the (valid) MAC label, if it exists, that+is dominated by both the MAC label labela and the MAC label labelb and dominates all other valid MAC labels that are dominated by both the MAC label
labela and the MAC label labelb.

426
427
428
429

This function may cause memory to be allocated. The caller should free any
releasable memory, when the MAC label is no longer required, by calling
mac_free() with the mac_t as an argument. In event an error occurs, no memory
shall be allocated and NULL shall be returned.

430

26.3.8.3 Returns

431
432
433

Upon successful completion, this returns a pointer to the allocated bounding MACc
label. Otherwise, no space shall be allocated, a (mac_t)NULL pointer shall be
returned, and errno shall be set to indicate the error.

434

26.3.8.4 Errors

435
436

If any of the following conditions occur, the mac_glb() function shall return a(mac_t)NULL and set errno to the corresponding value:

c

c

437
438

[EINVAL]At least one of the input labels is not a valid MAC label as −defined by mac_valid().

439[ENOENT]The bounding MAC label does not exist or is not valid.

440
441

[ENOMEM] The MAC label requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −442

26.3.8.5 Cross-References443

mac_free(), 26.3.3; mac_lub(), 26.3.9; mac_valid(), 26.3.15.

444

26.3.9 Compute the Least Upper Bound

445

Function: mac_lub()446

26.3.9.1 Synopsis

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

208

26 Mandatory Access Control

c

−

447

#include <sys/mac.h>448

mac_t mac_lub (mac_t labela,, mac_t labelb));

449

26.3.9.2 Description

450
451
452
453

The function mac_lub() returns a pointer to the (valid) MAC label (if it exists)that dominates both the MAC label labela and the MAC label labelb and is dominated by all other valid MAC labels that dominate both the MAC label labela andthe MAC label labelb.

454
455
456
457

This function may cause memory to be allocated. The caller should free any
releasable memory, when the MAC label is no longer required, by calling
mac_free() with the mac_t as an argument. In event an error occurs, no memory
shall be allocated and NULL shall be returned.

458

26.3.9.3 Returns

459
460
461

Upon successful completion, this function shall return a pointer to the bounding c
MAC label. Otherwise, a (mac_t)NULL pointer shall be returned and errno shall cbe set to indicate the error.

462

26.3.9.4 Errors

463
464

If any of the following conditions occur, the mac_lub() function shall return a(mac_t)NULL and set errno to the corresponding value:

c

c

465
466

[EINVAL]At least one of the input labels is not a valid MAC label as −defined by mac_valid().

467[ENOENT]The bounding MAC label does not exist or is not valid.

468
469

[ENOMEM] The MAC label requires more memory than is allowed by the
hardware or system-imposed memory management constraints. −470

26.3.9.5 Cross-References471

mac_free(), 26.3.3; mac_glb(), 26.3.8; mac_valid(), 26.3.15.

472

26.3.10 Set the Label of a File Identified by File Descriptor

473

Function: mac_set_fd()474

26.3.10.1 Synopsis

475#include <sys/mac.h>476

int mac_set_fd (int fildes, mac_t label)
);

−

c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
26.3 Functions

209

477

26.3.10.2 Description

478
479

This function sets the MAC label of a file to label. The function requires thatfildes be a valid file descriptor to indicate the file.

480
481
482
483
484

A process can set the MAC label for a file only if the process has a valid filedescriptor for the file and has MAC write access to the file. Additionally, only
processes with an effective user ID equal to the owner of the file or with appropriate privileges may change the label of the file. If {_POSIX_CAP} is defined, thenappropriate privilege shall include CAP_FOWNER.

485
486
487
488
489
490
491

The mac_set_fd() function shall fail if the new MAC label is not equivalent to the cfile’s previous label and the process does not possess appropriate privilege. If{_POSIX_CAP} is defined, and the new MAC label dominates, but is not cequivalent to the file’s previous MAC label, then appropriate privilege shall
include CAP_MAC_UPGRADE. If {_POSIX_CAP} is defined, and the new MAC clabel does not dominate the file’s previous MAC label then appropriate privilege
shall include CAP_MAC_DOWNGRADE.

492
493
494

It is implementation-defined whether an implementation will return [EBUSY] orwill perform revocation of access if other processes have current access to the fileat the time of MAC label modification.

495

26.3.10.3 Returns

496
497

Upon successful completion, the function shall return a value of 0. Otherwise, avalue of −1 shall be returned and errno shall be set to indicate the error.

498

26.3.10.4 Errors

499
500

If any of the following conditions occur, the mac_set_fd() function shall return −1
and set errno to the corresponding value:c

501[EACCES]MAC write access is denied to the file specified.

502[EBADF]The fildes argument is not a valid file descriptor.

503
504
505

[EBUSY]The file named by the fildes argument is currently in a state inwhich the implementation does not allow the label to bechanged.

506
507[EINVAL]

The MAC label label is not a valid MAC label as defined by −mac_valid().
−

508
509
510

[ENOTSUP] {_POSIX_MAC} is defined, but this function is not supported on c
the file referred to by fildes, i.e., {_POSIX_MAC_PRESENT} is
not in effect for the file referred to by fildes.

511
512

[EPERM]An attempt was made to change the MAC label of a file and theprocess does not possess appropriate privilege.

513
514

[EROFS]This function requires modification of a file system which iscurrently read-only.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

210

26 Mandatory Access Control

515

26.3.10.5 Cross-References516

mac_get_fd(), 26.3.5; mac_set_file(), 26.3.11; mac_valid(), 26.3.15.

517

26.3.11 Set the Label of a File Designated by Pathname

518

Function: mac_set_file()

519

26.3.11.1 Synopsis

520#include <sys/mac.h>521

int mac_set_file (const char ∗path_p, mac_t label));

522

26.3.11.2 Description

523

This function sets the MAC label of the pathname pointed to by path_p to label.

524
525
526
527
528

A process can set the MAC label for a file only if the process has search access tothe path and has MAC write access to the file. Additionally, only processes with
an effective user ID equal to the owner of the file or with appropriate privileges
may change the label of the file. If {_POSIX_CAP} is defined, then appropriate
privilege shall include CAP_FOWNER.

529
530
531
532
533
534
535

The mac_set_file() function shall fail if the new MAC label is not equivalent to thec
file’s previous MAC label and the process does not possess appropriate privilege.
If {_POSIX_CAP} is defined, and the new MAC label dominates, but is not
equivalent to the file’s previous MAC label, then appropriate privilege shall
include CAP_MAC_UPGRADE. If {_POSIX_CAP} is defined, and the new MAC
label does not dominate the file’s previous MAC label then appropriate privilege
shall include CAP_MAC_DOWNGRADE.

536
537
538

It is implementation-defined whether an implementation will return [EBUSY] orwill perform revocation of access if other processes have current access to the fileat the time of MAC label modification.

539

26.3.11.3 Returns

540
541

Upon successful completion, the function shall return a value of 0. Otherwise, avalue of −1 shall be returned and errno shall be set to indicate the error.

542

26.3.11.4 Errors

543
544

If any of the following conditions occur, the mac_set_file() function shall return −1
and set errno to the corresponding value:

545
546

[EACCES]c

Search permission is denied for a component of the path prefix
or MAC write access to the target file is denied.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
26.3 Functions

211

c

c

c

547
548
549

[EBUSY]The file or directory indicated by path_p is currently in a state inwhich the implementation does not allow the label to bechanged.

550
551[EINVAL]

The MAC label label is not a valid MAC label as defined by −mac_valid().

552
553
554
555

[ENAMETOOLONG]
The length of the path_p argument exceeds {PATH_MAX}, or apathname component is longer than {NAME_MAX} while{POSIX_NO_TRUNC} is in effect.

556
557

[ENOENT]

558[ENOTDIR] A component of the path prefix is not a directory.

559
560
561

[ENOTSUP] {_POSIX_MAC} is defined, but this function is not supported on c
the file specified, i.e., {_POSIX_MAC_PRESENT} is not in effectfor the file specified.

562
563

[EPERM]An attempt was made to change the MAC label of a file and theprocess does not possess appropriate privilege.

564
565

[EROFS]This function requires modification of a file system which iscurrently read-only.

The named file/directory does not exist, or the path_p argument
points to an empty string.
−566

26.3.11.5 Cross-References567

mac_get_file(), 26.3.6; mac_set_fd(), 26.3.10; mac_valid(), 26.3.15.

568

26.3.12 Set the Process Label

569

Function: mac_set_proc()570

26.3.12.1 Synopsis

571#include <sys/mac.h>572

int mac_set_proc (mac_t label));

573

26.3.12.2 Description

574
575
576
577

The mac_set_proc() function is used to set (write) the MAC label of the requestingprocess. The new label is specified by label. A process may only alter its MAC
label if it possesses appropriate privilege. If {_POSIX_CAP} is defined, thenappropriate privilege shall include CAP_MAC_RELABEL_SUBJ.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

212

26 Mandatory Access Control

c

c

578

26.3.12.3 Returns

579
580

Upon successful completion, mac_set_proc() shall return a value of 0. Otherwise,a value of −1 shall be returned and errno shall be set to indicate the error.

581

26.3.12.4 Errors

582
583

If any of the following conditions occur, the mac_set_proc() function shall return−1 and set errno to the corresponding value:

584
585

[EINVAL]

The MAC label label is not a valid MAC label as defined by −mac_valid().

586
587

[EPERM]

The process does not have appropriate privilege to perform theoperation requested.

588

26.3.12.5 Cross-References589

mac_valid(), 26.3.15.

590

26.3.13 Get the Size of a MAC Label

591

Function: mac_size()592

26.3.13.1 Synopsis

593#include <sys/mac.h>594

ssize_t mac_size (mac_t label));

595

26.3.13.2 Description

596
597
598

The mac_size() function returns the size in bytes of the MAC label specified bylabel if the label is valid. Note: this is the size of the internal MAC label, not thesize of the text representation as produced by the mac_to_text() function.

599

26.3.13.3 Returns

600
601

Upon successful completion, this function shall return the size of the MAC label.
Otherwise, a value of −1 shall be returned and errno

602

26.3.13.4 Errors

603
604

If any of the following conditions occur, the mac_size() function shall return −1
and set errno to the corresponding value:cc

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
26.3 Functions

213

605

[EINVAL]−

The MAC label label is invalid as defined by mac_valid().

606

26.3.13.5 Cross-References607

mac_valid(), 26.3.15.

608

26.3.14 Convert Internal MAC Label to Textual Representation

609

Function: mac_to_text()

610

26.3.14.1 Synopsis

611#include <sys/mac.h>612

char ∗mac_to_text (mac_t label,, size_t ∗len_p));613

26.3.14.2 Description

614
615
616
617
618
619
620
621
622

The function mac_to_text() converts the internal representation of the MAC label
pointed to by label into a human-readable, NULL terminated, character string.
The output of mac_to_text() shall be suitable for re-input as the text_p parameterto mac_from_text() in 26.3.4, or as the label operand to the setfmac utility as cdefined in section 11 of POSIX.2c on the same system or other systems with identical MAC label definitions. The function returns a pointer to the text representa- ction of the MAC label. If the pointer len_p is not NULL, the function shall returnthe length of the string (not including the NULL terminator) in the location
pointed to by len_p.

623
624
625
626

This function may cause memory to be allocated. The caller should free any
releasable memory, when the text label is no longer required, by calling
mac_free() with the string address as an argument. In event an error occurs, nomemory shall be allocated and NULL shall be returned.

627

26.3.14.3 Returns

628
629
630
631
632
633

Upon successful completion, the function mac_to_text() returns a pointer to thetext representation of the MAC label, and if the pointer len_p is not NULL,
returns the length of the string (not including the NULL terminator) in the location pointer to by len_p. Otherwise, no memory shall be allocated, the memoryreferred to by len_p shall be unchanged, a (char ∗) NULL pointer shall be
returned and errno shall be set to indicate the error.

634

26.3.14.4 Errors

635
636

NULL pointer and set errno to the corresponding value:c

If any of the following conditions occur, the mac_to_text() function shall return a

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

214

26 Mandatory Access Control

c

c

c

The MAC label label is not a valid MAC label as defined by −mac_valid().

637
638

[EINVAL]

639
640
641

[ENOMEM] The text to be returned requires more memory than is allowedby the hardware or system-imposed memory management constraints.
−

642

26.3.14.5 Cross-References643

mac_from_text(), 26.3.4; mac_valid(), 26.3.15; setfmac, POSIX.2c - 11.3.

644

26.3.15 Label Validity

645

Function: mac_valid()

646

26.3.15.1 Synopsis

647#include <sys/mac.h>648

int mac_valid (mac_t label));

649

26.3.15.2 Description

650
651

The mac_valid() function determines if label is a valid MAC label. The meaning −of validity is implementation-defined.
−

652

26.3.15.3 Returns

653
654
655

Upon successful completion, the function shall return 1 if label is valid, and 0 if it −is invalid. Otherwise a value of −1 shall be returned and errno is set to indicate
the error.

656

26.3.15.4 Errors

657
658
659

This standard does not specify any error conditions that are required to be
detected for the mac_valid() function. Some errors may be detected under conditions that are unspecified by this part of the standard.

660

26.3.15.5 Cross-References

661

None.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
26.3 Functions

215

c

c
c

Section 27: Information Labeling1

2

27.1 General Overview

3
4
5
6
7

This section describes the Information Label Option. The section defines anddiscusses the information label concepts, outlines the information label policy
adopted in this standard, and outlines the impact of information labels on existing POSIX.1 functions. Support for the interfaces defined in this section is
optional but shall be provided if the symbol {POSIX_INF} is defined.

8

27.1.1 Information Label Concepts

9

Information Labels

10
11
12
13

The Information Label is the item visible at the POSIX.1 interface that is used for
associating labeling information with data. This labeling information is not
related to Mandatory Access Control, nor does the information labeling policies inany way override the MAC or DAC options, if they are in effect.

14
15
16

In order to promote the flexibility with which conforming implementations may
define an information labeling policy, specific components of information labels
and their textual representation are not defined by this standard.

17

Information Label Relationships

18
19
20
21
22
23
24
25

Two relationships are defined between information labels: equivalence and dominance. A conforming implementation must provide the interfaces for determining
whether two information labels have these relationships. Note that it would be
acceptable for a conforming implementation to implement information labels insuch a manner that no information label is equivalent to, nor dominates, any
information label other than itself. Thus, while interfaces for determining dominance and equivalence must be provided, the detailed definitions of these relationships are left undefined.

26

Information Label Floating

27
28
29
30
31
32
33

The inf_float() operation is used in the statement of the information label policy.
The operation inf_float(inf_p1, inf_p2) returns an information label whose value isdependent on the values of inf_p1 and inf_p2 and the implementation-defined
floating policy. The precise definition of inf_float() is left to the conforming implementation, however, its intended use is described in 27.1.2. (As a result of thispermitted flexibility, a conforming implementation could, for example, choose toalways return just inf_p2.)

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
27.1 General Overview

217

34

Information Label Subjects

35
36
37
38

In the broad sense, a subject is an active entity that can cause information of any
kind to flow between controlled objects. Since processes are the only suchinterface-visible element in this standard, they are the only subjects treated in
the information label section.

39

Information Label Objects

40
41
42
43
44
45
46
47
48
49

Objects are passive entities that contain or receive data. Access to objects potentially implies access to the data they contain. However, objects not only containdata, but also possess attributes. The data portion of an object is that portion
that contains the bytes intended to be stored by the object (e.g., the bytes written
to a regular file comprise that file’s data portion). The attribute portion of an
object is that portion that contains descriptive, or control, information pertaining
to the object (e.g., a regular file’s access and modification times, permission bits,
length, and so forth). The granting of access to an object’s data and to that object’s
attributes may be based upon different criteria. Information labeling, as
described in greater detail below, relies on this distinction.

50
51
52
53

The objects to which information labeling applies include the data portion of thefollowing objects: regular files, FIFO-special files, and (unnamed) pipes. Notethat conforming implementations may choose to apply the information labelingpolicy more broadly by including, for example, object attributes.

54

27.1.2 Information Label Policy

55
56

The information label policy presented below is logically structured into the following named policies:

57

I: The fundamental statement of information labeling58

FI.∗: The refinements of I that apply to file objects (FI.1, FI.2, etc.)

59

PI.∗: The refinements of I that apply to process objects

60

The following information labeling requirement is imposed:

61
62
63

Each subject and each object that contains data, as opposed to attributes (e.g., mandatory access control label and access time), shall haveas an additional attribute an information label at all times.

64
65

Policies for initial assignment and constraints on the changing of information
labels are given in the refining policies below.

66

The fundamental information label policy I is:

67
68
69
70
71
72

I:

When subjects cause data (as opposed to attributes) to flow from asource with information label inf_p1 to a destination with information label inf_p2, the destination’s information label shall be
automatically set to the value returned by inf_float (inf_p1, inf_p2).

There are several important exceptions or limitations to the application of I and
its refinements to POSIX.1 functions:
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

218

27 Information Labeling

73

Processes Possessing Appropriate Privilege

74
75
76
77
78
79
80
81
82

Implicit in the statement of I is the assumption that none of the policies
need necessarily apply to processes possessing appropriate privilege
unless explicitly stated. If {POSIX_CAP} is defined, the list of capabilities that satisfy the appropriate privilege requirements are defined bythis standard in section 25.2. Note that conforming implementations
can further restrict the policies that can be bypassed using capabilities.
For example, if {POSIX_CAP} is defined, the effect of the
CAP_INF_RELABEL_OBJ capability may be limited to a range of information labels, where such a range is implementation defined.

83

Additional Implementation-Defined Floating

84
85
86
87
88
89

It is understood that a conforming implementation may cause the floating described above through the automatic application of the inf_float()
operation to occur at other times in addition to those covered by the general policy. Additionally it may cause other changes (including ‘‘downward’’ adjustments) of information labels under implementation-defined
circumstances.

90

27.1.2.1 FI: File Function Policies

91
92
93
94

Information labeling for files results from the application of basic policies (FI.∗) tothe file data object. The straightforward application of these rules to the object
model determines the specific information label restrictions for a large number offile-related interfaces.

95
96
97
98

The object that encompasses a POSIX.1 file is defined to consist of a data portion,
and an attribute portion that contains the POSIX-defined attributes including theinformation label. For the purposes of information labeling, the information labelof a file applies only to the data portion of the file.

99

The following policy rules apply:

100
101
102

FI.1: When an process with information label inf_p1 writes data to a file withinformation label inf_p2, the information label of the file shall automatically be set to the value returned by inf_float(inf_p1, inf_p2).

103
104

FI.2: The information label of a newly created file object shall automatically be
set to a value that dominates the value returned by inf_default().

105
106
107
108
109
110

A conforming implementation may modify these policy rules for certain objects.
For example, some objects may be designated ‘‘non-floating.’’ The information
label of these objects will not change on process writes. Other objects may support
additional or finer-grained labeling which will modify the application of FI.1 (aswell as PI.1 below.) Precisely which objects are subject to modified rules is
implementation-defined.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
27.1 General Overview

219

111

27.1.2.1.1 POSIX.1 Functions Covered by IL File Policies

112

This policy is applied to the following POSIX.1 functions:

113

Table 27-1 − POSIX.1 Functions Covered by Information Label File Policies

114
115
116

Existing
POSIX.1
Function
Sectioni
iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

117
118
119
120
121

creat
mkfifo
open
pipe
write

122
123
124

New
POSIX.1eFunction
Synopsisi
iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

125
126
127
128
129

aud_write
inf_get_fd
inf_get_file
inf_set_fd
inf_set_file

5.3.2
5.4.2
5.3.1
6.1.1
6.4.2

Write an Audit Record
Get the Information Label of a File Identified by File Descriptor
Get the Information Label of a File Identified by Pathname
Set the Information Label of a File Identified by File Descriptor
Set the Information Label of a File Identified by Pathname

13027.1.2.2 PI: Process Function Policies

131
132

Information labeling for processes stems from the application of the basic information label policy to the few affected POSIX.1 functions.

133
134

When treated as an object, the process shall consist of its internal data (including
the environment data), its executable image, and its status information.

135

The following policy rules apply:

136
137
138

PI.1: When a process with information label inf_p1 reads data from a file withinformation label inf_p2, the information label of the process shall be
automatically set to the value returned by inf_float(inf_p2, inf_p1).

139
140
141

PI.2: When a process with information label inf_p1 executes a file with information label inf_p2, the information label of the process shall be
automatically set to the value returned by inf_float(inf_p2, inf_p1).

142
143

PI.3: A newly created process shall be assigned the information label of thecreating subject (process).

144
145
146
147

As mentioned previously, a conforming implementation may modify these rules
for certain objects. For example, some objects may support additional or finergrained labeling which will modify the application of PI.1. Precisely which
objects are subject to modified rules is implementation defined.

148

27.1.2.2.1 POSIX.1 Functions Covered by IL Process Policies

149

This policy is applied to the following POSIX.1 functions:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

220

27 Information Labeling150

Table 27-2 − POSIX.1 Functions Covered by Information Label Process Policies

151
152
153

Existing
POSIX.1
Function
Sectioni iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

154
155
156
157
158
159
160
161

execl
execv
execleexecveexeclpexecvp
fork
read

162
163
164

New
POSIX.1eFunction
Synopsisi iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii

165
166
167

aud_read
inf_get_proc
inf_set_proc

3.1.2
3.1.2
3.1.2
3.1.2
3.1.2
3.1.2
3.1.1
6.4.1

Read an Audit Record
Get the Process Information LabelSet the Process Information Label

168

27.2 Header

169
170
171
172

Some of the data types used by the information label functions are not defined aspart of this standard, but shall be implementation-defined. If {POSIX_INF} isdefined, these types shall be defined in the header <sys/inf.h>, which contains
definitions for at least the following type.

173

27.2.1 inf_t

174
175
176

This type defines a pointer to an ‘‘exportable’’ object containing an information
label. The object is opaque, persistent, and self-contained. Thus, the object can becopied by duplicating the bytes without knowledge of any underlying structure.

177

27.3 Functions

178
179
180
181
182
183
184

The functions in this section comprise the set of services that permit a process toget, set, and manipulate information labels. Support for the information label
facility functions described in this section is optional. If the symbol{_POSIX_INF} is defined, the implementation supports the information label coption and all of the information label functions shall be implemented as
described in this section. If {_POSIX_INF} is not defined, the result of calling any cof these functions is unspecified.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
27.3 Functions

221

185
186
187

The error [ENOTSUP] shall be returned in those cases where the system supports
the information label facility but the particular information label operation cannot be applied because of restrictions imposed by the implementation.
−

188

27.3.1 Initial Information Label

189

Function: inf_default()

190

27.3.1.1 Synopsis

191#include <sys/inf.h>192

inf_t inf_default (void)

193

27.3.1.2 Description

194
195
196

The inf_default() function returns a pointer to an information label with an initial+
information label value that a conforming application may associate with newlycreated or fully truncated objects.

197
198
199
200

The system may allocate space for the information label to be returned. The
caller should free any releasable memory when the new label is no longer
required by calling inf_free() with the inf_t as an argument. In the event an errorccoccurs, no memory shall be allocated and (inf_t)NULL shall be returned.

201
202
203
204
205

The precise method by which this label is determined is implementation-defined
and therefore may vary arbitrarily (e.g., based on process ID). As a result, the initial information label may not be the same on all newly created objects. However,this label is guaranteed to be a valid label which, if applied to a newly-createdobject, will be consistent with the implementation’s information label policy.

206

27.3.1.3 Returns

207
208
209

The function inf_default() returns a pointer to the initial information label unless c
one of the errors below occurs, in which case no space is allocated, a value of(inf_t)NULL is returned, and errno is set to indicate the error.

210

27.3.1.4 Errors

211
212

If any of the following conditions occur, the inf_default() function shall return avalue of (inf_t)NULL and set errno to the corresponding value:
c

213
214
215

[ENOMEM] The label to be returned required more memory than wasallowed by the hardware or by system-imposed memory management constraints.
−c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

222

27 Information Labeling

c

216

27.3.1.5 Cross-References217

inf_free(), 27.3.5; inf_set_fd(), 27.3.10; inf_set_file(), 27.3.11.

218

27.3.2 Test Information Labels For Dominance219

Function: inf_dominate()

22027.3.2.1 Synopsis

221#include <sys/inf.h>222

int inf_dominate (inf_t labela,, inf_t labelb));

223

27.3.2.2 Description

224
225
226
227
228

The inf_dominate() function determines whether labela dominates labelb. The
precise method for determining dominance is implementation-defined. Dominance includes equivalence. Hence, if one label is equivalent to another, then ceach shall dominate the other. Note that it is possible for neither of two labels todominate the other.
−229

27.3.2.3 Returns

230
231
232

The function inf_dominate() returns 1 if labela dominates labelb. A value of 0 is
returned if labela does not dominate labelb. Otherwise, a result of −1 is returned,
and errno is set to indicate the error.

233

27.3.2.4 Errors

234
235

If any of the following conditions occur, the inf_dominate() function shall return−1 and set errno to the corresponding value:

236
237

[EINVAL]c

One or both of the labels is not a valid information label as
defined by inf_valid().
−238

27.3.2.5 Cross-References239

inf_equal(), 27.3.3; inf_valid(), 27.3.15.

240

27.3.3 Test Information Labels For Equivalence

241

Function: inf_equal()

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
27.3 Functions

223

242

27.3.3.1 Synopsis

243#include <sys/inf.h>244

int inf_equal (inf_t labela,, inf_t labelb));

245

27.3.3.2 Description

246
247

The inf_equal() function determines whether labela is equivalent to labelb. The
precise method for determining equivalence is implementation-defined.

248
249

This function is provided to allow conforming applications to test for equivalencesince a comparison of the labels themselves may yield an indeterminate result. c

250

27.3.3.3 Returns

251
252
253

The function inf_equal() returns 1 if labela is equivalent to labelb. A value of 0 is
returned if labela not equivalent to labelb. Otherwise, a value of −1 is returned,
and errno is set to indicate the error.

254

27.3.3.4 Errors

255
256

If any of the following conditions occur, the inf_equal() function shall return −1
and set errno to the corresponding value:

257
258

[EINVAL]cc

One or both of the labels is not a valid information label as
defined by inf_valid().
−259

27.3.3.5 Cross-References260

inf_dominate(), 27.3.2; inf_valid(), 27.3.15.

261

27.3.4 Floating Information Labels

262

Function: inf_float()263

27.3.4.1 Synopsis

264#include <sys/inf.h>265

inf_t inf_float (inf_t labela,, inf_t labelb));

266

27.3.4.2 Description

267
268
269

The inf_float() function returns a pointer to an information label that represents a+
combination of labela and labelb in a manner dependent on the implementationdefined floating policy.

270
271
272

The system may allocate space for the information label to be returned. The
caller should free any releasable memory when the new label is no longer
required by calling inf_free() with the returned inf_t as an argument. In the +c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

224

27 Information Labeling

273
274

event an error occurs, no memory shall be allocated and (inf_t)NULL shall be
returned.

275
276
277
278

Note, that the notion of floating presupposes the introduction of data with one
label into a separately labeled subject or object. The labela argument represents
the information label of the data being introduced, the argument labelb
represents the subject’s or object’s current information label.

279

27.3.4.3 Returns

280
281
282

Upon successful completion, this function returns a pointer to the new informa- −tion label. Otherwise, no space is allocated, a value of (inf_t)NULL is returned, cand errno is set to indicate the error.

283

27.3.4.4 Errors

284
285

If any of the following conditions occur, the inf_float() function shall return acvalue of (inf_t)NULL and set errno to the corresponding value:

286
287

[EINVAL]

288
289
290

[ENOMEM] The label to be returned required more memory than wasallowed by the hardware or by system-imposed memory management constraints.
−

One or both of the labels is not a valid information label as
defined by inv_valid()291

27.3.4.5 Cross-References292

inf_free(), 27.3.5; inf_valid(), 27.3.15.

293

27.3.5 Free Allocated Information Label Memory

294

Function: inf_free()295

27.3.5.1 Synopsis

296#include <sys/inf.h>297

int inf_free (void ∗buf_p));298

27.3.5.2 Description

299
300
301

The inf_free() function frees any releasable memory currently allocated to thebuffer identified by buf_p. The buf_p argument may be either a (void∗)inf_t, or a c(void∗)char∗ allocated by the inf_to_text() function.

c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
27.3 Functions

c

225

302

27.3.5.3 Returns

303
304

Upon successful completion, the function inf_free() returns a value of 0. Otherwise, a value of −1 is returned and errno is set to indicate the error.

305

27.3.5.4 Errors

306
307
308

This standard does not specify any error conditions that are required to be
detected for the inf_free() function. Some errors may be detected under conditions cthat are unspecified by this part of the standard.

309

27.3.5.5 Cross-References

310
311

inf_default(), 27.3.1; inf_float(), 27.3.4; inf_get_fd(), 27.3.7; inf_get_file(), 27.3.8;
inf_get_proc(), 27.3.9; inf_from_text(), 27.3.6; inf_to_text(), 27.3.14.

312

27.3.6 Convert Text Label to Internal Representation

313

Function: inf_from_text()

314

27.3.6.1 Synopsis

315#include <sys/inf.h>316

inf_t inf_from_text (const char ∗text_p));317

27.3.6.2 Description

318
319
320

The inf_from_text() function converts the text representation of an information
label, text_p into its internal representation, and returns a pointer to a copy of theinternal representation.

321
322
323
324

The system may allocate space for the information label to be returned. The
caller should free any releasable memory when the new label is no longer
required by calling inf_free() with the inf_t as an argument. In the event an errorccoccurs, no memory shall be allocated and (inf_t)NULL shall be returned.

325

27.3.6.3 Returns

326
327
328

Upon successful completion, this function returns a pointer to the information −label. Otherwise, no space is allocated, a value of (inf_t)NULL is returned, and cerrno is set to indicate the error.

329

27.3.6.4 Errors

330
331

If any of the following conditions occur, the inf_from_text() function shall return acvalue of (inf_t)NULL and set errno to the corresponding value:cc

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

226c

27 Information Labeling

332
333

[EINVAL]

text_p is not a valid textual representation of an information
label as defined by inf_valid().

334
335
336

[ENOMEM] The label to be returned required more memory than wasallowed by the hardware or by system-imposed memory management constraints.
−

337

27.3.6.5 Cross-References338

inf_free(), 27.3.5; inf_to_text(), 27.3.14; inf_valid(), 27.3.15.

339

27.3.7 Get the Information Label of a File Identified by File Descriptor

340

Function: inf_get_fd()341

27.3.7.1 Synopsis

342#include <sys/inf.h>343

inf_t inf_get_fd (int fildes));

344

27.3.7.2 Description

345
346
347

The inf_get_fd() function returns the information label associated with a file. The
function accepts a valid file descriptor and returns a pointer to the information
label of the file referenced by the descriptor.

348
349
350
351

The system may allocate space for the information label to be returned. The
caller should free any releasable memory when the new label is no longer
required by calling inf_free() with the inf_t as an argument. In the event an errorccoccurs, no memory shall be allocated and (inf_t)NULL shall be returned.

352
353
354

A process can get the information label of any file for which the process has avalid file descriptor. If {_POSIX_MAC} is defined, the process must also have
MAC read access to the file.

355

27.3.7.3 Returns

356
357
358

Upon successful completion, this function returns the information label. Other- cwise, no space is allocated, a value of (inf_t)NULL is returned, and errno is set to cindicate the error.

359

27.3.7.4 Errors

360
361

If any of the following conditions occur, the inf_get_fd() function shall return acvalue of (inf_t)NULL and set errno to the corresponding value:

362[EACCES]c

The required access to the file referred to by fildes was denied.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
27.3 Functions

227

c

363

[EBADF]The fildes argument is not a valid file descriptor.

364
365
366

[ENOMEM] The label to be returned required more memory than wasallowed by the hardware or by system-imposed memory management constraints.
−

367

27.3.7.5 Cross-References368

inf_free(), 27.3.5; inf_get_file(), 27.3.8; inf_set_fd(), 27.3.10.

369

27.3.8 Get the Information Label of a File Identified by Pathname370

Function: inf_get_file()371

27.3.8.1 Synopsis

372#include <sys/inf.h>373

inf_t inf_get_file (const char ∗path_p));374

27.3.8.2 Description

375
376
377

The inf_get_file() function returns the information label associated with a file.
The function accepts a pathname to indicate the file. The function returns apointer to the information label of the pathname pointed to by path_p.

378
379
380
381

The system may allocate space for the information label to be returned. The
caller should free any releasable memory when the new label is no longer
required by calling inf_free() with the inf_t as an argument. In the event an errorccoccurs, no memory shall be allocated and (inf_t)NULL shall be returned.

382
383
384

A process can get the information label of any file for which the process has
search access to the path specified. If {_POSIX_MAC} is defined, the process mustc
also have MAC read access to the file.

385

27.3.8.3 Returns

386
387
388

Upon successful completion, this function returns the information label. Other- cwise, no space is allocated, a value of (inf_t)NULL is returned, and errno is set to cindicate the error.

389

27.3.8.4 Errors

390
391

If any of the following conditions occur, the inf_get_file() function shall return acvalue of (inf_t)NULL and set errno to the corresponding value:

c

392
393

[EACCES]

Search permission is denied for a component of the path prefixor the required access to path_p is denied.

394
395

[ENAMETOOLONG]
The length of the pathname exceeds {PATH_MAX}, or a
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

228

27 Information Labeling

396
397

pathname component is longer than {NAME_MAX} while{POSIX_NO_TRUNC} is in effect.

398
399

[ENOENT]The named file does not exist or the path_p argument points toan empty string.

400
401
402

[ENOMEM] The label to be returned required more memory than wasallowed by the hardware or by system-imposed memory management constraints.
−

403[ENOTDIR] A component of the path prefix is not a directory.

404

27.3.8.5 Cross-References405

inf_free(), 27.3.5; inf_get_fd(), 27.3.7; inf_set_file(), 27.3.11.

406

27.3.9 Get the Process Information Label

407

Function: inf_get_proc()408

27.3.9.1 Synopsis

409#include <sys/inf.h>410

inf_t inf_get_proc (void);

411

27.3.9.2 Description

412
413

The inf_get_proc() function returns a pointer to the information label associatedwith the requesting process.

414
415
416
417

The system may allocate space for the information label to be returned. The
caller should free any releasable memory when the new label is no longer
required by calling inf_free() with the inf_t as an argument. In the event an errorccoccurs, no memory shall be allocated and (inf_t)NULL shall be returned.

418

27.3.9.3 Returns

419
420
421

Upon successful completion, this function returns the information label. Other- cwise, no space is allocated, a value of (inf_t)NULL is returned, and errno is set to cindicate the error.

422

27.3.9.4 Errors

423
424

If any of the following conditions occur, the inf_get_proc() function shall return acvalue of (inf_t)NULL and set errno to the corresponding value:

425
426
427

[ENOMEM] The label to be returned required more memory than wasallowed by the hardware or by system-imposed memory management constraints.
−c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
27.3 Functions

229

428

27.3.9.5 Cross-References429

inf_free(), 27.3.5; inf_set_proc(), 27.3.12.

430

27.3.10 Set the Information Label of a File Identified by File Descriptor

431

Function: inf_set_fd()432

27.3.10.1 Synopsis

433#include <sys/inf.h>434

int inf_set_fd (int fildes,, inf_t label));

435

27.3.10.2 Description

436
437
438

The inf_set_fd() function sets (writes) the information label of a file. The new
information label is label. The function accepts a valid file descriptor to indicate
the file.

439
440
441
442
443
444
445
446

A process can set the information label for a file using this function only if theprocess has a valid file descriptor for the file. If {_POSIX_MAC} is defined, the cprocess must have mandatory write access to the file. Use of this function may
also require appropriate privilege. If {_POSIX_CAP} is defined, and the effective cuser ID of the process is not equal to the file owner, appropriate privilege includes
the CAP_FOWNER capability. In addition, if label is not equivalent to the information label associated with the file referred to by fildes, appropriate privilege
includes the CAP_INF_RELABEL_OBJ capability.

447

27.3.10.3 Returns

448
449

Upon successful completion, this function returns a value of 0. Otherwise, a valueof −1 is returned and errno is set to indicate the error.

450

27.3.10.4 Errors

451
452

If any of the following conditions occur, the inf_set_fd() function shall return −1
and set errno to the corresponding value:c453[EACCES]The required access to the file referred to by fildes is denied.

454[EBADF]The fildes argument is not a valid file descriptor.

455
456

[EINVAL]

The label in label is not a valid information label as defined by
inf_valid().
−

457
458

[ENOTSUP] pathconf() indicates that {_POSIX_INF_PRESENT} is not in
effect for the file referenced.

459[EPERM]

The process does not have appropriate privilege to perform thisWITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

230

27 Information Labeling

460
461
462

operation.
[EROFS]This function requires modification of a file system which iscurrently read-only.

463

27.3.10.5 Cross-References464

inf_get_fd(), 27.3.7; inf_set_file(), 27.3.11; inf_valid(), 27.3.15.

465

27.3.11 Set the Information Label of a File Identified by Pathname466

Function: inf_set_file()

467

27.3.11.1 Synopsis

468#include <sys/inf.h>469

int inf_set_file (const char ∗path_p,, inf_t label));

470

27.3.11.2 Description

471
472

The inf_set_file() function sets (writes) the information label of a file. The new
information label is label. The function accepts a pathname to indicate the file.

473
474
475
476
477
478
479
480

A process can set the information label for a file only if the process has searchaccess to the path specified. If {_POSIX_MAC} is defined, the process must have c
mandatory write access to the file. Use of this function may also require appropriate privilege. If {_POSIX_CAP} is defined, and the effective user ID of the process c
is not equal to the file owner, then appropriate privilege includes the
CAP_FOWNER capability. In addition, if label is not equivalent to the information label associated with the file referred to by path_p, appropriate privilege
includes the CAP_INF_RELABEL_OBJ capability.

481

27.3.11.3 Returns

482
483

Upon successful completion, this function returns a value of 0. Otherwise, a valueof −1 is returned and errno is set to indicate the error.

484

27.3.11.4 Errors

485
486

If any of the following conditions occur, the inf_set_file() function shall return −1
and set errno to the corresponding value:

c

487
488

[EACCES]

Search permission is denied for a component of the path prefixor the required access to path_p is denied.

489
490

[EINVAL]

The label in label is not a valid information label as defined by
inf_valid().

491
492

[ENAMETOOLONG]
The length of the pathname exceeded {PATH_MAX}, or a
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

27.3 Functions

231

493
494

pathname component is longer than {NAME_MAX} while{POSIX_NO_TRUNC} is in effect.

495
496

[ENOENT]The named file does not exist or the path_p argument points toan empty string.
−

497[ENOTDIR] A component of the path prefix is not a directory.

498
499

[ENOTSUP] pathconf() indicates that {_POSIX_INF_PRESENT} is not in
effect for path_p.

500
501

[EPERM]

The process does not have appropriate privilege to perform thisoperation.

502
503

[EROFS]This function requires modification of a file system which iscurrently read only.

504

27.3.11.5 Cross-References505

inf_get_file(), 27.3.8; inf_set_fd(), 27.3.10; inf_valid(), 27.3.15.

506

27.3.12 Set the Process Information Label

507

Function: inf_set_proc()508

27.3.12.1 Synopsis

509#include <sys/inf.h>510

int inf_set_proc (inf_t label));

511

27.3.12.2 Description

512
513
514
515
516

The inf_set_proc() function sets (writes) the information label of the requestingprocess. The new information label is label. If label is not equivalent to the information label associated with the process, then appropriate privilege is required
for this operation. If {_POSIX_CAP} is defined, appropriate privilege includes the c
CAP_INF_RELABEL_SUBJ capability.

517

27.3.12.3 Returns

518
519

Upon successful completion, inf_set_proc() returns a value of 0. Otherwise, avalue of −1 is returned and errno is set to indicate the error.

520

27.3.12.4 Errors

521
522

If any of the following conditions occur, the inf_set_proc() function shall return −1
and set errno to the corresponding value:c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

232

27 Information Labeling

523
524

[EINVAL]

The label in label is not a valid information label as defined by
inf_valid().
−

525
526

[EPERM]

The process does not have appropriate privilege to perform thisoperation.

527

27.3.12.5 Cross-References528

inf_get_proc(), 27.3.9; inf_valid(), 27.3.15.

529

27.3.13 Get the Size of an Information Label

530

Function: inf_size()531

27.3.13.1 Synopsis

532#include <sys/inf.h>533

ssize_t inf_size (inf_t label));

534

27.3.13.2 Description

535
536

The inf_size() function returns the size in bytes of the internal representation of
the information label in label, if it is valid.

537

27.3.13.3 Returns

538
539

Upon successful completion, the function returns the size of the information label.
Otherwise, a value of −1 is returned and errno is set to indicate the error.

540

27.3.13.4 Errors

541
542

If any of the following conditions occur, the inf_size() function shall return −1 andset errno to the corresponding value:

543
544

[EINVAL]c

The label argument is not a valid information label as defined by
inf_valid().
−545

27.3.13.5 Cross-References546

inf_free(), 27.3.5; inf_valid(), 27.3.15.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
27.3 Functions

233

547

27.3.14 Convert Internal Label Representation to Text

548

Function: inf_to_text()

549

27.3.14.1 Synopsis

550#include <sys/inf.h>551

char ∗inf_to_text (inf_t label,, size_t ∗len_p));552

27.3.14.2 Description

553
554
555
556
557
558
559
560

The inf_to_text() function converts the information label contained in label into ahuman readable, NULL-terminated, character string which shall be suitable forthe text_p parameter to inf_from_text() in section 27.3.9 and for re-input as the
inflabel operand to the setfinf utility as defined in section 12 of POSIX.2c. This function −returns a pointer to the string. If the pointer len_p is not NULL, the function shall also returnthe length of the string (not including the NULL terminator) in the location pointed to by
len_p. The information label in label shall be completely represented in the returned character string.

561
562
563
564

The system may allocate space for the string to be returned. The caller should free any releasable memory when the string is no longer required by calling inf_free() with the char ∗ as an cargument. In the event an error occurs, no memory shall be allocated and (inf_t)NULL shall cbe returned.

565

27.3.14.3 Returns

566
567
568
569

Upon successful completion, inf_to_text() returns a pointer to the text representa- −tion. Otherwise, in all cases, the memory referred to by len_p shall remainunchanged, a value of (char ∗)NULL is returned, and errno is set to indicate the cerror.

570

27.3.14.4 Errors

571
572

If any of the following conditions occur, the inf_to_text() function shall return acvalue of (char ∗)NULL and set errno to the corresponding value:

c

573
574

[EINVAL]

The label in label is not a valid information label as defined by
inf_valid().

575
576
577

[ENOMEM] The text to be returned required more memory than was allowedby the hardware or by system-imposed memory management
constraints.
−

578

27.3.14.5 Cross-References579

inf_free(), 27.3.5; inf_from_text(), 27.3.6; inf_valid(), 27.3.15; setfinf, 12.3.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

234

27 Information Labeling580

27.3.15 Information Label Validity

581

Function: inf_valid()582

27.3.15.1 Synopsis

583#include <sys/inf.h>584

int inf_valid (inf_t label));

585

27.3.15.2 Description

586
587
588
589
590

The inf_valid() function determines whether the label in label is a valid information label. The precise meaning of validity is implementation-defined. Examples
of some reasons why a label may be considered invalid include: the label is malformed, the label contains components that are not currently defined on the system, or the label is simply forbidden to be dealt with by the system.

591

27.3.15.3 Returns

592
593

Upon successful completion, the function returns 1 if label is valid, and 0 if it isinvalid. Otherwise, a value of −1 is returned and errno is set to indicate the error.

594

27.3.15.4 Errors

595
596
597

This standard does not specify any error conditions that are required to be
detected for the inf_valid() function. Some errors may be detected under conditions that are unspecified by this part of the standard.

598

27.3.15.5 Cross-References

599

None.

c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
27.3 Functions

235

c

c

1

Annex B(informative)

2

Revisions to Rationale and Notes

3

B.1 Revisions to Scope and Normative References

45⇒ B.1.1 Scope This rationale is to be revised and integrated appropriately into
the scope rationale when POSIX.1e is approved:

6
7
8
9
10
11
12
13
14

The goal of this standard is to specify an interface to protection, audit, andcontrol functions for a POSIX.1 system in order to promote application portability. Implementation of any or all of these interfaces does not ensure thesecurity of the conforming system or of conforming applications. In particular,
there is no assurance that a vendor will implement the interfaces in a secure
fashion or that the implementation of the interfaces will not cause additional
security flaws. Even if such assurances were required or provided, there aremany more aspects of a ‘‘secure system’’ than the interfaces defined in thisstandard.

15
16
17
18

This interface is extendible to allow for innovations that provide greater (ordifferent) security functions in various markets. It is expected that conforming
implementations may augment the mechanisms defined in this standard andmay also provide security functions in areas not included in this standard.

19
20
21
22
23

It was not a goal of this document to address assurance requirements whichconstrain the implementation and not the interface. POSIX.1 standards define
operating system interfaces only and attempt to allow for the greatest possible
latitude in implementation so as to promote greater acceptance of the standards.

24
25
26
27
28
29
30
31
32
33

The United States Department of Defense Trusted Computer System Evaluation Criteria (TCSEC) document was a main source of requirements for thisstandard. The TCSEC is a comprehensive set of guidelines which has received
extensive review. The TCSEC requirements are themselves general, and havebeen used to guide the development of a variety of computer systems, ranging
from general purpose time-sharing systems to specialized networking components. The TCSEC has received broad distribution and acceptance and has
been the basis for much of the work which followed it. Functions are drawn
from all TCSEC classes where it is agreed that inclusion of the function in thestandard will enhance application portability.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.1 Revisions to Scope and Normative References

237

34
35
36

Even though the TCSEC was a source of requirements for the interfaces
defined in this standard, this standard is not to be construed as defining a setof interfaces intended to satisfy the requirements of any particular level.

3738⇒ B.1.3.6 Supported Security Mechanisms (POSIX.1: line 474) Add the following new section:

39

B.1.3.6 Supported Security Mechanisms

40
41
42
43
44

The security mechanisms supported by this standard were chosen for their generality. The specific interfaces defined were selected because they were perceived
to be generally useful to applications (trusted and untrusted). Two mechanisms,
access control lists and privilege, are defined specifically to address areas in the
POSIX.1 standard that were deferred to this standard.

45
46⇒ B.1.3.7 Unsupported Security Mechanisms Add the following new sections
B.1.3.7 - B.1.3.7.11:

47

B.1.3.7 Unsupported Security Mechanisms

48
49
50

The purpose of this standard is to provide for application portability between conforming systems. As a result, this standard does not address several functional
security-related issues. Specifically, the POSIX.1e standard does not address:

51(1) Identification and Authentication

52(2) Networking Services and Protocols

53(3) Administrative Services and Management of Security Information

54(4) Covert Channels

55(5) Assurance Issues

56(6) Evaluation Ratings Based on Current Trust Criteria

57(7) The General Terminal Interface as described in the POSIX.1 standard

58
59

The rationale for excluding these and other potentially relevant topics is provided
below.

60

B.1.3.7.1 Identification and Authentication

61
62
63
64

I&A mechanisms are being deferred to a future version of this standard. It was
felt that the I&A mechanism should take into consideration third-party authentication schemes. It was also felt that deferring this area to a future standard
would allow existing practice to become more stabilized prior to standardization.

−

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

238

B Revisions to Rationale and Notes

65

B.1.3.7.2 Networking Services

66
67
68
69
70

Networking services are being deferred to a future version of this standard. Thiswas done to allow the various POSIX Distributed Services working groups tofurther progress their work prior to standardization. It was also felt that deferring this area to a future standard would allow existing practice to become morestabilized prior to standardization.

71
72

B.1.3.7.3 Administrative Services and Management of Security Information

73
74
75
76
77
78
79

Administrative services and the management of security information are being
deferred to a future version of this standard. This was done to allow the POSIX
System Administration working group to further progress their work prior to −standardization. System administration will ultimately be standardized througha document that is distinct from the POSIX.1 or POSIX.2 standards. The current
POSIX.1e work is limited to modifications to the POSIX.1 and POSIX.2 standards.
−

80

B.1.3.7.4 Covert Channels

81
82
83
84
85

Covert channel analysis is undertaken from the perspective of the interface, andnot the underlying implementation. This means that covert channels associatedwith resource exhaustion, e.g., process IDs, i-nodes, and file descriptors, are notconsidered. Covert channels visible at the interface are treated. These include theuse of exclusive locks and the updating of file access times.

86

B.1.3.7.5 Assurance Issues

87
88
89
90

Assurance issues that do not require function or utility interfaces are not explicitly treated as part of the standard. But assurance requirements that constrain
the system interfaces are implicitly part of the standard. The principal issues
here are:91

B.1.3.7.5.1 Modularity, Security Kernels, Software Engineering

92
93

These are mostly kernel internals design and implementation issues, which arebeyond the scope of POSIX standards.

94

B.1.3.7.5.2 Minimality

95
96

The TCB minimality assurance requirement is not addressed by this standard.
This is an implementation question only.

97
98
99
100
101

The minimality requirement, introduced at the B3 level of the TCSEC, does notconstrain the definition of any POSIX.1e interface, because minimality pertains
only to the definition of the partition between the trusted code of the system,i.e.,
the TCB, and the untrusted code of the system. This standard does not specify
that the interfaces it defines must be TCB interfaces.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.1 Revisions to Scope and Normative References

239

102

B.1.3.7.5.3 System Integrity

103
104
105

System Integrity interfaces are being deferred to a future version of this standard.
It was felt that deferring this area to a future standard would allow existing
practice to become more stabilized prior to standardization.

106

B.1.3.7.5.4 Formal Security Policy Model

107
108
109
110
111
112

No security policy models are defined as part of this standard because the standard is not intended to define a complete system. In some areas the implementation may want to extend the standard, and in other areas the implementation will
have to extend the standard. Given this incompleteness, a model would be
difficult (and perhaps impossible) to define. Also, a full, formal model would constrain implementations beyond the point necessary for application portability.

113

B.1.3.7.5.5 Separation of Administrative Roles

114
115
116

Without a complete definition of administrative function, this is clearly beyond
the scope of this standard. Also, this is an area where implementations may wish
to target particular and isolated installations.
−117

B.1.3.7.5.6 Resource Controls

118
119
120
121

Resource controls (quotas) are used to support a system availability policy. They
are not included in this standard because of a lack of existing practice in UNIXsystems and, more importantly, the resources controlled tend to reflect implementation limits (static tables, ...) rather than physical ones.

122

B.1.3.7.5.7 Trusted Path

123
124
125
126
127
128

A Trusted Path mechanism is not defined because the notion of terminal definedin POSIX.1 is limited to dumb ttys, and is incomplete as well. Existing practice islacking here as well. The standardization of the key sequence used for invoking
the trusted path is possible, but it would also be necessary to define the behaviorof the system upon trusted path invocation. It was felt that this would be impossible without a well-defined Trusted Path.

129

B.1.3.7.5.8 Protected Subsystems

130
131
132
133
134

The UNIX-protected subsystem mechanism (programs with the set-user-ID or
set-group-ID mode bits set) is subject to abuse by knowledgeable users andmisuse by naive users. Its shortcomings are not addressed due to some notabledisagreements concerning the desirability of the mechanism. It also doesn’t add
much to portability.

135

B.1.3.7.6 Evaluation Ratings Based on Current Trust Criteria

136
137
138
139

Evaluations of products under current trust criteria involve analysis of all aspectsof the product, especially of implementation details. This standard only deals
with interfaces. Therefore, it is inherently incomplete and unsuited for evaluation under these criteria. In addition, a conforming system could implement the
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

240

B Revisions to Rationale and Notes

c

140
141

functionality under the interfaces in an insecure manner. Therefore, conformanceto this standard does not guarantee that a system should be trusted.
c142

B.1.3.7.7 General Terminal Interface

143
144
145

This standard does not extend General Terminal Interfaces described in sections
7.1 and 7.2. This section explains some of the problems with the GTI from a security perspective.

146
147
148
149
150
151

The existing interfaces do not require that the file descriptor used for changing
terminal attributes be opened for writing. Given the MAC policy of read-down, aprocess could open a terminal which it dominates, and by manipulating terminal
attributes perform data downgrade. This violates the basic MAC policies.
Requiring that the device is opened for write (or that the process have MAC write
access) solves this problem.

152
153
154
155
156
157
158

Manipulation of device attributes can interfere with invocation of trusted path.
For example, a process could change the baud rate of its controlling terminal.
The trusted path would be unable to determine if the baud rate was changed at
the user’s request, i.e., because the baud rate was adjusted on the physical terminal, or by a malicious or malfunctioning application. Thus, the user might beunable to communicate via the trusted path. Changing the baud rate should be
restricted using privilege or trusted path.

159
160
161
162
163

Applications may cause output to be suspended (using the tcflow() function withthe action set to TCOOFF). If the trusted path is invoked in such a case, thestandard would need to define what happens, i.e., the trusted path can re-enable
output, but the status of queued output would need to be determined. An
appropriate solution to this problem is not clear.

164
165
166

While these problems generally involve trusted path (which is not a part of thestandard), it is important not to enact a standard which would preclude buildinga system that includes a trusted path mechanism.

167
168

⇒ B.1.3.8 Portable Trusted Applications Add the following new sections
B.1.3.8:

169

B.1.3.8 Portable Trusted Applications

170
171
172
173
174
175

Portable trusted applications are those applications that are: portable because thecsystem call interface they use is that defined by POSIX.1e; and trusted, because
they perform some security-related functionality and/or need some privilege fromthe system in order to function correctly, and which therefore must be trusted toperform the security-related functionality correctly and/or to not abuse theprivilege granted to the application.

176
177
178

Such portable trusted applications may rely on the TCB of the host system to perform certain security-critical functions that are necessary to ensure the correctand secure operation of the portable trusted application. For example: a portable
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.1 Revisions to Scope and Normative References

241

c

179
180
181

trusted application may need to protect some persistent data from tampering byunauthorized processes, and may therefore use DAC features to control access tothe persistent data as stored in a file.

182
183
184
185
186
187

If the secure operation of the portable trusted application depends on the correct
operation of such POSIX.1e functions, then those POSIX.1e functions must be
implemented by the TCB of the host system on which the application is running;otherwise, the portable trusted application would be relying on untrusted code toperform functionality upon which the security of the portable trusted application
depends.

188
189
190
191
192
193

Furthermore, the secure state of the entire system may be at stake if the portable
trusted application runs with system privileges, because the portable trusted
application may operate incorrectly and abuse its privilege as a result of malfunction of untrusted code performing functionality which is security-related as usedby the portable trusted application. However, the interfaces defined in this stan- cdard are not required to be TCB interfaces.

194
195
196
197
198
199
200
201
202
203

As a result, a portable trusted application may be portable to various POSIX.1econformant systems, but only some of those conformant systems may actually
implement as TCB interfaces those POSIX.1e interface functions upon which
depends the secure operation of the portable trusted application. Therefore, portable trusted applications under some circumstances may not be trust-worthy evenwhen run on conformant systems. Proper use of portable trusted applications
depends on the specification of the system interfaces which are security-critical tothe portable trusted application, and the determination of whether all those interfaces are implemented by the TCB of a system which can run the portable trusted
application.

204

B.2 Revisions to Definitions and General Requirements

205⇒ B.2.2.2 General Terms Insert the following after line 986:

206
207
208

user: the term user is used in this document to denote a person who interacts
with a computer system. It is not meant to include programs that ‘‘look like’’users.

209
210⇒ B.2.10 Security Interface (POSIX.1: line 1741) Add the following sections
B.2.10 and B.2.10.1:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

242

B Revisions to Rationale and Notes

c

211

B.2.10 Security Interface

212

B.2.10.1 Opaque Data Objects

213
214
215
216

Each functional area (MAC, ACL, IL, capabilities, and audit) defines one or moreopaque data objects. Certain restrictions are applied to some of those opaque data
objects, namely persistence and self-containment. This section describes therationale for these requirements and their implications.

217
218
219
220
221
222
223
224
225

Opaque data objects by definition can contain any type of data, in any form, solong as the functions which manipulate those objects understand that form. For
example, Access Control Lists are frequently implemented as linked lists. However, some applications need to pass opaque objects to other processes (e.g., bywriting them in FIFOs), or to store them in files. For example, a trusted databasesystem might store a MAC label for each record in the database. Truly opaquedata cannot be stored, because an application does not know how much to store,
and there is no guarantee that the data will be meaningful when retrieved fromthe database.

226
227
228
229
230
231
232
233
234
235
236
237

In each section, an interface is provided to free memory associated with data −structures. (Thus, for example, there are mac_free(), inf_free(), etc., routines).
The description of these routines state that they free any "releasable" memory.
Once these routines have been called, the data structure freed can no longer beused by applications: in general, these routines will deallocate all memory associated with the data structure. That is, the ∗_free() routines generally work analogously to the malloc() and free() routines of standard C. However, no require- −ment imposed by this standard that requires all allocated memory to be freed.
Conforming implementations, then, can use their own memory management
schemes. Nevertheless, portable applications must assume that the memory
freed has been completely deallocated and that any pointers to the freed data
structure are no longer valid.

238

B.3 Revisions to Process Primitives

239
240

⇒ B.3.1.2 Process Creation (POSIX.1: 1770) Rationale for changes to this section in POSIX.1 is provided below:

241
242
243
244
245

When a new process is created via a fork() call, the new process is an exact
copy of its parent, including the current MAC label, information label, etc.
Because this standard does not define the contents of many data structures, it
is important to note that both the parent and child may continue using data
structures independently.

246
247
248
249

For example, consider an implementation where a MAC label structure (that is
an object referenced by mac_t) is simply a number. That number could be anindex into a kernel table. Functions which use the MAC label could make kernel calls, and all manipulation of the MAC label would take place in the
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.3 Revisions to Process Primitives

243

250
251
252

kernel. When the fork() function is executed, the system must duplicate thekernel table so both the parent and child processes are able to modify the MAC
label without interfering with each other.

253
254

⇒ B.3.1.2 Execute a File (POSIX.1: line 1821) Rationale for changes to thissection in POSIX.1 is provided below:

255
256
257
258
259
260
261
262
263
264

At first glance it might appear that a child’s information label should be set
either to the information label of the file being executed, or to the lowest label
in the system. However, the process performing the exec∗() operation can pass
information to the new process image by way of file descriptors and environment variables. Hence, the old process information label should be incorporated in the new process information label. Note that the standard recommends an information label, but does not require it; other information label
policies are possible and allowed by this standard. Additionally, the standard
does not require use of the inf_float() function to calculate the new information
label; this is a suggestion of one way to perform the calculation.

265
266

⇒ B.3.3.2 Send a Signal to a Process (POSIX.1: line 2428)
changes to this section in POSIX.1 is provided below:

Rationale for

267
268
269
270

Using a signal between two processes is effectively sending data. While theamount of data (the signal number) is small, this standard is careful to avoid
requiring information flow which contradicts the MAC security policy. Hence,
the four cases described in the standard:

271
272

MAC label of sender equivalent to MAC label of receiver: no MAC restrictions

273
274
275

MAC label of sender dominates MAC label of receiver (i.e., write-down):
appropriate privilege is required, and if {_POSIX_CAP} is defined,
appropriate privilege includes the capability CAP_MAC_WRITE.

276
277
278
279
280
281
282
283

MAC label of receiver dominates MAC label of sender (i.e., write-up):appropriate privilege may or may not be required. A write-up is not
an inherent violation of the security policy, except that the sender isable to determine the existence of a higher level process. Systems
which address covert channels may wish to close this channel byrequiring appropriate privilege. If {_POSIX_CAP} is defined,
appropriate privilege includes the capability CAP_MAC_READ(because the existence of the higher level process is read).

284
285
286
287
288
289

MAC label of sender and receiver are incomparable: in this case, appropriate privilege is certainly required at least as strong as the case where
the label of the sender dominates that of the receiver. If{_POSIX_CAP} is defined, appropriate privilege includes the capability CAP_MAC_WRITE. In addition, implementations may requireappropriate privilege to perform the read-up, viewing the operation as
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

244

B Revisions to Rationale and Notes

290
291
292
293
294

a write-down followed by a read-up. In this case, if {_POSIX_CAP} isdefined,appropriate
privilege
includesthecapability
CAP_MAC_READ. However, the additional capability is not definedby the standard, since implementations are free to add additional restrictions as desired.

295
296
297
298
299
300
301
302

The kill() function allows notification of a process group. The error code isdefined in POSIX.1 as success if any signal was sent, and a failure only if noprocesses could be signaled. This standard extends that notion: if a processgroup contains processes with different MAC labels, then a signal is successfully sent to the process group if even a single process in the group can be signaled. This is consistent with the notion in IEEE Std 1003.1-1990 where a signal could be successful even if processes in the process group have different
user IDs, and hence only some of them can be signaled.

303
304
305
306
307
308
309
310

If not even one process can be signaled, then there are two possible errors
returned: [EPERM] and [ESRCH]. [EPERM] is used when the sending process
dominates at least one of the potential receiving processes, but did not havethe required appropriate privilege to send the signal. In this case, the sending
process could determine the existence of the potential receiver, so no information channel exists by returning [EPERM]. By contrast, [ESRCH] is returned
to indicate that either the process group did not exist, or none of the processes
in the process group were visible to the sending process.

311
312
313
314

While this standard imposes no information label requirements on signals,
implementations may consider the signal as having an information label, andhence float the information label of the receiving process to include the information label of the sending process.

315
316

This standard does not extend the notion of access control based on user IDs toinclude the notion of an access control list on a process.

317
318
319
320
321
322

Another architecture not discussed by this standard is to allow overrides of thesignaling policy based on the privileges of the receiver. In such an architecture, a daemon process could be set up to accept signals from any process,regardless of the MAC label of the sender. However, the POSIX.1 standard
does not recognize this notion for user ID based privileges, so this standard
does not extend it for MAC.

323
324

⇒ B.4 Revisions to Process Environment (POSIX.1: line 2645) Rationale forchanges to this section in POSIX.1 is provided below:

325
326
327

As previously described, each of the options described in this standard may be
selected independently. The sysconf() variables listed in this section are toallow programs to determine at runtime whether the option is available.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.3 Revisions to Process Primitives

245

328
329

⇒ B.5 Files and Directories (POSIX.1: line 2896) Rationale for changes tothis section in POSIX.1 is provided below:

330
331
332
333
334
335
336

The extensions specified in this standard for file access avoid changing theinterfaces specified in POSIX.1 any more than necessary. Specifically, nochanges are made to parameter types, and where data structures are involved,
no changes are made to add or remove elements from the structure. In somecases the data returned by the interface may be changed. This is most noticeable when examining the file permission bits of a file which has an access control list.

337
338

⇒ B.5.3.1 Open a File (POSIX.1: line 3077) Rationale for changes to this section in POSIX.1 is provided below:

339
340
341
342

While it might appear that a newly created file would always have the information label inf_default() this is not true. For example, implementations
might set the information label of a new file to the information label of the containing directory or the information label of the creating process.

343
344
345
346
347
348

When opening a FIFO, the MAC restriction should be that process and FIFO
MAC labels should be equivalent to avoid massive covert channels associatedwith MAC inequalities. Since the MAC policy defined by this standard allows
MAC write-up, it is possible to be POSIX compliant and still include thiscovert channel. However, since the normal MAC policy is write-equals, this is
not a major concern.

349
350

⇒ B.5.6.2 Get File Status (POSIX.1: line 3208) Rationale for changes to thissection in POSIX.1 is provided below:

351
352
353

The stat() call in POSIX.1 provides the caller with all file attributes. This
standard does not extend stat() to return the extended attributes such as MAC
label or access control list. There were several reasons:

354
355

This standard had as a goal to leave the syntax of existing interfaces
unchanged.

356
357
358
359

The data structures defined in this standard are potentially variable
length, unlike in POSIX.1 where they are all fixed length. Thus, thestat structure would have to be adapted to handle pointers to the variable length items. This would make the interface more complicated.

360
361
362

Each portion of this standard is independent, so not all data types arenecessarily defined. Thus, the stat structure would have to be set up
differently depending which options are provided.

363
364
365
366

Existing programs designed to use a version of stat() as defined in POSIX.1
might get back additional information. If the program had not been
recompiled to allow for a larger structure, this might overwrite otherdata, and cause the program to fail.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

246

B Revisions to Rationale and Notes

367
368

Thus, the standard leaves stat() unchanged, and adds new functions for getting the individual extended file attributes.

369
370
371
372
373

Note that if {_POSIX_ACL} is defined and {_POSIX_ACL_EXTENDED} is ineffect for the pathname, the semantics of stat() and fstat() are changed.
Specifically, stat() and fstat() no longer return all the discretionary accessinformation, so applications that depend on it doing so (e.g., when copying discretionary file attributes to another file) may have to be changed.

374
375

⇒ B.5.6.3 File Access (POSIX.1: line 3216) Rationale for changes to this section in POSIX.1 is provided below:

376
377
378
379
380
381
382
383
384

POSIX.1 does not list the specific permissions required for each function (e.g.,open(), mkdir(). Rather, it relies on the descriptions of pathname resolution
and file access in POSIX.1, 2.3, together with additional information (e.g.,
error codes) in the individual function descriptions. For example, the description of open() does not specify that the caller must have search access to eachpathname component, and must also have write access to the directory if a
new file is being created. The pathname resolution portion is implicit fromPOSIX.1, 2.3, and write access to the parent directory is provided by thedescription of the EACCES error number.

385
386
387
388
389

In a similar fashion, this standard does not describe the MAC requirements forfile access, instead referring to POSIX.1, 2.3. Additional information is provided where appropriate, such as linking files (which requires MAC write permission to the existing file) and opening a FIFO (which requires MAC write
permission to the FIFO file).

390
391
392
393
394

Unlinking a file might appear to need MAC write access to the containing
directory only. However, the unlink operation updates the link count on thefile, which is effectively a write operation to the file. Hence, MAC write accessis required. Similarly, removing a directory updates the directory link count,and consequently MAC write access is required to the directory being removed.

395

Clearing setuid/setgid and Privileges

396
397
398
399
400
401
402

One security-relevant issue not addressed by this standard is resetting of thesetuid/setgid bits. For example, most historical implementations clear thesetuid and setgid bits when a file is written into. The security risk is that if a
setuid utility is improperly installed (e.g., with write permission) and thesetuid bit is not cleared, a malicious user could replace the utility with a different version. However, neither IEEE Std 1003.1-1990 nor this standard
require (nor prohibit) clearing the setuid and setgid bits.

403
404
405
406
407

There were several reasons for not specifying the behavior. The most important was determining which interfaces should trigger clearing setuid/setgid
bits. Should they be cleared when the file is opened, when it is written to,when it is closed, or some combination? Each leaves certain timing windows,
and has potential performance implications.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.3 Revisions to Process Primitives

247

408
409
410
411
412

The capability flags provided by this standard provide an extension to thenotion of setuid/setgid, with somewhat finer granularity. If setuid/setgid bits
are to be cleared, should capability flags also be cleared? Just as this standard
makes no statements about setuid/setgid, it does not require (nor prohibit)
clearing of capability flags.

413
414
415
416
417
418
419
420
421
422
423
424

If capability flags are cleared when a file is written, the implementor should
also consider whether they should be cleared when file attributes are changed.
For example, consider a program file which has the MAC read-up exemption
capability, and the file has a MAC label of secret. When executed, that program may read top secret data, but at worst it can relabel it as secret (because
only a user with at least a secret security level will be able to access the file,and hence execute the program). If the file’s MAC label is changed to
unclassified, then an uncleared user may be able to execute it, thus allowing
top secret data to be written into an unclassified file. Thus, the change in the
MAC label of a file impacted the system security, by allowing additional risks.
System implementors may wish to consider these types of threats, even though
they are not required by this standard.

425
426

Finally, system implementors should consider whether capability andsetuid/setgid bits should be cleared when the file owner is changed.

427

Object Reuse and File Erasure

428
429
430
431
432
433
434
435

Another topic of concern in trusted systems is object reuse, particularly as it
applies to files. POSIX.1 requires that newly allocated files be cleared, so theprevious contents of the file are inaccessible. While some historical systems
overwrite the contents of a file when the file is deleted, this standard imposesno such requirement. Because the contents are cleared when the file is first
read, this is not an issue except when the device which stores the file (i.e., thedisk) can be accessed outside the file system (e.g., through a raw device). Such
concepts are beyond the scope of this standard.

436

Initial Information Labels

437
438
439
440
441

When a file (including a directory or FIFO) is created, the initial information
label on the file must be set. This standard does not specify an information
label policy. Hence, the standard does not specify what the initial label willbe. In most cases the initial label will be the same as the result of a call to
inf_default().

442
443
444
445
446
447
448
449

⇒ B.6.1 Pipes (POSIX.1: line 3380)
POSIX.1 is provided below:

Rationale for changes to this section in

Pipes provide communication between related processes (typically a parent
and child). Excluding the effects of privileged processes, the related processes
by definition have the same MAC label. Hence, specifying the MAC label ofthe pipe is somewhat irrelevant. However, processes can request the MAC
label of the file associated with a file descriptor. This standard defines the
MAC label of the pipe as the MAC label of the creating process so such a
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

248

B Revisions to Rationale and Notes

450

451

request can be answered.
⇒ B.6.5.2 File Locking (POSIX.1: line 3613)

452
453
454
455
456
457
458
459
460
461
462

The file locking mechanism defined in IEEE Std 1003.1-1990 allows advisory
locks to be placed and detected on a file. The mechanism does not specify thefile mode used by processes placing or testing the locks. When a MAC policy isadded, the locking mechanism can be used as an information flow channel. At
earlier stages of development of this standard strict requirements for MAC
access were specified and varying capabilities specified to obtain MAC access.
Due to significant ballot objections to the granularity of the capabilities
required, it was decided to let this standard be mute on the enforcement of
MAC for file locking operations. Implementations concerned with closing theinformation flow channel have been left free to handle the channel in whatever
way they choose. See B.25.4.3 for more discussion of this issue.
c

463
464

⇒ B.8 Language-Specific Services for the C Programming Language
Rationale for changes to this section in POSIX.1 is provided below:

465
466
467
468
469
470

Historical implementations implement the interfaces defined in this section
using the base POSIX.1 interfaces. This concept is reflected by the descriptionof the interfaces as having underlying functions. However, there is no requirement that implementations use the underlying functions, as noted in POSIX.1
Section 8, lines 341-345. As a result, this standard defines the extensions to
the C standard I/O primitives.

471
472
473
474
475
476

Some consideration was given to defining security effects of making alongjmp() call. For example, to provide time bounding of capabilities thecurrent capability set could be restored to its state as of the setjmp() call. This
standard makes no such requirements, as applications are not required to timebound capabilities. Rather, applications developers are encouraged to clear
appropriate capabilities in the code invoked from the longjmp() call.

1

B.23 Access Control Lists

2
3

The overall requirements for an Access Control List (ACL) mechanism in a securesystem include the following:

4(1) Allow authorized users to specify and control sharing of objects

5(2) Supply discretionary access controls for objects.

67(3) Specify discretionary access by a list of users and groups with theirrespective access rights to the protected objects

89(4) Allow discretionary access to an object to be denied for a user or, in certain cases, a group of users.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.23 Access Control Lists

249

10
11

(5) Allow changes to the ACL only by the owner of the object or by a processwith the required access or appropriate privilege.

12
13
14

(6) Not allow more permissive discretionary access than either the initial orfinal access rights while the ACL is being written by acl_set_file() or
acl_set_fd().

15
16
17

The primary goal in defining access control lists in a POSIX.1e system is to provide a finer granularity of control in specifying user and/or group access to objects.
Additional goals for the ACL mechanism are:

18
19
20

(1) The mechanism should be compatible with the existing POSIX.1 and
POSIX.2 standards and, to the extent possible, existing interfaces should
continue to work as expected.

21
22
23
24

(2) Reasonable vendor extensions to the ACL mechanism should not be precluded. At a minimum, the specification of read, write andexecute/search permissions should be supported. Other permissions
should neither be required nor should they be precluded as extensions.

25(3) New interfaces should be easy to use.

2627(4) Intermixing use between the existing mechanism and newly defined ACL
functions/utilities should provide predictable, well understood results.

28
29
30
31
32
33
34
35
36

Another goal is to be compatible with existing POSIX.1 standards. Current interfaces will continue to exist and will affect the overall ACL. Some users will continue to only use the file permission bits. Existing programs may not be modified
to use the ACL interface and may continue to manipulate DAC attributes using
current POSIX.1 interfaces. These programs should operate on objects with ACLs
in a manner similar to their operation on objects without ACLs. However, complete compatibility between the existing POSIX.1 DAC interfaces and the
POSIX.1e ACL interfaces is simply not achievable. For a discussion of theseissues, please refer to B.23.1.

37
38
39

The POSIX.1e ACL interfaces should not restrict vendors from providing extensions to the basic ACL mechanism; the POSIX.1e ACL interface should not
exclude such extensions.

40
41
42

For the sake of usability and user acceptance, new interfaces should be as simple
as possible while maintaining a reasonable level of compatibility with existing
POSIX.1 interfaces.

43
44

The intermixing of usage between the existing POSIX.1 DAC and the POSIX.1e
ACL mechanisms should be well defined and produce reasonable results.

45
46
47
48
49
50
51
52

The DAC interfaces described in POSIX.1 are adequate for some needs. The filepermission bits defined in POSIX.1 are associated with three classes: owner,group, and other; access for each class is represented by a three-bit field allowing
for read, write, and execute/search permissions. The POSIX.1e ACL interfaces
extend the POSIX.1 interfaces by defining access control lists (ACLs) in order toprovide finer granularity in the control of access to objects. ACLs can provide theability to allow or deny access for individually-specified users and groups of users.
However, implementations which allow processes to modify the process’ group
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

250

B Revisions to Rationale and Notes

53

membership may not be capable of denying access to users based on groups.

54
55
56
57
58
59

Several methods exist for allowing discretionary access control on objects. Thesemethods include capability lists, profiles, access control lists (ACLs), permission
bits, and password DAC mechanisms. ACLs were selected for the POSIX.1e interfaces because they meet the goals stated earlier in this section. ACLs are astraightforward extension of the existing POSIX.1 file permission bits which may
be viewed as a limited form of ACL containing only three entries.

60

The following features are outside the scope of this document:

61— Shared ACLs

62
63
64
65

An ACL is shared if it is associated with more than one object; changes to ashared ACL affect the discretionary access for all objects with which the
ACL is associated. Shared ACLs are useful as a single point of control forthe specification of DAC attributes for large numbers of objects.

66
67

Although the implementation of shared ACLs is not precluded, shared
ACLs are not defined in this standard for the following reasons:

68
69
70

g

It may be difficult to determine the set of objects sharing an ACL. A
user could modify the ACL associated with an object and unintentionally grant access to another object.

71
72

g

When changing a shared ACL, it may be necessary to produce an audit
record for each file system object that is protected by the ACL.

73
74

g

Any changes to a shared ACL which have an unintended security result
affect all objects sharing the ACL.

75

— Named ACLs

76
77
78

A named ACL is an ACL which exists in the file system space and can bereferred to by name. Named ACLs are primarily useful for implementing
shared ACLs.

79
80

Although the implementation of named ACLs is not precluded, named
ACLs are not defined in this standard for the following reasons:

81
82

g

As file system objects, ACLs themselves may be required to contain discretionary access controls which could require recursive ACLs.

83
84
85

g

The owner of a named ACL may not be the owner of the object(s) withwhich the ACL is associated. The owner of an object could lose control of
the DAC attributes associated with that object.

86

B.23.1 General Overview

87
88
89
90

POSIX.1 specifies basic DAC interfaces consisting of permissions which specify
the access granted to processes in the file owner class, the file group class, and thefile other class. These classes correspond to the intuitive notions of the file’sowner, members of the file’s owning group, and all other users.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.23 Access Control Lists

251

91

B.23.1.1 Extensions to POSIX.1 DAC Interfaces

92
93

The specification of the POSIX.1 interfaces provides for two ways to extend discretionary access controls beyond the basic file permission bits:

94
95
96

g

An additional access control mechanism may be provided by an implementation, however, the mechanism must only further restrict the access permissions granted by the file permission bits.

97
98
99

g

An alternate access control mechanism may be provided by implementation, however, POSIX.1 requires that a chmod() function call disable any
alternate access control attributes which may be associated with the file.

100
101
102
103
104
105
106
107
108

The POSIX.1e access control interfaces are defined as an additional access control
mechanism in order to satisfy the basic goal of working in conjunction with theexisting DAC functions and commands; essentially, the ACL interfaces can beviewed as an extension of the base POSIX.1 file permission bits. Also, the
POSIX.1e definition of the ACL interfaces only further restrict the access specified
by the file permission bits. If the POSIX.1e interfaces were to be defined as analternate access mechanism, then the POSIX.1e interfaces would have to operate
independently of the existing POSIX.1 interfaces with no correlation between thepermissions granted by the alternate mechanism and the file permission bits.

109

B.23.1.2 Extensions to File Classes

110
111
112
113
114
115

POSIX.1 permits that implementation-defined members may be added to the filegroup class. As such, the ACL entries for individually specified users and groups
are defined as members of the file group class. Since the file permission bits forthe file group class are defined as the maximum permissions which can be
granted to any member of the file group class, then the POSIX.1e interfaces conform to the POSIX.1 definition of an additional access mechanism.

116
117
118
119
120
121

An alternative is to define the additional ACL entries as members of the file otherclass instead of the file group class. The apparent advantage of extending the fileother class is that the permissions granted to the file’s owning group would be
explicitly specified in the base file permission bits. However, this would not be thecase since individually named user entries would be checked prior to the owninggroup permissions even if the specified user was a member of the owning group.

122
123

Refer to B.23.3 for more details on how ACL entries map to the different fileclasses.

124

B.23.2 ACL Entry Composition

125
126
127
128

An ACL entry consists of at least three pieces of information as defined in thestandard: the type of ACL entry, the entry tag qualifier, and the access permissions associated with the entry. The standard permits conforming implementations to include additional pieces of information in an ACL entry.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

252

B Revisions to Rationale and Notes

129

B.23.2.1 ACL Entry Tag Type Field

130
131
132
133

Seven distinct ACL entry tag types are defined to be the minimum set of tag types
which must be supported by a conforming implementation: ACL_USER_OBJ,
ACL_GROUP_OBJ, ACL_OTHER, ACL_USER, ACL_GROUP, ACL_MASK, andACL_UNDEFINED_TAG.

134
135
136
137
138
139
140
141

The ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER tag type ACL
entries are required to exist in all ACLs. If no other entries exist in the ACL, thenthese entries correspond to the owner, group, and other file permission bits. Since
these permission bits can never be removed from a file, the ACL entries
corresponding to the permission bits are also required. If an ACL contains any
additional ACL entries, then an ACL_MASK entry is also required since it thencorresponds to the file group permissions and serves as the maximum permissions
that may be granted to the additional ACL entries.

142
143
144
145
146
147
148

While implementations can define additional tag types, the standard does allow
an implementation to require the existence of any additional entries in an ACL. If
this were allowed, then an file containing only the file permission bits (i.e., an
ACL with only three entries) would not be a valid ACL. This would prevent astrictly conforming application from executing correctly on such an implementation which would violate the goal of providing compatibility with the existing
POSIX.1 interfaces.

149
150
151
152
153
154

An additional ACL entry tag type that could be defined is a ‘‘user and group’’
where such entries specify the access permissions for an individual user within a
specific group. While such an ACL entry is useful in some environments, it is not
required in the standard since it does not appear to provide widely useful functionality. Implementations are not precluded from defining a ‘‘user and group’’ tag
type.

155
156
157
158
159
160

Implementations which currently allow ‘‘user and group’’ tag type ACL entries
can consider the ACL_USER_OBJ and ACL_USER ACL entry tag types torepresent access to a user regardless of group membership, e.g., ‘‘user.∗’’. Likewise, ACL_GROUP_OBJ and ACL_GROUP ACL tag types represent group accessregardless of user identity, e.g., ‘‘∗.group’’, and ACL_OTHER represents anybody
in any group, e.g., ‘‘∗.∗’’.

161
162
163
164
165

The names of all ACL entry tag types all begin with the prefix ‘‘ACL_’’ in order toprovide consistency in naming with other areas of the POSIX standards. While
this may make the use of such names slightly more cumbersome for the programmer, avoiding name conflict through a consistent naming scheme is more important.

166
167
168
169
170
171
172
173

POSIX.1e defines two types of ACLs: access and default ACLs. All objects have anaccess ACL since the POSIX.1 file permission bits are interpreted as a minimal
ACL. In addition, a default ACL may be associated with a directory. The rules for
ACL entry tag types are the same for both types of ACL. As such, an application
can create an ACL and apply it to a file as either an access ACL or a default ACL
without changing the ACL structure or any of the ACL data. If POSIX.1e defined
ACL entry types which applied to only one type of ACL or if the rules for required
ACL entries differed between the types of ACL, then a single ACL could not be
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.23 Access Control Lists

253

174

applied as both an access and a default ACL.

175

B.23.2.2 ACL Entry Qualifier Field

176
177
178
179
180
181
182
183
184

The data type of the qualifier field in an ACL entry is specific to the ACL entry
tag type. Also, the qualifier field is not extensible for POSIX.1e defined tag types.
However, implementations may define the type and structure of the qualifier for
entries with implementation-defined tag types. For example, an implementationthat wishes to allow the assignment of permissions to an individual user within a
specific group could create a tag type, ACL_USER_GROUP, with a qualifier containing the identification of both the user and the group. An implementation could
also define a user/time entry which could use the qualifier to identify a process
within a specified time of day interval.

185
186
187
188
189
190
191
192
193
194
195
196
197

If an implementation could extend the POSIX.1e defined ACL entry qualifier
fields, then a strictly conforming application might not function as expected whenmanipulating an ACL with extended qualifier fields. For example, an implementation extends the qualifier field of the ACL_USER entry type to include a time ofday (TOD) interval. A strictly conforming application attempts to manipulate an
object’s ACL which contains two entries for user fred; one entry contains a TOD
qualifier for 0800->1800 and one entry has a TOD qualifier for 1800->0800. If thestrictly conforming application intends to change the access allowed for user fred,then the application would call acl_get_entry() and acl_get_qualifier() until it
locates an ACL_USER entry for fred and would then update the entry. The application would expect only one ACL_USER entry for fred and would only update
one entry; since there are two entries for fred, the resulting access for user fred
may not be as desired.

198
199
200
201

The special qualifier field value, ACL_UNDEFINED_ID, is defined as a value
which cannot be used by the implementation as a valid group or user id. Thisvalue is used to initialize the qualifier field within a newly created ACL entry to avalue which is not a valid group or user id.

202

B.23.2.3 ACL Entry Permissions Field

203
204

ACL entries are required to support read, write, and execute/search permissions
for the following reasons:

205
206

(1) These permissions allow the abstraction of the POSIX.1 file permission
bits as ACL entries.

207
208

(2) Existing practice dictates that at least these permissions must be
retained.

209
210
211
212
213

File permissions in addition to read, write, and execute/search are allowed by an
implementation because this would allow finer-grained and extended control ofaccess to objects. For example, an implementation could add ‘‘append only’’ or‘‘delete object allowed’’ permissions. However, such extended permissions are notrequired by this standard because such permissions are not universally required.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

254

B Revisions to Rationale and Notes

214

B.23.2.4 Uniqueness of ACL Entries

215
216
217
218

The combination of ACL entry tag type and qualifier are required to be unique
within an ACL. The requirement for unique ACL entries, in combination with theorder in which access is checked, provides a simple and unambiguous model forthe specification of access information for an object.

219
220
221
222
223
224
225
226
227
228
229

Note that it is possible for the owner of a file to be explicitly named in an
ACL_USER entry within the ACL associated with the file. While this entry may
appear to conflict with the entry for the file’s owner (i.e., the ACL_USER_OBJ
entry), the ACL_USER_OBJ entry will be encountered before any ACL_USER
entries during the ACL access check algorithm. Thus, in this case the
ACL_USER_OBJ entry would uniquely determine the access permissions for theowner of the file; the individual ACL_USER entry for the file’s owner would be
ignored. The requirement is that the combination of tag type and qualifier must
be unique. Also, the ACL_USER_OBJ entry and the ACL_USER entry are quite
different semantically even if the ACL_USER entry contains the identity of thefile owner.

230
231
232
233
234
235

Likewise, an ACL_GROUP entry with a qualifier id matching the owning group ofa file does not conflict with the ACL_GROUP_OBJ entry in the ACL. In such acase, all applicable group entries would be examined to determine if any entry
grants the access requested by the process. Both the ACL_GROUP_OBJ entry
and the ACL_GROUP entry matching the owning group would be examined andmight provide the desired access.

236

B.23.3 Relationship with File Permission Bits

237
238
239
240
241
242
243
244

ACLs expand upon the discretionary access control facility which is already provided by the file permission bits. Although file permission bits do not provide finegranularity DAC, they are sufficient for many uses and are the only mechanism
available to existing applications. All existing applications that are security conscious use file permission bits to control access. The relationship between the ACL
and the file permission bits must be defined in order to determine the level ofcompatibility provided to existing programs which manipulate the file permission
bits.

245
246
247
248
249

Several approaches are possible for handling the interaction of ACLs with file permission bits. Each approach is presented in a separate sub-section with adescription of the approach, a list of the advantages, and a list of the disadvantages. Final commentary and a conclusion follow the presentation of theapproaches.

250

B.23.3.1 ACL Always Replaces File Permission Bits (Pure ACL)

251
252
253
254
255

In this approach, the file permission bits are no longer consulted for ACL decisions. Instead, each object has an ACL and the ACL completely determines
access. File permission bits would be unused in the standard and the interaction
between the file permission bits and ACL entries should be implementationdefined. This method would prevent the use of the old access control mechanism
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.23 Access Control Lists

255

256

in a strictly conforming application.

257

This approach has the following advantages:

258
259
260

— Reduces complexity because there are no compatibility issues between
ACLs and permission bits. Permission bits are no longer used for DAC
decisions.

261— A single, well defined discretionary access policy is employed.

262
263

— Increases security. The old access control mechanism does not provide theproper level of security to meet the requirements of this document.

264

This approach has the following disadvantages:

265
266
267

— existing applications that use chmod() or stat() must be examined to see ifthey are making DAC decisions. This is because chmod() and stat() update
and return, respectively, more than just DAC information.

268
269

— existing applications that make DAC decisions must be rewritten to use the
new interfaces.

270
271
272
273

— Compatibility between file permission bits and ACLs is left up the vendors
who, realistically, must provide some compatibility with their old implementations. Without standardization the compatibility solutions will be
vendor specific and not portable.

274

B.23.3.2 Owner Selects ACL Or File Permission Bits

275
276
277
278
279
280

In this approach, either the file permission bits or the ACL are consulted for theaccess control decision on a per object basis. The owner of the object determines
whether to use the file permission bits or the ACL. If an ACL is set on a file, thenthe functions that manipulate file permission bits would return an error. If filepermission bits are set on a file, then the ACL manipulation functions would
return an error for that file.

281

This approach has the following advantages:282— If ACLs are never set, then there are no compatibility problems.

283
284

— If an access ACL is set on an object or a default ACL set on a directory,
then the behavior is like the pure ACL system.

285

This approach has the following disadvantages:

286
287

— Like the previous approach, existing applications that use chmod() or stat()must be examined to see if they are making DAC decisions.

288
289
290

— Existing applications that make DAC decisions must be rewritten to determine which mechanism is in effect for each object it manages and then use
the correct interface.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

256

B Revisions to Rationale and Notes

291

B.23.3.3 Independent ACL And File Permission Bits (AND)

292
293
294

In this approach, both the file permission bits and the ACL are consulted for thediscretionary access control decision. Access is granted if and only if it is granted
by both the ACL and the file permission bits.

295

This approach has the following advantages:

296
297

— Calls to chmod() have the desired effect from a restrictive point of view;
ACL entries can further restrict access.

298
299

— The relationship between ACLs and file permission bits is easily defined:
to be allowed access both must grant access.

300

This approach has the following disadvantages:

301
302
303

— To fully utilize the ACL as the effective access control mechanism requiresthat the file permission bits be set wide-open, i.e. read, write, and execute
bits are set for user, group and other.

304
305

— In order to grant access, users must be prepared to change both the ACL
and the file permission bits.

306
307
308

— An application would have to use chmod() and stat() to manipulate the filepermission bits and the ACL functions to manipulate the ACL entries on a
file.

309

B.23.3.4 Independent ACL And File Permission Bits (OR)

310
311
312
313

In this approach, both the file permission bits and the ACL are consulted for thediscretionary access control decision. Access is granted if it is granted by either
the ACL or the file permission bits. The ACL is used to grant access beyond what
is set in the file permission bits.

314

This approach has the following advantage:315— Calls to chmod() have the desired effect from a permissive point of view.

316
317

— The relationship between ACLs and file permission bits is easily defined:
to be allowed access either must grant access.

318

This approach has the following disadvantages:319— A chmod(<object>, 0) call does not deny all access to an object with an ACL.

320
321

— In order to deny access, users must be prepared to change both the ACL
and the file permission bits.

322
323
324

— An application would have to use chmod() and stat() to manipulate the filepermission bits and the ACL functions to manipulate the ACL entries on a
file.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.23 Access Control Lists

257

325

B.23.3.5 File Permission Bits Contained Within ACL Without a Mask

326
327
328
329
330

In this approach, only the ACL is consulted for discretionary access control decisions. The file permission bits are logically "mapped" to three base entries in the
ACL. Calls to chmod() modify the ACL_USER_OBJ, ACL_GROUP_OBJ, and
ACL_OTHER entries contained in the ACL. Calls to stat() return this information from the ACL.

331

This approach has the following advantages:

332
333

— The mapping of ACL entries to permission bits is straight forward. Thereis no mask entry that may or may not be there.

334
335

— With no additional entries, the semantic meaning of the file permission bits
are preserved.

336
337
338

— There is some compatibility between file permission bits and ACLs. Use of
chmod() to grant access is compatible. Use of stat() to return access for theowning group is compatible.

339

This approach has the following disadvantages:

340
341
342

— chmod(<object>, 0) may or may not prevent access to the object dependingon the number of ACL entries. With additional entries, the chmod() calldoes not prevent access to the object and this breaks old style file locking.

343
344
345

— chmod go-rwx <object> may or may not restrict access only to the ownerdepending on the number of ACL entries. With additional entries, thechmod() call does not give owner only access.

346
347
348

— creat(<object>, 0600) may or may not restrict access to the newly createdobject to the owner. If a non-minimal default ACL exists on the parent
directory, then owner only access is not guaranteed.

349

B.23.3.6 File Permission Bits Contained Within ACL Including a Mask

350
351
352
353
354

In this approach, only the ACL is consulted for discretionary access control decisions. The file permission bits are logically "mapped" to entries in the ACL. Logically, the file permission bits are the equivalent of a three entry ACL. Calls to
chmod() modify the ACL entries corresponding to the file permission bits. Calls
to stat() return this information from the ACL.

355
356
357
358
359

If there are ACL_USER, ACL_GROUP or implementation-defined ACL entries,
then an ACL_MASK entry is required and it restricts the permissions that can be
granted by these entries. If there is an ACL_MASK entry, then chmod() changes
the ACL_MASK entry instead of the ACL_GROUP_OBJ entry and stat() returns
information from the ACL_MASK entry instead of the ACL_GROUP_OBJ entry.

360

This approach has the following advantages:

361
362

— chmod(<object>, 0) prevents access to the object. This provides compatibility with the old locking mechanism.

363
364

— chmod go-rwx <object> restricts access only to the owner. This utility call,especially when used with the find utility, is useful for restricting access
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

258

B Revisions to Rationale and Notes

365
366
367
368
369
370

to objects to the owner.
— The ACL_MASK entry restricts the permissions that are granted via
ACL_USER, ACL_GROUP and implementation-defined ACL entries during
object creation. For example, without these restrictions, a creat(<object>,0600) would not restrict access of a newly created object to the owner.
This approach has the following disadvantages:

371
372
373
374
375
376

— The mapping between the file group class permission bits is not constant.
If the ACL_MASK entry exists, then the bits map to it. Otherwise, the bits
map to the ACL_GROUP_OBJ entry. This means that chmod() and stat()
update and return, respectively, different information based on theexistence of the ACL_MASK entry. This behavior adds complexity to the
ACL mechanism.

377
378
379

— The ACL_MASK entry does not provide complete compatibility with theuses of chmod() and stat(). chmod g+rwx <object> may grant more accessthan expected due to additional ACL entries.

380
381

There are several sub-issues with having an ACL mask. The following subsections describe those issues.

382(1) Using ACL_GROUP_OBJ as a Mask

383
384

The working group considered having the ACL_GROUP_OBJ performthe masking for additional ACL entries.

385

This approach has the following advantages:

386
387

g

Removes the five (5) ACL entry to four (4) ACL entry transition problem as described in "Automatic Removal of the ACL_MASK".

388
389
390

g

Removes the special cases in chmod() for four (4) ACL entries versus
five (5) or more ACL entries as described in "Requiring ACL_MASK to
be Present".

391

This approach has the following disadvantages:

392
393
394
395
396
397
398
399
400

g

The permission bits associated with the ACL_MASK limit the accessgranted by additional ACL entries that are added during object creation. There are two solutions if the ACL_MASK is removed. First,
simply do not limit the access granted by the additional ACL entries.
See section "File Permission Bits Contained Within ACL Including a
Mask" for more details on why this solution is not acceptable. The
second solution is to modify the additional ACL entries to grant nomore access than was specified by the creating process. See B.23.5.1
for more details on why this solution is not acceptable.

401
402
403
404
405
406

g

It is not possible to grant an additional ACL entry more access thanthe owning group. It is possible to solve this by using a special groupwith no members as the owning group. However, this solution complicates the setfacl utility. In the case where an object only grants
read access to the owning group and a user wants to add an additional ACL entry that grants read-write access, the setfacl utility

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.23 Access Control Lists

259

407
408
409
410
411
412
413
414
415
416
417
418
419
420

would have to add an explicit entry for the owning group, change theowning group to the special group, and add the new ACL entry. Thissolution adds extreme complexity that will be visible to the user.
g

If the file is setgid, then write access is unlikely to be granted by the
ACL_GROUP_OBJ entry. This means that additional ACL entries
would be unable to be granted write access. However, it is questionable if the owner would want to grant write access to a setgid file.

While using the ACL_GROUP_OBJ entry as the mask reduces the complexity associated with masking additional ACL entries, its benefits do
not outweigh the disadvantages in the areas of object creation and usefulness of the ACL_GROUP_OBJ entry itself. Therefore, a separate
ACL_MASK entry is defined and the ACL_GROUP_OBJ entry is used
only to specify the permissions granted to the owning group.
(2) Requiring ACL_MASK to be Present

421
422

The working group considered a strategy to require the ACL_MASK ACL
entry to always be present.

423
424
425
426
427

Either decision adds complexity to the chmod() interface. If the
ACL_MASK is required, then chmod() will behave differently if there are
four (4) ACL entries versus five (5) or more ACL entries. If the
ACL_MASK is optional, then chmod() will behave differently if the
ACL_MASK is present versus if the ACL_MASK is absent.

428This approach has the following advantages:

429
430
431
432
433
434
435
436
437
438

g

Requiring the presence of an ACL_MASK ACL entry provides consistency. Consider the following sequence: A user creates an object ina directory without a default ACL. The user examines the ACL andwill only see the ACL_USER_OBJ, ACL_GROUP_OBJ and
ACL_OTHER entries. The user adds an additional ACL entry. The
user examines the ACL and will see the new ACL entry and the
ACL_MASK entry, in addition to the ACL_USER_OBJ,
ACL_GROUP_OBJ and ACL_OTHER entries. The ACL_MASK entry
has suddenly "sprung" into existence.

This approach has the following disadvantages:

439
440
441
442

g

Requiring the presence of an ACL_MASK entry requires mapping four
ACL entries (ACL_USER_OBJ, ACL_GROUP_OBJ, ACL_OTHER and
ACL_MASK) onto three groups of permission bits if only the base ACL
entries are present.

443
444
445

g

The ACL_MASK serves no purpose if there are no additional ACL
entries. Since it serves no purpose in this case, it should not be
required.

446
447
448
449

The expected use of a system with ACLs includes the use of default
ACLs. Therefore, objects without an ACL_MASK ACL entry are expected
to be rare, and most users will not see an ACL_MASK entry "spring" into
existence. The standard does not require the ACL_MASK entry to be
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

260

B Revisions to Rationale and Notes

450
451
452

present if there are no ACL_GROUP, ACL_USER or implementationdefined ACL entries present.
(3) Automatic Removal of the ACL_MASK

453
454
455
456

The working group considered requiring that the ACL_MASK entry
automatically be removed when all ACL entries other than
ACL_USER_OBJ, ACL_GROUP_OBJ, ACL_OTHER and ACL_MASK
were removed.

457This approach has the following advantages:

458
459

g

Requiring automatic removal makes the existence of the ACL_MASK
less obvious to the user.

460
461

g

Requiring automatic removal is simply a clean-up step.
ACL_MASK has performed its function and is no longer needed.

462
463
464
465
466
467
468
469
470

This approach has the following disadvantage:g

g

g

Set ACL_GROUP_OBJ to the value of ACL_MASK.
If the ACL_MASK has more access than the old ACL_GROUP_OBJ,
this case could unintentionally grant increased access rights. Since
this is a security violation, this case is rejected.

g

480
481
482
483
484
485
486
487
488

Leave ACL_GROUP_OBJ unchanged.
If the ACL_GROUP_OBJ has more access than the old ACL_MASK,
this case could unintentionally grant increased access rights. Since
this is a security violation, this case is rejected.

475
476
477
478
479

Requiring automatic removal of the ACL_MASK and the resultant
resetting of the ACL_GROUP_OBJ permission bits leads to execution
order specific results (in the absence of automatic recalculation). See
below for an example.

If ACL_MASK is explicitly removed, then the permissions of
ACL_GROUP_OBJ must be set to reasonable values. The working groupconsidered the following cases:

471
472
473
474

The

Return an error to the user if an attempt is made to delete
ACL_MASK when ACL_MASK and ACL_GROUP_OBJ differ.
This case was viewed as confusing and was rejected, because deletingan ACL entry should be independent of the ACL_MASK and
ACL_GROUP_OBJ interactions. It does force the user to understandthe problem and take immediate action, rather than waiting until the
inadvertent access reductions from the next case are discovered.
Finding out about a problem immediately is generally better than discovering it inadvertently much later.

g

Logically AND the ACL_MASK and ACL_GROUP_OBJ together andset ACL_GROUP_OBJ to the result.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.23 Access Control Lists

261

489
490
491
492
493
494
495
496

This case can lead to inadvertent access reduction (in the absence ofautomatic recalculation). For example, an object has an ACL with
ACL_GROUP_OBJ ACL entry with read-only access and an
ACL_USER(fred) entry with read-write access. Deleting the
ACL_USER(fred) entry and then adding an ACL_USER(wilma) entry
will produce an ACL that does not allow wilma to have write access tothe object. However, adding ACL_USER(wilma) followed by deleting
ACL_USER(fred) produces the desired affect.

497
498
499
500
501

While automatically removing the ACL_MASK when it is no longer
needed makes the mask less obvious to the user, its benefits do not
outweigh the complexity it adds to the programmatic interface. Therefore, the application must take an explicit action to remove the
ACL_MASK entry when it is no longer needed within the ACL.

502(4) Migration Path Flag

503
504

It is possible to define a flag to indicate whether masking is enabled or
disabled for the implementation.

505

This approach has the following advantages:

506
507
508

g

This flag would give individual system administrators the choice ofdetermining the type of operation required for their specific installation.

509
510

g

The flag would provide a migration path for some applications which
use the chmod() function for file locking.

511

This approach has the following disadvantages:

512
513
514
515

g

The existence of a flag would complicate DAC knowledgeable applications. Software vendors would have to provide different versions of
the applications for the different environments or will have to modify
their applications to work within the different environments.

516
517
518
519

g

The existence of a flag will complicate the utility interfaces defined bythis standard when used in a networked environment where somesystems have the flag enabled and some systems have the flagcleared.

520
521
522

g

The working group is chartered with only producing interfaces. Providing a migration path to a future usage model is beyond the scope of
this standard.

523
524

Given the complexity involved with providing a migration path flag, thisstandard does not include such a flag.

525

B.23.3.7 The Conclusion

526
527
528
529

Compatibility with the existing DAC interfaces in some form or another is theoverriding goal of this section. Most of the approaches considered provided somelevel of compatibility with the existing DAC interfaces. The file permission bits
cannot reflect all the information that can be contained in an ACL. However, the
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

262

B Revisions to Rationale and Notes

530
531
532
533

stat() function should still reflect a reasonable amount of information regarding
the access rights of files and the chmod() function should still be reasonably compatible with the previous semantics regarding the update of access information on
files. Each approach has compelling advantages and discouraging disadvantages.

534
535

g

The "ACL Always Replaces File Permission Bits (Pure ACL)" approach was
rejected because it provides no compatibility.

536
537
538

g

The "Owner Selects ACL Or File Permission Bits" approach was rejected
because it requires existing applications that manage DAC to be modified
to be used on a system with ACLs.

539
540
541

g

The "Independent ACL and File Permission Bits (AND)" approach was
rejected because it leads to wide-open file permission bits on systems thatmake use of ACLs with additional entries.

542
543
544
545

g

The "Independent ACL and File Permission Bits (OR)" approach was
rejected because a user of the existing DAC interfaces can be fooled into
thinking that an object with additional ACL entries is secure when, in fact,others have access to the object.

546
547
548
549

g

The "File Permission Bits Contained Within ACL Without a Mask"
approach was rejected because a user of the existing DAC interfaces can befooled into thinking that an object with additional ACL entries is secure
when, in fact, others have access to the object.

550
551
552

g

The "File Permission Bits Contained Within ACL Including a Mask"
approach was chosen because it provides the "best" compatibility with theexisting DAC interfaces.

553

B.23.3.8 Altering Permission Bit Mapping

554
555
556
557
558
559
560
561
562
563
564
565
566
567

Allowing implementation-defined ACL entries to alter the mapping between filepermission bits and ACL entries defined by this standard was considered. If an
implementation-defined entry is allowed to modify the permission bits, then it ispossible for a strictly conforming POSIX.1e application to fail. Note that a strictly
conforming application cannot add the implementation-defined entry to an ACL,
but the strictly conforming application may not function properly if it modifies an
ACL that contains the implementation-defined ACL entry. Consider the following: an strictly conforming application modifies the ACL_USER_OBJ entry in an
ACL that contains an implementation-defined ACL entry. The implementationdefined ACL entry modifies the permission bits. The strictly conforming application expects the middle permission bits to be identical to the permission bits in
the ACL_GROUP_OBJ entry. However, the permission bits have been modified
by the implementation-defined ACL entry. The strictly conforming application isbroken.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.23 Access Control Lists

263

568

B.23.4 Default ACLs

569
570
571

A default ACL is a defined set of ACL entries that are automatically assigned toan object at creation time. There were five major decisions with default ACLs.
The following subsections explain the rationale for these decisions.

572(1) Why Define Default ACLs?

573(2) Types of Default ACLs

574

(3) Inheritance of Default ACLs During Object Creation

575(4) Compulsory versus Non-compulsory ACLs

576

(5) Default ACL Composition

577

B.23.4.1 Why Define Default ACLs

578
579

Should support for default ACLs be defined by the standard? The following reasons support inclusion of default ACLs in the standard:

580(1) ACL use is encouraged in secure systems.

581
582
583

(2) Default ACLs allow the finer granularity of control provided by ACLs to
be automatically applied to newly created objects. This control can beeither restrictive or permissive.

584
585

(3) In a pure ACL environment, it is necessary to provide some initial accessrights to a newly created object.

586

The following reasons support exclusion of default ACLs from the standard:

587
588
589
590
591
592
593

(1) It is not clear that the benefit of default ACLs outweighs the complexity
introduced in object creation and object attribute management. Object
creation will have to accommodate the existence of default ACLs in addition to the umask and the object creation mode bits. Either a new set ofinterfaces has to be created for manipulating default ACLs or the interfaces for access ACL manipulation will have to be modified to accommodate default ACLs.

594
595
596
597
598
599

(2) The default ACL in any form is a new influence on the ACL of a newly
created object and cannot be manipulated or worked around by existing
applications. Most existing applications will be able to coexist withdefault ACLs. However, existing applications that make security
relevant decisions may not work on a system with default ACLs. See
B.23.5 for specific examples.

600
601
602
603

In general, default ACLs appear to be a useful feature. Several existing ACL
implementations have some form of default ACL mechanism. Certainly, default
ACLs add complexity to the standard; however, they also add considerable value
and should have a well defined standard interface.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

264

B Revisions to Rationale and Notes

604

B.23.4.2 Types of Default ACLs

605
606
607
608

Several different types of default ACLs were discussed by the working group. The
advantages and disadvantages of each type of default ACL are discussed in thefollowing paragraphs. The final paragraph of this section discusses why a particular type of default ACL was chosen.

609(1) System Wide Default ACLs

610
611
612

One specific default ACL is assigned to any object created on the system
by any process, in any directory. System wide default ACLs have the following advantages:

613
614

— Can only be set by the system administrator who is likely to be security conscious

615— Is not complex or difficult to understand and explain

616

System wide default ACLs have the following disadvantage:

617
618

— Limits the specification of the initial discretionary access control on
objects to system administrators rather than the user

619

(2) Per-Process Default ACLs

620
621
622

Each user process defines a default ACL which is assigned to any object
created by the process. Per-process default ACLs have the following
advantages:

623— Models an existing interface, i.e., the umask paradigm

624
625

— Allows the user to retain complete control over the configuration of
discretionary access

626

Per-process default ACLs have the following disadvantages:

627
628

— Follows a paradigm that is considered to be inadequate for present
needs, i.e., the umask paradigm

629
630
631

— Requires the user to be security cognizant at all times; however, aknowledgeable user will only make security relevant decisions with amodest degree of frequency

632— Might not be the right default ACL in a shared directory

633— Allows the user to set only a single default ACL for all files created634(3) Per-Directory Default ACLs

635
636
637
638

Each directory is allowed to have a default ACL which is assigned to all
objects created in the directory. Newly created subdirectories inherit thedefault ACL of the parent directory. Per-directory default ACLs have thefollowing advantages:

639— Allows the user to set up the hierarchy once

640
641

— Prevents the user from having to set a new default ACL as working
directories are changed
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.23 Access Control Lists

265

642
643
644

— Allows system administrators to establish initial default ACLs on
users’ home directories which will propagate to objects created within
the directories

645
646
647

— Allows project administrators to establish initial default ACLs on
shared directories which will propagate to objects created within the
directories

648

Per-directory default ACLs have the following disadvantages:

649
650

— Propagates the default ACL down through the file system hierarchy incases where it is not necessary

651
652

— An implementation written to conserve disk space may have to implement a default ACL sharing mechanism

653
654

— Gives the choice of the default ACL to the directory owner instead of
the file creator

655
656
657
658
659
660

The working group recognizes that a per-directory default ACL gives the
directory owner control over the default value. However, the directoryowner currently has control over at least one attribute of objects createdin the directory: specifying the owning group. Also note that the directory owner has control over object creation, deletion, renaming andreplacement.

661
662
663

The value added by per-directory default ACLs outweighs the complexity introduced by the mechanism and was, therefore, selected as the default ACL mechanism.

664

B.23.4.3 Inheritance of Default ACLs During Object Creation

665
666
667
668

While the working group felt that default ACLs on a per-directory basis provided
the best solution, it considered alternatives to simply propagating the default
ACL to all newly created objects in a directory. The working group considered
two basic schemes for inheritance of ACLs involving the default ACL mechanism:

669
670
671
672
673
674
675
676
677
678
679
680
681
682

(1) Inheritance of Default ACLs for All Objects
The first alternative considered was to have all objects created in a directory inherit the default ACL of the directory. The working group felt that
this solution provided an ACL inheritance mechanism that was consistent across all objects. This option does not take into account any
differing permission requirements for directories as opposed to nondirectory objects.
(2) Inheritance of Access ACLs for Directory Objects
The second alternative specified inheritance of the default ACL as theaccess ACL for all newly-created objects except directories. A newlycreated directory would inherit the access ACL of its parent directory as
its access ACL instead of inheriting the parent’s default ACL. Thisapproach was attractive because it allowed propagation of common properties through a sub-hierarchy which was thought to be the most
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

266

B Revisions to Rationale and Notes

683
684

common case. It further allowed different permissions to be applied todirectories and non-directories which was considered a useful feature.

685

The disadvantages to this approach were the following:

686
687
688
689

— The implementation would not be consistent across all objects. The
semantics for applying initial access control information to a single
type of file object would differ from the semantics for all other types of
file.

690
691

— In the case where a parent directory has no default ACL, counterintuitive side effects were unavoidable.

692
693
694
695
696
697

g

If the access ACL were applied to a newly created directory object
only when a default ACL is present, the application of initialaccess attributes to the directory is determined by an event unrelated to the action of creating the directory, i.e., the presence of a
default ACL. This behavior violates the Principle of Least Astonishment.

698
699
700
701
702
703

g

If the access ACL were always applied to a newly created directory, the semantics of POSIX.1 are violated. The method for applying initial access attributes to directories no longer would allow
the capability to create a minimal ACL, i.e., one corresponding topermission bits, in a manner consistent with the POSIX.1 umask
capability.

704
705
706
707
708
709

The working group selected the first mechanism because the ease in which it
could be consistently applied. The working group felt that the advantages of thesecond approach were not sufficiently beneficial to warrant accepting the disadvantages. If a more flexible default ACL mechanism providing some of the advantages of the second alternative is desired, an implementation may include additional default ACLs for this purpose.

710

B.23.4.4 Compulsory Versus Non-Compulsory Default ACLs

711
712
713

The standard requires a conforming implementation to support a per-directory
default ACL mechanism. The working group discussed whether or not default
ACLs should be required on every directory.

714

The following supports requiring default ACLs on every directory:

715
716

(1) Allows a consistent ACL policy to be maintained for all newly createdobjects

717(2) minimizes the need for the umask

718

The following supports the optional use of default ACLs:

719
720

(1) Allows users who wish to use only the permission bits to use only theexisting DAC mechanism

721
722

(2) Allows existing mechanisms to further restrict access on the newly
created object, i.e. creat and umask
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.23 Access Control Lists

267

723
724
725

The working group feels that allowing users to use either default ACLs or theumask interface provides a significant amount of flexibility. Thus, the working
group decided to make the use of default ACLs on directories optional.

726

B.23.4.5 Default ACL Composition

727
728

The working group discussed having the same required entries for default andaccess ACLs or to have no required entries in default ACLs.

729
730

The following supports having identical required entries for default and access
ACLs:

731
732

(1) Supporting optional default ACL entries leads to a more complex object
creation algorithm that is difficult to explain.

733

The following supports having no required entries in default ACLs:

734
735

(1) The user has the flexibility to configure the default ACL with theminimum amount of access information that is necessary.

736
737
738
739
740

The working group feels that consistency between default ACLs and access ACLs
contributes dramatically to the conceptual simplicity of the default ACL mechanism and that the need for simplicity far outweighs the small increase in flexibility
provided by optional default ACL entries. Therefore, default ACLs have the samerequired entries as access ACLs.

741
742
743
744
745
746

Note that default ACLs are optional on individual directories. However, if a directory has a default ACL, then that ACL must contain at least the three required
entries for owning user, owning group, and all other users. It may contain additional named user and group entries. If a default ACL contains ACL_USER,ACL_GROUP or implementation-defined ACL entries, then an ACL_MASK entry
is also required.

747
748
749
750
751

Also note that a default ACL with no entries is not equivalent to no default ACL
existing on a directory. A default ACL with no entries is an error and any attempt
to associate such a default (or access) ACL on an object will be rejected with anappropriate error code. The appropriate functions (or options on the setfacl
utility) must be used to completely remove a default ACL from a directory.

752

B.23.5 Associating an ACL with an Object at Object Creation Time

753
754

The following goals guided the working group in determining how ACLs should be
assigned on object creation:

755
756
757
758
759

g

The object creation calls and the open() call with the O_CREAT flag specify
the mode to use when an object is created. The mode provided is the
program’s way of indicating the access limitations for the object. It was agoal that no access be permitted to the object if it would not traditionallyhave been granted.

760
761

g

There are many existing programs that use creat(filename, 0) as a locking
mechanism. Although this is no longer a recommended way of doing
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

268

B Revisions to Rationale and Notes

762

locking, preserving this functionality shall be given high priority.

763
764
765

g

The process umask is the user’s way of specifying security for newly createdobjects. It was a goal to preserve this behavior unless it is specifically overridden in a default ACL.

766
767
768
769
770

g

The access determined by an ACL is discretionary access control. But discretion of whom, the creator or the directory owner? Traditionally, discretion has been up to the creator. However, ACLs are often used by projects
in shared directories. It was a goal to permit the directory owner to havecontrol, but only within the limits specified by the creator.

771
772

g

The Principle of Least Astonishment is a guideline that states that changes
to existing interfaces should provide a minimal amount of surprise.

773
774
775
776
777

The working group considered whether the creating process should be allowed tocontrol the inheritance of default ACLs. If the process controls inheritance, thenthe process can keep a default ACL from further restricting the permissions. But
the creator can achieve this anyway, by changing the ACL after creation. Therefore no additional control for the creator was provided.

778
779

The algorithm chosen for determining the mode of a newly-created object is in the
body of the standard. The reasons why this algorithm was chosen are:

780
781
782

(1) If there is no default ACL on the parent directory of the created object,
the ACL assigned to the object is fully compatible with the access granted
to the object in a POSIX.1 system.

783
784
785

(2) The entries of the default ACL are used in place of the equivalent umask
bits. Thus, the creator of the default ACL can control the maximum permissions for newly created files in the directory.

786
787
788
789
790

If umask were used when a default ACL exists, then the user is likely to
set a very permissive umask to permit the full utilization of the default
ACL. This permissive umask would be inappropriate in a directory
without a default ACL. The chosen solution allows umask and default
ACLs to co-exist.

791
792
793
794
795
796
797
798

(3) The newly created object has all the ACL_USER and ACL_GROUP ACL
entries specified in the default ACL. The ACL_USER_OBJ,
ACL_GROUP_OBJ, and ACL_OTHER entries are as close to the ones
specified in the default ACL as possible, within the constraints of thecreator’s mode parameter. If the default ACL contains an ACL_MASK
entry, then it is constrained by the creator’s mode parameter instead of
the ACL_GROUP_OBJ entry. In this case, the newly created object has
the ACL_GROUP_OBJ entry as specified in the default ACL.

799
800
801

(4) The overall effect is that the access granted to the newly created object
has the granularity specified by the default ACL, while preserving theconstraints specified by the object creator.

802
803
804

The only disadvantage recognized by the working group for this algorithm is thatthe umask is not taken into consideration when creating files in a directory with adefault ACL. This solution gives the user little protection against a program that
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.23 Access Control Lists

269

805
806

specifies an unwise create mode when creating a file in a directory with an inappropriate default ACL.

807
808
809
810
811
812
813

Another possible approach is to ignore both the mode parameter of the creat()function and the umask value if a default ACL entry exists. This approach wasconsidered because it gives the directory owner complete control over newly
created objects in her/his directory. Allowing the directory owner to have control
over the permissions of newly created objects is a logical extension. This solution
also supports the contention that the directory owner knows how to set up thepermissions for newly created objects in a particular hierarchy.

814
815
816
817
818

This algorithm was not selected because the directory owner can override theprogram’s advice about the use of a newly created object, i.e., override the create
mode. Traditionally, the creator of an object has complete control over the modeof a newly created object. This solution would completely usurp that control fromthe creator.

819
820
821
822
823
824

The specification of the semantics for applying ACLs on a newly created object isincluded as part of this standard so that applications can predict reliably theaccess that will be granted (or more accurately, the maximum access that will be
granted) based on a default ACL set by that application. This is simply an extension of the specification of the setting of the file permission bits for newly createdfiles in the POSIX.1 standard without the ACL option.

825

B.23.5.1 Modification of ACL Entries on Object Creation

826
827
828
829

The working group considered changing the default ACL mechanism to modify
the permissions granted by additional ACL entries that are added during object
creation. The permissions would be modified to grant no more access than was
specified by the creating process.

830

This strategy has the following advantage:

831
832
833
834
835
836
837
838
839
840

g

If the permissions of the additional ACL entries are modified as describedabove, then the mode parameter specified at object creation could be used
to remove undesired permissions from all entries in the new object’s access
ACL.

This strategy was rejected for the following reasons:g

If the permissions of the additional ACL entries are modified as describedabove, then information that the creator of the default ACL entered is lost.
The most common example is that a creat(file, 0600) would lose the information in the default ACL for all ACL_USER and ACL_GROUP entries.
This represents a potential for considerable information loss.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

270

B Revisions to Rationale and Notes

841

B.23.6 ACL Access Check Algorithm

842

The ACL access check algorithm has several important characteristics.

843(1) Support for concurrent membership in multiple groups.

844
845
846
847
848
849
850
851
852
853
854
855

If a process belongs to multiple groups, the specific access modes
requested are granted if they are granted by the owning group entry or
by a matching group entry in the ACL.
(2) Consistency with existing POSIX.1 features.
The chmod() and stat() functions will continue to operate on the permissions associated with the object’s owner, owning group, and other users
not matching entries in the ACL.
(3) Relative ordering of algorithm steps.
The relative ordering of the algorithm steps is essential to be able toexclude specific users even if they belong to a group that otherwise may
be granted access to the resource.
(4) Support for extensibility.

856
857
858

Implementations that include additional ACL entry tag types or extensions may insert them as appropriate into the relative order of thedefined steps in the algorithm.

859
860

The rationale for the first of these characteristics is covered in detail below. The
issue of interoperability is discussed in detail in B.23.3.

861

B.23.6.1 Multiple Group Evaluation

862
863
864
865
866
867

The design of supplemental groups in POSIX.1 was intended to provide flexibility
in allowing users access to files without requiring separate actions to first change
their group identities. The ACL mechanism facilitates that intent by allowing theinclusion of multiple named group entries in the ACL. Since it is possible for aprocess to match more than one named group entry in the ACL at a time, it isnecessary to define the access that is granted by the matched entries.

868

The following paragraphs discuss the approaches that were considered:

869
870
871

(1) First group-id match. In this approach, the first entry that matches oneof the process’s groups is used to determine access. Access is granted if
the matched entry grants the requested permissions.

872
873
874
875
876
877

This approach does provide a simple solution to the problem, but it doesso by putting a burden on the user to order the ACL_GROUP entries
correctly to get the desired result. Also, while this is an efficient method
to implement, it does dictate implementation details because the ACL
entries must be maintained by the system in the order that they wereentered by the user.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.23 Access Control Lists

271

878
879
880
881

(2) Intersection of matching entries. In this approach, the permissions of all
the entries which match groups of the process are intersected (ANDed)
together. Access is granted if the result of the intersection grants therequested permissions.

882
883
884
885

This approach does provide a slightly complex solution (from a user pointof view) to the problem, but it is considered very restrictive. It is difficult
to justify that a process that is granted read access through one groupand write access through another group should actually get no access.

886
887
888

(3) Union of matching entries. In this approach, the union is taken of thepermissions of all the entries which match groups of the process. Accessis granted if the result of the union grants the requested permissions.

889
890
891
892
893
894
895
896

This approach does provide a slightly complex solution (from a user pointof view) to the problem, but it is considered rather permissive. It is notpossible to ensure denial of access to all members of a group via a restrictive group entry because members of that group may be allowed access
via membership in other groups. It is also possible for a process to be
granted more access than is granted by a single entry, e.g., one entry
grants read access, one entry grants write access and the process isgranted read and write access.

897
898
899
900

(4) Permission match. In this approach, the permissions of all the entries
which match groups of the process are compared with the requested
access. Access is granted if at least one matched entry grants therequested permissions.

901
902
903
904
905
906
907

This approach provides a simple solution to the problem that is very
similar to the POSIX.1 semantics. In POSIX.1, if a process is in the filegroup class and the file group class permissions grant at least therequested access, then the process is granted access. In this approach, if
a process is in the file group class and the permissions of one of the ACL
entries in the file group class grant at least the requested access, thenthe process is granted access.

908
909
910

One of the goals of the ACL mechanism is to be compatible with POSIX.1. Of thedifferent approaches considered, the "Permission match" approach provides thesemantics that most closely match POSIX.1 and is the chosen approach.

911

B.23.6.2 Multiple User Evaluation

912
913
914
915
916
917
918
919

If the effective group ID or any of the supplementary group IDs of a process
matches the group ID of an object, then the POSIX.1e access check algorithm uses
the permissions associated with the ACL_GROUP_OBJ entry and the permissions associated with any matching ACL_GROUP entries in determining theaccess which can be granted to the process. However, if the effective user ID of
the process matches the user ID of an object owner, then only permissions associated with the ACL_USER_OBJ entry are used to determine the access allowed forthe process. No ACL_USER entries are used even if the process matches the
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

272

B Revisions to Rationale and Notes

920

qualifier information for one or more entries.

921
922

This type of behavior is consistent with the previous POSIX.1 interface since a
process could not match multiple user identities yet could match multiple groups.

923

B.23.7 ACL Functions

924

B.23.7.1 ACL Storage Management

925
926
927
928

These issues apply to both access ACLs and default ACLs. The decision to manipulate ACL entries in working storage was made for two reasons: 1) the possibility of unsecure states and 2) the fact that there can be a variable number of ACL
entries.

929
930
931
932
933
934

If ACL entries could be manipulated directly, or if ACL entries could be manipulated while the ACL continued to protect the object, unsecure states could arise.
This is because the functions which manipulate ACL entries only manipulate single entries. The procedural interfaces we have chosen are not capable of changing
several entries in a single autonomous operation. Because of this the possibility
exists that a less secure state could arise during the modification of an ACL.

935

B.23.7.1.1 Allocating ACL Storage

936
937
938
939
940
941

Since an ACL can contain a variable number of ACL entries, mechanisms to allocate and free dynamic memory are required. The working group considered four
approaches. The first approach was to have a single function that allocates a
specific amount of memory for the ACL. The disadvantage to this approach isthat the user must allocate enough storage or an error will occur and new larger
working storage will have to be allocated and the ACL entries recreated.

942
943
944

The second approach is to have two functions that allocate space for the ACL.
The first function allocates a specific amount of space for the ACL and the second
function increases the space allocated by the first function to a specific size.

945
946
947
948
949
950

The third approach is to have a single function that allocates an initial amount ofmemory. Applications would then provide the address of the pre-allocated ACL
storage area to the ACL manipulation functions. The acl_copy_int(),
acl_create_entry(), acl_from_text(), acl_get_fd(), and acl_get_file() functions would
manipulate the ACL within the ACL storage area provided by the application andwould allocate additional memory as needed.

951
952
953
954
955
956

The fourth approach is to have the routines which work with working storage
areas for opaque data types allocate the working storage as needed and thenreturn pointers to descriptors for those areas. Functions which then manipulate
the ACL in the working storage area would allocate additional memory for working storage as needed. In addition, a function to allocate storage for an ACL withno entries would be provided.

957
958

The final approach has been chosen for inclusion in the standard in order to provide a consistent interface among the various sections of POSIX.1e.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.23 Access Control Lists

273

959

B.23.7.1.2 Copying ACL Storage

960
961
962

The acl_copy_entry() function is provided for several reasons: an acl_entry_t is a
descriptor and cannot be byte copied; an implementation can have extensions andwithout the function it is not possible for a portable application to copy an entry.

963
964
965
966

The acl_copy_entry() function is also provided to allow an application to copy anentry from one ACL to another ACL. This is useful when the source ACL is a listof "defaults" that the application provides for building ACLs to apply to arbitrary
objects.

967
968
969
970
971
972

The acl_copy_entry() function allows an application an easy means of copying an
ACL entry from one ACL to another ACL. For example, one implementation of an
ACL builder application may maintain an ACL "scratch pad" that is used to build
ACLs to be applied to objects. The application may provide a means of highlighting specific ACL entries in the "scratch pad" to be copied to the ACL that is being
built.

973

B.23.7.1.3 Freeing ACL Storage

974
975
976
977

An explicit interface for freeing ACL storage is provided. The working group considered embedding this functionality into the acl_set_file() and acl_set_fd() interfaces. The disadvantage is that a program wanting to apply a single ACL to multiple files would have to create or read the ACL for each application of the ACL.

978

B.23.7.2 ACL Entry Manipulation

979
980
981

Interfaces are provided to manipulate ACL entries. There were five major decisions with ACL entry manipulation. The following subsections explain therationale for these decisions.

982

B.23.7.2.1 Procedural Versus Data Oriented Interfaces

983
984

This standard uses a procedural interface to manipulate ACL entries instead of
the traditional UNIX style data oriented interface.

985
986
987
988
989
990
991

A data oriented interface specification typically defines a small set of primitives toaccess data objects, e.g. read, write, or commit. The application must be aware of
the structure of the data and is responsible for direct manipulation of the data.
The advantages of a data oriented interface is that it provides the application asubstantial amount of flexibility in accessing and manipulating the data. However, because the application must know the structure of the data, any change inthe ordering, size, or type of the data will impact the application.

992
993
994
995
996
997
998

A procedural interface isolates the application from the structure of the data. Theinterface consists of a larger set of functions where each function performs one
operation on one field within the object. The application manipulates the data
items within an object by using a series of functions to get/set each data item anda smaller set of functions to read and write the object. The advantage of a procedural interface is that it allows changes and extensions to the structure of thedata without any impact to applications using that data. However, isolating the
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

274

B Revisions to Rationale and Notes

999 application from the data structure provides the application with less flexibility in1000 accessing and manipulating the data and exhibit poorer performance.
1001

A data oriented interface has the following advantages:

1002

g

consists of a small set of functions.

1003

g

can be manipulated by language primitives.

1004

g

is consistent with traditional UNIX calls, e.g., stat(), chmod(), etc.

1005

A procedural interface has the following advantages:

1006
1007

g

allows changes/extensions to the data structures without impacting applications.

1008

g

contains fewer visible data structures

1009
1010

g

supports a move toward object oriented interfaces which tends to encourage
more portable code

1011
1012
1013

The advantages of isolating applications from the structure of ACLs and ACL
entries are substantial. Thus, a procedural interface was chosen to manipulate
access control list information.

1014
1015
1016
1017
1018
1019

We originally did not choose to define a procedural interface for manipulating thepermission set within an ACL entry. Our reason was that the application must
be aware of the structure of permission sets (bits within a long data type) andshould be responsible for manipulating the bits directly. In our original opinion,
the ease of direct language manipulation of the permission bits far exceeded any
advantage gained in hiding the structure of the information.

1020
1021
1022
1023
1024
1025

During balloting it became clear that procedural interfaces for permission bits
had additional advantages. Functions to manipulate permission sets were added
later to allow an implementation to have more permissions than could fit in anatural data type (32 bits). While it is somewhat difficult to imagine why morethan 32 permissions are needed, it is not good design to preclude such an implementation.

1026

B.23.7.2.2 Automatic Recalculation of the File Group Permission Bits

1027
1028
1029

The initial proposal was to recalculate the file group permission bits whenevera new ACL entry is added. The following example illustrates a problem with thisapproach.

1030
1031
1032
1033
1034
1035
1036
1037
1038
1039

Consider a file created with a file creation mask of 0 in a directory that
contained a fully populated default ACL. This file will have file grouppermission bits of 0, i.e., ---, yet may have named ACL_USER or
ACL_GROUP entries specifically granting permissions. (These entries
will be effectively ignored during access checking because of the masking
effect of the 0 file group permission bits.) If the file group permission bits are automatically recalculated whenever a new ACL entry isadded, the result of adding a ACL_USER entry specifically denying auser access will be to effectively grant access to the previously masked
ACL entries.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.23 Access Control Lists

275

1040
1041
1042

It seems counter-productive at best to have an entry that denies a user access also
grant access to other users. However, there does not exist a technique to allow for
the application of a single entry in an ACL and the exclusion of others.

1043
1044
1045
1046
1047
1048

Other proposed alternatives include providing a mechanism in the setfacl utility to specifically request recalculation. A problem with this alternative is thattypically a user adds an entry to an ACL with the intent of having the new entry
affect the access decision. It isn’t possible to have one new named ACL_USER or
ACL_GROUP entry be guaranteed effective in the access algorithm without recalculating the file group permission bits based on all entries.

1049
1050

The final alternative considered by the working group is to provide an explicit
interface for recalculating the mask.

1051

B.23.7.2.3 Convenience Functions

1052
1053
1054
1055

The acl_calc_mask() function is provided for the convenience of applications.
Applications could be required to perform this function, but DAC knowledgeable
applications are likely to need it. Therefore, it is better to provide a standard
interface.

1056
1057
1058
1059

The acl_valid() function is provided as a convenience for applications. Applications could be required to perform this function, however this functionality will
likely be used by ACL cognizant applications. Therefore it is better to provide astandard interface for this functionality.

1060
1061
1062
1063
1064

It is possible to merge the acl_valid() and acl_set_∗() functions together. However, it may be useful for ACL cognizant applications to be able to perform theacl_valid() function without having to apply (write out) the ACL to an object.
This was seen as particularly useful for interactive tools in dealing with accessand default ACLs.

1065
1066
1067
1068
1069
1070
1071
1072

The group considered providing program interfaces for the creation of objects witha specified ACL and other security attributes. The motivation for this is that
security-conscious programs may wish to ensure that objects they create havecorrect ACL and other security attributes throughout their life, from the instantthey are created. The group decided not to standardize such interfaces because
programs can achieve the security objective by creating the object using existing
POSIX.1 interfaces specifying very restrictive permissions and then setting the
ACL to the required value.

1073
1074
1075
1076

The acl_first_entry() function was added to allow applications to revisit ACL
entries previously referenced with acl_get_entry(). This is particularly needed byapplications which are creating an ACL in working storage and need to revisit a
previously created entry.

1077

B.23.7.2.4 Hooks For Sorting

1078
1079
1080
1081

The acl_valid() function may change the ordering of ACL entries. This behavior
allows an implementation to sort ACL entries before passing them to theacl_set_∗() function. This allows a performance improvement to be recognized.
Since the acl_set_∗() function does not require any specific ordering, the system
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

276

B Revisions to Rationale and Notes

1082
1083
1084
1085

will likely sort all entries so that it may check for duplicates. If the sorting is performed by the acl_valid() function, the system may only need to make one passthrough the ACL resulting in an order (N) sort when the acl_set_∗() function iscalled.

1086
1087
1088

Functions which may add entries to an ACL, or remove them, are also allowed toreorder the entries of an ACL. This permits, but does not require, an implementation to keep an ACL in some implementation specific order.

1089
1090
1091
1092

Note that the standard requires that even implementations that reorder theentries of an ACL do not invalidate any existing ACL entry descriptors that referto the ACL: these must continue to refer to the same entries even if the implementation reorders the entries.

1093

B.23.7.2.5 Separate Functions for Tag and Permission

1094
1095
1096
1097
1098
1099

A single function (for example, acl_get_entryinfo()) could have been provided for
retrieving ACL entry fields rather than separate functions. However, the standard provides individual interfaces for retrieving and setting each logical piece of
information within an ACL entry. Implementations can add information to an
entry and add a separate interface for that implementation-specific information
rather than changing the ones specified in this standard.

1100
1101
1102
1103
1104
1105
1106

Implementations are allowed to define additional ACL entry types with arbitrary
size qualifier fields. Because of this, acl_get_qualifier() cannot simply copy out auser ID or group ID size object. The acl_get_qualifier() interface returns a pointerto an independent copy of the qualifier data in the ACL entry. The copy is
independent because the ACL entry may be relocated by an acl_create_entry() or
acl_delete_entry() call. When the application is done with the ACL entry, thespace needs to be released; hence, the need for for a call to acl_free().

1107

B.23.7.3 ACL Manipulation on an Object

1108
1109
1110
1111
1112

Interfaces for manipulating an ACL on an object are provided for reading an ACL
into working storage and for writing an ACL to a file. These functions provide atype parameter to allow for implementations which include additional types ofdefault ACLs not defined in the standard. See the rationale for ‘‘ACL Storage
Management’’ for additional information.

1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124

An earlier version of the draft contained a requirement that modifying an an ACL
on an object and removing a default ACL from a directory be implemented as"atomic operations". The specific requirement was that the operations be atomic
with respect to the invocation and termination of the function calls and any use of
the ACL (access or default ACL). There was also the requirement that changes toan existing access or default ACL could not result in any intermediate state suchthat both the original ACL and the result ACL were both associated with the target file. While these requirements are certainly necessary, they are requirements
upon the implementation, not the functional interface. As such, it is left to theimplementation to define and enforce its own atomicity requirements. In addition
to not being an interface issue, such atomicity requirements are inherently nontestable. As such, it is unreasonable to require the construction of tests to
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.23 Access Control Lists

277

1125
1126
1127

demonstrate conformance these atomicity requirements. For these reasons, allatomicity requirements were removed from the acl_delete_def_file(), acl_set_fd(),
and acl_set_file() functions.

1128

B.23.7.4 ACL Format Translation

1129

There are three formats of an ACL visible to the programmer:

1130(1) An internal representation that is used by the ACL interfaces.

1131
1132

(2) A self contained data package which can be written to audit logs, stored
in databases, or passed to other processes on the same system.

1133(3) A NULL terminated text package (string) that can be displayed to users.

1134
1135

The ACL copy and conversion functions provide the means to translate an ACL
among the various ACL representations.

1136
1137
1138

The NULL terminated text package may contain a representation of an ACL ineither a long text form or a short text form. The following is an example of a valid
ACL in the long text form:

1139
1140
1141
1142
1143
1144
1145
1146

user::rwx
mask::rwx
user:jon:rwx
user:lynne:r-x
user:dan:−−−group::rwx
group:posix:r−x
other::−−x1147

The following is a representation of the same ACL in the short text form:1148

u::rwx,m::rwx,u:jon:rwx,u:lynne:r-x,u:dan:−−−,g::rwx,g:posix:r−x,o::−−x

1149
1150
1151

The working group considered using the self contained data package as the internal representation of an ACL. The working group rejected this option for the following reasons:

1152
1153
1154

(1) Implies that some implementations would have to translate an internal
form into a self contained form on every POSIX.1e compliant ACL operation.

1155
1156
1157
1158
1159

(2) The programmer has to keep track of the size and location of the ACL
with every operation that can modify the ACL. The size must be tracked
because the ACL size may grow or shrink. The location must be tracked
because an ACL may not be able to grow in its present location andwould have to be relocated.

1160

B.23.7.5 Function Return Values and Parameters

1161
1162
1163

The acl_get_∗() functions can return pointers, descriptors and discrete values. If
an acl_get_∗() function returns a pointer, then it is returned as the function
return value. This is because a NULL pointer is valid indicator for error
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

278

B Revisions to Rationale and Notes

1164
1165
1166

conditions. If an acl_get_∗() function returns a descriptor or a discrete value, thenit is returned as a write-back parameter. This is because there is not a welldefined value that can be returned to indicate that an error has occurred.

1167

B.23.7.6 File Descriptor Functions

1168
1169
1170
1171
1172

The working group decided to specify functions that operated via file descriptors
in addition to functions that operated via a file name. These functions allow anapplication to open an object and then pass around a file descriptor to that object
instead of both the name and the file descriptor. BSD has found the related
fchdir(), fchmod(), fchown() and fchroot() interfaces to be useful.

1173

B.23.8 Header

1174
1175

Values for acl_perm_t are defined in the header because no definitions in POSIX.1
were suitable. Those definitions considered in POSIX.1 were:

1176
1177

(1) Definitions in POSIX.1, 5.6.1.2. These definitions refer to the nine permission bits whereas ACL entry permissions have only three values.

1178
1179

(2) Definitions in POSIX.1, 2.9.1. These names, e.g., R_OK, were notappropriate for ACL entry permissions.

1180

B.23.9 Misc Rationale

1181

B.23.9.1 Objects Without Extended ACLs

1182
1183

This standard specifies that each file will always have an ACL associated with thefile, but does not require each file to have an extended ACL.

1184
1185
1186
1187
1188

Originally, the provided ACL functions allowed for returning [ENOSYS] if{_POSIX_ACL} was defined and the specified file cannot have an extended ACL.
This was subsequently changed because of objections to the overloading of[ENOSYS] to return [ENOTSUP] for the cases where a file cannot have an
extended ACL.

1189
1190
1191
1192
1193
1194
1195
1196
1197

A pathconf() variable {_POSIX_ACL_EXTENDED} is provided to allow applications to determine if a file can have an extended ACL. This standard does not
specify the specific situations where a file cannot have an extended ACL. Examples of possible situations are: CD-ROM file systems, and pre-existing file systems
with insufficient space to insert extended ACLs. The acl_get_fd() and
acl_get_file() functions will always return an ACL because each file will always
have an ACL associated with the file. The acl_delete_def_file(), acl_set_fd(), and
acl_set_file() functions can return [ENOTSUP] if the specified file cannot have an
extended ACL.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.23 Access Control Lists

279

1

B.24 Audit

2

B.24.1 Goals

3

The goals for the POSIX.1e audit option are:4

(1) Support for Portable Audit-generating Applications

56(a) Define standard interfaces for applications to generate audit
records.

78(b) Define standard interfaces for applications to request that the system suspend its generation of audit records for the current process.

9(c) Define capabilities for these interfaces.

10(2) Support for Portable Audit Post-processing Applications

1112(a) Define a standard format for system- and application-generated
audit records, as viewed through audit post-processing interfaces.

1314(b) Define a minimum set of the POSIX.1e interfaces which shall bereportable in a conforming implementation.

15
16
17

(c) Define a standard set of record types, corresponding to the reportable POSIX.1e interfaces, and the required content of those record
types as viewed through the audit post-processing interfaces.

1819(d) Define standard interfaces for reading an audit log and processing
the audit records that are read.

20(3) Extensibility for Implementation-specific Requirements

2122(a) Ensure that standard reading and writing interfaces allow
specification of arbitrary data in application-defined audit records.

2324(b) Allow for reporting of additional implementation-defined events byconforming implementations.

2526(c) Ensure that standard definitions of the content of required auditable events allow for extension by conforming implementations.

2728(d) Define standard interfaces for access to implementation-specificaudit storage mechanisms (audit logs).

29
30
31
32
33
34
35

The auditing interfaces specified by this standard are intended to be compatible
with the auditing requirements of a number of specifications, including but notlimited to the U.S. TCSEC levels C2 and above and the European ITSEC functionality levels F-C2 and above. It should be noted that this compatibility extends−
only to the functional specifications; and also that meeting the requirements ofthis standard would not necessarily be sufficient to meet all of the audit requirements of any of the above specifications.

36
37
38

There was recognition by the working group that it should be possible for anumber of differing implementations to be developed all meeting the POSIX.1e
audit requirements. Additionally, consideration was given to the fact that
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

280

B Revisions to Rationale and Notes

39
40
41

implementations may (will) wish to extend the set of audit functions, audit eventsand audit records in various ways. For these reasons, flexibility in the POSIX.1e
audit requirements was a primary goal.

42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

In developing the POSIX.1e audit functions, the working group envisaged two distinct types of auditing applications. First were the class of applications which
need to generate their own audit data. These applications, usually trusted, shouldbe able to generate audit data in a standard audit log, rather than simply adding
data to an application specific log file. Second were the class of applications thatprocess audit logs. These analysis tools typically read, analyze and produce
reports based on the audit data contained in the log. Optimally, these tools
should be able to read and analyze audit logs from any POSIX.1e audit conforming application. Currently this goal is only partially met. The POSIX.1e audit
option provides functions which could be used to develop a audit analysis tool,
however, a common (portable) audit log format is not currently defined by thisstandard. Note that the POSIX.1e audit option specifies only the functions which
an analysis tool would use, not the tool itself. The definition of a portable postprocessing utility is left to a later stage, when security administration utilities are
standardized.

57

B.24.1.1 Goal: Support for Portable Audit-Generating Applications

58
59
60
61
62
63

Commonly, portable applications, for example a data base, generate and record
application specific audit data. Preferably, this data should be recorded in a system audit log rather than maintaining application-specific log files, or, worse, justignoring security-relevant events as is common today. It is clearly more desirable
for applications to use the standard system auditing mechanism than for each toinvent its own.

64
65
66
67
68

In support of this goal, POSIX.1e audit provides a set of portable interfaces which
an application could use to construct audit records and deliver them to an
appropriate destination. In some cases it may be desirable to have these records
added directly to the system audit log while in other cases a separate log may berequired.

69
70
71
72
73
74
75
76
77
78
79

In order to provide maximum flexibility, the ability to support multiple audit logs
has been provided. Applications get access to logs (other than write access to thecurrent system audit log) via the POSIX file abstraction: that is, the POSIX.1
open() function is used. An additional function, aud_write(), is provided to allow
records to be added to an audit log by self-auditing applications, since records
written will normally have additional data added to them, and may betransmuted into some internal format, by the system in a way which is not consistent with the normal semantics of write(). A file descriptor parameter is normally used to tell this aud_write() interface which log is the destination, but a
special value is defined to identify the system audit log (see ‘‘Protecting the Audit
Log’’ below for rationale for this).

80
81
82

Records of security-relevant events, generated by an application, often relate toactions performed by, or on behalf of, a process (ie, acting as a subject), on one ormore objects. The record needs to be structured so that the data that relates to
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.24 Audit

281

83
84
85
86
87
88
89
90

the subject, or a particular object, or other aspects of the event, can be related
together: for example, if the record contains a UID, it needs to be clear which subject or object it is related to. The standard therefore provides means for an application to build structured audit records, with separate sections for each subject orobject. Such records can be quite complex, and it would be inefficient if the application had to build each one from scratch. The standard therefore provides means
for the application to alter fields within a record it has constructed, allowing reuseof records.

91
92
93
94
95
96
97
98
99
100
101

In general, applications that generate audit records will also perform operations
that cause the system to record audit records on their behalf. For example, a database may open several files in normal course of action. For some applications,these system-generated records may be irrelevant and confusing, because theapplication itself might generate records that are more precise and informative.
Therefore a provision is made to allow these, presumably trustworthy, applications to request that recording of system-generated records be suspended because
they will provide their own. To ensure the integrity of the audit log, appropriate
privilege is required to request suspension of audit records. Also note that this isa ‘‘request’’ to suspend the generation of audit records; an implementation is free
to ignore this request.

102

B.24.1.2 Goal: Support for Portable Audit Post-Processing Applications

103
104
105
106
107
108
109
110
111

The working group recognized that a practical need for audit analysis tools, applications which read, analyze and formulate audit reports, existed. Additionally, tobe of maximum value, these tools must be able to access and analyze audit logs
from any conforming implementation. Currently, few audit analysis tools exist,
and none of the tools examined by the working group were very sophisticated. It
is therefore difficult to determine what functions are required for these analysis
tools to function adequately. The working group determined that, at minimum,
an analysis tool would need to access (open), read and terminate access (close) tothe audit log.

112
113
114
115
116
117
118
119
120
121
122
123
124

In Draft 14 the working group recognized the need to make audit records available as they are committed to the audit log. The group felt that tools such as
intrusion detection programs would require such a feature. The function
aud_tail() was added to allow an application to request that records be madeavailable to it as they are being written. However, it was later pointed out thatthe required effects could be obtained without use of a specialized interface: forexample, an intrusion detection application could read from the end of the filecurrently used for the system audit log, using mechanisms similar to tail(1); andit could be told by the administrator (or other software) when the file corresponding to the system audit log gets altered. Accordingly, the interface was removed
again. (There was some concern that this might result in records not being
delivered for analysis until after a delay due to system buffering, but this was felt
to be an implementation matter.)

125
126

The working group considered the addition of functions to query (selectively read)the audit log but rejected the idea for several reasons:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

282

B Revisions to Rationale and Notes

127
128
129

1.

Understanding of need. The group could not determine what type of query
functionality would be required by a portable analysis tool. Lack of market
models made the task more difficult.

130
131
132

2.

Defined query language. The group was unable to locate an agreed upon
standard language for formulating a query. The working group was reluctant to invent a query language for POSIX.1e audit.

133
134
135

3.

Extraneous functionality. The working group felt that as long as an analysis
tool could access the next sequential record, that an analysis tool could provide its own query capability.

136
137
138
139
140
141
142

In addition to a set of common functions, a portable analysis tool may need toread and analyze audit logs from various sources. Thus, a portable tool may be
dependent upon the definition of a standard audit record format. This standard
does define a set of standard audit events, and the required record content for
those events; it also defines means by which additional information in thoserecords, and information in other records, can be obtained in a syntacticallymeaningful way.

143
144
145
146
147
148
149
150
151
152

Early versions of this standard contained requirements for storage of data in astandard form. This form proved to be unacceptable for most implementations,which have varying requirements for efficient storage of audit data. The working
group decided to allow for storage of data in ‘‘native format’’ by default with an
option to record data in a ‘‘portable format’’, to be defined. Without this interchange format, analysis of audit data across multiple storage implementations
requires the application to do several conversions; from native format to humanreadable text (e.g., internal to external), gather the data on a single machine andthen convert the human readable text to internal format (e.g., external to internal).

153
154
155

Since the portable audit log definition has yet to be developed, a possible goal of
support for portable audit post-processing applications is currently satisfied onlyin part, primarily by defining functional interfaces to audit data.

156
157
158
159

In addition to the definition of standard functions, POSIX.1e audit also defines a
set of standard audit events. These events, based on standard POSIX.1 and
POSIX.1e interfaces, define the minimum data elements to be supplied by a conforming implementation when the event occurs (assuming auditing is enabled).

160
161
162
163
164
165

Events generated by standard POSIX.1 operations are defined to ensure that a
portable analysis tool has some common ground in any system, although in practice, application-specific analysis tools (using standard interfaces to readapplication-specific data) will probably be fairly common. By defining the event
types in this standard, a consistent mapping across all conforming systems isachieved.

166
167
168
169
170

There was some debate on whether to include events related to the relatively
small set of POSIX.2 interfaces that are (arguably) security-relevant. However, a
POSIX.2 interface is not necessarily built over POSIX.1; conversely, a POSIX.1
system does not necessarily provide POSIX.2 commands and utilities. There isthus no basis for defining POSIX.1e audit events for the POSIX.2 interfaces. The
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.24 Audit

283

171

following were also seen to be reasons for excluding these events:

172
173
174
175

1.

If a POSIX.2 implementation is built over POSIX.1, many of the POSIX.2
interfaces are adequately audited by the underlying audit events: eg,
chmod(1) is adequately audited by the events for exec(2) of the command andchmod(2).

176
177
178

2.

The most important security relevant commands, such as login, are notincluded in POSIX.2; those that are administrative are generally deferred toc
the POSIX 1387 working group.

179
180
181
182
183
184
185

3.

In many cases, the commands that are included in POSIX.2 are not the ones
that need to be audited. For example, it is not particularly relevant that auser has requested that a file be printed, or a batch job be started; what isrelevant is the actual printing or starting of the job, which may or may notoccur. POSIX.2 does not define the means by which these latter actions
actually occur, any more than it specifies login or administrative interfaces,
so it is not possible to standardize audit records for these occurrences.

186
187
188
189
190
191
192
193
194

The working group had debated including commonly known functions such as
login, cron, etc to the set of standard events. However, the majority of the working
group felt that adding non-POSIX events was not acceptable because (a) whilethese events were ‘‘common’’ they were not ‘‘standard’’, hence the ‘‘common’’events were not deemed acceptable for inclusion and (b) systems which did notsupport these ‘‘common’’ functions would still have to support all the POSIX.1e
audit event types. Additionally, there was some variance between the implementations of the ‘‘common’’ events. For these reasons the working group decided tolimit the scope of POSIX.1e audit events to the domain of POSIX standards.

195
196
197
198
199
200
201
202
203
204
205
206
207

The working group debated the set of included events at great length; the goal
was to include only those events which were security related and/or critical to theaudit log. For example, consideration was given to including AUD_READ in theset of auditable events, however, it was felt that the information deemed desirable
would be obtained by auditing the opening of the audit log. The AUD_WRITE
event was also debated, with similar results (except that it was decided to audit
AUD_WRITE failures). The working group felt that the amount of information
derived from events such as these did not justify the potential performance
penalty (e.g., auditing each read/write). Consideration was given to making these
events optional. The group felt that the concept of ‘‘optional’’ events had little
value because portable applications could not depend on the events being supported (because the events were optional) and hence the ‘‘optional’’ events would
be of little use.

208

B.24.1.3 Goal: Extensibility for Implementation-Specific Requirements

209
210
211
212
213

It is important to allow applications to generate arbitrary records. Rather thanhaving a single generic record, however, applications are permitted to place information in audit records that, while application-specified, has existing syntax associated with it that allows an analysis program to process the information. For
instance, an application refers to a file by pathname, and because there is a
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

284

B Revisions to Rationale and Notes

214
215
216

standard way to describe a file in an audit record, an analysis program can selectrecords concerning a particular file without knowing anything about the application generating the record that mentions the file.

217
218
219
220
221

Similarly, it is important to allow applications to specify arbitrary information inaudit records, because not all the items an application needs to specify will be of
the sort that can be interpreted in a portable way. The set of audit attributes is
extensible to allow this, and additionally includes an explicitly defined opaquedata object for application use.

222
223
224
225
226
227
228
229

Not all applications will want to use the system audit log; indeed, a particular
implementation may not permit such use. So, it is important to allow implementations to provide other audit logs. Because the POSIX file abstraction provides
defined interfaces without mandating any particular implementation mechanism,
it is appropriate to use this for access to audit logs. Some proposals for this standard specified that audit logs were independent of the normal file systems, having
their own set of interfaces (e.g., aud_open(), aud_close()) however these were notseen to provide any particular advantages.

230
231
232
233
234
235

Apart from the above application-oriented considerations, it is important that
implementations be able to extend the set of auditable system interfaces, and toextend the set of data that is reported in audit records for the standard auditableinterfaces. They will thus be able to report the occurrence of security relevant
events that are beyond the current scope of ratified POSIX.1 standards, and torecord additional security information for the standard events.

236

B.24.2 Scope

237
238

The scope of security auditing specifications in POSIX.1e is defined by the above
goals. In addition, the following items are specifically excluded:

239
240
241
242
243

(1) Administration
Functions and utilities to support security audit administration are
excluded. These exclusions include the assignment of audit control
parameters to specific users, and pre-selection of which auditable events
are to be recorded.

244
245
246
247

(2) Audit data storage
The definition of formats and organization for permanent audit data
storage is not addressed, nor is there any required storage organization
for a system’s audit log.

248
249
250

(3) Portability/Data interchange
The definition of formats and organization required for a portable audit
log and for interchange of audit data are not addressed.

251
252
253

(4) Audit delivery mechanism
The definition of a mechanism for delivering records is not addressed,
although the interface to this mechanism, 24.4.40, is included.

254
255

Administrative functions are excluded from the POSIX.1e auditing scope, these
are the province of POSIX.7.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.24 Audit

285

256
257
258
259

The specification of criteria for the pre-selection of which audit records should berecorded is deemed to be an administrative issue. It was felt that portable
trusted applications could not reasonably make use of interfaces to control preselection.

260
261
262
263
264
265
266
267
268
269

A grouping of event types into classes of events for post-processing were excluded
from the scope because it was felt that not enough is currently known about postprocessing to allow a solid set of post-processing classes to be included in the
POSIX.1 standard. The group felt there were two compelling reasons why it was
inappropriate to standardize event classes: (1) the grouping of events into classes
is inherently arbitrary; while the group could easily agree on a standard set ofcommon events (based on POSIX.1) the grouping of these events into classes differed widely, (2) the definition of classes does not add greatly to application portability because the event type rather than class is what is stored in the audit
record.

270
271
272
273
274

This standard does not address audit data storage. It is expected that each conforming implementation may have a different form of permanent storage for audit
data. Similarly, the issues of interchange of audit data are not addressed. A key
problem in the definition of data interchange is that current standards do notaddress data size issues at all.

275
276
277
278
279

This standard does not address the actual mechanism for delivering audit records
from a trusted application (or from the operating system itself) to a system’s audit
log. However, the interfaces that an application (or the operating system) would
use to perform the delivery are specified. An actual delivery mechanism might
involve spooling daemons, special network protocols, etc.

280
281

This standard also does not address the issue of protection of the audit data, thatbeing an implementation’s responsibility (see below for further rationale for this).

282

B.24.3 General Overview

283
284
285
286
287
288
289
290

In this standard, the general architecture for audit record processing is that theinternal format of audit records is opaque, and functional interfaces are provided
both for audit-generating applications to construct audit records (adding, changing and deleting fields) and for audit post-processing applications to analyze
records (reading fields). The system manages the working storage used to holdthe record; interfaces are provided to create new (empty) records in the working
store, to read records from an audit log into the working store, and to write
records from working store into an audit log.

291
292
293
294
295
296
297

An earlier version of this document used explicitly different storage representations for data structures used in reading records and in writing records. Writing
records used opaque storage (called an Audit Record Descriptor), whereas readingused a caller-supplied buffer that was implied (but not required) to be a directly
accessible storage representation of the portable audit record format. In principle, this would have allowed a processing program to have performed manipulations directly on the record contents, without using the reading interfaces.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

286

B Revisions to Rationale and Notes

298
299
300
301
302
303

A major criticism of this proposal was that it required that all data should be
written in a portable format that was biased toward machines that support
expanded data types. In abandoning the requirement that all audit data should
be stored directly in the portable format, it became impossible to provide this ability. It also became apparent that the defined set of interfaces had become
sufficiently complete and efficient that the ability was no longer important.

304
305
306
307
308
309
310
311
312
313
314

The original proposal defined audit records as consisting of individual ‘‘tokens’’
where a ‘‘token’’ represented an independent element of a record, for example apathname. To make the token opaque all manipulation of the token (read/write)
was done using per-token interfaces. For example get_pathname_token and
put_pathname_token would be required to get (read) and put (write) a specifictoken. It is easy to see how this style of interface could lead to an excessive
number of token types and in turn, an excessive number of interfaces required tomanipulate each token type. There was also the possibility of inconsistent use of
the tokens by applications performing their own auditing. The concerns regarding
efficiency of storage and number of interfaces led to the replacement of the ‘‘token
based’’ proposal.

315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331

In draft 13, self-auditing applications were required to construct audit records inuser-managed storage, because the user (application) knows the size and contentsof the record, and there is no point in making the data opaque. Also, the record
may be used as a ‘‘template’’, that is the record may be modified and written multiple times without requiring multiple allocate/free operations of system managed
storage. However, this proposal was criticized in ballot for not providing either
sufficient record structuring capabilities or sufficient support for portable applications; extending the proposal to provide additional structuring would add considerably to the complexity of the data structures applications would have to manipulate (giving problems in some language bindings), and would exacerbate thesecond criticism. In contrast, system-managed storage was used for reading
records, because in many cases the application will rapidly eliminate most records
from the analysis, and keeping them in system-managed space saves the cost of
converting the whole of each record from an internal to a standard format. Also,
programs reading records are likely to be processing many records sequentially,
and correspondingly benefit from eliminating application-level storage management overhead.

332
333
334
335
336
337
338
339
340
341
342

The current set of interfaces and corresponding data structures have been
designed to provide reasonable application support with reasonable efficiency,
without an excessive number of interfaces. Data storage representations are notdefined. The interfaces deal with opaque structures at the top level, and individual components at a lower level; the latter use ’get item’ interfaces, and a ’type
length pointer’ data structure, thus providing flexible functionality through asmall number of interfaces. The interface for application generation of audit
records similarly uses ’put_item’ interfaces and the ’type length pointer’ structure
to specify the data to be recorded. Several tradeoffs exist, as described below, andthese are not the most efficient interfaces imaginable; merely the most efficient
portable interface proposed so far.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.24 Audit

287

343
344
345
346
347
348
349

One tradeoff exists in the granularity of information access to the audit record. An
audit record consisting of individual attributes is the more general interface but
also is more inefficient. Structure-based interfaces that put and get information inlarge chunks are more familiar to programmers but it may be more difficult tovalidate the attributes; and structures are inconvenient if there are a large
number of variable size components (or components with opaque structure that
may be variable size).

350
351
352
353
354

Another tradeoff is caused by offering only indirect access to the audit record,
because the information must be retrieved procedurally. The cost could be minimized by implementing these interfaces as macros and a procedural interface
allows an implementation greater flexibility in defining audit log storage andaccess methods.

355

B.24.4 Audit Logs and Records

356

B.24.4.1 Protecting the Audit Log

357
358
359
360
361
362
363

Of all the data in a secure computing system, the audit log is perhaps the one
item which is most important to protect against invalid manipulations EVEN byapparently authorized users. For instance, if an intruder can defeat a system’s
access control mechanisms, and assume all the rights and powers of an authorized system administrator, it would still be extremely useful to be able to audit
the intruder’s activities. To any extent possible, the auditing mechanism and theaudit log should be protected against external attacks.

364
365
366
367
368
369
370

The group considered specifying a few possible mechanisms that provide elements
of protection against this threat, but decided not to do so. The group took thisposition because any mechanism that is sufficiently general (not implementationdependent) to specify in a standard would not, itself, provide significant protection. Only a combination of mechanisms, most of them implementationdependent and outside the scope of POSIX, can protect a system’s audit log to ameaningful degree beyond basic file protection.

371
372
373
374
375
376
377
378
379
380
381
382

If the audit file is protected using the normal filesystem protection mechanisms,
the degree of protection increases with the security of the system. Thus in an
ACL based system with a single super-user, it could be read/write to superuser
only. On a system with the administrative roles divided according to the principleof least privilege, it could be owned by the audit administrator, with read accessavailable also to the security administrator. On a system with MAC controls of
disclosure and integrity, it could be owned by audit administrator with a disclosure label making it readable only to security and audit administrators, and an
integrity label making it writable only by the system. Of course, these access controls do not prevent the audit subsystem itself from writing to the audit log torecord actions of users, even though the users don’t have write access to the audit
log file.

383
384
385

Thus when audit logs are accessed via the POSIX file abstraction, this standard
does not mandate any protection mechanism other than the normal file systemaccess control mechanisms. The exception to this occurs in the case where an
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

288

B Revisions to Rationale and Notes

386
387
388
389
390
391
392
393
394
395
396
397
398

application needs to write to the current system audit log. There are two reasons
why it would not be appropriate to rely on the usual file protection mechanisms,
exercised through open(), in this case. Firstly, a self-auditing application should
generally not have the ability to open the system audit log for write, since thiswould confer the ability to corrupt data that was already in the log, for example
by writing random data at random positions in the log. Thus in this case an alternative means of accessing the log is needed to ensure its integrity. Secondly, an
implementation may not have a fixed mapping between the current system log
and a POSIX file: either the log data may be sent to different files at different
times (e.g. when the current file reaches a certain size), or the data may not besent to a medium that is accessible through a POSIX file name. Therefore thisstandard specifies that the current system log is written without use of open(),and uses appropriate privileges as the means to control access to that log.

399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414

The working group debated whether self-auditing applications should be permitted to provide all the data of an audit record, some people holding the view thatthe system should be required to provide some of the data (especially in the record
header) in order to protect the integrity of the audit log and provide accountability
for application-generated records. However, others held that it is only necessary
to protect the integrity of the audit log, and that the application is trusted tocreate the entire contents of the audit record itself - some even suggested that theapplication should not even have to be privileged to do this. The final consensus
took the ‘middle way’: that the integrity of the audit log should be protected (byallowing applications to write records without giving them general write access;and by allowing the system to check the format of audit records); and that only
‘trusted’ applications should be able to write records, the control being provided
by use of appropriate privilege. The latter control allows implementations, oreven installations, to set their own policy about the degree of trust needed in selfauditing applications, since they can control how widely the privilege to write
audit records is distributed.

415

B.24.4.2 Audit Log and Record Format

416
417
418
419
420
421
422
423
424
425
426
427

The logical audit log is a stream of audit records. That is, an audit log appears to
the application program as a sequence of discrete, variable length records. Each
record contains a complete description of an audit event: records are intended tobe largely independent entities. An important distinction must be made between
the ‘‘logical’’ and ‘‘physical’’ descriptions of the audit record. The ‘‘logical’’ appearance of the audit log refers to the appearance of the audit records returned by thefunctions defined by this standard. The ‘‘physical’’ description of the audit record
refers to the audit record as it exists in the audit log, that is how the record would
appear if the audit log were read in its raw state. This standard does not definethe ‘‘physical’’ view of the audit log. Additionally, this standard does not definethe ‘‘logical’’ view of audit records when viewed by interfaces not defined by thisstandard.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.24 Audit

289

c

428

B.24.4.3 Audit Record Contents

429
430
431
432

The statement above that audit records should be largely independent is an acknowledgement that no audit data can be completely context-independent, and an
encouragement that audit records contain enough context to be meaningful for
analysis in most circumstances.

433
434
435
436
437
438
439
440
441

Each audit record contains at least a header and a set of subject attributes (theterm ‘subject attributes’ is used in preference to ‘process attributes’ because a process can also be an object (e.g. when receiving a signal), and also the particular
set of attributes reported is that appropriate to the process’s role as a subject, as
opposed to all the attributes of the process). Most records also contain one ormore sets of event specific data, and zero or more sets of object specific information. The header defines a version number (see below), the data format the record
is written in, and includes fields for event type, event time, and event status. The
event time is compatible with the timespec structure in POSIX.1b 1993.

442
443
444
445
446
447
448
449
450
451

To allow future versions of this standard to extend the audit record format andretain compatibility with previous versions, a version number in each record
header identifies the version of the standard the record conforms to. For example,
the version number defined by this iteration of the standard may be c
AUD_STD_1997_1 (the digits implying 1997, POSIX.1) while the version number
defined by the first revision of this standard may be AUD_STD_1998_1. Thus, a c
conforming implementation, by reading the version number will know what audit
record definition matches the audit record read. Note that the current defined version identifier AUD_STD_NNNN_N will have to be updated to reflect this itera- ction of the standard, such as AUD_STD_1997_1.
c

452
453
454
455
456
457
458
459

The format field specifies the format of the data contained in the audit log.
Currently, only the format AUD_NATIVE is supported. The AUD_NATIVE format indicates that the audit data contained in the log is written in native
machine format. This field is primarily a place holder for future revisions of thisstandard which are expected to add other formats such as a portable audit format.
It is important for the portable application to know what type of data is written in
the field, thus the application knows what kind of data to expect (i.e., byte ordering, data type sizes, etc.)

460
461
462

The status value was added to indicate the status of the audit event with someindication greater than success or failure. The following event statuses are
currently defined:

463

AUD_SUCCESS The event completed successfully.

464
465
466
467
468
469
470
471
472

AUD_PRIV_USED The event completed successfully and privilege was exercised. Conforming implementations are not required toreport this value (reporting AUD_SUCCESS instead), since
not all audit policies require that use of privilege be audited.
If the value is reported, however, this does imply thatprivilege was required, not just that privilege was available
and was used. The working group felt this distinction was
important because although some implementations may notneed to distinguish between a privilege which was used and
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

290

B Revisions to Rationale and Notes

c

473
474
475
476

a privilege which was required, existing practice has shownthat for security auditing it is important to report the use ofprivilege to achieve an operation that would have failed
without it.

477
478

AUD_FAIL_DAC The event failed because of discretionary access control
checks.

479

AUD_FAIL_MAC The event failed because of mandatory access control checks.

480
481
482
483
484
485
486

AUD_FAIL_PRIV The event failed because of lack of appropriate privilege. −The audit record does not contain an indication of what theappropriate privileges were, though if the POSIX capability
option is in use it does indicate the capabilities available tothe subject, and other security attributes of the subject andobject; thus it would be possible to deduce which capabilities
would have been needed to complete the operation.

487
488
489
490
491
492
493
494

AUD_FAIL_OTHER The event failed for some reason, none of the above. This
includes implementation-defined policy extensions.
Note that implementations are free to extend this list with additional statusvalues. Note also that the standard does not define which of the various
AUD_FAIL statuses is to be returned if the event could have failed for more than
one reason: if this were specified it would imply that implementations had to perform tests in a certain order, or carry out all tests even if one had already failed,
and the working group did not think this a reasonable requirement.

495
496
497
498
499
500
501
502
503
504
505
506

The audit record header includes an identifier, the audit ID, for the individual
human user accountable for the event: it is a fundamental principle of accountability that each event should identify the human user accountable for it (see below
for further rationale related to audit IDs). For system-generated events, if theprocess initiating an action does so on behalf of a user who is not directly associated with the process (e.g., a server process acting on behalf of a client) the
directly accountable user should probably be the one that initiated the server.
However, if there is no accountable user (e.g., the server was started automatically at system initiation) then the standard does allow the system to provide anull audit ID. For application-generated records, the standard specifies interfacesthat allow a server process to record the audit ID of the client process for which itis acting.

507
508
509
510
511
512
513
514
515

The subject attributes are required to include the process ID and the basic security attributes of the subject: the effective UID and GID; means for reporting
other security attributes (e.g., supplementary groups, labels, capabilities) is also
provided. The working group considered requiring that all these attributes bepresent (at least if the relevant POSIX options are implemented) but rejected thisbecause it was not clear that all systems implementing audit would need to provide this information. It is a matter for the policy of the system. Accordingly thestandard defines how the information can be provided, and what happens if it isnot, and allows implementations to decide on policy.

516
517

The object specific information includes fields for the type and name of the object,and object security attributes. Again, some of the security attributes are optional,
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.24 Audit

291

518
519
520
521

it being up to the implementation security policy to define whether they are provided. In general, the standard requires that object details be supplied whenever
the attributes or data of an object may be accessed or altered; it does not require
it otherwise (for example, on a chdir()).

522
523
524
525
526
527

The audit events for interfaces that operate on files via file descriptors include thefd among the data reported. There was some feeling that this was in itself notvery useful, since the file descriptor is not directly meaningful to an audit
administrator, but the audit record for the open() call that created the file descriptor is also reportable, and does enable an audit post-processing tool, or audit
administrator, to make the link back to a human-readable name.

528
529
530
531
532
533
534
535
536
537
538

For records that report changes to subject or object attributes, the standard
includes the new attributes, through inclusion of the function arguments. It also
requires that details of the relevant subject/object are included; it specifies that if
the relevant attribute is included in the details, then the old value shall be given.
However, it does not generally require that the relevant attribute must be
included in the details. There are several reasons for this: not all security policies
require that the old attributes be audited; in some implementations there is no
reason for the old attribute to be available to the audit subsystem; for some attributes there could be a significant performance/space impact (e.g. recording 1000- centry ACLs!). Thus the standard always requires the new attribute to berecorded, and permits (but does not require) the old attribute.

539

B.24.4.3.1 Semantics of Audit Event Types

540
541
542
543
544
545
546
547
548
549

The standard includes a set of pre-defined system event types with fixed interpretations (corresponding to interfaces defined in POSIX.1). These system event
types are defined primarily for use by audit analysis tools such that they can havea base set of defined, standard event types for analysis. It was felt by the working
group that a standard means of uniquely identifying these system event types
was required to avoid collisions (e.g., various definitions of the same event type);
therefore the standard includes a means of identifying the event types themselves, that is, a standard naming of system event types is provided. The event
type defines the minimum logical content of the record as it is returned by the
POSIX.1e audit functions.

550
551
552
553
554
555
556
557
558

The working group felt that some applications may need to query the list of system event types supported by a system. For example, a interactive audit analysis
tool may want to get all the system event types supported on a system, thenprompt the user to determine what event types to analyze the audit log for. This
type of capability also requires a interface to convert the audit event type from its
internal representation (numeric) to text for display purposes, then from text (ornumeric-text) to internal format (numeric). To provide this functionality to an
analysis tool the following interfaces were defined: aud_get_all_evid(),
aud_evid_to_text(), aud_evid_from_text().

559
560
561
562

Applications also need some defined semantics for audit events. A portable application wishing to generate its own audit records must be able to specify the formand content of the record so that it can convey this information to an audit
analysis application. Like system events, application events also require some
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

292

B Revisions to Rationale and Notes

563

means of identifying the event type.

564
565
566
567
568
569
570
571
572
573
574
575
576
577
578

The working group debated how best to define the event types. Some iterations of
this standard specified the event types as numeric constants (e.g., 1,2, ... nnnn).
The working group felt that a portable analysis tool would be most efficient
searching for and comparing numeric event type identifiers. For example, ananalysis tool searching for records of type AUD_AET_KILL could simply search
for records of event type 1. However, the working group felt that the expression of
event types as character strings, e.g., "AUD_AET_AUD_OPEN" allowed for easier
future expansion. The standard could thus reserve the AUD_AET_ prefix for
future use (as opposed to reserving 1-xxx). The former option was proposed in thefirst ballot of the standard (attracting ballot objections related to extensibility,
and the likelihood of applications choosing the same event types); the latter was
proposed in the second ballot (attracting ballot objections related to efficiency ofprocessing and storage). Finally, it was decided to adopt a combination, using
numeric identifiers for system events and string identifiers for application events.
This accomplished several goals:

579

A.

System events can be recorded and processed with maximum efficiency.

580
581
582
583
584

B.

Applications wishing to do self-auditing were less likely to have audit event
type collisions. For example a database could generate records of
AET_<MYNAME>_DB as opposed to records of event type 150. The groupfelt it was far less likely that two applications would choose the same character string.

585

C.

Application event types cannot clash with system event types.

586

B.24.4.4 Audit Record Data Format

587
588
589
590
591
592

The physical format of an audit record is unspecified - that is, a post-processing
application may make no assumptions about the format and location of theheader, subject, object and event specific data as it actually exists in the record.
Logically, an audit record is a collection of opaque segments (headers, sets of subject attributes, etc) each of which is referred to by a descriptor and accessed only
by functions referencing that descriptor.

593
594
595
596
597

The segments of a particular type in a record are ordered, so that semantics may
be attached to their relative positions; this is likely to be particularly important if
a record contains details of more than one object, since these may represent thesource and sink of data. Descriptors for the various structures can be obtained
either serially or by random access (e.g. to the second set of object attributes).
c

598
599
600
601
602
603
604

The segments which comprise a system-generated audit record contain at least
the data items defined by this standard and may include additional,
implementation-defined data items. The data type of each of the required data
items is defined by this standard, as is the ordering of the items. Note that thesize and byte-ordering of the data items may vary from system to system. That is,there is no intention that the binary data in the opaque structures is directly portable from system to system.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.24 Audit

293

605
606
607
608
609
610
611
612
613
614
615
616
617
618

A header segment must be (logically) included in every record. For systemgenerated records, the fields of it are set by the system; for application-generated
records, the application is required to specify values for certain fields, and may
supply more (the system will supply certain fields if the application does not).
Similarly, the subject attributes of system-generated records are provided entirelyby the system, but for application generated records the application is trusted toprovide subject attributes, for example of a client process (again, the system will
supply ’default’ values, describing the current process, if the application providesnone). There was considerable debate in the working group about whether theapplication could be trusted to supply header and subject attributes; somemembers felt that the system should always provide the header (except for the
event type and status) and subject attributes for the current process. However,
the alternative view prevailed, that an application that is trusted to generate
audit records (in the system audit log) can also be trusted to do it right.

619
620
621
622

Although the number and ordering of segments in the record is important, it
should be noted that for failed events, some objects and data in the record for the
standard event types may be omitted, because this information may be missing
from the function or utility invocation.

623

B.24.4.4.1 Portable Audit Record Format

624
625
626
627
628
629

The current version of the standard does not contain a definition for a portable
audit log format. This is currently being investigated for a future iteration of thestandard. Earlier drafts of this standard did contain a portable audit log format.
However, the standard required that all records be written in this format which
proved to be controversial. The rationale contained here defines the reasons why
the working group felt a portable format was necessary.

630
631
632
633
634
635
636
637

A portable audit log format allows the audit data to be analyzed on systems otherthan the systems which generated it. Several methods were proposed to place
audit records in portable format. One method proposed was to write all audit
records in the portable format. This method was rejected because it had thepotential to impose performance penalties on those implementations which did
not support the data sizes required by the portable format as their ‘‘native’’ datatypes, in other words, some systems may be required to do size and type conversions on each record written.

638
639
640
641
642

To avoid this unnecessary penalty, the data that is returned in the structures isalways in the local format. An alternate method proposed was to allow the audit
records to be written in native machine format with the conversion to the portableformat to be done by some form of audit record filter. These records can then betransferred to other systems.

643
644
645
646

There are two costs to this approach, however. The first is that each system must
be prepared to read the portable format(s) defined. The second is that theserecords are always translated twice - once on the generating system and once on
the system used for analysis.

647
648

The portable data formats are not defined in this document. That is, the size ofuids, gids, MAC labels, etc. is unspecified at this point. While the elements of a
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

294

B Revisions to Rationale and Notes

649
650

portable audit log can be outlined, the definition of the portable audit log format
is not defined.

651
652
653
654
655

Auditing by nature is the gathering of data, not the definition of it. Almost all thedata types contained in a typical audit record are external to the audit group.
True data portability is a problem much larger than the need for a portable audit
log. Currently, neither the POSIX.1 standard nor the POSIX.2 standard address
data interchange sufficiently to define a portable audit format.

656
657
658
659

After extensive research and discussion, the audit subgroup has concluded thatthe portable audit format is a subject that cannot be resolved with the present
amount of information obtainable from other internationally recognized standards
bodies.

660
661

Analysis of the problem revealed the following issues, all of which need to beresolved before a portable audit log format can be developed. The issues are:662

(1) Data format (byte ordering)

663(2) Data field sizes (very specific! number of bytes or equivalent)

664(3) Field mappings (user ID <-> user name, etc.)

665(4) Time coherence (time zone, etc.)

666(5) Internationalization issues (at least for text strings contained in the file)667(6) Byte size

668
669

(7) Field identification and boundaries (how to tell where a record begins
and ends)

670
671(8) Naming convention (uniqueness of user, for example user ID plus process
ID)

672
673
674
675
676
677
678

It was decided that the audit log header file needs to contain: an indicator thatmarks the log as being in POSIX.1e portable format, the version of the standardof the portable format, the data format indicator of the log (XDR, NDR, or ASN1
format), the time zone in which the log was created and any applicable maps
required by that machine. There may be several machine identifiers and associated maps, keyed by machine_id. Not much more information can be generated
without input from the interchange format group.

679
680
681
682

The audit subgroup has also yielded the format of the MAC label, ACL, and capabilities associated with the portable audit format to those associated groups.
However, they too will be unable to determine the data sizes to be used in a portable interchange format without input from the interchange format subgroup.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.24 Audit

295

683

B.24.5 Audit Event Types and Event Classes

684
685
686
687
688
689
690

The distinction between event types and event classes has generated considerable
controversy. Two differing proposals were considered. One suggested that grouping types into event classes is arbitrary and may differ from one system toanother. Another proposal suggested that event types should belong to a small,
fixed set of standard event classes. This proposal also suggested that the eventclass be recorded in a header, with the event type, thus making it the responsibility of the auditing program to fix the relationship between the two.

691
692
693
694
695
696
697
698
699

Initially the latter proposal was accepted. However, after further reflection, it
was decided that recording the event class in a header was not tenable. If an
event type belongs to many classes, but only one can be recorded in a header, thenthe inclusion of such a value might serve to confuse rather than clarify the reason
for the audit record. Eventually it proved impossible to reach consensus on how
event classes should be standardized; there was also a body of opinion that said it
was unnecessary to standardize them, because post-processing applications could
group event types into classes at that level. Accordingly, the concept of eventclass was removed from the standard.

700
701
702
703
704

It also turns out to be very hard to define precisely when an event deserves anevent type of its own. For instance, are successful and failed open calls the same
event type? Probably so, because they can be differentiated by the result field in
the record header (though looked at another way, that really means that theresult field is part of the event type, and so they are two different types).

705
706
707
708
709

Are open of a file for reading, and open of a file for read/write, different event
types? Though they differ only in one bit of a system call argument, maybe theyought to be different types, because they represent very different abilities being
exercised. This example leads to a circular definition of event types: two types
should be separate when it would make sense to assign them to separate classes.

710
711
712
713
714
715

It was finally decided to define no more than one event type for each of the POSIX
interfaces being audited; in a few cases a single event type was used for several
closely related interfaces (e.g. the exec() family). The separation of, eg open-read cand open-write can then be done by post-processing tools on the basis of information in the record; implementation-specific means could be used to separate thesefor event pre-selection purposes too (see below).

716

B.24.6 Selection Criteria

717
718
719
720
721
722
723
724
725

At various times, drafts of this standard have included facilities for both preselection and post-selection of audit records: that is, selection of the records thatare recorded in the log, and those that are reported from the log to an audit postprocessing application. However, the standard does not finally contain any selection facilities. The pre-selection interfaces have been removed because they areseen to be an administrative facility, and therefore out of scope. The postselection interfaces have been removed on more pragmatic grounds: there was noagreement on what facilities are needed, or how post-selection criteria should bespecified. Additionally, the group felt that so long as the next sequential record
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

296

B Revisions to Rationale and Notes

726
727

could always be made available, applications could build selection criteria themselves.

728

B.24.7 Audit Interfaces

729

B.24.7.1 Gaining access to the Audit Log

730
731
732
733
734
735
736
737
738
739

In earlier drafts of this standard, to provide some separation of audit log from filethe concept of an audit_log_descriptor was conceived. The audit log descriptor provides a level of abstraction above the file descriptor interface. An attempt wasmade to define a set of interfaces for use in analyzing abstract audit logs, concealing the storage method, location and format of the actual data. In draft 13 (andprevious drafts) there were two functions provided to initiate and terminate
access to the audit log; aud_open() and aud_close(). However, this resulted in aneed to reinvent a complete I/O package for such objects. Also, it did not succeed
in defining any particularly useful interfaces, other than a record-oriented readfunction.

740
741
742
743
744
745
746
747
748
749
750

In draft 13 several balloters objected to the concept of an "audit descriptor". There
were two flavors of objection. One type of objection cited existing practice claimingthat existing practice (or all that was known to the objector) used files so theabstraction of an audit descriptor was not reflective of current practice. Anothertype of objection stated that since the descriptor was largely implementation
defined that it was of little use to the portable application. In response to theseballot objections, the aud_open() and aud_close() as well as all concept of "audit
descriptor" was deleted. The aud_open(), aud_close() and "audit descriptor" were
replaced by the P1003.1 open() and close() calls while the audit log descriptor was
replaced with a file descriptor. The result of this change was to make the POSIX
audit functions more reflective of existing practice.

751

B.24.7.2 Distinction Between System Audit Log and Audit Log Files

752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767

With the removal of the audit descriptor abstraction some semantic differences
between the "system audit log" and file-based audit logs (i.e. non-system logs) surfaced. The primary difference being the fact that the system has some a priori
knowledge of the system audit log while the file-based audit log may only beknown by the application. An example of the difference between the "system log"
and file based logs lies in the amount of support which may be provided by thesystem in ensuring the integrity of the audit records and the audit files. In thecase of the system log, the system is responsible for ensuring the integrity of theaudit log. For example if an application issues an aud_write() call on the system
audit log, the system is responsible for ensuring that the audit data is eventually
written to a properly formatted audit log. The system is also responsible forproper sequencing of the records and supplying any accessory information necessary to post-process the record (e.g. UID to text representation). When dealing
with a file based audit log the system cannot guarantee that the file specified as
an "audit log" is in fact properly formatted (i.e. meets the system’s requirements
for a proper audit log), that the file offset is correct or that any accessory
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.24 Audit

297

c

768
769
770
771
772
773
774

information required for later translation (by aud_rec_to_text()) is properly
represented in the file. Additionally, if multiple aud_write() calls are made to thefile based audit log the system has little control over the sequencing of therecords. The only method provided by the standard for providing the concept of"next" record is via the POSIX concept of file append. That is if the file based
audit logs are opened with the O_APPEND option the system can provide theassurance that the "next" record written is properly placed in the audit log.

775

B.24.7.3 Read/Write access to the Audit Log

776
777
778
779
780
781
782
783

Appropriate privilege is required to write to the system log, but is not normallyrequired to read it. The rationale for this is that the write interface does not
require that the log has previously been opened (because the application should
not have unrestricted write access to the audit log, but only the ability to requestthat records be added to the log (subject to an implementation specific preselection policy); indeed, it may not even know the name of the file in which thelog is stored). However, for the read interface the log must first be opened, andnormal system access controls can be applied.

784
785
786

No privilege requirements are placed on implementation-defined audit logs
though implementation-defined forms of access control (including privilege) may
be applied.

787

B.24.7.4 Space Allocation

788
789
790
791
792
793

Space allocation for auditing functions is handled by the system throughout, withthe user only being required to notify the system when an item is no longer
required (by calling aud_free()). Functions that create or read in data on behalf of
the user automatically allocate space for the data: for example, for records readfrom audit logs and for text strings created by aud_id_to_text(). The only exception is aud_copy_ext() which specifically copies into user-created space.

794

B.24.7.5 Audit Identifiers

795
796
797
798

The audit ID, an identifier conceptually different from a UID, was introduced as ameans of satisfying the requirement for individual accountability. While thisrequirement can be met in other ways (e.g., unique UIDs) it was felt that the
introduction of the audit ID was the best means of meeting the requirement.

799
800
801
802
803
804
805
806
807
808

In many existing systems, the user has a username and a user ID. Neither ofthese is appropriate for use as the audit ID, because POSIX.1 does not requirethat either of these be mapped to an individual human user. Further, the user ID
is the basis of the (DAC) authorization policy of the system, which is logically distinct from the accountability policy. In particular, some systems allow aliasing of
one user ID to several usernames that all have the same DAC authorizations, or
permit several users to share a username; this is incompatible with use of theuser ID as an audit ID. An audit ID has its own unique type aud_id_t, because
only by doing this could an audit file be analyzed on systems of a different type tothe one on which it was generated. Some implementations might wish to define
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

298

B Revisions to Rationale and Notes

809
810

mappings between aud_id_t values and implementation-defined identifiers, suchas personnel numbers; this is not subject to standardization.

811
812
813
814
815
816

Note that there is nothing to stop a particular implementation from implementing
user ID and audit ID for each user as the same value, as long as it maintains individual accountability. However, confusion might arise from the existence of two
sets of interfaces to the same value. There is no requirement on how the audit ID
is assigned, thus it can be administrator or system assigned (in the latter case,perhaps equal to the UID).

817
818
819
820
821
822
823
824
825
826
827

Currently, two functions are provided for processing audit IDs. The function,
aud_id_to_text() is provided to allow an application to convert an audit ID to astring identifying the corresponding individual user.
The function,
aud_id_from_text() is provided to allow an application to convert a string identifying an individual user to an audit ID. The audit option does not define any relationship between the strings handled by these functions and the pw_name fieldobtainable from the function getpwuid(). Using these interfaces, an audit postprocessing application could provide record-selection facilities that permit anauditor to select records based on the identity of the individual accountable foractions; or could present the identity of the individual responsible for a particular
record to the auditor.

828
829
830

A further function, aud_get_id() is provided to allow a process that generates
records of its own activities to obtain the audit ID of the user accountable for theactions of a client process and include it in such records.

831
832
833

Note that the functions to set, store and allocate audit IDs are not defined by thisstandard, since these are considered to be administrative and therefore out of
scope.

834

B.24.7.6 Audit Post-Processing Interfaces

835

B.24.7.6.1 Reading the Audit Log

836
837

This standard provides a single read function aud_read() which operates with afile descriptor returned via open().

838
839
840
841
842
843
844
845
846
847
848

The aud_read() function returns a pointer to the next sequential record in theaudit log. Note that it is up to the underlying implementation to ensure that thenext sequential record is returned. Certain events occur on a system for which
sequence is important. For example, a parent process forks a child. It is possiblethat audit records from the child may appear in the physical log prior to therecord indicating the fork event had occurred. In any case, it is important that therecord for the parent’s fork is returned prior to any subsequent records for thechild (provided, of course, that the implementation-specific pre-selection policy
causes the fork event to be recorded). While the records in the internal audit log
may not be in the proper logical sequence, the sequence returned by aud_read()must reflect the proper sequence.

849
850
851

Note that if an application chooses to write its own audit records to a file-based
audit log (e.g. not the system log) it is left largely up to the application to ensure cthat the records are properly sequenced. The only mechanism provided by POSIXWITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.24 Audit

299

852
853

for maintaining the sequencing of records written to a file-based audit log is via
the O_APPEND flag supplied on open().

854
855

Since the system is not controlling the file-based audit log there may be no additional (system supplied) sequencing information provided.

856

B.24.7.6.2 Parsing Audit Records

857
858
859
860
861

An audit log may contain records in multiple data formats. All data in any given
record will be of the same format. The only format currently defined is
AUD_NATIVE; previously an AUD_PORTABLE format specifier was also
included, but this has been removed in the current draft because of the decision todelay addressing the issue of portable data interchange formats.

862
863
864
865
866
867
868
869
870

A previous draft stated that access to the sets of data within the various sections(headers, subjects, event-specific data and objects) of an audit record and to theindividual fields within these sets was sequential, i.e., to get to the nth fieldrequired reading all the fields up to that one also. Several objections were madeto this claiming that it was both restrictive and inefficient: it prevented the reading of the fields or sets in an arbitrary order and it required the processing offields or sets that were not needed. To respond to these objections, a third parameter has been added to the aud_get_∗() and the aud_get_∗_info() functions, where∗ is one of hdr, subj, event or obj.

871
872
873
874

For the aud_get_∗() functions, this parameter represents the ordinal number ofthe set being requested in the appropriate section. This allows random access tothe sets, while at the same time allowing all of the sets in a section to be processed sequentially.

875
876
877
878
879
880
881
882
883

For the aud_get_∗_info() functions, the third parameter represents a field_id,
identifying the field being requested; for system-generated records there aredefined values of field_id for each item; and the interfaces for construction of
application-generated records allow the application to specify the field_id for each
item (see below). Thus the field_id allows access to specific fields within the set.
Note that field_ids are not necessarily sequential. In addition, two special
field_ids, AUD_FIRST_ITEM and AUD_NEXT_ITEM are provided to allow
sequential access to the fields within a set. This can be used for rewinding a set.
Thus, both random and sequential access to the fields in a set are provided.

884
885
886
887
888
889

Note that the aud_get_∗() interfaces operate on audit record descriptors as
returned by any of aud_read(), aud_init_record() and aud_dup_record (). The
decision to use symmetric interfaces allows applications greater latitude in processing a record and allows the implementation to be considerably simplified
because separate writing functions are not needed for records that are read fromthe log as opposed to those that are created from scratch.

890
891
892
893
894

As mentioned above, the aud_read() function returns a pointer to an opaquestructure defining the next sequential record in the audit log. This record is thenread in logical pieces: the record header, subject attributes, event-specific information and object attributes. The record segments are read by calls to the following
functions:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

300

B Revisions to Rationale and Notes

895

1.

aud_get_hdr()

896

2.

aud_get_hdr_info()

897

3.

aud_get_subj()

898

4.

aud_get_subj_info()

899

5.

aud_get_event()

900

6.

aud_get_event_info()

901

7.

aud_get_obj()

902

8.

aud_get_obj_info()

903
904
905
906
907

aud_get_hdr()
returnsadescriptor
fortheheaderinformation.
aud_get_hdr_info() takes the descriptor returned by aud_get_hdr(), and returns
the data item from within the header of the audit record identified by the field_id.
If sequential access is being used, then repeated calls using AUD_NEXT_ITEM as
the field_id return the data items from the header in a predefined order.

908
909
910
911
912

aud_get_subj() returns a descriptor for a set of subject attributes.
aud_get_subj_info() takes the descriptor returned by aud_get_subj(), and returns
the data item from within the subject information of the audit record identified by
the field_id. If sequential access is being used, then repeated calls return thedata items from the subject attributes in a predefined order.

913
914
915
916
917
918
919

aud_get_event() returns a descriptor for an opaque data item defining a set of
event-specific data from the record. aud_get_event_info() takes the descriptor
returned by aud_get_event() and returns the data item from within the eventspecific information identified by the field_id. There are defined items of information to be returned in a defined order for the standard audit event types whensequential access is being used. Repeated calls to aud_get_info(), are required toread all items of event specific information.

920
921
922
923
924

aud_get_obj() returns a descriptor for an opaque data item defining a set of object
attributes. aud_get_obj_info() takes the descriptor returned by aud_get_obj() andreturns the data item from within the object specific information of the audit
record identified by the field_id. If sequential access is being used, then repeatedcalls return data items from the object information segment in a predefined order.

925
926
927
928
929
930
931

Implementations are free to add additional fields to system audit records. As
such, any of the audit record segments defined above may be extended. If theimplementation extends an audit record segment, the implementation-defined
data items are appended. That is, the implementation-defined data items will beread using AUD_NEXT_ITEM after all the items defined by this standard. Notethat this means that an application must issue successive calls to the above interfaces to make sure all data items in a record are read.

932

B.24.7.6.3 Example of Use

933
934

The following describes a brief example of the POSIX.1e audit functions used toread records from an audit log:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.24 Audit

301

sys_ad1; /∗ file descriptor to the audit log ∗/aud_rec1; /∗ record descriptor ∗/aud_hdr; /∗ audit record header ∗/aud_subj; /∗ audit subject info ∗/aud_event_info; /∗ audit event information ∗/aud_obj; /∗ audit object information ∗/aud_info_descr; /∗ audit info descriptor ∗/

935
936
937
938
939
940
941

int
aud_rec_t
aud_hdr_t
aud_subj_t
aud_event_t
aud_obj_t
aud_info_t

942

sys_ad1 = open (log, O_RDONLY) /∗ Open an audit log ∗/

943
944

while ((aud_rec1 = aud_read (sys_ad1)) != (aud_rec_t) NULL){

945/∗ Get audit header & header information ∗/

946
947

aud_get_hdr (sys_rd1, 1, &aud_hdr);
aud_get_hdr_info (aud_hdr, AUD_EVENT_TYPE_ID, &aud_info_descr);

948[ repeated calls to aud_get_hdr_info to get all hdr info ]949/∗ Get audit subject & related information ∗/950

aud_get_subj (sys_rd1, 1, &aud_subj);

951/∗ Get the UID from the subject portion of the record

952
953
954

aud_get_subj_info (aud_subj, AUD_EUID_ID, &aud_info_descr);[additional calls to aud_get_subj_info for example ... ]aud_get_subj_info (aud_subj, AUD_MODE_ID, &aud_info_descr);

955/∗ Get audit object & related information ∗/956

aud_get_obj (sys_rd1, 1, &aud_obj);

957[additional calls to aud_get_obj_info for example ... ]

958

∗/

aud_get_obj_info (aud_obj, AUD_ACL_ID, &aud_info_descr);

959/∗ You could now use the POSIX.1e ACL i/fs to analyze the ACL ∗/960/∗ Get audit event & related information ∗/961

aud_get_event (sys_rd1, 1, &aud_event_info);
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

302

B Revisions to Rationale and Notes

962[additional calls to aud_get_event_info for example ... ]

963
964
965

aud_get_event_info (aud_event_info, AUD_PATHNAME,&aud_info_descr);}

966

close (sys_ad1);

967
968
969
970

In the above example, the while loop reads records sequentially from the audit
log, referenced by sys_rd1. The record is then parsed by a series of calls to;
aud_get_hdr(),
aud_get_hdr_info(),
aud_get_subj(),
aud_get_subj_info(),
aud_get_obj(), aud_get_obj_info(), aud_get_event(), aud_get_event_info().

971
972
973
974
975
976

Note that the addition of the field_id allows for (somewhat) random access to therecord. In previous versions of this standard, access of this nature was not provided and access to a particular part of the record was sequential. Additionally
there had to be some a priori knowledge of the format of the record (i.e. that UID
was the 4th field in the record). This problem has been eliminated with the addition of the field_id.

977
978
979
980
981
982
983
984
985

The audit records are processed in logical blocks, the header, subject, object andevent information. The aud_get_∗() interfaces are used to (logically) extract thecorresponding logical block of the audit record so it may be processed by the application. In an implementation, the aud_get_∗() may simply position a index to a
portion of the audit record. For example a call to aud_get_hdr() may simply position a index to the beginning of the audit record header. After the call to
aud_get_∗(), subsequent calls to aud_get_∗_info() are used to extract data fields
from the record. For example, repeated calls to aud_get_hdr_info() are made to
extract the header data items from the audit record.

986

B.24.7.6.4 Audit Record Conversion

987
988
989

A function is provided to allow audit records to be converted from internal (native)
format to human readable format. This function is primarily intended to allow
applications to display audit records to a user.

990 The function aud_rec_to_text() converts an audit record, pointed to by an
991 aud_rec_t, from internal format to human readable text. The function returns a
992 pointer to the converted record. All space required for the converted record is allo993 cated by the underlying implementation. Aside from the ordering of information
994 in the converted record, the standard does not specify any details of the text; thus
995 the output of the function can be displayed to a user, but cannot be further pro996 cessed by an application (e.g. adding special formatting). Portable post- c
997 processing applications that want to provide formatted text for audit records
998 themselves can do so by using the aud_get_∗() and aud_get_∗_info() functions to
999 obtain the content of the record, and other POSIX.1 functions to convert each item
1000 to text. In draft 13 and 14 there was an attempt to define more details of the out1001 put of aud_rec_to_text(), but this was widely criticized (for example, it used new1002 line characters as delimiters, but these were taken to be formatting which was
1003 stated to be inappropriate to POSIX.1); therefore these details were withdrawn.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.24 Audit

303

1004
1005
1006

The converse function is not provided by the standard: there is no requirement tobe able to take a human readable record and convert it to internal form in order tosupport either post-processing or self-auditing applications.

1007

B.24.7.6.5 Copying Audit Records

1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018

The working group determined that some applications would find it desirable tosave audit records. They may be saved for functions such as backup/restore or for
applications which are building a database of audit records for later processing.
One way to achieve this is just to aud_read() records from one log andaud_write() them to another. However, this is not very flexible, since the destination has to be an audit log. It is desirable that it be possible to store a record inany user-defined destination. Since the POSIX.1e audit functions use system
allocated space to store audit records, a provision needed to be made to copy theaudit record from system managed space into user-managed space. Conversely,
the ability to move the record back into system managed space and allow it to beprocessed by the POSIX.1e audit functions was also needed.

1019
1020
1021
1022
1023
1024
1025
1026
1027
1028

The function aud_copy_ext() copies an audit record from system managed space touser-managed space. It is the responsibility of the application to ensure that adequate space is reserved for the copied record. To allow the application to determine the space required to hold the copied record, the function aud_size() is provided. The aud_size() function, accepts a pointer to an audit record in internal format and returns the size required to hold the audit record in user-managed space.
Note that the size returned by aud_size() may not be reflective of the space allocated for the internal record because pointers or various compression techniques
may be used by the underlying implementation to reduce the amount of spacerequired to store audit records.

1029
1030
1031
1032
1033
1034
1035
1036
1037
1038

The function aud_copy_int() copies an audit record from user-managed space backto system managed space. This function was provided to allow applications to reprocess audit records that have previously been copied to user space and, maybe,saved. It was suggested that if the POSIX.1e audit functions could be made tooperate on the user-managed copy of the record this capability would not beneeded. However, because the underlying implementation may use various techniques to compress the size of internally stored records (e.g., pointers) the
assumption that the POSIX.1e audit functions could be used on copied records
was not valid. The working group did not want to constrain implementations byrequiring that the internal and user-managed copies of audit records be identical.

1039

B.24.7.7 Application Auditing Interfaces

1040

B.24.7.7.1 Constructing Audit Records

1041
1042
1043
1044
1045
1046

In draft 12, interfaces were defined that allowed an application to construct anaudit record before writing it to an audit log. However, although it was clearly theintent that the application should be able to alter fields in the record, and thus
reuse the record, this was not in fact possible. In ballot, this deficiency was
widely criticized, as was the efficiency of such interfaces without an ability toreuse records.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

304

B Revisions to Rationale and Notes

1047
1048
1049
1050
1051
1052
1053
1054
1055

In draft 13, a major simplification of the interfaces was proposed. All interfaces
for constructing audit records were removed, and instead a data structure
approach was proposed; the application constructed the record using rows oftype/length/pointer structures to define the data, then passed these structures to
aud_write(). This too was widely criticized, as being insufficient application support, incompatible with the style of the rest of the standard, and providing
insufficient structuring capabilities: there was, for example, no means to indicatethat a particular group of data items in the record all related to one object or subject.

1056
1057
1058
1059
1060
1061

The standard has now reverted to interfaces based on those of draft 12, but
extended and completed to allow records to be built with all the structure of asystem-generated record, and full facilities for altering and reusing records.
Thus the objections to both the draft 12 and the draft 13 proposals should besatisfied. Indeed, much of the flexibility of the earlier, token based, proposal has
been achieved, without however proposing as many interfaces as that did.

1062
1063
1064
1065
1066
1067

The intent of the supplied interfaces is that an application should be able toimplement any reasonable strategy for constructing audit records. For instance,
an application is able to include much or little structure information in records: it
can specify that most of the data in the record has no defined structure; or it canstructure the data according to the subject(s) and object(s) to which it relates, andgive meaningful data types for much of the data. Also, an application can chose to

1068
1069

g

Create a new aud_rec_t for each record it constructs, deleting the aud_rec_t
when the record has been written to the audit log, or

1070
1071
1072
1073

g

Reuse a single aud_rec_t for various records, using the various aud_put_∗()and aud_put_∗_info() interfaces to add information, and using the various
aud_delete_∗() and aud_delete_∗_info() interfaces to remove information,
between invocations of aud_write().

1074
1075
1076
1077
1078
1079

The aud_put_∗() interfaces allow an application to ask the implementation tocreate new sections (e.g. header, sets of object attributes) in an audit record; the cinterface returns to the application an identifier (an opaque data item) for the
newly created section. The application used this identifier when adding content tothe section, and also when it wants to add another new section before the existing
one.

1080
1081
1082
1083

The aud_put_∗_info() interfaces allow an application to add content to a section
created as above. The application tells the i/f an identifier (an integer) for theitem that it is adding to the section; it can also give the i/f an identifier for a previously added item before which the new item is to be placed.

1084

B.24.7.7.2 Writing the Audit Log

1085
1086
1087
1088
1089
1090

The ability to write to the system audit log cannot be generally available, because
it could provide a malicious user with a means of denying service to other users(by filling up the audit file) or misleading an audit administrator (by seeding theaudit log with disinformation). Accordingly, utilities that use the aud_write()interface to write to the system audit log must have appropriate privilege and betrusted to use it properly.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.24 Audit

305

1091
1092
1093
1094
1095
1096
1097
1098

The aud_write() function accepts an aud_rec_t pointing to an audit record which
may have been constructed using the interfaces described above, or may havebeen read from another audit log. Some earlier drafts of the standard did not permit an application calling aud_write() to specify all the sections of a record; some
did not permit the internals of a record to be structured into sets of related detailsc(e.g. object attributes); some did not permit a record to be read from one log andwritten to another. All of these earlier restrictions were the subject of ballot
objections, leading to the current interfaces.

1099

B.24.7.7.3 Auditing Suspension and Resumption

1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110

Any process doing its own auditing may wish to suspend standard auditing of its
operations. This is likely to be used mainly by processes auditing themselves at amuch finer or coarser granularity than the kernel. For example, a program thatscans the filestore periodically and moves to tape any files that have been unused
for a long time could audit the movement of the files itself (in a more meaningful
way than the kernel); it seems unnecessary to record that it checked the accessdates of all files in the system, which would merely clutter the audit log withdata. Even standard utilities (with appropriate privilege) might make use of thisfacility, to provide a higher level view of events than would be given by the kernel.
The interface used to request that the system suspend and resume system auditing of the current process is aud_switch().

1111

B.24.7.7.4 Error Return Values+

1112 If the symbol {_POSIX_AUD} is defined, then the implementation supports the +1113 audit option and is required to support the audit functions as described in this +1114 standard. If the symbol {_POSIX_AUD} is not defined, then the implementation +1115 does not claim conformance to the audit option and the results of an application +1116 calling any of the audit functions are not specified within this standard. An alter- +1117 native is for the audit functions to specify that the error return code [ENOSYS] be+1118 returned by the functions if the audit option is not supported. However, in order +1119 to remain compliant with the policies of POSIX.1, this standard cannot specify +1 any requirements for implementations that do not support the option.

2

B.25 Capability

3

B.25.1 General Overview

4

Goals

5
6
7

The primary purpose of defining interfaces for a capability mechanism within thisstandard is to provide for a finer granularity of controlling and granting systemcapabilities than the traditional super-user model.

8

The major goals of this standard are to:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

306

B Revisions to Rationale and Notes

910(1) Provide a portable means of supporting the assignment of an ability for aprocess to invoke or perform restricted system services.

11
12
13

(2) Support the implementation of least privilege security policies by providing the means to constrain a process by enabling it to invoke only thosesystem capabilities necessary to perform its specific tasks.

14

The additional goals of this standard are to:15(1) Define a common terminology for addressing the topic of capability.

1617(2) Define the semantics of how process capabilities are acquired andaltered.

18(3) Define the system functions and utilities necessary to utilize capabilities.

19
20
21

(4) Provide compatibility with programs that depend upon the set user id on
execution and set group id on execution behavior to gain access to system
resources.

2223(5) Provide the means by which an implementation may grant capabilities inorder to emulate the traditional super-user.

24(6) Allow for extensibility by future implementations.

2526(7) Define a minimum set of capabilities necessary to support the development and execution of security-relevant programs.

2728(8) Ensure that there is a mechanism by which capabilities may be transported with their associated files.

29
30
31
32
33

It has been pointed out that the term privilege has been commonly used for amechanism that achieves the above stated goals. However, the term privilege isalso commonly used in the international community to mean something else
entirely. It is felt that the confusion that would result from using the term
privilege would not serve this standard well.
−

34
35
36

A capability mechanism is a common requirement for most operating systems.
Capability controls the availability of particularly important system services toprocesses that are known to maintain system integrity.

37
38
39
40
41
42
43
44

The principle of least privilege is a common requirement of security policies, thatis, granting to a process only the minimum rights and capabilities necessary to
perform a task. The purpose of this principle is to constrain the damage that may
arise from a violation of the security policy, e.g., disclosing confidential information or corrupting the integrity of the system. We must emphasize here that thestandard does not (nor can it) specify a least privilege mechanism—only interfaces
that, when used with a correctly defined set of capabilities, could successfully be
used to implement a least privilege security policy.

45
46
47
48
49

An example of the application of the principle of least privilege in the commercial
environment is the separation of roles in an accounting department. In most firmsof any size, the person who records and manages the Accounts Receivable is NOT
the person who records and manages the Accounts Payable. This is so one person
cannot create false bills and then write checks to pay them. A current example in
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.25 Capability

307

50
51
52
53
54

the computer world is the use of the restricted shell (rsh) for computer operator
consoles — the operator, who has a great deal of potential access to the entire
computer system by virtue of his or her physical access to the machine, can havethat access limited to those functions actually required to perform his or her job
by the system administrator.

55
56
57
58
59
60
61

Additional goals 1 and 2 are natural intermediate goals for meeting our major
goals. Before a capability mechanism can be defined, a terminology and the basic
concepts of capability must be laid out. Once that has been achieved, then thesemantics of how capabilities are acquired, manipulated, and controlled need to
be defined. Only after this step has been accomplished — deciding what operations are required to provide a capability mechanism — can the next step betaken.

62
63
64
65
66

Additional goal 3 is the end result of this effort — the definition of the interfacesthat can be used to provide the semantics developed above. The specification ofthese interfaces is the entire purpose of this effort — to provide a set of tools thatcan be used by conforming applications to perform those tasks necessary for its
functions.

67
68
69
70
71
72
73
74
75
76
77

Additional goals 4 and 5 are compatibility goals. The set user id and set group id
mechanisms of POSIX.1 continue to function as they have in the past, providing
DAC access to objects based upon the owning ids of the executed file. Set uid root
functionality may be provided by appropriate use of the file permitted capability
set. While our goal is to provide a mechanism that will support implementations
intended for high levels of trust, there will be implementations that will still needto support existing setuid root programs, and implementations that will still provide the ’superuser’ identity to administrators. While we would like to discourageboth of these practices, we understand that current practice is often slow tochange and that some existing applications will have to run unmodified on securemachines for at least a transition period.

78
79
80
81
82
83
84
85

Goal 6 is a basic goal of all systems — motherhood and apple pie to engineers. All
systems need to permit extensibility and flexibility so that unforeseen situations
and future improvements do not require an architectural change in order toaccommodate them. At some point, every system will need to be completely
replaced, but one would like to push that off as long as possible. Implementations
will need to provide capabilities not specified here to accommodate various security policies and system functions not part of this standard. Extensibility is therefore an absolute requirement.

86
87
88
89
90

Goal 7 is the specification of a standard set of capabilities — is a necessary part ofthis effort. Trusted applications will need to be able to acquire a certain capability to perform a specific function across all compliant implementations in order tobe portable, and that capability will need to have the same meaning across implementations.

91
92
93
94

Goal 8 was agreed upon primarily to support system backup and restoration
operations. This goal does not include the transfer of capabilities from system tosystem necessarily. Indeed, there is a good argument that requiring that degreeof portability adds risk to a system, and that a system administrator should be
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

308

B Revisions to Rationale and Notes

95
96
97

required to approve every new trusted program before it is assigned capability
attributes. As a result we define file capability attributes, but not their actual
representation or how they are stored with the file on a tape.

98

Scope

99
100
101
102
103
104
105
106
107
108
109
110

The scope is the natural result of our goals. In order to support the principle of
least privilege, interfaces that provide the means for programs to enable and disable capabilities while running are necessary. In order to support the compatibility goals, there must be a means for programs to pass capabilities to other programs that they execute, and the semantics of that inheritance must therefore be
specified to some degree. Because it is programs that are the ‘‘trusted’’ agents on
implementations, there must be some method to identify them as trusted —therefore attributes associated with program files must be specified. Finally, asmall set of capabilities to be used with the interfaces and utilities in the existing
POSIX.1 specifications must be defined so that writers of conforming applications
know which capabilities will be available to perform various functions and theirappropriate use.

111

Purpose of a Capability Mechanism

112
113
114
115
116
117
118
119

The purpose of a capability mechanism is to provide a finer granularity of control
over the access to restricted system services to specific users or processes thanthat provided by the traditional POSIX.1 "UID 0" access mechanism. A general
purpose capability mechanism supports not only the ability to implement the
principle of least privilege, but also provides the foundation for building an
authorization mechanism to support security administration. The interfaces andconcepts presented in this document have been designed to meet these requirements.

120

Authorization vs Capability

121
122
123
124
125
126
127
128
129

The power to perform an action in a trusted system based on user identity iscalled an ‘‘authorization.’’ Authorizations are generally designed around operational requirements and tasks rather than system services. For example, anauthorization to perform backups would be granted to a user. The backup program however, would enable and disable specific capabilities to perform the
backup function. A system that supports authorizations simplifies the administrative task of the security officer by eliminating the need to comprehend exactly
which capabilities each program requires and how to allocate those capabilities tousers.

130
131
132
133
134
135
136
137

The establishment of a user identity and a user’s authorizations based on thatuser’s identity is presently outside the scope of the POSIX standards. Because ofthis, the assignment of authorizations to users through a program such as login
and the use of an authorization mechanism for determining utility capability
bracketing is presently undefined, as is the relationship between the authorization mechanism and the capability mechanism used by a program. It is not, however, our intention to preclude any implementation of a user authorization
mechanism with this standard.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.25 Capability

309

138

General Discussion of Capability

139
140
141
142
143
144
145
146

Currently, most POSIX.1 and POSIX-like implementations grant all capabilities
to a particular user ID − 0 (root). Most of the time, the ability to log in as or toassume this identity is restricted to a small set of users on a system, one of whomis the system administrator. The ‘‘root’’ account has the ability to execute anyutility or use any system function regardless of what security restrictions may be
involved. Such special rights are necessary to do many administrative tasks, suchas system backups and restores, writes into special files, and to operate processes
such as line printer daemons and mail handling servers.

147
148
149
150
151
152

In the vast majority of cases, however, a process needs to invoke only a few
specific restricted system services or override a single type of access permission inorder to accomplish its task. A line printer daemon, for instance, needs to be able
to read any file in the system, but does not need the ability to write into them,and the same with a backup program. A login program needs to be able to change
its user identity, but it does not need to modify disk quotas, and so forth.

153
154
155
156
157
158
159
160

As has been demonstrated numerous times, the requirement that a process be
granted the ability to bypass all the security restrictions in a system just to
bypass some of them leads to accidents and purposeful misuse. Many times,
users do not realize that they are in privileged mode and perform a destructive
action ( rm ∗) without realizing that the system will not stop them in their current
state. Other times, a user acquires the ability to become ‘‘root’’ for a perfectly legitimate reason, and then passes it on to other users or applies the special abilities‘‘root’’ provides in ways not intended by the system administrator.

161
162
163
164
165
166
167

A capability mechanism provides the means for a system administrator to grant a
program the ability to use a restricted system service or bypass specific security
checks. For instance, user Joe can run the backup program for an entire network(that can read every file on the network) from the ‘‘admin’’ host. Properly implemented and administered, the capability mechanism could permit Joe to perform
his assigned task, but could prevent abuse of the world read access capability
such as browsing files normally not accessible to Joe.

168

Principle of Least Privilege

169
170
171
172
173
174
175
176
177

A process’s need for capability access to system resources and functions does notjustify giving the process uncontrolled use of capabilities. It is also not appropriate to establish for a process chain (a sequence of programs within a single process) a set of capabilities that remains fixed and active throughout the life of thatchain. Rather, the set of active capabilities of a process can be expected to change
as the functions of the process change, so that the process has active at any time
just those capabilities needed to perform its current function. This is an application of the principle of least privilege, and it applies equally to users and toprocesses.

178

Implications of the Principle of Least Privilege

179
180

Any capability mechanism will associate with each process a set of capabilities
that the process can potentially use, but capabilities should be controlled at the
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

310

B Revisions to Rationale and Notes

181
182
183
184
185

level of granularity of individual programs. The most straightforward way to dothat is to associate capability controls with the individual program files. The firstrequirement implied by the principle of least privilege, to control capability at the
granularity of individual programs, leads to the assignment of capability attributes to program files; this is the file capability state.

186
187
188
189
190
191
192

If a program is always executed in a single context, e.g., by a single user to perform a single function, then the specific set of capabilities for that contextprogram combination applies to all invocations of the program. However, in general a program is executed in varying contexts, e.g., by different users, or on different files, or for different purposes—such as a printer spooling program. Thus
we need to be able to change the capabilities of a process as its circumstanceschange.

193
194
195
196
197
198
199
200
201
202
203
204

This is the second requirement implied by the principle of least privilege: to control use of capability within the context of intended use. It further suggests thatprocess capabilities be divided into two classes: capabilities that are currently
active, and capabilities that could be activated. We do this by creating twocorresponding kinds of process capability flags: effective (indicating that the capability is active) and permitted (indicating that the capability could be activated).
Thus a process can increase its current set of active capabilities by making effective any capability that it is currently permitted , and can reduce its active capabilities at any time while retaining the ability to restore them. This ability of aprocess to adapt its active capabilities to the needs of the moment is referred to in
the standard as the ‘‘time bounding of capability’’ and is sometimes also referred
to as capability bracketing.

205
206
207
208
209

If a process image is instantiated from a program file, its capabilities will beaffected by the capability state associated with the file. A program will exec a program file to instantiate its successor program in a process chain. Here too theprinciple of least privilege implies that we adapt the use of capability to the context of use. There are two general ways to do this.

210
211
212
213

In the first, exec() constrains the maximal extent of capabilities for theprocess image it instantiates from a program file. In this way the
invoking process image can limit the capabilities of the successor process image.

214
215
216
217
218
219

In the second, exec() plays no role in limiting the set of capabilities thatthe instantiated process image may have; rather, the successor process
image sets the capabilities itself, choosing them from the set of capabilities associated with the program file from which it was instantiated,and possibly from a set of capabilities that a predecessor process image
had passed on.

220
221
222

In either case, the advantage of passing capabilities along a process chain is thatit allows the process to dynamically build up a capability context, rather than limiting its capability context to a single, per−process image state.

223
224
225

Besides providing a capability for a process image to pass capability information
to subsequent process images, it may be desirable that a specific process image
have capabilities that are not permitted to any of its predecessors. We therefore
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.25 Capability

311

226
227

need a way to increase the capabilities of a process based on the program file
being exec’ed.

228
229
230
231

Finally, we observe that a process image may wish to pass capabilities to somesuccessor process image through an intermediate third process image that is notitself trusted to properly use the passed capabilities. For example, a process may
initiate an untrusted shell that in turn will exec a third program file.

232

B.25.2 Major Features

233
234
235
236
237
238

There must be some method for a process to acquire capability(s) it needs if it is tobe able to use it(them) at some point. Because capabilities are security relevant,this method must be restricted to a trusted part of the system, which must grant
the ability to use capability based on one or more characteristics of the process.
We assert that the characteristic most relevant is the identity of the program orprograms that are run within that process.

239
240
241
242
243
244
245
246
247
248
249
250

A result of this assertion, that the identity of programs is the primary characteristic used to assign trust, is the requirement that there be some means to identify aprogram file as trusted. There are several means available to do this. The first is
to embed some form of identification in the program file itself in such a way thatthe loader can interpret it. This leads to problems, however, in that different installations may have different security policies, and that system administrators
may not trust the program developer enough to set the proper capability attributes. The second alternative is to attach capability attributes to the program
file. This alternative provides a much larger degree of flexibility, in that systemadministrators can differ in their trust of a particular program without modifying
or altering the actual program itself, and is much more consistent with current
practice and methods. As a result, file capability attributes were proposed.

251

B.25.2.1 Task Bounding of Capability

252
253
254
255
256
257
258

This standard has the advantage of being flexible enough that a given capability
may be bound either for the duration of an executable program or the duration ofa single system call. This allows flexibility in the granularity of capability, provides support for backwards compatibility, and allows trusted programs to support capability bracketing. The main advantage in task bounding of capability isthat it reduces the chance that program errors will have security-relevant side
effects.

259

B.25.2.2 Capability Inheritance

260
261
262
263
264
265
266

Trusted programs can perform complicated functions and, as a result, can be verylarge. The larger and more complicated a program is, however, the harder it is toevaluate for trust and the more difficult it becomes to maintain. In addition, oneof the basic tenants of the POSIX.1 operating system is to provide a set of simple
utilities that can be executed together or in series to perform more complicatedfunctions. As a result, it is desirable for a trusted program to be able to pass on
its capability characteristics to other programs to perform functions it would
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

312

B Revisions to Rationale and Notes

267

otherwise have to implement itself.

268
269
270
271
272
273
274
275
276
277

While one trusted program may want to pass all of its capabilities to another,more often the child program only needs a subset of the parent program’s capabilities to perform its functions. Also, should the child program be trusted, theparent trusted program may not be aware of how much trust that child program
actually has at any given time. Finally, a conforming program CANNOT betrusted to handle implementation-defined capabilities. Therefore, the developer
needs to have the ability to restrict what capabilities he or she desires to pass onto the child program, and the system developer and administrator need to have ameans of controlling what capabilities they are willing to permit the child program to have.

278
279

Since the exec() function is the means by which one program invokes another, it
must be modified:280g

To grant capabilities to programs when they are executed.

281g

To permit programs to pass capabilities to other programs.

282

g

To restrict which capabilities may be passed from one program to another.

283
284
285
286
287
288
289
290
291
292
293

So far, we have provided the basis for program level capabilities. In other words,
programs that are granted capabilities using the attributes specified so far havethose capabilities during their entire scope of execution. For many systems,
program-level capabilities may not provide the level of granularity desired by the
security policy. For instance, a program may need to have the capability to write
to a system administrative file only during a single call to the open() system function. For the remainder of the time the program executes, the capability is available but not required. In order to support implementations that support the concept of least privilege to a finer level of granularity, we need to provide the meansby which a program can enable a capability only during the scope of execution forwhich it is actually required.

294
295

In summary, then, the view of the principle of least privilege presented here andthe desired functionality described above implies the following:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.25 Capability

313

−

296
297

(1) There is capability state associated with program files as well as withprocesses.

298
299
300

(2) There are two kinds of process capability attributes: one which defines
what capabilities may be invoked by the process image, and another thatdefines what capabilities are currently invoked by the process.

301
302

(3) There is a way to increase the capabilities of a process that depends on
the process image file that it exec’s.

303
304

(4) There is a way to conditionally transmit capabilities from a process
image to its successor image(s).

305
306

(5) There is a way to restrict which capabilities may be passed to any particular process image that depends on the process image file.

307
308

(6) The exec() system function determines the capability attributes of theprocess it instantiates.

309

B.25.2.3 Process Capability Flags

310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325

A process image acquires capabilities from the set of capabilities attached to theprogram file from which it is initiated. The effective flag determines whether the −capability is active for the process. The permitted flag determines whether theprocess may choose to make the capability effective . The inheritable flag deter- cmines whether the process may pass on to its successor process image a condi- ctional right to use a capability. The right must be conditional because the capability may be inappropriate for intermediate image(s). Indication of thesuccessor’s appropriate capabilities is reasonably associated with the successor’s
process image file. In fact, this indication can be made precisely by the permitted cfile capability flag. The determination of the right to use a capability depends on −the current process’s value of the inheritable flag and on the values of the permit- c
ted and inheritable flags of the corresponding file capability. This determination
is made by exec(). In implementations that depend more heavily on use of the ceffective flag, the inheritable flag can be used by a process image to determine thetrust associated with its predecessor process image and therefore provide a basis
for enforcing its own security policy.

326

B.25.2.4 File Capability Flags

327
328
329

As we have seen, the principle of least privilege requires that with each program
file there is associated the set of capabilities that a process image, instantiatedfrom that file, requires to do any of its functions.
c

330
331
332

The inheritable flag determines which capabilities the resulting process image
may pass to subsequent process images and which ones the program may chose toc
use if the previous program image possessed the capability.
c

333
334
335

The permitted flag determines which capabilities the resulting process image
needs to have available in order for the program to function properly, regardlessof the capabilities of the previous process image.
cc

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

314

B Revisions to Rationale and Notes

c

c
c

336
337

The effective flag determines which capabilities the resulting process image will
possess in its effective process set.
c

338
339
340
341
342
343

The ability to support capability unaware applications on a per executable basis
ensures that these programs will continue to function with a limited set of capabilities, thus reducing the risk of unauthorized access to restricted functions.
Additionally, the risk of a trojan horse gaining unauthorized access to capabilities
is reduced if the inclusion of capabilities into the effective set is automatically limited to a per file basis.

344
345
346

Earlier versions of this standard provided a single set_effective flag instead of the ceffective set. The new process permitted set was promoted to the effective set on cexec() when this flag was set.

347

B.25.2.5 The Determination of Process Capability by fork()

348
349
350
351
352

This is a simple case. The fork() system function is meant to create a new processthat is, as much as possible, identical to its parent. Because capability is not an
attribute that uniquely identifies a process, such as process ID, the capability
state of a child process should be identical to that of its parent immediately after
the execution of the fork() system function.

353

B.25.2.6 The Determination of Process Capability by exec()

354
355
356
357
358
359
360

The inheritable and permitted capability flags of the program file and the inherit- cable capability flags of the current process together determine the contextdependent set of capabilities permitted to the instantiated process. The
context−independent set of capabilities that is included in the permitted capability
set of the program when it is executed is derived from the permitted file capabilityc
flags associated with the program file. The union of these two sets comprise theset of capabilities that the exec() function permits the new process image to use.

361
362
363
364
365

The initial state of the effective flags of the new process image depends on theinheritable flags in the old image and the values of inheritable, permitted, andeffective flags of the program file. The justification for selecting the transformation function for process capability state is incorporated throughout the text of
this section.

366

B.25.2.7 Support of the Capability State Attribute on Files

367
368
369
370
371
372

The intent of these interfaces is not to limit the manner in which processes cangain appropriate privilege. Thus, if the value of the pathname variable{_POSIX_CAP_PRESENT} is zero (meaning that the file does not support the
POSIX capability state attributes), then it is possible for an implementation to
specify other mechanisms. For example, the USL implementation provides both aprivilege mechanism and a superuser mechanism.

373
374
375

Certainly, there are implementations that allow files to be exec’ed from file systems that do not support capability attributes (for example, an NFS file system
mounted from a system not supporting the capability option). In this case, it is
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.25 Capability

315

c

c

c

c

376
377
378

suggested that an implementation treat this file exactly as it would a file without
a capability state attribute from a file system that does support capability attributes.

379

B.25.2.8 Extensions to This Standard

380
381
382
383
384
385
386
387
388
389

This specification does not preclude providing additional implementation-definedconstraints, such as a system-wide configuration variable to further constrain the ccapability inheritance rules. The value of this variable could be used to act as anadditional gating function to permit a single global value to be manipulated by asystem security officer to help stop or slow a security breach in progress by
preventing any permitted capabilities from being automatically included in every
process effective capability set. Additional file capability attributes and file capability flags can also be defined by an implementation. It must be emphasized thatsuch extensions are compliant only if they further constrain (prevent from becoming effective) capability.

390

B.25.2.9 Process Capability Manipulation

391
392
393
394
395
396

When a process image is instantiated from a program file, its capability flags
describe its capability state. As noted earlier, the effective, permitted, and inheritable flags respectively denote which capabilities are active, which may be
activated, and which the process image will (conditionally) pass on to its successors. A process should not be permitted to arbitrarily modify these flags, but isrestricted according to the following set of rules.

397
398
399
400
401
402

A process can promote to effective only those capabilities whose permitted flag isset. This lets the process adapt its degree of active capabilities to its current context, and so supports the principle of least privilege. On the other hand, the process can never promote a capability to effective if the permitted flag is turned off,and can never enable a permitted flag that is turned off. Thus the process cannot
assume for itself capabilities to which it is not entitled.

403
404

To prevent it from accumulating capabilities through inheritance, a process canenable an inheritable flag only if the corresponding permitted flag is set.

405
406
407
408
409

If a process disables a permitted flag, the corresponding effective flag is automatically disabled. The corresponding inheritable flag is not affected, so capabilities
can be conditionally transmitted along a process chain whose intermediate
processes may themselves have no capabilities. In no other case does changing
the value of any flag affect the value of any other flag.

410

B.25.3 Function Calls Modified for Capability

411
412
413
414
415

The standard defines the capabilities required by each of the POSIX.1 functions.
However, many implementations included additional functions that should be
modified to support the capabilities defined in this standard. While the list
presented here is by no means exhaustive, it is included as helpful information for
the reader.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

316

B Revisions to Rationale and Notes

416

Table B-3 − Other System Functions Potentially Affected by Capability Policies

417
418

Function
iiiiiiiiiiiiiii
iiiiiiiiiiiiiii

419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443

adjtimebindchrootkillpglimit
mincoremknod
mount
ptracereadv
rebootsethostname
settimeofday
shutdown
socketsocketpair
swaponsymlinksyscallumountvadvisevfork
vhangupwritevsysattr444

B.25.4 Capability Header

445
446
447
448

These types were defined to provide opaqueness and avoid specifying detail thatshould be left to the implementation. The capabilities defined in this section arelimited to those specifically called for in the POSIX.1 standard. Included also arethose capabilities defined in POSIX.1e.

449
450

B.25.4.1 Rationale for the Selection of Capabilities Defined in the Standard

451
452
453
454

This section will describe the process that the capability group used to develop theset of capabilities specified in this standard. Enough detail is provided about theprocess so that an implementor can duplicate it when analyzing an implementation to determine what additional capabilities, if any, are required.

455
456
457
458
459

We began the process of defining a capability set for the standard by first developing a set of guidelines to be used. These guidelines are contradictory to a degree,
and the group made trade offs between them when discussing each individual
capability in order to come up with a minimum set of capabilities that weredeemed necessary for the support of conforming applications.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.25 Capability

317

460

Principles for Determining a Capability Set

461
462

Principle #1: A capability should permit the system to exempt a process from a
specific security requirement.

463
464
465
466
467
468

In most cases, security requirements found in the function descriptions take theform: ‘‘In order for this function to succeed, <requirement>, or the process mustpossess appropriate privilege.’’ A specific example can be found in the POSIX.1
description of the chown() function, which states ‘‘In order for this function to
succeed, the UID associated with the process must match the owner ID of the file,or the process must possess appropriate privilege.’’
c

469
470
471

This principle is meant to support the principle of least privilege, in that a capability should provide only the minimum rights or authority to perform a specific
task.

472
473

Principle #2: There should be a minimal overlap between the effects of capabilities.

474
475
476

Capabilities should be defined such that they apply to logically distinct operations, and the granting of a set of capabilities should not, as a side effect, grant anadditional capability that is not in that set.

477
478
479
480
481

This principle was developed to address the concerns that capabilities should be
distinct and unique—no capability or combinations of capabilities should provide
the capabilities afforded by another capability. When a system administrator
grants one or more capabilities to a specific user or program, they should havesome assurance that the recipient is not gaining any additional capabilities.

482
483

Principle #3: Insofar as principles #1 and #2 are supported, fewer capabilities are
better than more.

484
485
486

When it makes sense to do so, and identical or nearly identical security requirements exist, a single capability should be defined for all those security requirements instead of a separate capability for each individual security requirement.

487
488
489
490
491
492
493
494

This principle was defined primarily to support ease of use and ease of administration. If each individual security requirement in an implementation had aunique capability, several hundred capabilities would be required, a managementnightmare that would be prone to misunderstanding, confusion and error. If a
specific security requirement is especially critical or sensitive, however, it was
generally agreed that it should be assigned a unique capability in order to assure
positive control over which processes/programs are exempted from the requirement.

495

Determining the Capability Set

496
497
498

Once the above general principles were agreed to, the group turned to the existingand draft POSIX documents to begin the process of actually developing the set ofcapabilities included in this standard.

499
500
501

The set of capabilities defined in this document is not intended to be all-inclusive.
Implementations may (and probably should) define additional capabilities to support the operation and maintenance of their systems. Finally, it should be
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

318

B Revisions to Rationale and Notes

c

502
503
504
505
506

emphasized that the development of a capability set is not a cookbook process—
implementors must consider their own system security requirements and thedesign of their own systems when determining what capabilities they will support. Our requirement was to develop a minimum set of capabilities we determined necessary to support conforming POSIX applications.

507
508
509
510
511

Step one in the process was to develop a list of security requirements from the
POSIX.1, and POSIX.2 documents. This involved searching through the descriptions of the functions and utilities looking for the phrase ‘‘appropriate privilege’’and also looking for text that implied a security requirement that was not directlystated.

512
513
514
515
516
517

Once we had developed the list of security requirements, or ‘‘checks’’, we grouped
sets of identical or nearly identical requirements together, and developed adescriptive name for each individual or group of requirements that remained.
When grouping requirements, each case was discussed to ensure that it really did
belong to the group, and it was not uncommon for a decision to be re-made as thelist developed and additional considerations were brought up.

518
519
520

The last step in the process was to review the entire list. Capabilities weredeleted or combined with another capability when it was deemed appropriate to
do so with respect to the third principle in B.25.4.1

521

B.25.4.2 Rationale for DAC Capability Specification

522
523
524

The DAC group defines the extensions to POSIX.6 for a finer granularity of discretionary access control beyond POSIX.1. For systems with {_POSIX_CAP} −configured, it is necessary to define the policy override capabilities.

525
526

The DAC group initially considered separating DAC overrides into 4 distinct
capabilities. These were:527

g

CAP_DAC_READ

528

g

CAP_DAC_WRITE

529

g

CAP_DAC_SEARCH

530

g

CAP_DAC_EXECUTE.

531
532
533
534
535
536
537

The CAP_DAC_READ and CAP_DAC_WRITE separation was considered necessary for providing read-only access for a wide range of applications that have noneed to write to the objects they are examining. The CAP_DAC_SEARCH and
CAP_DAC_EXECUTE capabilities were suggested because it was not necessarily
appropriate to group these abilities with the CAP_DAC_READ and
CAP_DAC_WRITE capabilities. Also, specification of four separate capabilities
maps one-to-one with the existing POSIX.1 features.

538
539

The group also considered a single CAP_DAC_OVERRIDE capability, but thisgranularity was considered insufficient for the following reasons:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.25 Capability

319

c

540
541
542
543
544
545
546

g

Demonstrated commercial need on other operating systems to support
separate CAP_DAC_READ and CAP_DAC_WRITE overrides based on functional requirements. For example, a backup program requires the ability toread all file objects on the system but only requires the ability to write to
the backup device. Additionally, this separation provided programmatic
support for administrative roles which allow for protection from inadvertent modification of system critical objects.

547
548
549

g

Worked examples of trusted systems evaluated at class B2 or higher
against the TCSEC on which similar mechanisms were required to meet
the System Architecture requirement.

550
551
552
553

Because the specification of four separate capabilities seemed to be unnecessary,and the specification of a single capability is not sufficient to support commercial
requirements, we decided to specify three capabilities and permit implementations to add additional capabilities if appropriate.

554
555
556
557

In fact, an analysis of the requirements determined that these three capabilities
are sufficient to support the principle of least privilege as well as the anticipatedcommercial demand. Note, however, the specification provides support for implementation defined capabilities where deemed necessary.

558
559
560

The consensus was that applications that required CAP_DAC_READ override
would also require CAP_DAC_SEARCH override. Therefore these two capabilities were combined.
−

561

B.25.4.3 Rationale for MAC Capability Specification

562
563
564
565
566
567

A MAC policy differs from a DAC policy in that an untrusted process or user does
not participate in establishing the access criteria. Rather, the system is responsible for enforcing the policy established by the security officer. As such, the MAC
policy can be considered to impose a higher degree of assurance on the protectionof an object compared to DAC. Therefore, MAC policy override capabilities must
be carefully considered.

568
569
570
571

The MAC group has established a set of policy overrides that are designed to support sufficient granularity of control to meet the needs of current security standards as well as to meet the needs of future trusted applications, such as databases, multi-level mailers, etc.

572

CAP_MAC_UPGRADE and CAP_MAC_DOWNGRADE

573
574
575
576
577
578
579
580

The MAC group originally considered a single MAC override capability to coverboth the upgrade and downgrade cases for manipulating object labels. Although
this level of granularity meets the needs of the current TCSEC, more recent security criteria, such as the ’91 Compartmented Mode Workstation Evaluation Criteria do require separation of the MAC override capabilities. In addition, theseparation of the upgrade and downgrade functions is a common operational
requirement. Supporting distinct capabilities is a logical extension of this operational requirement.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

320

B Revisions to Rationale and Notes

c

c

c

581

CAP_MAC_LOCK

582
583
584
585
586
587
588
589

At one time during the writing of this standard, the standard required that a process have MAC write access to a file at the time of a lock operation, or have
CAP_MAC_LOCK enabled. These protections were necessary because the set oflocks associated with a file are considered to be an object. More specifically,
because the data structure which defines the lock on a file can be directly written
by processes (by setting locks) and can be directly read by processes (by querying
locks), this data structure was deemed a communication channel that must be
subject to MAC constraints.

590
591
592
593
594
595
596

The straightforward application of MAC policy to locks requires that a process
have MAC write access to the file prior to setting locks. In a system with only
CAP_MAC_WRITE, a process must be trusted to use the override capability
appropriately. It can be argued that processes that need to use locks should betrusted enough to use the MAC write override capabilities for this purpose. Thisapproach also has the added feature of minimizing the number capabilities necessary for the MAC policy.

597
598
599
600
601
602
603
604
605

However, the use of CAP_MAC_WRITE to bypass this policy constraint was considered non intuitive and a violation of the principle of least privilege. For example, a process merely wishing to set a read lock on a lower level file simply to readthe file, e.g., a password file, would then need to be granted the MAC write capability, despite having no need to write data to the lower level file. Thus in casessuch as these, which in actual implementations are likely to be frequent, not onlyis a powerful capability being used to cover a relatively innocuous activity, butalso the use of a write capability to effectively perform a read is confusing. For
this reason CAP_MAC_LOCK was originally adopted.

606
607
608

Based on significant ballot objections, this capability was removed and the standard was made mute on the subject of how an implementation handles the channel created by fcntl and reading locks.

609

CAP_MAC_READ and CAP_MAC_WRITE

610
611
612
613
614
615
616

While the TCSEC does not require separation of the MAC override capability into
distinct READ and WRITE capabilities, other security specifications do. In addition MAC is a system enforced policy rather than a discretionary policy, requiringthat applications which need only to read an object also have the power to write
the object was considered an unwarranted risk. Separation of MAC_READ and
MAC_WRITE overrides will encourage application developers to be cautious with
their use.

617

CAP_MAC_RELABEL_SUBJ

618
619
620
621
622
623

The ability of a subject to change its own MAC label is controlled by the
CAP_MAC_RELABEL_SUBJ capability. This capability is intended for use bytrusted subjects which have the need to modify their label based on some (possibly external) criteria. For example, a trusted server which may need to reset its
MAC level prior to executing functions on behalf of a client request. Unlike
objects, which tend to have a static label, subjects would need a dynamic label
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.25 Capability

321

624

therefore a single capability is more appropriate for subjects.

625

B.25.4.4 Rationale for Information Labeling Capability Specification

626

CAP_INF_NOFLOAT_SUBJ and CAP_INF_NOFLOAT_OBJ

627
628
629
630
631
632
633
634

These two capabilities are the override capabilities for the Information Label Policy. The INF_NOFLOAT_OBJ capability is necessary to support programs which
need to write a shared single file at many information levels. An example of thisis the /etc/utmp file which the login program writes. Similarly, there areprocesses which may not wish to allow their information label to float. An example of this would be a server process which must fork off children to perform workin response to a specific request. The INF_NOFLOAT_SUBJ supports these typesof processes.

635

CAP_INF_RELABEL_OBJ and CAP_INF_RELABEL_SUBJ

636
637
638
639

These capabilities allow processes to explicitly set labels on subjects and objects.
As information labels are not an access control policy separate overrides for reading and writing object labels are unnecessary. Rather a single capability is
sufficient for applications which need to manipulate information labels on objects.

640

B.25.5 New Capability Functions

641

B.25.5.1 Function Naming Scheme

642
643
644
645
646
647
648

In order to provide for consistency across the sections of this document, a naming
scheme for all named entities was adopted. Functions are named with a subsystem identifier—cap_, first, followed by a short name that identifies the type ofoperation the function performs, then a short name that identifies the data thefunction operates on. While this scheme generates names that are somewhat
longer than are generally customary, it is generally evident from the name of thefunction what its purpose is and we found it easier to remember them.
c649

B.25.5.2 Allocate, Duplicate, and Release Storage for Capability State

650
651
652
653
654
655
656

The cap_init() function is necessary to create a new object to hold capability attri-−
butes. We did not desire to specify the contents and storage requirements of thisobject in order to permit as many differing implementations as possible. Having
provided an allocation function, we need also to provide a free function, cap_free(),cso that an implementor can release memory and structures associated with a process capability data object. In order to permit the representation to be copied, we
defined a duplication function, cap_dup ().
c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

322

B Revisions to Rationale and Notes

c

657

B.25.5.3 Initialize a Process Capability Data Object

658
659
660
661

The cap_clear() function permits a program to set the representation of the capa- −bility state to a known secure state. This has the advantage that a conforming
program need not know all the capabilities defined in the implementation to set
this ‘‘secure’’ state.

662

B.25.5.4 Read and Write the Capability Flags of a Process

663
664
665
666

The cap_set_proc() and cap_get_proc() functions permit a program to obtain andset the capability state of a process atomically. The atomicity of these functions is
significant—the state of a process could possibly change between multiple invocations of a function that deals with only one capability flag at a time.

667
668
669
670
671
672

The cap_set_proc() function is an especially security-critical function in any system that implements a capability mechanism, as it is here that the standard
requires that the security policy regarding the manipulation of process capability
state be applied. The requirement that the capability be permitted to the running
program provides the primary means to limit what capabilities any one program
can propagate through the system.
c673

B.25.5.5 Get and Set Values of Capability Flags

674
675
676
677
678
679
680
681
682
683
684

The cap_get_flag(), and cap_set_flag() functions provide the standard interface forc
getting and setting the values of the capability flags. Portable trusted applica- −tions will need to manipulate the process capability state on different implementations so that they can perform "time bounding of capabilities" and set what
capabilities they want to pass on to programs that they exec. The cap_get_flag() cfunction permits a conforming application to determine the state of a capability −without actually attempting to use it. Without a get function, conforming applications could generate numerous unnecessary audit messages attempting to use −capabilities not available to the current invocation of the program. The c
cap_set_flag() is the only means by which a conforming application can alter thestate of a specific capability.
c685

B.25.5.6 Exporting Capability Data

686
687
688
689
690
691
692
693

The cap_to_text() and cap_from_text() functions translate process capability cstates between human-readable text and capability data object representations. −These functions are necessary to provide a portable means of transferring capabil-−
ity information between systems. Implementations may also use these functions
to translate between text and data objects in order to support capability manipu- −lation and display. One possible use is the display of available capabilities using
a trusted shell utility, another is the transport of capability information across a
network in a form recognizable to all machines.

694
695
696

There are other valid reasons to want to store process capability data objects—for
instance, the process capability state could be an important field in certain audit
records. Textual data, while easily readable, is not compact. The internalcc

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.25 Capability

323

697
698
699
700
701
702
703

representation of capability state is not guaranteed by this standard to be valid
outside of the context in which it exists. For instance, it may contain pointers tostrings spread throughout the system-managed space. This was intentional topermit implementors the maximum possible freedom. Because of this, thecap_copy_ext() and cap_copy_int() functions are provided to convert the internal
representation to and from a self-contained binary format that should be morecompact than the textual version.

704

B.25.5.7 Manipulating File Capability Flags

705
706
707
708
709
710
711
712
713
714
715
716

When we developed the set of functions to manipulate file capability flags, we had
several goals in mind. First, we wanted the assignment of capability attributes tofiles to be atomic—there is a reasonable probability that a program file could beexecuted by another process in the middle of a sequence of non-atomic file attribute operations. Second, we wanted to continue to hide the actual representationof capability attributes in the standard and permit a wide variety of implementations. We feel that the interfaces defined support an implementation where thefile capability attributes are stored in the files’ inode AND an implementation
where the files’ capability attributes are stored in a central database maintainedby a capability server. Finally, the group as a whole decided to specify proceduralinterfaces wherever possible instead of data-oriented interfaces in order to bettersupport extensibility and flexibility in the future.

717
718
719
720
721
722
723
724
725

We did not resolve the atomicity problem to the extent we desired, but felt thatthe correct solution was really outside of our scope. POSIX has no mandatory filelocking mechanism, hence, there exists the possibility that file attributes havebeen altered by a second process between the time the first process has read themand the time it attempts to set them. This is a general problem not limited to filecapability state, but includes all file attributes and data. Instead of solving thegeneral problem, we have specified functions that read and write the entire capability state, rather than permit programs direct access to individual capability
flags and attributes. This should minimize, but not eliminate, this problem.
−

726

B.25.5.8 Read and Write the Capability State of a File

727
728
729
730
731
732

The cap_get_file() and cap_set_file() functions permit a program to obtain and set
the capability state of a file atomically. The atomicity of these functions is
significant—the state of a file could change between multiple invocations of afunction that deals with only one capability flag at a time. In addition, it keeps
device I/O required by the capability function set to these two functions—all therest can (but are not required to) be memory only operations.

733
734
735
736
737
738
739

The cap_set_file() function is a security-critical function in any system that implements a capability mechanism. We therefore imposed a number of restrictions on
the ability of programs to use this function. The requirement that the capability
be permitted to the running program provides the means to limit what capabilities any one program can propagate through the system. The requirement tohave the CAP_SETFCAP capability effective provides the means to restrict programs that are permitted a capability for other purposes from granting it to
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

324

B Revisions to Rationale and Notes

c

c

740
741
742
743
744
745

programs that the system administrator has not specifically approved. The
remaining restriction is that the UID associated with the process be equal to theowner of the file or that the process have the CAP_FOWNER capability
effective—this is a standard restriction for all operations dealing with file attributes. The combination of restrictions above are the minimum necessary to
prevent the unauthorized propagation of capabilities.
−

746
747
748
749
750

Many times a file is already opened when it is being assigned attributes. Many
programs use file-descriptor based functions in order to avoid the performance
penalty incurred to perform repeated pathname resolutions. To accommodate
this class of applications, we have provided the cap_set_fd() and cap_get_fd()
functions to set and get the capability state of an opened file.
+751

B.25.5.9 Error Return Values

752
753
754
755
756
757
758
759
760
761

If the symbol {_POSIX_CAP} is defined, then the implementation supports the +capability option and is required to support the capability functions as described +in this standard. If the symbol {_POSIX_CAP} is not defined, then the implemen- +tation does not claim conformance to the capability option and the results of an +application calling any of the capability functions are not specified within this +standard. An alternative is for the capability functions to specify that the error +return code [ENOSYS] be returned by the functions if the capability option is not +supported. However, in order to remain compliant with the policies of POSIX.1, +this standard cannot specify any requirements for implementations that do not +support the option.

762

B.25.6 Examples of Capability Inheritance and Assignment

763

B.25.6.1 A User-based Capability Model

764
765
766
767
768
769
770
771
772
773

The inheritance mechanism provides a method of controlling a process’ capabilities based upon the context in which the process is executed. An important partof the context is the identity of the user invoking the process. It is possible toassociate capabilities with a user profile which defines a subset of the capabilities
available to the trusted programs that a user may execute. Trusted programs
may therefore have greater or lesser abilities depending on which user executes
them. These user capabilities constitute the inheritable capability set on session
initialization. A subset of the user capabilities could be selected by utility options
to support user roles. The login shell will probably be an untrusted shell, and in
itself be incapable of using capability.
−

774
775
776
777
778
779
780
781

It is not possible for a user to alter the set of inheritable capabilities within an
untrusted shell or program. A user can only modify the set of inheritable capabilities by executing a program that gains capabilities either by having effective capa-cbilities or by having permitted capabilities that have already been set inheritable. c
Programs that have effective capabilities may validate a user’s authorization to c
use those capabilities, depending on whether or not the execution of the program
could have an adverse impact on the security of the system. This mechanism permits the emulation of a fully privileged user by executing a program that has all+

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.25 Capability

325

782

capabilities effective.

783

B.25.6.2 A Program-based Capability Model

784
785
786
787
788
789
790
791
792
793
794

Instead of forcing every trusted application to perform user authorization checks,
it is possible to create a single program that does so, and sets the inheritable flagof all capabilities authorized to a user. Program files in this style of implementation would have the permitted flags of all the capabilities they require for all their cpossible functions set. When executed, the program would receive only thosecapabilities actually authorized to the user, not necessarily the full set that they
are capable of using. It is thus possible to provide a trusted shell or user interface
program that will assign additional capabilities or disable existing capabilities
associated with a user based upon the specific functions to be performed and theninvoke one or more programs that are relieved of having to perform a user authorization check.

795
796
797
798
799
800

It is not possible for an executing program to acquire additional capability foritself through the execution of a more trusted program, i.e., through exec’ing a −more trusted executable file, but only to create a new process image that is moretrusted than it is. Since the new process image has, by definition, replaced theold process image, attempts to garner additional capability in this manner will
fail.

801

B.25.7 Capability Worked Examples

802
803
804
805
806

This section illustrates the POSIX.1e Capability mechanism by providing both
utility and function examples. Included are examples using the POSIX.2 chown
utility and POSIX.1 chown() function, examples of capability unaware programs,
and an illustration of how the capability mechanism defined in this standard canbe used to execute shell scripts.

807

B.25.7.1 CHOWN()

808
809

To change the user ID of a file, the chown() function imposes the following restrictions:

810
811

g

812
813
814
815
816
817

g

818
819
820
821

g

c

A process shall possess an effective user ID equal to the user ID of the file, or its
effective capability set shall include the CAP_FOWNER capability.
If the {_POSIX_CHOWN_RESTRICTED} option is in effect for the file, the process’ effective capability set shall include the CAP_CHOWN capability. Thus, tochange the user ID of the file, both the CAP_CHOWN and CAP_FOWNER capabilities may be required in the process’ effective capability set. If the system
implements the MAC option of this standard, the process may also require the
CAP_MAC_WRITE capability in the process’ effective capability set.
If the file is a regular file, the set-user-ID (S_ISUID) and set-group-ID (S_ISGID)
bits of the file mode shall be cleared upon successful return from chown(), unlessthe call is made by a process whose effective capability set includes the
CAP_FSETID capability, in which case, it is implementation defined whether
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

326

B Revisions to Rationale and Notes

822

those bits are altered.

823
824
825

In examples 1 through 3 below, the chown() executable file is assigned, via thecap_set_file() function, an empty effective set, an inheritable capability set that
includes:826

g

CAP_FOWNER

827g

CAP_CHOWN

828
829
830
831

g

832

g

CAP_DAC_READ_SEARCH

833

g

CAP_MAC_READ

834

g

CAP_MAC_WRITE

835

EXAMPLE 1

836
837
838
839
840
841
842
843

If the chown() utility is executed by a process that possesses all the above capabilities in its inheritable capability set, then all of these capabilities are included in
the resulting process’s permitted capability set. When these capabilities are madeeffective, via the cap_set_proc() function, the process may change the user ID of
the specified file without regard for mandatory and discretionary access restrictions, file ownership restrictions, or {_POSIX_CHOWN_RESTRICTED} restrictions. Alteration of the set-user-ID and set-group-ID bits of the file mode is implementation defined upon successful return from chown().

844

EXAMPLE 2

845
846
847
848
849

If the chown() utility is executed by a process that possesses no capabilities in its
inheritable capability set, then the resulting process’s permitted capability set
will not contain the three required capabilities. Therefore, the resulting process
shall not possess appropriate capabilities to override any of the chown() restrictions described above.

850

EXAMPLE 3

851
852
853
854
855
856
857
858
859

If the chown() utility is executed by a process that possesses only the
CAP_CHOWN and CAP_FOWNER capabilities in its inheritable capability set,
then the resulting process will possess the CAP_CHOWN and CAP_FOWNER
capabilities in its permitted capability set. When these capabilities are madeeffective, via the cap_set_proc() function, the process may change the user ID of
the file, regardless of the file’s initial user ID, or value of{_POSIX_CHOWN_RESTRICTED}. However, this process must satisfy all mandatory and discretionary access requirements, and the set-user-ID and set-groupID bits of the file mode shall be cleared upon successful return from chown().

CAP_FSETID
and a permitted capability set with flags set to potentially allow bypassing of DACc
and MAC restrictions imposed by the chown() function (See 25.2 for capability
descriptions.)c

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.25 Capability

327

c

860

EXAMPLE 4

861
862
863
864
865
866
867
868
869

In this example, the file capabilities are initialized as described for examples 1through 3, above, except that the CAP_FSETID capability is removed from thechown executable file’s inheritable capability set, and is assigned to the file’s per- cmitted capability set. The process resulting from execution of the chown utility
will possess the CAP_FSETID capability as part of its permitted capability set,
regardless of the contents of the exec’ing process’s inheritable capability set.
When the CAP_FSETID capability is made effective, via the cap_set_proc() function, alteration of the set-user-ID and set-group-ID bits of the file mode is implementation defined upon successful return from chown().

870

B.25.7.2 Capability Unaware Programs

871
872
873
874
875
876
877
878
879

In this section, we examine the behavior of capability unaware programs. This
specification provides support for backwards compatibility of binary executables
that depend on traditional UNIX set-user-ID behavior for proper operation. This
specification also provides a mechanism for overriding capability on a per executable basis. Additionally, the permitted flag provides for a finer granularity of con- ctrol to enable capabilities based on the inheritable flag of the exec’ing process. For
all capability unaware programs that require capability, the program file’s effective flag must be set. This is the only mechanism for enabling capabilities in theeffective capability set upon execution.

880

EXAMPLE 1

881
882
883
884
885

Suppose an old version of the mailx program requires discretionary and mandatory override capabilities to operate correctly on a particular implementation.
These capabilities can be enabled via the effective capability set regardless of the cexec’ing process’ inheritable capability set. This allows mailx to operate on a system supporting {_POSIX_CAP} without modifying the mailx source code.

886
887
888
889

If an administrator desires to control which capabilities become effective based on
the exec’ing program’s inheritable capabilities, then the permitted flag is used.
The inheritable flag is ANDed with the permitted flag and this result is includedin the new process’ effective flag.

890

EXAMPLE 2

891
892
893
894
895
896

The grep program may have the CAP_DAC_READ_SEARCH capability enabledin the permitted capability set, which would then permit the invoker to access all cfiles if and only if the CAP_DAC_READ_SEARCH inheritable capability wasenabled in the exec’ing process. This would permit a trusted process to exec thegrep program to locate a phrase in a file tree it normally would not have readaccess to.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

328

B Revisions to Rationale and Notes

c

c

c

897

B.25.7.3 Shell Script Execution

898
899
900
901
902
903
904
905
906

A shell script can be executed with capability using the capability mechanism
defined in this standard. For example, a program stub can be created that can be
invoked from the login shell that sets the inheritable capability attributes for
those capabilities needed for shell script execution. The system() function canthen be invoked to execute the shell script file. The capabilities set in the inheritable capability set are then passed through the shell executed by the system()function to the individual utilities constituting the shell script. The capabilities
available to each utility are then determined by the exec() function as described in
the capability mechanism.

907

B.25.7.4 Textual Representation of Capability States

908
909
910
911
912
913

The purpose of this clause is to specify a single, portable format for representing acapability state. This textual representation is intended for use by the
cap_to_text() function and the getcap command to represent the state of an
existing capability state object, and by the cap_from_text() function and thesetcap command to translate a textual representation of a capability state into
its internal form.

914

Examples of valid textual capability state specifications include:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.25 Capability

329

915

No flags for any capabilities defined in the implementation are set:916

"all="

917

"="

918
919
920
921
922
923
924
925
926

"CAP_CHOWN=
CAP_DAC_OVERRIDE=...
<all remaining POSIX-defined capabilities><implementation-defined capability>=<implementation-defined capability>=...
<all remaining implementation-defined capabilities>
"

927
928
929
930
931
932
933
934
935
936
937
938
939
940
941

Only the permitted flags for CAP_KILL, CAP_CHOWN, and CAP_DAC_OVERRIDE
are set. The remaining flags for the remaining capabilities are all
cleared:"CAP_KILL,CAP_CHOWN,CAP_DAC_OVERRIDE=p""all=
CAP_KILL=p CAP_CHOWN=+p-ei
CAP_DAC_OVERRIDE=p"
The inheritable flag for every capability defined by the implementationis set except for the CAP_MAC_∗ capabilities. The effective flag is set
for the CAP_DAC_OVERRIDE capability:"all=i
CAP_MAC_READ,CAP_MAC_WRITE,CAP_MAC_DOWNGRADE,CAP_MAC_LOCKCAP_DAC_OVERRIDE+e"

942
943
944
945

In order to promote the portability of capability state information between implementations, one representation must be specified in this standard. We chose to
standardize the textual representation as this promotes not only application portability but user portability as well.

946
947

We considered an alternative representation that was flag `set´ oriented, i.e.,something that would look like:

948
949
950

i=CAP_KILL,CAP_MAC_WRITE
p=all
...

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

330

B Revisions to Rationale and Notes

951
952
953
954
955
956

however, this was rejected as implying a specific implementation (e.g., implementation of capability data objects as multiple set structures) and potentially being
less compact (a privilege having all flags set must be named separately for eachflag.) In addition, the requirement in such a representation to name a capability
multiple times greatly increases the chances for human error when attempting to
specify or interpret the representation.

957
958
959
960
961
962

In general, it is felt that this specification provides implementations with a wide
degree of flexibility in how they can represent capability states, while ensuringthat they can correctly interpret such states created on other interpretations witha minimum of difficulty and implementation complexity. The same state can be
represented in a compact manner or a lengthy manner, depending on the purpose
for which it is intended.

1

B.26 Mandatory Access Control

2

B.26.1 Goals

3
4
5
6
7

The primary goal of adding support for a Mandatory Access Control (MAC)
mechanism in the POSIX.1 specification is to provide interfaces to mandatory
security policies. A mandatory security policy is a system-enforced access control
policy that is outside the control of unprivileged users. Additional goals included
are to:8910(1) address mandatory access controls that support appropriate, widely
recognized criteria, while providing as much flexibility for
implementation-specific MAC policies as is practical;

1112(2) define MAC interfaces for portable, trusted applications and specify MAC
restrictions on all other POSIX.1 functions;13(3) preserve the provision for POSIX.1 conforming applications to impose

14
15
16

(4) preserve 100% compatibility to the base POSIX.1 functionality among
subjects and objects operating under ‘‘single label conditions’’, i.e., allsubjects and objects have an equivalent MAC label;

17
18
19

(5) add no new MAC-specific error messages to existing POSIX.1 and otherinterface standards, as doing so could interfere with the desire to avoid
new covert channels.

20
21
22
23
24
25
26
27

The mandatory access control (MAC) interfaces are intended to be compatible
with the mandatory access requirements of a number of criteria, particularly compatibility with the U.S. TCSEC levels B1-B3, the European ITSEC functionality
levels FB1/FB3, and the U.S. CMW requirements for MAC. It should be notedthat compatibility with these criteria extends only to the functionality defined inthem, and not to the assurances they may require. Additionally, the interfaces
were designed to conform with the requirements for adding ‘‘extended security
controls’’ to POSIX-conforming systems, as stated in POSIX.1, section 2.3.1.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.26 Mandatory Access Control

331

28
29
30
31
32
33
34

There is a recognition that the underlying mechanisms involved can be implemented in a number of different ways that still fulfill the POSIX_MAC requirements. Another consideration is the expectation that POSIX.1 conforming systems will wish to extend the functionality defined in this standard to meet particular, specialized needs. For these reasons, flexibility in the POSIX_MAC requirements while still conforming to the criteria mentioned above, is an important
objective.

35
36
37
38
39

By defining POSIX.1e interfaces for MAC, it is possible to develop trusted applications which are portable across POSIX_MAC-compliant implementations. Identifying MAC restrictions for other POSIX.1e functions ensures that application
developers are made aware of possible changes required for their applications tofunction in a POSIX_MAC-compliant environment.

40
41
42
43
44
45
46
47
48
49
50

MAC is intended to be complete, covering all means of information transmission.
Hence for many interfaces (such as stat()) MAC read access is required even
where ordinary ACL read access is not required in POSIX. This completenessshould even cover areas which are not ordinarily regarded as informationtransmission channels (that is, ‘‘covert channels.’’) A complete analysis of covert
channels available through the POSIX interfaces is beyond the scope of this document. Instead, only those cases which have policy implications are discussed
here, although we have attempted to avoid introduction of any covert channels in
the new interfaces defined by this standard. Hence additional controls needed onreading FIFOs are discussed, but means of controlling the covert channel provided by the process ID returned by fork() are not.

51
52
53
54
55

No new error codes for existing POSIX.1 interfaces are introduced to minimize theconfusion for existing applications. While this confusion cannot be entirely eliminated (in particular because existing error codes can now be returned in situations which would not arise without MAC), avoiding new error values at least
ensures existing applications will be able to report errors.

56

B.26.2 Scope

57
58

Section 26 defines and discusses the overall MAC policy and refinements of thisoverall restriction for the two major current policy areas: files and processes.

59
60
61
62

It should be noted that the policies in section 26 do not constitute a formal security policy model with proven assertions. It is, however, the minimal set of mandatory access restrictions that shall be defined, and serves as a basis for both thetrusted interface, and the implementation-defined security policy model.

63

B.26.2.1 Downgrade and Upgrade

64
65
66

The definitions of downgrade and upgrade are the technically precise ones. They
may not be intuitive because downgrade includes incomparable labels. For example, changing Secret:A to Top_Secret:B is a downgrade.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

332

B Revisions to Rationale and Notes

67

B.26.2.2 Concepts Not Included

68
69
70

Several concepts that will commonly be implemented by conforming systems havenot been treated by this document, many because they have no basis in the
POSIX standards upon which this document is currently based. These include:

71
72
73
74
75
76
77
78
79
80
81
82

Process Clearance: There were discussions that each process be given, in addition to its MAC label, a second label called its ‘‘clearance.’’
The clearance would serve as an upper bound on certain
MAC operations. For example, if the process could request
to raise the MAC label of an object, the clearance might
limit the label to which it could be raised. However, because
there have been no concrete proposals for the process clearance (which should include expected circumstances underwhich it would be used), and since clearance is normallyassociated with a user, and users are not included in thebase POSIX.1 standard, process clearance is not included in
the current MAC proposal.

83
84

Range Restrictions: These include various sorts of system-wide, per-file system, per-user, and device MAC range restrictions.

85
86
87
88

The label testing function, mac_valid() is intended to help
provide an interface to at least some of these restrictions ina more portable manner. For example, the restrictions may
not be a simple range but a more complicated restriction.

89
90
91
92
93

System High/Low: A potential function that was rejected was one to return thecurrent ‘‘system high’’ and ‘‘system low’’ labels. Some implementations may not have a simple high and low, but rather
a more complex (flexible) notion of ‘‘system high and low,’’
for example, a set of high/low ranges.

94
95
96
97
98
99
100
101
102

Devices:Access to devices through device special files is not treatedin this document. Often implementations may have special
device access rules based on device-specific considerations.
Two common examples of such special device access rules
are device ‘‘ranges’’ (sets of allowed MAC labels for accessing
certain devices), and ‘‘public,’’ generally-accessible devices,such as /dev/null and /dev/tty. Since such devicespecific considerations have no basis in POSIX.1, devices asa whole are not addressed in this document.

103

File Systems:

Mounted file systems are not included.

104
105
106

Trusted User Commands:
Commands for both administrators and trusted or partiallytrusted users have not been included.

107
108
109

Label Translation: POSIX.1 does not address networked systems. Thus, theissue of translating MAC labels into a portable form is notaddressed in this standard.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.26 Mandatory Access Control

333

110
111
112
113
114
115
116
117
118
119
120
121

Process Label Functions:
The functions provided as part of this standard to retrieve or
set the MAC label associated with a process are limited to
the requesting process. That is, no interface is provided
whereby a process may specify another process (for example,
using a process id) to be the target of the mac_set_proc() or
mac_get_proc() functions. Such mechanisms have been
omitted in order to be consistent with the POSIX.1 standard
which provides no facilities for processes to manipulate, orbe cognizant of, other processes’ state information. Note,however, that conforming implementations may choose toprovide such functions.

122

B.26.3 File Object Model

123
124
125
126
127

An important part of mandatory access control for files is the seemingly simple
assumption that the file attributes and data comprise a logically single data container to which the file MAC label is applied—the ‘‘file object.’’ Virtually all MAC
function restrictions arise from applying the following two basic policy rules
under this assumption:

128
129

(FP.1) The MAC label of a file must be dominated by the MAC label of a process for the process to read the data or attributes of a file, and

130
131
132

(FP.2) The MAC label of a file must dominate the MAC label of a process forthe process to write the data or attributes of a file. (Allowed restrictions on this rule are discussed following in Direct Write-up).

133
134
135
136

For example, linking to a file involves altering the link count of that file, andhence MAC write access to the file is required (as well as appropriate restrictions
on the directory in which the link is created). This is discussed below in the link()
example.

137
138
139

MAC restrictions for virtually all file-related functions can be straightforwardly
derived from these basic policy assumptions. (See the Policy section for a complete list.)140

Two examples:141

mkdir()

142
143
144
145

The mkdir() function is used to create a directory, D. Apart from actuallycreating the directory itself, a link name must be placed in the specified
parent directory, PD. Application of the FP.1 and FP.2 yields the MAC restrictions:

146
147

(1) The process shall have search access to PD. (Search access is an outgrowth of FP.1.)

148
149
150

(2) In order to add the link name, the process shall have MAC write accessto PD, i.e., the MAC label of the process shall be dominated by that of thedirectory (from FP.2).
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

334

B Revisions to Rationale and Notes

151
152

D is created with the MAC label of the process (FP.4), and hence it is correct
to leave the file open to the process.

153
154

Note that the calls creat(), mkfifo(), and open-for-create are other functions
that create files and will have these same MAC restrictions.

155

link()

156
157
158

The link() function is a little more complicated. A new link is to be created ina directory D to an existing file F. This involves writing the new link name to
F into D. Hence the following MAC rules are applied:

159(1) The process shall have search access to the directory D.

160
161

(2) The process shall also have search access to the file F, because the function is implicitly testing for the existence of F.

162
163

(3) The process shall have MAC write access to D, i.e., under FP.2 the MAC
label of the process shall be dominated by that of D.

164
165

In making a new link to F, the link count of F must be increased. Hence,the process is implicitly writing into F, and:

166

(4) The process shall have MAC write access to F, under FP.2.

167

B.26.4 Direct Write-up

168
169
170
171
172
173
174

Originally, FP.2 dictated that a process can only open files for writing whose label
equals that of the process (‘‘write-at-label’’), but that, a POSIX.1e conforming
implementation could allow write access under relaxed conditions, in particular,when the MAC label of the file properly dominates that of the process. Because
POSIX.1 mandates that additional conditions can only be more restrictive, thiswas changed to write-up, with write-equal allowed as part of a fully conforming
implementation.

175
176
177
178
179

The usefulness of allowing open-for-write of higher-label files (‘‘direct write-up’’)seemed too small given potential implementation difficulties. For this reason,
direct write-up was not required by the standard. However, direct write-up may
be a useful feature for the vendor willing to address its implementation problems,and for this reason, along with the reason cited above, the change was made.

180
181

Implementations which implement direct write-up will need to consider the
impact on return codes and potential covert channels.

182
183
184

Note that the creator of a portable application cannot assume such relaxations arepresent because they are not required by the standard. Write-at-label must
instead be assumed as the rule for MAC write.

185
186

In the following discussions, it is generally assumed that write-at-label is the
case.

187
188
189

The option of creating objects with MAC labels dominating that of the creatingprocess is allowed, but interfaces to do so are not provided. This facility would be
effected by the same set of concerns expressed with regard to direct write-up,
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.26 Mandatory Access Control

335

190
191
192

hence the more conservative approach. Furthermore, providing an interface forcreating an object with a MAC label begs the question of why we don’t provide amechanism for an ACL and a capability set.

193

B.26.5 Protection of Link Names

194
195
196
197

As discussed above, in POSIX.1 there really is no such thing as a ‘‘filename.’’ Thisis true both logically and physically, i.e., no name is stored in the file itself.
Instead there are only link names to files that are both logically and physicallydata items within the parent directory.

198
199
200
201

This proposal takes the most direct interpretation of the protection of link names
within a directory: the link names are simply considered data in the directory.
This means that the names are protected by the MAC label of the directory that
contains them, even when they indicate files or directories at other MAC labels.

202
203
204
205
206
207
208
209
210

A process could determine the link name and hence existence of objects at labels
not dominated by the process. However, this cannot be used as a covert channel
because the process that defined those names must have had write access to thecontaining directory, which means that its label equals (or, in some implementations, was dominated by) the label of the directory. More precisely, the covert
channel ‘‘sender’’ that creates the link name must be equal to (or, in some implementations, dominated by) the MAC label of the directory, and the ‘‘reader’’ must
dominate that label. Hence, because information is at most going to a higher
MAC label there is no covert channel.

211
212
213

Since link names may be protected at a lower MAC label than the file to which
they point, the user must be careful to choose a name that is adequately protected
at the MAC label of the parent directory.

214
215
216

This interpretation is both natural and common for UNIX file systems and underscores that link (‘‘file’’) names are not a property of the file, but rather of a parent
directory.

217
218
219
220
221

One of the suggested alternatives is the so-called ‘‘name-hiding’’ model where
each link in a directory is considered an object labeled at the label of the file towhich it links. This alternative was rejected because it is more complex, anddoesn’t offer any real improvement over the alternative that was accepted. Accessto the link names in a directory must therefore be controlled on a per-link basis.

222

B.26.6 Pathname Search Access

223
224
225
226
227
228
229

Files are commonly referenced by a pathname, for example A/B/F. If the pathname starts with the ‘‘/’’ character, then the pathname starts at the absolute rootof the file system. Otherwise it starts at the current working directory of the process. Even pathnames that contain only one name, e.g., F, are still pathnames.
Each such reference requires an implicit reading of a sequence of directories, andFP.1 must be applied to this process. This is called search access in this document.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

336

B Revisions to Rationale and Notes

230
231
232
233
234
235

A pathname consists of a sequence of link names ( A, B, and F in the previous
example) i.e., each name in the pathname is a link name contained in some directory. In other words, the name that most users commonly assume is ‘‘attached to’’a file is actually the name of a link in a directory, where the link only points tothe actual file. There may be many such links with different names to a single
file.

236
237
238
239

In locating a file on behalf of the process, the system is in effect opening thesequence of directories that contain the link names in the pathname, finding(reading) the next link name, and proceeding to the next file or directory namedby that link. The following basic constraint is required under FP.1:

240

MAC Search Access

241
242
243
244
245

In order for the system to perform this implicit reading of the directories in
the pathname, the process is required to have MAC read access to each directory that contains a link name of the pathname. Specifically, the MAC labelof the process must dominate that of the directory. (Note that ACL execute‘‘x’’ permission is also required, as in standard POSIX.)

246
247
248
249
250

For relative pathnames, the current working directory (‘‘.’’) is considered the first,
implicit directory in the pathname and is checked first. For absolute pathnames,
the absolute root directory is checked first, and, because it is customarily at thelowest MAC label on the system, search access will always proceed from absolute
root.

251
252
253
254
255

Note that the last element in the pathname is the final link name. Once this final
link name is read from the directory in which it resides, search access is considered complete. Hence, by definition the final target element ( F in the current
example) is not itself checked for any MAC access during search access, although
it will certainly be checked in the context of specific operations.

256
257
258

Basically, MAC search access determines whether a process can detect theexistence of a file, specifically, whether the process can read a directory containing
a link to the file.

259
260

As a general rule, MAC search access is applied to all pathnames presented in afunction. If this succeeds, then other MAC checks follow.

261

B.26.7 Check-Access-on-Open Only

262
263
264
265

The MAC policies follow the standing POSIX.1 metaphor that access to the data
portion of a file object is checked only when access is requested and not for eachdata read and write. Subsequently, access to the file is not revoked or changed inmode until the process willingly closes the file.

266
267
268
269
270

With this form of access, it is important that the MAC label of a file object not bealtered if the alteration would allow information flow to a subject which would
have not occurred at the new label. This requirement was originally stated in a
FP.5, but this was removed when it was pointed out that FP.5 is really just saying you can not violate FP.1 or FP.2.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.26 Mandatory Access Control

337

271
272

There are some conditions (which are rejected in this document) where the label
could technically be allowed to change:

273
274

— When the file references were write-only and the label was being raised. However, this seems a relatively rare case.

275— When the system supported some type of access revocation or recalculation.

276
277

— Allow changing the label only when the requesting process is currently referring to the file.

278
279
280

— If all processes currently referencing the file were appropriately privileged,then the label might be allowed to change. The danger here is that the privileged
processes may not be aware of the label change.

281
282
283
284
285

The application of FP.1 and FP.2 to the mac_set_file() and mac_set_fd() functions
takes the simple approach and make the handling implementation-defined as towhether changing of the file label when there are open connections to the file,(other than the calling process in the case of mac_set_fd() ), are disallowed, evenwhen the processes are privileged, or whether revocation is performed.

286

B.26.8 Creating Upgraded Directories

287
288

An upgraded directory is one whose MAC label properly dominates that of its
parent directory.

289
290
291

While in general the operation of FP.2 and FP.4 do not allow unprivileged
processes to create files or directories at other than the process MAC level, somemeans of creating multi-label file trees is necessary.

292
293
294
295
296

In particular, the ability to create upgraded directories gives a convenient meansfor organizing a multi-label file tree appropriately, and need not violate any fundamental security constraints. Hence it is appropriate to provide unprivileged
processes with some means of doing so; though it has been chosen not to do so as
part of this standard.

297

B.26.9 Objects without MAC labels

298
299

This standard specifies that each file will always have a MAC label associatedwith the file, but does not require each file to have its own unique MAC label.

300
301
302
303
304

Originally, the provided MAC functions allowed for returning [ENOSYS] if{_POSIX_MAC} was defined and the specified file did not have its own MAC label.
This was subsequently changed because of objections to the overloading of[ENOSYS] to return [ENOTSUP] for the cases where a file does not have its own
MAC label.

305
306
307
308
309

A pathconf() variable {_POSIX_MAC_PRESENT} is provided to allow applications
to determine if a file has its own MAC label. This standard does not specify the
specific situations where a file does not have its own MAC label. Examples of possible situations are: read only file systems; pre-existing file systems withinsufficient space to insert MAC labels; and certain devices such as /dev/null. The
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

338

B Revisions to Rationale and Notes

310
311
312
313

mac_get_file() and mac_get_fd() functions will always return a MAC label because
each file will always have a MAC label associated with the file. The mac_set_file()
and mac_set_fd() functions can return [ENOTSUP] if the specified file does nothave its own unique MAC label but shares the MAC label of a file system.

314

B.26.10 Error Return Values

315
316

The MAC functions specified in this standard may return one of several errors
depending on how the implementation has addressed MAC labeling.

317
318
319
320
321
322
323
324
325

If the symbol {_POSIX_MAC} is defined, then the implementation supports the +MAC option and is required to support the MAC functions as described in this +standard. If the symbol {_POSIX_MAC} is not defined, then the implementation +does not claim conformance to the MAC option and the results of an application +calling any of the MAC functions are not specified within this standard. An alter- +native is for the MAC functions to specify that the error return code [ENOSYS] be+returned by the functions if the MAC option is not supported. However, in order +to remain compliant with the policies of POSIX.1, this standard cannot specify +any requirements for implementations that do not support the option.

326
327
328
329
330
331
332
333
334
335

The error [ENOTSUP] shall be returned in those cases where the system supports
MAC but the particular operation cannot be applied because restrictions imposedby the implementation. For example, if an application attempts to set the MAC
label on a file on a system where sysconf() indicates that an MAC is supported by
the system, but the value that pathconf() returns for {_POSIX_MAC_PRESENT}
for that file indicates that individual MAC labels are not supported on that file,the application shall receive the [ENOTSUP] error. Therefore, if an application
attempts to set the MAC label on a file, it is the application’s responsibility to firstuse pathconf() to determine whether the implementation supports MAC labels onthat file.

336
337
338
339
340
341
342
343
344
345
346

It should be noted that, in general, this standard attempts to avoid adding anddefining new errors. However, in the case of [ENOTSUP], the following points
were noted: First, the need exists to provide feedback to applications concerninga new error condition. Second, while it is possible to use an existing error code insuch cases (for example, ENOSYS), the group felt that this would overload thoseerrors. P1003.1, when consulted, concurred with this view and agreed that thecreation of a new error code, in this case, was appropriate. Third, the error[ENOTSUP] is also being used by P1003.4 for roughly the same reasons. Therefore, the consensus of several POSIX working groups is that while adding newerrors is generally not recommended, that this case warrants the creation of a
new error and that the new error should be [ENOTSUP].

347
348
349
350
351
352

The [EINVAL] error is returned by functions when the MAC label specified in thefunction call is syntactically incorrect or the MAC label is not permitted on thesystem because implementation-defined restrictions, (e.g., range restrictions).
That is, this error is used to indicate the invalidity of the MAC label specified,
independent of whether the operation would have succeeded had it been a validlabel.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.26 Mandatory Access Control

339

353
354
355
356
357
358
359
360
361
362
363
364
365

Although POSIX.1 does not specify precedence for error return values, carefulconsideration should be given to this matter in the security standard to ensurethat covert channel considerations are adequately addressed. Specifically, if an
unprivileged application attempts a function for which privileges are required andthe implementation returns the EINVAL error in favor of the EPERM error, it
may be possible for the application to determine the system’s MAC label range
restrictions based on whether EINVAL is returned (indicating the label is outside
the system’s range), or EPERM is returned (indicating the label is valid for thesystem, but that the application failed the privilege check). Therefore, despite
this standard’s silence on the issue, it is recommended that when a function could
return multiple errors in a particular instance, that the errors be given the following precedence (from most favored to least favored): EPERM, EINVAL,
ENOTSUP.

366

B.26.11 Valid MAC Labels

367

MAC labels have two forms: internal and external.

368
369
370
371
372
373
374
375
376

The basic MAC label structure defined in this standard (mac_t) is a pointer to an
opaque data structure. The binary format of that opaque data structure may
include such data as a hierarchical classification and non-hierarchical categories.
The standard makes no assumptions regarding the underlying representation
other than imposing the following constraint: the structure must be an exportable object. That is, the structure is opaque, persistent, and self-contained. The
structure can therefore be copied by duplicating the bytes without knowledge of
its syntax. Such a copy can be changed without any effect on the original, and theoriginal can be changed without any effect on the copy.

377
378
379
380

The external format of a label is a text string of undetermined format. Any
separator character between fields in the textual representation is
implementation-defined. As noted in POSIX.1 section B.2.3.5, the character set
used for textual representation of MAC labels is not defined by this standard.

381
382

The meaning of a valid MAC label is implementation-defined, as described in
mac_valid(). A MAC label could be invalid for many reasons, such as:

383
384

A.

It is malformed, e.g., the label contains a checksum in the opaque typewhich does not agree with the checksum calculated from the data.

385
386
387

B.

It is out of the security level range of the system, e.g., the label refers to aclassification or category or combination which is outside the set of valid
MAC labels for the system.

388
389
390

C.

It is out of the security level range of a process, e.g., the label refers to aclassification or category or combination which is outside the set of valid
MAC labels for a process.

391
392
393

D.

It is outside the representation range, e.g., a system could allow no morethan n categories from a universe of m, even though each of the m categories
is valid.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

340

B Revisions to Rationale and Notes

394
395
396
397
398

Invalid MAC labels may appear for a number of reasons. Examples include: constructing a MAC label in process memory without regard to semantics of the bits,
importing a MAC label from a dissimilar system, reading a MAC label previously
stored in a file, etc. Note, however, that none of the MAC interfaces defined inthis standard will ever return an invalid MAC label.

399
400
401
402
403
404

The mac_valid() function is the means for an implementation to communicate toa portable application that the application should not ‘‘deal with’’ certain MAC
labels—that they are undefined, disallowed, or some implementation-restrictedstate. Note however that an implementation may impose additional restrictions
on the MAC labels for a particular object or process beyond the system-wide constraints that are addressed by mac_valid().

405

B.26.12 Modification of MAC labels

406
407
408
409
410

Unlike some of the other features in this standard, the basic unit of data for mandatory access control (the MAC label) is not usually manipulated. Interfaces anda memory management model to support manipulation of MAC labels weredeemed inappropriate, except for the least upper and greatest lower bounds functions discussed below.

411

B.26.13 Least upper bounds and greatest lower bounds

412
413
414
415
416
417

The function mac_glb() is useful for applications that wish to limit their activities
to those permitted by both labels. For example, if a user wants to know the maximum classification of data that the user can transmit via a network cleared for
MAC label labelA to a machine cleared for MAC label labelB. Likewise, themac_lub() function allows applications to determine a MAC label which dominates two specified labels.

418
419

It is the intent that conforming applications only use these functions, rather thanmore primitive manipulation of the label structures themselves.

420

B.26.14 Functions returning MAC labels

421
422
423
424
425
426
427
428
429
430
431
432

Functions which return MAC labels should use a common implementation specificallocation mechanism. For example, mac_get_file() allocates space for a MAC
label, fills in the MAC label from the requested file system object, and returns apointer to this space to the caller. The system allocates space because a MAC
label could be of variable length in some implementations. Such systems include
those which use a sparse matrix representation. If the system did not allocate thespace a portable application would have to query the system about the size of a
(subject’s or object’s) MAC label, reserve space for the label, and then call anotherfunction to obtain the MAC label. The overhead for systems with a fixed length
MAC label is excessive. The use of additional level of indirection in the presentinterfaces accommodates systems with both fixed and variable sized labels withreasonable efficiency.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.26 Mandatory Access Control

341

433
434
435

The use of an allocator implies the use of a deallocator. The function mac_free()frees the storage space allocated by any MAC function which allocated a MAC
label.

436
437
438
439
440
441
442
443
444
445

A function to allow for the translation of an internal label to an alternative external label format was considered and rejected. For example, it is anticipated thatsome trusted applications will wish to display a short form of the MAC label on adisplay terminal, perhaps as part of an icon, rather than the entire (possibly very
lengthy) external text form. An option considered was to alter the mac_to_text()
function to include a form argument. Trusted applications could specify the external form of the label desired, e.g., icon, abbreviated, long. The proposal was
rejected because the TCSEC, ITSEC, and CMW requirements criteria do not
specify alternative external formats. Thus, most implementations do not provide
for alternative text labels.

446

B.26.15 Multi-level directories

447
448
449
450
451
452
453
454
455
456

Interfaces to create, remove, and scan multi-level directories were considered andactually appeared in earlier drafts, but were removed because a lack of consensus
and ballot objections. The basic reason for a multi-level directory mechanism isthat certain portions of the filesystem namespace are ‘‘well known’’ and need to be
publicly available. The most obvious example is /tmp; many applications expect
to be able to create files within this directory. However, in a system with MAC,
allowing applications at any level to freely create visible files in /tmp would be an
unacceptable security hole; it allows a trivial means for a Trojan horse program tomake great quantities of data visible at lower levels (by encoding the data in filenames).

457
458
459

Data at a MAC label higher than that of the multi-level directory may be stored in
the multi-level directory by an unprivileged user. However, access to this data
will still be governed by the MAC policy.

460

B.26.15.1 Underlying Mechanism

461
462
463
464
465
466
467
468
469
470
471
472
473
474

To overcome this problem, while still allowing applications free access to wellknown directories, some means of hiding parts of the file system name space isneeded. The most direct method, what has been called a ‘‘true’’ multi-level directory, is to implement a new directory structure which allows entries to be truly
hidden. Here, for example, readdir() would only return entries at the requester’s
MAC level or lower. While conceptually nice, this is hard to implement properly.
For example, compatibility and prevention of a covert channel require lower levelprocesses (at least) to be able to create entries with the same names as preexisting ones created by higher-level processes. To avoid confusion, the appearance of these names then needs to be altered somehow (for example, by appending
a representation of the label) for reference by higher-level processes. To avoid
other channels, the apparent size of the directory may need to be altered toprevent visibility of creating and deleting files which might cause the size of thedirectory to change.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

342

B Revisions to Rationale and Notes

475
476
477
478

A simpler implementation uses the separation already provided by subdirectories
to achieve the goal. References to pathnames such as /tmp/foo are ‘‘redirected’’during pathname resolution to ‘‘hidden’’ subdirectories of /tmp, usually to something like479

/tmp/LabelRepresentation/foo

480
481
482
483

Here, LabelRepresentation tends to be a base 64 or hex representation of thebinary form of the label. These hidden subdirectories must of course be createdsomehow, presumably either beforehand by a trusted program or administrator,
or as needed by the system.

484

B.26.15.2 Getting Around The Hiding

485
486
487
488
489
490

Both mechanisms hide part of the file system namespace from applications.
There are times when this is not desirable, e.g. when backing up filesystems, orwhen a user simply wants to get at a lower level file. This is especially pressing
with the subdirectory approach, which conceals lower level files just as well as
higher level ones. Hence some means of generating a reference to an otherwise
invisible object is needed.

491
492

Again, two basic approaches have been taken. Either the reference is generated
directly by some special pathname:493/tmp/DON’T∗DO∗REDIRECTION!!/LabelRepresentation/foo

494
495

or it is generated indirectly by setting some process mode which allows using the‘‘real’’ filename496/tmp/LabelRepresentation/foo

497
498
499

The ‘‘modal’’ methods are less flexible in allowing redirected and real representations to be mixed, although some of this can be ameliorated by having multiple
modes such as

500
501
502
503

redirect none
redirect ‘‘system’’ directories (/tmp, /usr/tmp) only
redirect both system and application (/usr/spool/mail, etc.)
directories)

504
505
506

Their interaction with things like symbolic links involves difficulties as well.
(Allowing a symbolic link to a file in a hidden directory requires some means ofspecifying the mode in the symbolic link.)

507
508
509
510

The ‘‘non-modal’’ special pathname method has the disadvantage of reserving partof the file name space, something which unfortunately there is no precedent for inhistorical implementations. If the portion reserved, e.g., the pathname component

511

DON’T∗DO∗REDIRECTION!!

512
513
514

in the (fictitious) implementation above, were not standardized, a portable application would have to abide by every namespace restriction imposed by every
implementation.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.26 Mandatory Access Control

343

515
516
517
518
519
520
521

Finally, there are ways to address these issues without changing the way directories are processed at all. One such mechanism is the "variable symlink", inwhich a component of the user’s environment is use to replace a specified pathname component in the symlink. Thus, if the symlink /tmp contained"/orary/MACLABEL", a process with the environment variable MACLABEL set to"secret" would be directed to "/orary/secret". Other mechanisms, such as an exotic
file system type, are also possible.

522

B.26.16 The Directory Model

523
524
525
526
527
528

The relationships between the MAC label of a directory and its subdirectories andfiles is often referred to as the ‘‘directory model.’’ One of the more common models
for POSIX-like systems is for files to equal and for directories to dominate thelabel of their parent directories. This is sometimes called the ‘‘non-decreasing
directory’’ model because MAC labels at most increase as one transverses from theroot of a directory tree to its leaves. Multics, for example, used this model.

529
530

The following discussion applies only when untrusted processes are allowed tocreate upgraded directories under one of the schemes above.

531
532
533
534
535
536
537

This proposal does not absolutely impose the non-decreasing directory model.
Neither does it prevent conforming implementations from imposing a nondecreasing restriction. However, the application of the basic MAC restrictions on
the processes for accessing and creating the files as simple, labeled data containers leads to the restriction that unprivileged processes (users) can only create
non-decreasing directory trees. Privileged processes are not bound by these restrictions and can create files and directories at arbitrary MAC labels.

538
539

Implicit in the preceding discussion on upgraded directories is the assumptionthat trees created by unprivileged processes will be non-decreasing.

540
541
542
543
544
545
546

The non-decreasing nature of file trees combined with the minor user difficulties
of creating upgraded directories (changing login sessions) will tend to group directories according to MAC label. That is, instead of highly intermixed files anddirectories at various MAC labels, they will tend to be segregated according to
MAC label. This is generally a good practice anyway, because the close intermingling of file system elements at different labels tends to be a breeding ground forcovert channels and confusion.

547
548
549

Basically, this proposal takes the position that non-decreasing hierarchies areappropriate for unprivileged processes, but that POSIX.1e should not so restrict
appropriately privileged processes.

550

B.26.17 File Tranquillity

551
552
553

The original FP.5 dealt with file object tranquillity. (Note, this rule was removed
as an explicit rule when it was pointed out that it is just a restatement of FP.1
and FP.2.)

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

344

B Revisions to Rationale and Notes

c

554
555
556

FP.5: The MAC label of an object cannot be changed to a new MAC label if thechange would allow information flow between a process and an open fileobject which could not have occurred at the new MAC label.

557
558

There are two general ways that a conforming implementation could enforce thefile change-level constraint:

559

Tranquillity

560
561
562

The change request could be denied if there were any open connections to thefile (other than the requesting process in the case of the mac_set_fd() function).

563

Readjustment

564
565
566
567
568

The change request could be fulfilled if it could be determined that all open
connections could have been made in the mode requested after the label waschanged. The implementation could either preemptively close the newlydisallowed connections, or attempt to readjust the current access modes of theopen connections.

569
570
571
572
573

Readjustment can be difficult to implement and is not required by the standard,
but is also not precluded by the standard. Since readjustment is not required,this leaves strict tranquillity as the lowest common denominator of conforming
implementations. For this reason, portable applications must assume no morethan strict tranquillity for maximum portability under the standard.

574

B.26.18 Process Tranquillity

575
576
577

Requirements for ‘‘process tranquillity’’ do not exist because any process
privileged to change its own label is presumed to ensure it does not subsequently
cause undesired information flows.

578

B.26.19 Unnamed Pipes

579
580
581
582
583

Unnamed pipes are considered labeled objects. However, because they are notaddressable, i.e., cannot be opened, and because MAC is enforced only when
objects are opened for access, there are never any actual MAC checks against thelabel of the pipe. The label will however need to be retrieved in the mac_get_fd()
function.

584
585
586

The primary rationale for labeling unnamed pipes is so that processes using
mac_get_fd() (who may not know whether the file descriptor is a pipe) will not see
anomalous behavior for pipes.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.26 Mandatory Access Control

345

587

B.26.20 FIFOs

588
589
590
591
592
593
594

First-in-first-out (FIFO) data objects have an inherent covert channel in thathigher-label readers can affect the state of the object in a manner that can bedetected by other (lower-label) readers/writers. For example, a reader/writer at
L1 can write sequences to the FIFO and then determine how much data has beenread by a reader at L2 by reading the FIFO (where L2 is not dominated by L1 ).
This constitutes information flow in that is contrary to the basic MAC policy
FP.3.

595
596

FIFOs in POSIX.1 include only FIFO-special files. In order to control the covert
channels for these FIFO-special files, the following rule is imposed:

597
598
599

Unprivileged processes may open FIFO-special files for reading only if theprocess also has MAC write access to the FIFO, i.e., the process is at thesame MAC label as the FIFO-special file.

600
601
602

Hence, unprivileged processes at different MAC labels may not obtain a FIFO
between them even if opened such that information may only flow in accordancewith P.

603

B.26.21 Inclusion of mac_set_fd()

604
605
606

Originally, this function was not included. It was felt that there was too little
demonstrated need for the function against potential implementation difficulties.
The only mentioned use was by login.

607
608
609
610
611
612

One notable implementation difficulty is that it is difficult to find the parent
directory (or directories) of a file given only a file descriptor. This makes it
difficult for implementations that wish to absolutely enforce the relationshipbetween a file and its parent directory. (Note that the issue of unique parent
directory is side-stepped when a pathname is given in that the directory given in
the pathname is the one to which various mandatory access controls are applied.)

613
614

However, in the interest of consistency with the other POSIX.1e options, it was
decided to include the mac_set_fd() function.

615

B.26.22 Inclusion of mac_size()

616
617
618
619
620
621
622

The mac_size() function has been provided to allow applications to obtain the sizeof a MAC label. Applications need to know the size of MAC labels only if they aregoing to store the MAC label. There is no reason to know the size to use the provided MAC functions. An example of using the mac_size() function is a data basesystem which needs to store a MAC label for each record. It would use themac_size() function to find out the size of the space to allocate and then could byte
copy the MAC label to the data base record.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

346

B Revisions to Rationale and Notes

623

B.26.23 Restrictions on Signals

624

The following, minimal MAC restriction governs the sending of signals:

625
626
627
628

An unprivileged process cannot send signals to another unprivileged process
when the signals would result in actions other than an upgrading of information, i.e., the signal is only allowed when the label of the receiver dominatesthat of the sender.

629
630
631

The general philosophy is to prohibit only those signals that can be repeatedly
sent thus causing high-bandwidth covert channels. This affects mainly the kill()function.

632
633

No additional restrictions are imposed between two processes at the same label orwhen at least one of the processes is privileged.

634

B.26.24 Alteration of atime

635
636
637
638
639
640

Many functions require that the file atime be marked for update. However, thecase where the actions of a process could affect the atime of a file whose label does
not dominate that of the process presents a potential covert channel. Some implementations can adjust when the atime is actually set and thus adequately confine
such covert channels, but this is not required by the standard. Instead, the effecton atime in such cases is implementation-defined.

641

B.26.25 Multi-Label Untrusted Process Hierarchies

642
643
644
645
646
647

There are situations where untrusted processes at different MAC labels can havean ancestral relationship. Processes with an ancestral relationship have special
opportunities for communicating information, e.g., wait, waitpid of POSIX.1 section 3.2.1, and when both processes are untrusted and at different MAC labelsthese opportunities present potential covert channels. There are no MAC restrictions for at least some of the following reasons:

648
649
650
651

— These situations can only be set up by trusted processes who change their MAC
label. It is assumed that a trusted process who changes its label and creates (byfork() or exec()) untrusted processes will take actions to confine potential covert
channels.

652— The channels are typically low-bandwidth.

653
654

— Restricting all such operations seems like too much imposition for too little
gain.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.26 Mandatory Access Control

347

655

B.26.26 File Status Queries

656
657
658
659

Following the precedence of IEEE Std 1003.1-1990, no DAC access is required todetermine the various status attributes of a file (DAC information, labels, owner,etc.) including all new attributes, such as the MAC label. However, MAC readaccess is required to prevent potential covert channels.

1

B.27 Information Labeling2

B.27.1 Goals

3
4
5
6
7
8

The primary goal of adding support for an information labeling mechanism in the
POSIX.1 specification is to provide interfaces to non-access control related datalabeling policies. An information labeling policy, unlike access control related policies (such as mandatory or discretionary access control), provides a means for
associating security-relevant information with the data maintained by the system. More specifically, the information labeling mechanism’s goals are to:

9
10
11
12
13
14
15
16
17
18
19

(1) Address the need for non-access control related mechanisms to implement data labeling policies as specified in existing standards and criteria
while providing as much flexibility for implementation-specific information labeling policies as is practical. Specifically, to allow for the variances between existing standards, the interfaces are intended to provide
the latitude for implementations to support multiple information label
uses. For example: to allow information labels to be applied to subjects
and objects by the system, and altered by the system, to record the flow ofdata between subjects and objects, or to allow information labels to be
applied to objects by users, and altered by them on a discretionary basis,to record handling restrictions on the object contents.

20
21
22
23
24
25
26
27
28

(2) The information label interfaces are intended to be compatible with theinformation label requirements of a number of standards and criteria. In
particular, goals include compatibility with the U.S. Compartmented
Mode Workstation Information Label requirements, and the European
vendor and customer demands, along with DIA document DDS-26005502-87 and DIA document DDS-2600-6243-91. Finally, the interfaces
were designed to conform with the requirements for adding ‘‘extended
security controls’’ to POSIX-conforming systems, as stated in section
2.3.1 of POSIX.1.

29
30
31
32
33
34
35

There is a recognition that the underlying mechanisms involved can be
implemented in a number of different ways that still fulfill the
POSIX_INF requirements. Another consideration is the expectation that
POSIX.1 conforming systems will wish to extend the functionality
defined in this standard to meet particular, specialized needs. For thesereasons, flexibility in the POSIX_INF requirements while still conforming to the criteria mentioned above, is an important objective.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

348

B Revisions to Rationale and Notes

36
37
38

(3) Define information labeling interfaces for conforming applications. By sodoing, it becomes possible to develop trusted applications which are portable across POSIX_INF-compliant implementations.

39
40
41
42
43

(4) Specify information labeling enhancements on other POSIX.1 functions
as necessary. Identifying information labeling modifications to other
POSIX.1 functions ensures that application developers are made awareof possible changes required for their applications to function in a
POSIX_INF-compliant environment.

44
45
46
47
48
49
50

(5) Address information labeling-related aspects of all forms of data accessand transmission visible through the POSIX.1 interfaces. (Please notethe distinction made between data and control information, clarified laterin this section.) The interface, however, is designed for flexibility: thestandard defines the minimum functionality that must be provided.
Naturally, conforming implementations may choose to perform information labeling on objects, or at times, not required by this standard.

51
52
53
54

(6) Preserve 100% compatibility with the base POSIX.1 functionality. Thatis, it is undesirable to require new restrictions on the operation of existing POSIX.1 interfaces, or to require changes to the syntax of existing
POSIX interfaces.

55
56
57
58
59
60
61

(7) Add no new information labeling-specific error messages to existing
POSIX.1 interfaces and thus minimize the potential for confusing existing applications. While this potential for confusion cannot be entirely
eliminated (in particular because existing error codes can now be
returned in situations which would not arise without information labeling present), avoiding new error values at least ensures existing applications will be able to report errors.

62

B.27.2 Scope

63
64
65
66

This section examines the information labeling interfaces provided by this standard and explains the overall motivation for including the information labelinginterfaces. Rationale and design tradeoffs are presented for the key information
label interfaces.

67
68
69
70
71
72
73
74
75
76
77
78

This standard supports a security policy of nondisclosure, primarily through theinterfaces defined for discretionary and mandatory access control. In particular,
mandatory access control mechanisms implemented using the defined interfaces
are expected to conform with the overall intent established in the security standards to which they are targeted. These security standards, (e.g., the TCSEC),
normally require policies and mechanisms that protect objects at the level of themost sensitive data that they can contain. Often, however, the data contained in
objects is actually much less sensitive than indicated by the mandatory access
control label associated with that object. In addition, many security policies
require that certain non-mandatory access control related information be associated with subjects and objects. Thus, in addition to mandatory access control
labeling, this standard provides optional interfaces for data labeling. Use of these
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.27 Information Labeling

349

79
80

interfaces by conforming implementations permit support for a variety of datalabeling policies.

81

B.27.3 Concepts Not Included

82
83
84

Several concepts that will commonly be implemented by conforming systems havenot been treated by this document, many because they have no basis in the
POSIX standards upon which this document is currently based. These include:

85
86
87

Label Translation: POSIX.1 does not address networked systems. Thus, thetranslation of information labels into an exportable form is
not addressed in this standard.

88
89
90
91
92
93
94
95
96
97
98

Process Label Functions: The functions provided as part of this standard to
retrieve or set the information label associated with a process are limited to the requesting process. That is, no interface is provided whereby a process may specify another process (for example, using a process id) to be the target of the
inf_get_proc() or inf_set_proc() functions. Such mechanisms
have been omitted in order to be consistent with the
POSIX.1 standard which provides no facilities for processes
to manipulate, or be cognizant of, other processes’ state
information. Note, however, that conforming implementations may choose to provide such functions.

99

B.27.4 Data Labeling Policies

100
101
102
103
104
105
106
107
108

There are many instances when security-related information should be associatedwith subjects and objects even though that information may not, in general, be
used for mandatory access control. Such information may include markings thatindicate the source of some data, what the data is about, the ‘‘trustworthiness’’ ofthe data, or anything else about the data other than how it should be protected.
This non-mandatory access control related information is represented in an information label that should be associated with data when it is printed or otherwise
exported. This specification provides functions to assign initial information
labels, combine two information labels, and manipulate information labels.

109
110
111
112
113
114
115
116

A sample non-mandatory access control data labeling policy might be one targetedat virus detection. For example, under this policy, programs downloaded from apublic bulletin board might be labeled with the marking ‘‘suspect-file.’’ If the program contained a virus, and if the inf_float() function (discussed below) implemented the Compartmented Mode Workstation (also discussed below) style offloating labels, then it would be easy to track the spread of any infection
throughout the system because every file infected by the virus would automatically be stamped with the ‘‘suspect-file’’ marking.

117
118
119

Other examples of non-mandatory access control information that should be associated with data include handling caveats, warning notices, discretionary access
control advisories, and release markings. The ability to implement standardsWITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

350

B Revisions to Rationale and Notes

120
121

based systems that support these and other non-mandatory access control markings is of great interest to many vendors and users.

122
123
124
125
126

One example of existing non-mandatory access control policies this interface isintended to support are those proposed by the European trusted system vendor
community. The functionality necessary is that users must be allowed to apply
data labels to subjects and objects, and alter them on a discretionary basis, inorder to record handling restrictions on the objects’ contents.

127
128
129
130
131

To provide a data labeling interface that can easily support the existing multiple
data labeling policies, the information label interfaces have been carefully generalized to provide a mechanism to support these policies, without attempting toenforce the specifics of any particular policy. The burden of implementing specificpolicies is left to conforming implementations.

132

B.27.4.1 General Information Label Policy

133
134
135

Section 27.1.2 of this standard defines a general information labeling policy capable of supporting multiple particular data labeling policies. The information label
policy statement consists of:

136(1) A broad policy statement

137
138

(2) Refinements of this policy for the two major current policy areas: files
and processes.

139
140
141
142

It should be noted that the policies in this section do not constitute a formal security policy model with proven assertions. It is, however, the most fundamental setof information label policies that should be defined. The general information label
policy is as follows.

143
144
145

Information Label Policy: Each subject (process) and each object that contains data (as opposed to control information) shall have as an attribute an
information label at all times.

146
147
148

Information labels are said to ‘‘float’’ as data from one object is introduced toanother object. The general information label floating policy is intentionally flexible and can be stated as follows:

149
150
151

Information Label Floating Policy: The implementation-defined policy that
determines to what degree information labels associated with data areautomatically adjusted as data flows through the system.

152
153
154
155

The information label float policy is embodied by the inf_float() function. Thisfunction computes a new information label that is the combination of two information labels passed as arguments. As noted above, the new information label iscalculated according to implementation-defined policies.

156
157
158
159

Note that the information label policy as applied to process functions specifies (inPI.2) that when a process with an information label inf_p1 executes a file withinformation label inf_p2, the information label of the process shall be set to thevalue returned by inf_float(inf_p1, inf_p2). However, in implementations where
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.27 Information Labeling

351

160
161
162
163
164
165
166

the new file executed completely overlays the process’ address space, i.e., there isno data transfer from the originally executing process to the newly executing process, the information label of the process after executing the file may be set toinf_p2. The central factor in determining whether such an implementation conforms to the information label policy is whether data is transferred: the transfer
of control information (such as process id, and various user ids) is inevitable andpermissible; the transfer of data is unacceptable.

167

B.27.4.2 Error Return Values

168
169
170

The information labeling functions specified in this standard may return one ofseveral errors depending on how the implementation has addressed information
labeling.

171
172
173
174
175
176
177
178
179
180

If the symbol {_POSIX_INF} is defined, then the implementation supports the +information label option and is required to support the information label functions+as described in this standard. If the symbol {_POSIX_INF} is not defined, then the+implementation does not claim conformance to the information label option and +the results of an application calling any of the information label functions are not +specified within this standard. An alternative is for the information label func- +tions to specify that the error return code [ENOSYS] be returned by the functions +if the information label option is not supported. However, in order to remain com- +pliant with the policies of POSIX.1, this standard cannot specify any require- +ments for implementations that do not support the option.

181
182
183
184
185
186
187
188
189
190
191

The error [ENOTSUP] shall be returned in those cases where the system supports
the information label facility but the particular information label operation cannot be applied because restrictions imposed by the implementation. For example,
if an application attempts to set the information label on a file on a system wheresysconf() indicates that an information label facility is supported by the system,
but the value that pathconf() returns for {_POSIX_INF_PRESENT} for that file
indicates that information labels are not supported on that file, the application
shall receive the [ENOTSUP] error. Therefore, if an application attempts to set
the information label on a file, it is the application’s responsibility to first use
pathconf() to determine whether the implementation supports information labelson that file.

192
193
194
195
196
197
198
199
200
201
202

It should be noted that, in general, this standard attempts to avoid adding anddefining new errors. However, in the case of [ENOTSUP], the following points
were noted: First, the need exists to provide feedback to applications concerninga new error condition. Second, while it is possible to use an existing error code insuch cases (for example, ENOSYS), the group felt that this would overload thoseerrors. P1003.1, when consulted, concurred with this view and agreed that thecreation of a new error code, in this case, was appropriate. Third, the error[ENOTSUP] is also being used by P1003.4 for roughly the same reasons. Therefore, the consensus of several POSIX working groups is that while adding newerrors is generally not recommended, that this case warrants the creation of a
new error and that the new error should be [ENOTSUP].

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

352

B Revisions to Rationale and Notes

203
204
205
206
207
208

The [EINVAL] error is returned by functions when the information label specified
in the function call is syntactically incorrect or the information label is not permitted on the system because implementation-defined restrictions, (e.g., range
restrictions). That is, this error is used to indicate the invalidity of the information label specified, independent of whether the operation would have succeeded
had it been a valid label.

209
210
211
212
213
214
215
216
217
218
219
220
221
222
223

Although POSIX.1 does not specify precedence for error return values, carefulconsideration should be given to this matter in the security standard to ensurethat covert channel considerations are adequately addressed. While information
labeling is not usually subject to covert channels, in certain cases they may arise.
Specifically, if an application that does not possess appropriate privilege attempts
a function for which appropriate privilege is required and the implementation
returns the EINVAL error in favor of the EPERM error, it may be possible for theapplication to determine the system’s information label range restrictions basedon whether EINVAL is returned (indicating the label is outside the system’s
range), or EPERM is returned (indicating the label is valid for the system, butthat the application did not possess appropriate privilege). Therefore, despite thisstandard’s silence on the issue, it is recommended that when a function could
return multiple errors in a particular instance, that the errors be given the following precedence (from most favored to least favored): ENOSYS, EPERM, EINVAL,
ENOTSUP.

224

B.27.4.3 Rationale for Pointer Arguments

225
226
227
228
229
230
231
232
233
234
235
236
237

The functions provided to support information labeling use an opaque data type.
Nevertheless, in order to accommodate systems in which the size of an information label may vary (e.g., depending on the actual label encoded or depending on
the total set of labels supported), the information label functions operate on
pointers. For this reason, the basic information label structure defined in thisstandard (inf_t) is defined to be a pointer to an opaque data structure. In thisway, conforming applications need not determine the size of a label prior torequesting an operation that will produce or modify that label. (In some cases,
such as inf_float(), this would be particularly difficult inasmuch as the resultant
information label is not known prior to making the request.) Instead, the system
functions themselves are responsible for allocating the space necessary to containa new label, and a function is provided to applications to free that space when thelabel is no longer needed.

238
239
240
241
242
243
244

The tradeoffs between the approach adopted by the information label functions
specified in this standard and alternative approaches are many and varied. The
structure of the information label function interfaces have been designed to beconsistent with those provided by the interfaces supplied in support of the otherfeatures included in this standard, and the mandatory access control interfaces inparticular. Thus, a more detailed and complete rationale for the adoption of thesetypes of interfaces can be found in the mandatory access control rationale.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.27 Information Labeling

353

245

B.27.4.4 Rationale for POSIX.1e Functions

246
247
248
249
250
251

The inf_float() function is not specified in detail to allow for a range of
implementation-defined floating policies. The range of policies would determine
the degree to which information labels associated with data are automaticallyadjusted as data flows through the system. Two explicit floating policies thathave been articulated are intended to be supportable in POSIX through thedefinition of inf_float().

252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267

The first policy is that articulated as part of the Compartmented Mode Workstation project (see IEEE Transactions on Software Engineering, Vol. 16, No. 6, June
1990, pp 608-618). Under this policy, every data read or write is intended to(potentially) modify the information label of the object being modified through theread or write. In the case of a subject reading an object, the subject’s information
label would be modified (‘‘floated’’) to a combination of the information label of thesubject before the read, and the information label associated with the object.
When a subject writes to an object, the object’s information label would be floatedto represent the combination of the information label of the object before thewrite, and the information label associated with the subject. This policy makes agreat deal of sense in the case where there are a large number of different information label values, and it is desired to track the flow of data through the systemby having the data’s information label follow the data. To accommodate this policy, inf_float() would always combine its two arguments and return the result.
The details of the combination would depend on the semantics of the particular
information labels involved.

268
269
270
271
272
273
274
275

The second policy makes more sense when there are a relatively small, morestatic number of information label values. In this policy, the intention is that
objects, when created, inherit their creator’s information label, but that the information label does not automatically change thereafter. To accommodate this policy, inf_float() would be defined such that it floated an information label only one
time. In other words, inf_float() would return a result other than its second argument only when its second argument is equal to inf_default() and its first argument is not inf_default().

276

B.27.4.5 System Floating

277
278
279
280
281
282
283
284
285
286
287

Because the inf_float() routine takes two labels and returns the result of a float
operation, it is not an entirely general function. That is, it cannot base the resultof the float operation on any factor other than the two input labels. However, it ispossible to imagine other data labeling policies that require different floating
rules based on any number of factors (e.g., files involved, or time of day). Support
for these peculiar types of policies is not explicitly required in this standard. The
main reason for this exclusion is that, of the multiple data labeling polices
intended to be supported by this standard, none require such extensions to the
inf_float() function. Indeed, to the group’s knowledge, no known data labelingpolicy currently used in commercially available systems that would require suchextensions presently exists.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

354

B Revisions to Rationale and Notes

288
289
290
291
292
293
294
295
296
297
298
299
300
301

The second major reason for the lack of true generality in the floating function
was due to technical obstacles. To make the inf_float() function more general,
additional arguments would be required. The addition of more information used
to characterize the two labels involved in floating was discussed. Particular consideration was given to adding type information so that the type of the object withwhich the information label is associated could be determined. This was to allow
the implementation-defined algorithm to act differently based on the types of theobjects involved. This addition was rejected because the working group could see
no use for it in an external (application level) interface for conforming applications. The group also considered including arguments to identify the specificobject being floated. Again, due to lack of motivation, and an inability to devise a
useful interface that could be used to identify all POSIX objects that could support ILs, and still be extensible to non-POSIX objects (in a curt acknowledgementof the needs of the real world), this option, too, was dropped.

302
303
304
305
306

Note that the inf_float() function nevertheless remains a valuable and necessaryinterface: it allows conforming applications to call a routine which the systemprovides that is guaranteed to provide a label float operation consistent with thesystem’s data labeling policies. Using the function, trusted applications can perform fine-grained labeling of their own resources.

307

B.27.4.6 Object Labeling

308
309
310
311
312
313
314
315
316
317
318
319

The objects to which this standard requires information labels be applied include
the expected POSIX.1 objects: files. Not included among the objects areprocesses. As observed in the mandatory access control section, processes may act
as objects under certain conditions. For example, when one process sends a signal
to another, the former is effectively writing to the latter, and therefore the latter
could be considered an object, from the perspective of this function. However,
because many data labeling policies consider signals of this type to be a transmission of control information, and therefore not necessarily subject to the information label policies, many data labeling policies do not consider the process to be an
object (from the information label perspective) with respect to these functions.
Because POSIX.1 does not provide any other functions in which processes act asobjects, the information labeling standard does not include processes as objects.

320
321
322
323
324
325
326

Note that information labels are not required to be applied to directories. Arguments for why they should be are as follows. Directories, like any other type of
file, contain arbitrary length strings of process-specified data. This data is, byintent, designed to be communicative to users; that is, it is meaningful information (from the human perspective). Since this is the type of information datalabeling policies are intended to label, it would make sense to require that directories be subject to the information label policies.

327
328
329
330
331
332

Alternatively, opposing opinions have been expressed that information labels
should not be required to be applied to directories. These arguments are as follows. Directories are not containers of data, but rather are organizers of data containers (such as regular files). As such, the notion that information labels areapplied to ‘‘data’’ as opposed to ‘‘control information’’ suggests that information
labels may not necessarily be needed on directories. In addition, as with
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.27 Information Labeling

355

333
334
335
336
337
338
339

mandatory access control, existing mechanisms and techniques for applying information labels to directories vary widely (directory labeling, directory entry labeling, etc.). Worse yet, directory information labeling must necessarily be closely
tied to the multi-level directory implementations used for mandatory access control. As witnessed by the absence of a multi-level directory specification in the
mandatory access control section, directory labeling is not an area amenable tostandardization at this time.

340
341
342

For the reasons set forth above, information labeling on directories is not requiredby this standard. Note, however, that conforming implementations may certainly
provide that capability.

343

B.27.5 Initial Information Labels

344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359

This standard provides an interface that returns a valid information label that, if
applied to a newly created file, will adequately label that file in a manner consistent with the system’s information labeling policy. One intended use of thisfunction is by trusted applications that wish to create, maintain, and properly
label objects other than system-labeled objects. Examples of process-maintained
independently-labeled objects could include: database records, individual mailmessages, and so forth. When a process creates an instance of such an object, inorder to perform floating as data is written to the object, the object must startwith a correct initial information label. However, because these objects residepurely within the process space of the application, or are subcomponents of alarger single system-labeled object, the trusted application must assume responsibility for maintaining the labels on the object, including the initial label. For
trusted applications, this initial label may well differ from the process label (especially if the process had floated prior to creating the object). For this reason the
inf_default() function is provided. (In systems targeted for the CMW requirements, this label is often referred to as ‘‘system-low’’.)

360
361
362
363
364
365
366
367
368
369
370
371
372

The inf_default() function has deliberately been specified in very general terms inorder to allow the widest range of implementations to conform to the standard. In
particular, the function does not require that each call return the same value; theinitial label may vary based on implementation-defined factors (for example, timeof day, process id of the calling process, etc.). In addition, it is not guaranteedthat the label returned by inf_default() will be the same as other systemgenerated labels at the same time. For example, a process that performs a call to
inf_default() and immediately creates a new file may well find that the information label applied to the file differs from the information label returned by the callto inf_default(). This fact promotes flexibility in meeting this standard withouthindering application portability: that the labels returned by inf_default() areconsistent with the system’s information labeling policy when applied to newlycreated objects is sufficient for conforming applications to function properly.

373
374
375
376

Uses to which this flexibility may be put include: systems on which files createdat particular times during the day may be more sensitive than files created atother times, systems on which files on particular file systems are labeled differently from those on other file systems, and so forth.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

356

B Revisions to Rationale and Notes

377
378
379
380
381
382
383
384
385

The addition of more information used to characterize the object to receive an initial information label was discussed. Particular consideration was given toadding type information so that the type of the object with which the initial information label is to be associated could be determined. This was to allow the
implementation-defined algorithm to act differently based on the type of object tobe labeled. This addition was rejected because the working group could see nouse for it in an external (user level) interface for conforming applications. Internal (system-specific) initial information labels are not required to use
inf_default() and therefore can be different based on the object being labeled.

386

B.27.6 Information Label Validity

387

Information labels have two forms: internal and external.

388
389
390
391
392
393
394
395
396
397

The basic information label structure defined in this standard (inf_t) is a pointerto an opaque data structure. The binary format of that opaque data structure
may include such data as a hierarchical classification, non-hierarchical categories,
or non-access control related markings. The standard makes no assumptions
regarding the underlying representation or contents of the structure other than
imposing the following constraint: the structure must be an exportable object.
That is, the structure is opaque, persistent, and self-contained. The structure cantherefore be copied by duplicating the bytes without knowledge of its syntax.
Such a copy can be changed without any effect on the original, and the originalcan be changed without any effect on the copy.

398
399
400
401
402

The external format of a label is a text string of unspecified format. Any separator characters appearing between the components of an information label are
implementation-defined. Note that this standard does not specify the set of legal
characters that may be used in the text representation of an information label.
Further rationale for this decision can be found in POSIX.1, section B.2.3.5.

403
404
405

The meaning of a valid information label is implementation-defined, as describedin inf_valid(). An information label could be invalid for a variety of reasons.
Some reasons why a label may be invalid on some systems include:

406
407

It is malformed (e.g., the label contains a checksum in the opaque typethat does not agree with the checksum calculated from the data).

408
409

It is out of the cleared range of the system (e.g., the label refers to aclassification that is outside the set of valid classifications for the system).

410
411
412

It is outside the representation range (e.g., a system could allow no morethan n categories from a universe of m, even though each of the mcategories is valid).

413
414
415
416

If {_POSIX_MAC} is defined, and the mandatory access control label of aprocess does not dominate the mandatory access control label associatedwith all components of an information label, then that information label
may be invalid for the process, even though it is valid for other processes
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.27 Information Labeling

357

417

executing on the same system.

418
419
420
421
422
423
424
425
426

Invalid information labels may appear for a great number of reasons. Examples
include: constructing an information label in process memory without regard tosemantics of the bits, importing an information label from a dissimilar system,
etc. Note, however, that combining two information labels (e.g., using inf_float()),
will calculate an information label that is valid. This is because information
labeling, as noted elsewhere in this section, is used for data labeling, not access
control. Therefore, if the other security policies implemented in a conforming system permit data to be combined, the information labeling mechanism is obligatedto calculate an accurate and valid information label for the combined data.

427

B.27.7 Control Information

428
429
430
431
432
433
434
435
436
437
438
439
440
441
442

The policy discussion contained in section 27.1.2 specifically notes that the information label of a file applies only to the data portion of the file. That is, manipulation of control information need not result in an information label float operation. This ‘‘special’’ treatment for control information results from a tradeoff
between functionality and security. If information labels floated when control
information was manipulated (e.g., at file open time, instead of at data transfertime), the information labels associated with subjects and objects would have atendency to float too often and would lose some of their utility as a mechanism totrack the flow of data throughout a system. It can be argued that floating whencontrol information is manipulated would result in more ‘‘trustworthy’’ information labels, however, several groups have expressed interest in favoring functionality over security in this case. It is understood that a conforming implementation may cause the float operation to occur at times in addition to those coveredby the specified information labeling policy; such implementations may chooseenhanced trustworthiness over security.

443

B.27.8 Relationship between ILs and Mandatory Access Control Labels

444
445
446
447
448
449
450
451
452
453
454
455

In some systems, such as compartmented mode workstations, there exist certain
invariants that hold between ILs and mandatory access control labels. In thecase of CMWs, this invariant states that for any specific subject’s or object’s
labels, the access related portion of the information label (e.g., the classificationand categories) must be dominated by the mandatory access control label. While
this notion is useful for CMWs, it is not generally applicable to all systems thatmight support the information label interfaces specified in this document. Most
notably, some companies that support the fundamental concept of information
labels, employ them in a manner such that mandating a relationship between
mandatory access control labels and ILs has no meaning. Indeed, there is norequirement in this standard that the mandatory access control option be supported in order to support the IL section.

456
457
458

Note that conforming implementations are always at liberty to enforce additional
constraints. Thus a conforming implementation may certainly enforce a relationship between mandatory access control labels and ILs (such as dominance). The
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

358

B Revisions to Rationale and Notes

459
460
461

silence of this standard on the topic of specific relationships between mandatory
access control labels and ILs should not dramatically impact portable applications.

462

B.27.9 Additional Uses of Information Labeling

463
464
465
466
467
468
469
470
471
472
473
474

The Compartmented Mode Workstation (CMW) security requirements are wellknown in many parts of the computer security community and have attracted considerable vendor interest. The CMW requirements are documented formally in‘‘Security Requirements for System High and Compartmented Mode Workstations’’, Defense Intelligence Agency document DDS-2600-5502-87 and are discussed less formally in the June 1990 issue of IEEE Transactions on Software
Engineering. Information labeling is a key component of the CMW requirements
both for meeting certain data labeling policies that concern non-mandatory access
control related information, and to avoid a potential data overclassification problem that may result from use of mandatory access control label-only systems.
This section of the rationale will further examine the data overclassification problem as an additional example of the utility of information labels.

475
476
477
478
479

According to mandatory access control policy FP.4, a newly created file object
shall be assigned the mandatory access control label of the creating subject (process). Such a policy is necessary to prevent any subjects with mandatory access
control labels dominated by the creator’s label from discovering the ‘‘fact ofexistence’’ of the object, thereby closing a covert channel.

480
481
482
483
484

Although the mandatory access control label of a newly created object correctly
represents the sensitivity of the object from the standpoint of mandatory access
control, it most likely incorrectly represents the actual sensitivity of the data contained in the object. Since the newly-created object contains no data, the sensitivity of the (null) data itself should be considered some system low value.

485
486
487
488
489
490
491
492
493
494
495
496

Another example of the overclassification problem is as follows. Consider a shellprocess (subject) executing with a mandatory access control label of mac_p2. During the lifetime of this shell the user decides to make a copy of another user’s filecontaining data with a sensitivity of mac_p1 and therefore a mandatory access
control label of mac_p1. mac_p2 dominates mac_p1, so the copy operation would
be permitted by mandatory access control policy FP.1. The copy process will becreated with a mandatory access control label of mac_p2 (in accordance with mandatory access control policy PP.2), will read the data from the original file andstore a copy of the data in a newly created file. In accordance with FP.4, thenewly created file will have a mandatory access control label of mac_p2, eventhough the original data was only sensitive enough to require protection at the
mac_p1 level.

497
498
499
500
501
502

These overclassification problems can be mitigated with the use of information
labels. In particular, an implementation could define inf_default() to return an
information label of ‘‘system low’’ and inf_float() to combine information labels as
per the CMW requirements. In such a system the information label of a newly
created (empty) object would be system low—an accurate representation of theactual sensitivity of the (null) data contained within the object. Note that thisWITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

B.27 Information Labeling

359

503
504
505
506
507

newly created object (and the fact that this object existed) would still be correctly
protected by the object’s mandatory access control label. When a process reads
from a file, the process information label floats with the file information label.
When a process writes to a file, the file information label floats with the process
information label.

508
509
510
511
512
513
514
515
516
517
518
519
520
521

Returning to the copy example, say the information label of the source file is
inf_p1. The copy process will start with an information label of inf_p2, which we
assume is system low as defined by inf_default() (as will generally be the case).
In the model of information label floating described in the paragraph above, when
the copy process reads the data from the file to be copied, the copy process’ information label will float to the value returned by inf_float(inf_p1, inf_p2), which,because inf_p2 is system low, will equal inf_p1. When the copy process creates
and writes the target file, that file will float to inf_p1 (the copy process’ label).
Thus the information label of the data in the source file will follow the data as it
moves through the system. So, even though the target file has a mandatory
access control label that is higher than the mandatory access control label of thesource file, the target file’s information label is the same as the source file’s information label and remains an accurate representation of the actual sensitivity ofthe data in the file.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

360

B Revisions to Rationale and Notes

Annex F(informative)
Ballot Instructions

This annex will not appear in the final standard. It is included in the draft to provide instructions for balloting that cannot be separated easily from the main document, as a cover letter might.

It is important that you read this annex, whether you are an official
member of the PSSG Balloting Group or not; comments on this draft are
welcomed from all interested technical experts.
Summary of Draft 17 Instructions
This is a recirculation on the P1003.1e ballot. The procedure for a recirculation is
described in this annex. Because this is a recirculation comments may only beprovided concerning sections that have changed, sections affected by thosechanges, or on rejected comments from the previous ballot.
Send your ballot and/or comments to:IEEE Standards OfficeComputer Society Secretariat
ATTN: PSSG Ballot (Carol Buonfiglio)
P.O. Box 1331
445 Hoes Lane
Piscataway, NJ 08855-1331
It would also be very helpful if you sent us your ballot in machine-readable form.
Your official ballot must be returned via mail to the IEEE office; if we receive only
the e-mail or diskette version, that version will not count as an official document.
However, the online version would be a great help to ballot resolution. Please
send your e-mail copies to the following address:
casey@sgi.com
or you may send your files in ASCII format on DOS 3.5 inch formatted diskettes(720Kb or 1.4Mb), or Sun-style QIC-24 cartridge tapes to:

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.27 Information Labeling361

Casey Schaufler
Silicon Graphics
2011 North Shoreline Blvd.
P.O. Box 7311
Mountain View, CA 94039-7311
Background on Balloting Procedures
The Balloting Group consists of approximately eighty technical experts who aremembers of the IEEE or the IEEE Computer Society; enrollment of individuals inthis group has already been closed. There are also a few ‘‘parties of interest’’ who
are not members of the IEEE or the Computer Society. Members of the Balloting
Group are required to return ballots within the balloting period. Other individuals who may happen to read this draft are also encouraged to submit comments
concerning this draft. The only real difference between members of the Balloting
Group and other individuals submitting ballots is that affirmative ballots are only
counted from Balloting Group members who are also IEEE or Computer Society
members. (There are minimum requirements for the percentages of ballots
returned and for affirmative ballots out of that group.) However, objections andnonbinding comments must be resolved if received from any individual, as follows:(1) Some objections or comments will result in changes to the standard. This
will occur either by the republication of the entire draft or by the publication of a list of changes. The objections/comments are reviewed by ateam from the POSIX Security working group, consisting of the Chair,Vice Chair, Technical Editor, and a group of Technical Reviewers. The
Chair will act as the Ballot Coordinator. The Technical Reviewers eachhave subject matter expertise in a particular area and are responsible forobjection resolution in one or more sections.
(2) Other objections/comments will not result in changes.
(a) Some are misunderstandings or cover portions of the document(front matter, informative annexes, rationale, editorial matters,etc.) that are not subject to balloting.
(b) Others are so vaguely worded that it is impossible to determine
what changes would satisfy the objector. These are referred to as
Unresponsive. (The Technical Reviewers will make a reasonable
effort to contact the objector to resolve this and get a newly worded
objection.) Further examples of unresponsive submittals are those
not marked as either Objection, Comment, or Editorial; those that
do not identify the portion of the document that is being objected to(each objection must be separately labeled); those that object tomaterial in a recirculation that has not changed and do not cite anunresolved objection; those that do not provide specific or generalguidance on what changes would be required to resolve the objection.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

362

F Ballot Instructions

(c) Finally, others are valid technical points, but they would result in
decreasing the consensus of the Balloting Group. (This judgment ismade based on other ballots and on the experiences of the working
group through over seven years of work and fifteen drafts preceding
this one.) These are referred to as Unresolved Objections. Summaries of unresolved objections and their reasons for rejection are
maintained throughout the balloting process and are presented to
the IEEE Standards Board when the final draft is offered for approval. Summaries of all unresolved objections and their reason forrejection will also be sent to members of the Balloting Group for
their consideration upon a recirculation ballot. (Unresolved objections are not circulated to the ballot group for a re-ballot.)
Unresolved objections are only circulated to the balloting groupwhen they are presented by members of the balloting group or byparties of interest. Unsolicited correspondence from outside these
two groups may result in draft changes, but are not recirculated tothe balloting group members.
Please ensure that you correctly characterize your ballot by providing oneof the following:(1) Your IEEE member number(2) Your IEEE Computer Society affiliate number(3) If (1) or (2) don’t apply, a statement that you are a ‘‘Party ofInterest’’
Ballot Resolution
The general procedure for resolving ballots is:(1) The ballots are put online and distributed to the Technical Reviewers.
(2) If a ballot contains an objection, the balloter may be contacted individually by telephone, letter, or e-mail and the corrective action to be taken
described (or negotiated). The personal contact will most likely not occur
if the objection is very simple and obvious to fix or the balloter cannot bereached after a few reasonable attempts. Repeated failed attempts to elicit a response from a balloter may result in an objection being consideredunresponsive, based on the judgment of the Ballot Coordinator. Once all
objections in a ballot have been resolved, it becomes an affirmative ballot.
(3) If any objection cannot be resolved, the entire ballot remains negative.
(4) After the ballot resolution period the technical reviewers may chose toeither re-ballot or recirculate the ballot, based on the status of the standard and the number and nature of outstanding (i.e., rejected orunresolved) objections. The ballot group may or may not be reformed at
this time. If a reballot is chosen, the entire process of balloting begins
anew. If a recirculation is chosen, only those portions affected by the previous ballot will be under consideration. This ballot falls into this latter
category
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.27 Information Labeling363

(5) On a recirculation ballot, the list of unresolved objections, along with theballot resolution group’s reasons for rejecting them will be circulated tothe existing ballot group along with a copy of the document that clearly
indicates all changes that were made during the last ballot period. You
have a minimum of ten days (after an appropriate time to ensure themail got through) to review these two documents and take one of the following actions:(a) Do nothing; your ballots will continue to be counted as we haveclassified them, based on items (3) and (4).
(b) Explicitly change your negative ballot to affirmative by agreeing to
remove all of your unresolved objections.
(c) Explicitly change your affirmative ballot to negative based on yourdisapproval of either of the two documents you reviewed. If anissue is not contained in an unresolved objection or is not the resultof a change to the document during the last ballot resolution period,
it is not allowed. Negative ballots that come in on recirculations
cannot be cumulative. They shall repeat any objections that theballoter considers unresolved from the previous recirculation. Ballots that simply say ‘‘and all the unresolved objections from lasttime’’ will be declared unresponsive. Ballots that are silent will be
presumed to fully replace the previous ballot, and all objections not
mentioned on the most current ballot will be considered as successfully resolved.
(6) Rather than reissue the entire document, a small number of changes may
result in the issuance of a change list rather than the entire document
during recirculation.
(7) A copy of all your objections and our resolutions will be mailed to you.
(8) If at the end of a recirculation period there remain greater than seventyfive percent affirmative ballots, and no new objections have been
received, a new draft is prepared that incorporates all the changes. This
draft and the unresolved objections list go to the IEEE Standards Board
for approval. If the changes cause too many ballots to slip back into
negative status, another resolution and recirculation cycle begins.
Balloting Guidelines
This section consists of guidelines on how to write and submit the most effective
ballot possible. The activity of resolving balloting comments is difficult and time
consuming. Poorly constructed comments can make that even worse.
We have found several things that can be done to a ballot that make our job moredifficult than it needs to be, and likely will result in a less than optimal response
to ballots that do not follow the form below. Thus it is to your advantage, as wellas ours, for you to follow these recommendations and requirements.
If a ballot that significantly violates the guidelines described in this section comesto us, we may determine that the ballot is unresponsive.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

364

F Ballot Instructions

If we recognize a ballot as ‘‘unresponsive,’’ we will try to inform the balloter assoon as possible so he/she can correct it, but it is ultimately the balloter’s responsibility to assure the ballot is responsive. Ballots deemed to be ‘‘unresponsive’’
may be ignored in their entirety.
Some general guidelines to follow before you object to something:(1) Read the Rationale section that applies to the troublesome area. In general there is a matching informative section in the Rationale Annex foreach normative section of the standard. This rationale often explains
why choices were made and why other alternatives were not chosen.
(2) Read the Scope, section 1, to see what subset of functionality we are trying to achieve. This standard does not attempt to be everything you everwanted for accomplishing secure software systems. If you feel that anadditional area of system interface requires standardization, you areinvited to participate in the security working group which is actively
involved in determining future work.
(3) Be cognizant of definitions in section 2. We often rely in the document on
a precise definition from section 2 which may be slightly different thanyour expectation.
Typesetting is not particularly useful to us. Also please do not send handwritten
ballots. Typewritten (or equivalent) is fine, and if some font information is lost it
will be restored by the Technical Editor in any case. You may use any word processor to generate your objections but do not send [nt]roff (or any other word
processor) input text. Also avoid backslashes, leading periods and apostrophes inyour text as they will confuse our word processor during collation and printing ofyour comments. The ideal ballot is formatted as a ‘‘flat ASCII file,’’ without any
attempt at reproducing the typography of the draft and without embedded control
characters or overstrikes; it is then printed in Courier (or some other typewriterlike) font for paper-mailing to the IEEE Standards Office and simultaneously emailed to the Working Group Ballot Coordinator at the following email address.
casey@sgi.com
Don’t quote others’ ballots. Cite them if you want to refer to another’s ballot. If
more than one person wants to endorse the same ballot, send just the cover sheets
and one copy of the comments and objections. [Note to Institutional Representatives of groups like X/Open, OSF, UI, etc.: this applies to you, too. Please don’t
duplicate objection text with your members.] Multiple identical copies are easy todeal with, but just increase the paper volume. Multiple almost-identical ballots
are a disaster, because we can’t tell if they are identical or not, and are likely tomiss the subtle differences. Responses of the forms:— ‘‘I agree with the item in <someone>’s ballot, but I’d like to see this done
instead’’— ‘‘I am familiar with the changes to foo in <someone>’s ballot and I would
object if this change is [or is not] included’’

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.27 Information Labeling365

are very useful information to us. If we resolve the objection with the original
balloter (the one whose ballot you are referencing), we will also consider yours to
be closed, unless you specifically include some text in your objection indicatingthat should not be done.
Be very careful of ‘‘Oh, by the way, this applies <here> too’’ items, particularly ifthey are in different sections of the document that are likely to be seen by different reviewers. They are probably going to be missed! Note the problem in theappropriate section, and cite the detailed description if it’s too much trouble tocopy it. The reviewers don’t read the whole ballot. They only read the parts thatappear in the sections that they have responsibility for reviewing. Particularly
where definitions are involved, if the change really belongs in one section but therelevant content is in another, please include two separate comments/objections.
Please consider this a new ballot that should stand on its own. Please do notmake backward references to your ballots for the previous draft. Include all thetext you want considered here, because the Technical Reviewer will not have yourold ballot. (The old section and line numbers won’t match up anyway.) If one ofyour objections was not accepted exactly as you wanted, it may not be useful tosend in the exact text you sent before; read our response to your objection (youwill receive these in a separate mailing) and the associated Rationale section andcome up with a more compelling (or clearly-stated) justification for the change.
Please be very wary about global statements, such as ‘‘all of the arithmetic functions need to be defined more clearly.’’ Unless you are prepared to cite specificinstances of where you want changes made, with reasonably precise replacement
language, your ballot will be considered unresponsive.
Ballot Form
The following form is strongly recommended. We would greatly appreciate it if
you sent the ballot in electronic form in addition to the required paper copy. Ourpolicy is to handle all ballots online, so if you don’t send it to us that way, we haveto type it in manually. See the first page of this Annex for the addresses andmedia. As you’ll see from the following, formatting a ballot that’s sent to us
online is much simpler than a paper-only ballot.
The paper ballot should be page-numbered, and each page should contain thename, e-mail address, and phone number(s) of the objector(s). The electronic copyof the ballot should only have it once, in the beginning. Please leave adequate (atleast one inch) margins on both sides.
Don’t format the ballot as a letter or document with its own section numbers.
These are simply confusing. As shown below, it is best if you cause each objection
and comment to have a sequential number that we can refer to amongst ourselves
and to you over the phone. Number sequentially from 1 and count objections,comments, and editorial comments the same; don’t number each in its own range.
We recognize three types of responses:
Objection A problem that must be resolved to your satisfaction prior to yourcasting an "affirmative" vote for the document.
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

366

F Ballot Instructions

Comment A problem that you might want to be resolved by the reviewer, butwhich does not in any way affect whether your ballot is negative or
positive. Any response concerning the pages preceding page 1 (theFront matter), Rationale text with shaded margins, Annexes,
NOTES in the text, footnotes, or examples will be treated as a nonbinding comment whether you label it that way or not. (It would
help us if you’d label it correctly.)
Editorial A problem that is strictly an editorial oversight and is not of a technical nature. Examples are: typos; misspellings; English syntax orusage errors; appearances of lists or tables; arrangement of sections,clauses, and subclauses (except where the location of information
changes the optionality of a feature).
To help us in our processing of your objections and comments, we are requiringthat all comments, objections and editorial comments meet the following specificformat. (We know that the format defined below contains redundant information
but it has become a de facto standard used by many different POSIX standard
ballots. It is felt that it is better to continue to use this format with the redundancies rather than to create a new format just for 1003.1e and P1003.2c)
Separate each objection/comment with a line of dashes ("-"), e.g.,------------------------------------------------------------------------------------Precede each objection/comment with two lines of identifying information:
The first line should contain:@ <section>.
.<clause> <code> <seqno>
where:@

At-sign in column 1 (which means no @’s in any other column 1’s).

<section>

The major section (chapter or annex) number or letter in column
3. Use zero for Global or for something, like the frontmatter, thathas no section or annex number.

<clause>The clause number (second-level header). Please do not go deeper
than these two levels. In the text of your objection or comment,go as deep as you can in describing the location, but this code line
uses two levels only.

<code>

One of the following lowercase letters, preceded and followed by
spaces:o Objection.
c Comment.
e Editorial Comment.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.27 Information Labeling367

<seqno>A sequence number, counting all objections and comments in asingle range.

The second line should contain:<seqno>.
. Sect <sectno> <type>.
. page <pageno>,, line <lineno>::
where:<seqno>The sequence number from the preceding line

<sectno>The full section number. (Go as deep as you can in describing thelocation.)<type>

One of the following key words/phrases, preceded and followed by
spaces:OBJECTION
COMMENTEDITORIAL COMMENT<pageno>The page number from the document.

<lineno>The line number or range
object/comment relates to.

of

line

numbers

that

the

For each objection, comment, or editorial comment, you should provide a clear
statement of the problem followed by the action required to solve that problem.
Problem:A clear statement of the problem that is observed, sufficient for others to understand the nature of the problem. (Note that you should identify problems by section, page, and line numbers. This may seem redundant, but if you transpose adigit pair, we may get totally lost without a cross-check like this. Use the line
number where the problem starts, not just where the section itself starts; wesometimes attempt to sort objections by line numbers to make editing more accurate. If you are referring to a range of lines, please don’t say ‘‘lines 10xx;’’ use areal range so we can tell where to stop looking. Please try to include enough context information in the problem statement (such as the name of the function orcommand) so we can understand it without having the draft in our laps at thetime. (It also helps you when we e-mail it back to you.)
Action:A precise statement of the actions to be taken on the document to resolve theobjection above, which if taken verbatim will completely remove the objection.
If there is an acceptable range of actions, any of which will resolve the problem foryou if taken exactly, please indicate all of them. If we accept any of these, yourobjection will be considered as resolved.
If the Action section is omitted or is vague in its solution, the objection may bereclassified as a nonbinding comment. The Technical Reviewers, being human,
will give more attention to Actions that are well-described than ones that are
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

368

F Ballot Instructions

vague or imprecise. The best ballots of all have very explicit directions to substitute, delete, or add text in a style consistent with the rest of the document, suchas:
Delete the sentence on lines 101-102:"The implementation shall not ... or standard error."On line 245, change "shall not" to "should not".
After line 711, add:-c

Calculate the mask permissions and update the mask.

Some examples of poorly-constructed actions:Remove all features of this command that are not supported by BSD.
Add -i.
Make this command more efficient and reliable.
Use some other flag that isn’t so confusing.
I don’t understand this section.
Specify a value--I don’t care what.

Sample Response:

Joseph Balloter
EMAIL: jmb@m
mycomp.com

FAX:(999)123-4567(999)890-1234

page

4 of 17.

---------------------------------------------------------------@ 1.1 o 23
23. Sect 1.1 OBJECTION. page 7, line 9:
Problem:
The current draft describes one the mechanisms specified in it as"Least Privilege" which is incorrect. "Least Privilege" is a
general principle related to access control rather than a mechanism.
In fact, the definition given in the standard (p. 91, l. 274)
calls it a principle rather than a mechanism.
Action:Replace line 9 with:"(3)

Enforcement of Least Privilege"---------------------------------------------------------------@ 3.1 o 24
24. Sect 3.1 OBJECTION. page 27, line 13:
Problem:"during process of changing ACL" is vague.
Could be read as the duration from acl_read through acl_write.
Action:WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.27 Information Labeling369

Should state "while ACL is being written (acl_write)".
---------------------------------------------------------------@ 3.3 e 25
25. Sect 3.3.1 EDITORIAL COMMENT. page 29, line 68:
Problem:
The two previous sentences describe the "ACL_USER_OBJ entry" andthe "ACL_GROUP_OBJ entry". Line 68 describes "ACL_OTHER_OBJ",
the word "entry" should be added for consistency.
Action:change "ACL_OTHER_OBJ" to "ACL_OTHER_OBJ entry"

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

370

F Ballot Instructions

Sample Response (continued):Joseph Balloter
EMAIL: jmb@m
mycomp.com

FAX:(999)123-4567(999)890-1234

page

5 of 17.

---------------------------------------------------------------@ 4.5 c 26
26. Sect 4.5.1.1 COMMENT. page 92, line 836:
Problem:
There is no introduction to table 4-1.
Action:Add before line 836 "The aud_ev_info_t structure shall contain atleast the following fields:"---------------------------------------------------------------@ 6.5 o 27
27. Sect 6.5.7.2 OBJECTION. page 181, line 449-450:
Problem:
Can this "must" be tested ?
Is this really needed since the format of the label is undefinedand no functions are provided to access the individual components(so that a comparison could be made). This seems to be a commentthat could just as easily be applied to most other mac functions,
say mac_freelabel for example.
Action:Suggest either moving this into the MAC introductory section,
striking or changing "must" to "should" or "are advised".
----------------------------------------------------------------

Thank you for your cooperation and assistance in this important balloting process.

Lynne M. Ambuel
Chair, POSIX Security Working GroupWITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
B.27 Information Labeling371

Identifier Index

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
G Identifier Index

373

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

374

G Identifier Index

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.
G Identifier Index

375

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

376

G Identifier Index

Topical Index

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

378

Topical Index

Contents

SECTION

PAGE

Section 1: Revisions to the General Section

.

.

.

.

.

.

.

.

.

.

.

1

Section 2: Revisions to Terminology and General
Requirements. . . . . . . . . . .

.

.

.

.

.

.

.

.

.

3

Section 3: Revisions to Process Primitives

.

.

.

.

.

.

.

.

.

.

.

17

Section 4: Revisions to Process Environment .

.

.

.

.

.

.

.

.

.

.

21

Section 5: Revisions to Files and Directories .

.

.

.

.

.

.

.

.

.

.

23

Section 6: Revisions to Input and Output Primitives

.

.

.

.

.

.

.

.

35

Section 8: Revisions to C Programming Language Specific
Services. . . . . . . . . . . . . . . .

.

.

.

.

.

.

37

Section 23: Access Control Lists . . . . . . . . . . . . . .
23.1 General Overview . . . . . . . . . . . . . . . .
23.1.1 ACL Entry Composition . . . . . . . . . . .
23.1.2 Relationship with File Permission Bits . . . . . .
23.1.3 Default ACLs
. . . . . . . . . . . . . .
23.1.4 Associating an ACL with an Object at Object CreationTime. . . . . . . . . . . . . . . . .
23.1.5 ACL Access Check Algorithm . . . . . . . . .
23.1.6 ACL Functions . . . . . . . . . . . . . .
23.1.7 POSIX.1 Functions Covered by ACLs . . . . . .
23.2 Header . . . . . . . . . . . . . . . . . . . .
23.2.1 acl_entry_t. . . . . . . . . . . . . . .
23.2.2 acl_perm_t. . . . . . . . . . . . . . .
23.2.3 acl_permset_t. . . . . . . . . . . . . .
23.2.4 acl_t . . . . . . . . . . . . . . . . . .
23.2.5 acl_tag_t . . . . . . . . . . . . . . . .
23.2.6 acl_type_t . . . . . . . . . . . . . . . .
23.2.7 ACL Qualifier . . . . . . . . . . . . . .
23.2.8 ACL Entry. . . . . . . . . . . . . . .
23.3 Text Form Representation . . . . . . . . . . . . .
23.3.1 Long Text Form for ACLs . . . . . . . . . .
23.3.2 Short Text Form for ACLs . . . . . . . . . .
23.4 Functions . . . . . . . . . . . . . . . . . . .
23.4.1 Add a Permission to an ACL Permission Set . . . .
23.4.2 Calculate the File Group Class Mask
. . . . . .
23.4.3 Clear All Permissions from an ACL Permission
Set . . . . . . . . . . . . . . . . . .
23.4.4 Copy an ACL Entry. . . . . . . . . . . .
23.4.5 Copy an ACL From System to User Space . . . . .

.
.
.
.
.

39
39
40
41
42

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

42
43
44
46
47
47
48
48
48
48
49
49
50
50
50
52
52
53
53

.
.
.

55
55
56

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

ii

SECTION

PAGE

23.4.623.4.723.4.823.4.923.4.1023.4.1123.4.1223.4.1323.4.1423.4.15
23.4.16
23.4.1723.4.18
23.4.19
23.4.20
23.4.2123.4.2223.4.23
23.4.24
23.4.25
23.4.26
23.4.27
23.4.28

Copy an ACL From User to System Space . .
Create a New ACL Entry. . . . . . .
Delete a Default ACL by Filename . . . .
Delete an ACL Entry . . . . . . . . .
Delete Permissions from an ACL Permission
Set . . . . . . . . . . . . . . .
Duplicate an ACL . . . . . . . . . .
Release Memory Allocated to an ACL Data
Object . . . . . . . . . . . . . .
Create an ACL from Text
. . . . . . .
Get an ACL Entry . . . . . . . . . .
Get an ACL by File Descriptor . . . . . .
Get an ACL by Filename. . . . . . .
Retrieve the Permission Set from an ACL
Entry . . . . . . . . . . . . . .
Get ACL Entry Qualifier . . . . . . . .
Get ACL Entry Tag Type. . . . . . .
Initialize ACL Working Storage . . . . .
Set an ACL by File Descriptor . . . . . .
Set an ACL by Filename . . . . . . . .
Set the Permissions in an ACL Entry . . .
Set ACL Entry Tag Qualifier . . . . . .
Set ACL Entry Tag Type . . . . . . . .
Get the Size of an ACL . . . . . . . .
Convert an ACL to Text . . . . . . . .
Validate an ACL. . . . . . . . . .

Section 24: Audit . . . . . . . . . . . . . .
24.1 General Overview . . . . . . . . . . .
24.1.1 Audit Logs
. . . . . . . . . .
24.1.2 Audit Records . . . . . . . . .
24.1.3 Audit Interfaces. . . . . . . .
24.1.4 Summary of POSIX.1 System Interface
Impact . . . . . . . . . . . .
24.2 Audit Record Content . . . . . . . . . .
24.2.1 Auditable Interfaces and Event Types .
24.2.2 Audit Event Types and Record Content
24.3 Header . . . . . . . . . . . . . . .
24.3.1 aud_evinfo_t . . . . . . . . . .
24.3.2 aud_hdr_t . . . . . . . . . . .
24.3.3 aud_id_t . . . . . . . . . . .
24.3.4 aud_info_t. . . . . . . . . .
24.3.5 aud_obj_t . . . . . . . . . . .
24.3.6 aud_obj_type_t . . . . . . . . .
24.3.7 aud_rec_t . . . . . . . . . . .
24.3.8 aud_state_t . . . . . . . . . .
24.3.9 aud_status_t . . . . . . . . . .
24.3.10 aud_subj_t. . . . . . . . . .

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

57
58
59
61

.
.

.
.

.
.

.
.

61
62

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

63
64
65
66
67

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

69
70
71
72
73
74
76
77
78
79
80
81

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

83
83
83
84
85

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

89
89
90
92
106
108
108
108
108
109
110
110
110
110
111

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

iii

SECTION

PAGE

24.3.11 aud_time_t . . . . . . . . . . . .
24.4 Functions . . . . . . . . . . . . . . . .
24.4.1 Copy an Audit Record From System to UserSpace . . . . . . . . . . . . . .
24.4.2 Copy an Audit Record From User to System
Space . . . . . . . . . . . . . .
24.4.3 Delete Set of Event-specific Data from a
Record . . . . . . . . . . . . . .
24.4.4 Delete Item from Set of Event-specific Data .
24.4.5 Delete Header from an Audit Record. . .
24.4.6 Delete Item from Audit Record Header . . .
24.4.7 Delete Set of Object Attributes from a Record
24.4.8 Delete Item from Set of Object Attributes . .
24.4.9 Delete Set of Subject Attributes from a
Record . . . . . . . . . . . . . .
24.4.10 Delete Item from Set of Subject Attributes.
24.4.11 Duplicate an Audit Record . . . . . . .
24.4.12 Map Text to Event Type . . . . . . . .
24.4.13 Map Event Type to Text . . . . . . . .
24.4.14 Release Memory Allocated to an Audit Data
Object . . . . . . . . . . . . . .
24.4.15 Get All Audit Event Types . . . . . . .
24.4.16 Get Audit Record Event-specific Data
Descriptor . . . . . . . . . . . . .
24.4.17 Examine Audit Record Event-specific Data.
24.4.18 Get an Audit Record Header Descriptor. .
24.4.19 Examine an Audit Record Header. . . .
24.4.20 Get a Process Audit ID . . . . . . . .
24.4.21 Get an Audit Record Object Descriptor . . .
24.4.22 Examine Audit Record Object Data . . . .
24.4.23 Get an Audit Record Subject Descriptor. .
24.4.24 Examine Audit Record Subject Data . . . .
24.4.25 Map Text to Audit ID . . . . . . . . .
24.4.26 Map Audit ID to Text . . . . . . . . .
24.4.27 Create a New Audit Record . . . . . . .
24.4.28 Add Set of Event-specific Data to Audit
Record . . . . . . . . . . . . . .
24.4.29 Add Item to Set of Event-specific Data . . .
24.4.30 Add Header to Audit Record. . . . . .
24.4.31 Add Item to Audit Record Header. . . .
24.4.32 Add Set of Object Attributes to Audit Record .
24.4.33 Add Item to Set of Object Attributes . . . .
24.4.34 Add Set of Subject Attributes to Audit Record
24.4.35 Add Item to Set of Subject Attributes . . .
24.4.36 Read an Audit Record . . . . . . . . .
24.4.37 Convert an Audit Record to Text . . . . .
24.4.38 Get the Size of an Audit Record . . . . .
WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

iv

.
.

.
.

.
.

.
.

111
112

.

.

.

.

112

.

.

.

.

113

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

114
115
116
117
118
118

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

119
120
121
122
123

.
.

.
.

.
.

.
.

124
125

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

126
127
129
130
132
133
134
137
138
141
141
142

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

143
144
146
147
149
150
151
153
154
156
157

SECTION

PAGE

24.4.39 Control the Generation of Audit Records
24.4.40 Validate an Audit Record. . . . .
24.4.41 Write an Audit Record. . . . . .

.
.
.

158
159
160

Section 25: Capabilities . . . . . . . . . . . . . . . . . .
25.1 General Overview . . . . . . . . . . . . . . . . .
25.1.1 Major Features . . . . . . . . . . . . . . .
25.1.2 Capability Functions . . . . . . . . . . . . .
25.2 Header . . . . . . . . . . . . . . . . . . . . .
25.3 Text Form Representation . . . . . . . . . . . . . .
25.3.1 Grammar . . . . . . . . . . . . . . . . .
25.4 Functions . . . . . . . . . . . . . . . . . . . .
25.4.1 Initialize a Capability State in Working
Storage. . . . . . . . . . . . . . . . .
25.4.2 Copy a Capability State From System to UserSpace . . . . . . . . . . . . . . . . . .
25.4.3 Copy a Capability State From User to System
Space . . . . . . . . . . . . . . . . . .
25.4.4 Duplicate a Capability State in Working
Storage. . . . . . . . . . . . . . . . .
25.4.5 Release Memory Allocated to a Capability State in Working Storage . . . . . . . . . . . . . . . .
25.4.6 Convert Text to a Capability State in Working
Storage. . . . . . . . . . . . . . . . .
25.4.7 Get the Capability State of an Open File . . . . . .
25.4.8 Get the Capability State of a File . . . . . . . . .
25.4.9 Get the Value of a Capability Flag . . . . . . . .
25.4.10 Obtain the Current Process Capability State . . . . .
25.4.11 Allocate and Initialize a Capability State in Working
Storage. . . . . . . . . . . . . . . . .
25.4.12 Set the Capability State of an Open File . . . . . .
25.4.13 Set the Capability State of a File . . . . . . . . .
25.4.14 Set the Value of a Capability Flag
. . . . . . . .
25.4.15 Set the Process Capability State . . . . . . . . .
25.4.16 Get the Size of a Capability Data Record . . . . . .
25.4.17 Convert a Capability State in Working Storage to
Text . . . . . . . . . . . . . . . . . . .

163
163
164
167
169
175
176
177

Section 26: Mandatory Access Control . . . . .
26.1 General Overview . . . . . . . . .
26.1.1 MAC Concepts . . . . . . .
26.1.2 MAC Policy . . . . . . . .
26.2 Header . . . . . . . . . . . . .
26.2.1 mac_t . . . . . . . . . .
26.3 Functions . . . . . . . . . . . .
26.3.1 Test MAC Labels for Dominance .
26.3.2 Test MAC Labels for Equivalence
26.3.3 Free MAC Label Storage Space
.

195
195
195
196
200
201
201
201
202
203

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

178
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

v

SECTION

PAGE

26.3.4

Convert Text MAC Label to Internal
Representation . . . . . . . . . .
Get the Label of a File Designated by a File
Descriptor . . . . . . . . . . . .
Get the Label of a File Designated by a
Pathname . . . . . . . . . . . .
Get the Process Label . . . . . . . .
Compute the Greatest Lower Bound . . .
Compute the Least Upper Bound . . . .
Set the Label of a File Identified by File
Descriptor . . . . . . . . . . . .
Set the Label of a File Designated by
Pathname . . . . . . . . . . . .
Set the Process Label . . . . . . . .
Get the Size of a MAC Label. . . . .
Convert Internal MAC Label to Textual
Representation . . . . . . . . . .
Label Validity . . . . . . . . . .

.

.

.

.

.

203

.

.

.

.

.

204

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

205
207
207
208

.

.

.

.

.

209

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

211
212
213

.
.

.
.

.
.

.
.

.
.

214
215

Section 27: Information Labeling . . . . . . . . . . . . .
27.1 General Overview . . . . . . . . . . . . . . .
27.1.1 Information Label Concepts. . . . . . . .
27.1.2 Information Label Policy . . . . . . . . . .
27.2 Header . . . . . . . . . . . . . . . . . . .
27.2.1 inf_t . . . . . . . . . . . . . . . . .
27.3 Functions . . . . . . . . . . . . . . . . . .
27.3.1 Initial Information Label. . . . . . . . .
27.3.2 Test Information Labels For Dominance . . . .
27.3.3 Test Information Labels For Equivalence . . . .
27.3.4 Floating Information Labels. . . . . . . .
27.3.5 Free Allocated Information Label Memory. . .
27.3.6 Convert Text Label to Internal
Representation . . . . . . . . . . . . .
27.3.7 Get the Information Label of a File Identified by File
Descriptor . . . . . . . . . . . . . . .
27.3.8 Get the Information Label of a File Identified by
Pathname . . . . . . . . . . . . . . .
27.3.9 Get the Process Information Label . . . . . .
27.3.10 Set the Information Label of a File Identified by File
Descriptor . . . . . . . . . . . . . . .
27.3.11 Set the Information Label of a File Identified by
Pathname . . . . . . . . . . . . . . .
27.3.12 Set the Process Information Label. . . . . .
27.3.13 Get the Size of an Information Label. . . . .
27.3.14 Convert Internal Label Representation to
Text . . . . . . . . . . . . . . . . .
27.3.15 Information Label Validity . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

217
217
217
218
221
221
221
222
223
223
224
225

.

.

226

.

.

227

.
.

.
.

228
229

.

.

230

.
.
.

.
.
.

231
232
233

.
.

.
.

234
235

26.3.526.3.626.3.726.3.826.3.926.3.1026.3.1126.3.1226.3.1326.3.1426.3.15

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

vi

SECTION

PAGE

Annex B (informative) Revisions to Rationale and Notes. . . . .
B.1 Revisions to Scope and Normative References. . . . . .
B.2 Revisions to Definitions and General Requirements. . . .
B.2.10 Security Interface . . . . . . . . . . . . .
B.3 Revisions to Process Primitives. . . . . . . . . . .
B.23 Access Control Lists . . . . . . . . . . . . . . .
B.23.1 General Overview . . . . . . . . . . . . .
B.23.2 ACL Entry Composition . . . . . . . . . . .
B.23.3 Relationship with File Permission Bits . . . . . .
B.23.4 Default ACLs
. . . . . . . . . . . . . .
B.23.5 Associating an ACL with an Object at Object CreationTime. . . . . . . . . . . . . . . . .
B.23.6 ACL Access Check Algorithm . . . . . . . . .
B.23.7 ACL Functions . . . . . . . . . . . . . .
B.23.8 Header . . . . . . . . . . . . . . . . .
B.23.9 Misc Rationale . . . . . . . . . . . . . .
B.24 Audit. . . . . . . . . . . . . . . . . . . .
B.24.1 Goals . . . . . . . . . . . . . . . . .
B.24.2 Scope . . . . . . . . . . . . . . . . .
B.24.3 General Overview . . . . . . . . . . . . .
B.24.4 Audit Logs and Records . . . . . . . . . . .
B.24.5 Audit Event Types and Event Classes . . . . . .
B.24.6 Selection Criteria . . . . . . . . . . . . .
B.24.7 Audit Interfaces. . . . . . . . . . . . .
B.25 Capability . . . . . . . . . . . . . . . . . . .
B.25.1 General Overview . . . . . . . . . . . . .
B.25.2 Major Features . . . . . . . . . . . . . .
B.25.3 Function Calls Modified for Capability . . . . . .
B.25.4 Capability Header . . . . . . . . . . . . .
B.25.5 New Capability Functions . . . . . . . . . .
B.25.6 Examples of Capability Inheritance andAssignment . . . . . . . . . . . . . . .
B.25.7 Capability Worked Examples . . . . . . . . .
B.26 Mandatory Access Control . . . . . . . . . . . . .
B.26.1 Goals . . . . . . . . . . . . . . . . .
B.26.2 Scope . . . . . . . . . . . . . . . . .
B.26.3 File Object Model . . . . . . . . . . . . .
B.26.4 Direct Write-up . . . . . . . . . . . . . .
B.26.5 Protection of Link Names. . . . . . . . . .
B.26.6 Pathname Search Access. . . . . . . . . .
B.26.7 Check-Access-on-Open Only
. . . . . . . . .
B.26.8 Creating Upgraded Directories. . . . . . . .
B.26.9 Objects without MAC labels. . . . . . . . .
B.26.10 Error Return Values . . . . . . . . . . . .
B.26.11 Valid MAC Labels . . . . . . . . . . . . .
B.26.12 Modification of MAC labels . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.

237
237
242
243
243
249
251
252
255
264

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

268
271
273
279
279
280
280
285
286
288
296
296
297
306
306
312
316
317
322

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

325
326
331
331
332
334
335
336
336
337
338
338
339
340
341

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

vii

SECTION

PAGE

B.26.13 Least upper bounds and greatest lower
bounds . . . . . . . . . . . . . . . . . .
B.26.14 Functions returning MAC labels . . . . . . . . .
B.26.15 Multi-level directories. . . . . . . . . . . .
B.26.16 The Directory Model . . . . . . . . . . . . .
B.26.17 File Tranquillity. . . . . . . . . . . . . .
B.26.18 Process Tranquillity . . . . . . . . . . . . .
B.26.19 Unnamed Pipes . . . . . . . . . . . . . . .
B.26.20 FIFOs . . . . . . . . . . . . . . . . . .
B.26.21 Inclusion of mac_set_fd() . . . . . . . . . . . .
B.26.22 Inclusion of mac_size(). . . . . . . . . . . .
B.26.23 Restrictions on Signals . . . . . . . . . . . .
B.26.24 Alteration of atime . . . . . . . . . . . . . .
B.26.25 Multi-Label Untrusted Process Hierarchies . . . . .
B.26.26 File Status Queries. . . . . . . . . . . . .
B.27 Information Labeling . . . . . . . . . . . . . . . .
B.27.1 Goals . . . . . . . . . . . . . . . . . .
B.27.2 Scope . . . . . . . . . . . . . . . . . .
B.27.3 Concepts Not Included. . . . . . . . . . . .
B.27.4 Data Labeling Policies. . . . . . . . . . . .
B.27.5 Initial Information Labels . . . . . . . . . . .
B.27.6 Information Label Validity . . . . . . . . . . .
B.27.7 Control Information . . . . . . . . . . . . .
B.27.8 Relationship between ILs and Mandatory Access Control
Labels . . . . . . . . . . . . . . . . . .
B.27.9 Additional Uses of Information Labeling . . . . . .
Annex F (informative) Ballot Instructions

341
341
342
344
344
345
345
346
346
346
347
347
347
348
348
348
349
350
350
356
357
358
358
359

.

.

.

.

.

.

.

.

.

.

.

361

Identifier Index .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

373

Topical Index

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

378

Table 23-1 − ACL Data Types

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

47

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

48

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

49

Table 23-4 − acl_type_t Values .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

49

Table 23-5 − ACL Qualifier Constants

.

.

.

.

.

.

.

.

.

.

.

.

.

49

Table 23-6 − ACL Entry Constants

.

.

.

.

.

.

.

.

.

.

.

.

.

50

Table 24-1 − Interfaces and Corresponding Audit Events .

.

.

.

.

.

.

91

Table 24-2 − Audit Data Types .

.

.

.

.

.

.

107

.

TABLES

Table 23-2 − acl_perm_t Values
Table 23-3 − acl_tag_t Values

.

.

.

.

.

.

.

.

.

.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

viii

Table 24-3 − Other Constants

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

107

Table 24-4 − aud_info_t members .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

108

Table 24-5 − Values for aud_info_type Member

.

.

.

.

.

.

.

.

.

.

109

Table 24-6 − aud_obj_type_t Values

.

.

.

.

.

.

.

.

.

.

.

.

.

.

110

Table 24-7 − aud_state_t Values

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

110

Table 24-8 − aud_status_t Values .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

111

Table 24-9 − aud_time_t Members

.

.

.

.

.

.

.

.

.

.

.

.

.

.

111

Table 24-10 − aud_hdr_info_p Values

.

.

.

.

.

.

.

.

.

.

.

.

.

131

Table 24-11 − aud_obj_info_p Values

.

.

.

.

.

.

.

.

.

.

.

.

.

135

Table 24-12 − aud_subj_info_p Values

.

.

.

.

.

.

.

.

.

.

.

.

.

139

Table 25-1 − POSIX.1 Functions Covered by Capability
Policies . . . . . . . . . . . . . . . .

.

.

.

.

.

.

.

166

Table 25-2 − Capability Data Types .

.

.

.

.

.

.

.

.

.

.

.

.

.

169

Table 25-3 − cap_flag_t Values .

.

.

.

.

.

.

.

.

.

.

.

.

.

169

.

.

.

.

.

.

.

.

.

.

.

.

.

169

.

.

.

.

.

.

.

.

.

.

.

.

.

170

Table 25-6 − cap_value_t Values for Mandatory AccessControls. . . . . . . . . . . . . . .

.

.

.

.

.

.

.

173

Table 25-7 − cap_value_t Values for Information Labels

.

.

.

.

.

.

.

174

Table 25-8 − cap_value_t Values for Audit .

.

.

.

.

.

.

.

174

.

.

.

.

199

.

.

.

.

200

Table 27-1 − POSIX.1 Functions Covered by Information Label File
Policies . . . . . . . . . . . . . . . . . . . . .

.

.

220

Table 27-2 − POSIX.1 Functions Covered by Information Label Process
Policies . . . . . . . . . . . . . . . . . . . . . .

.

221

Table B-3 − Other System Functions Potentially Affected by Capability
Policies . . . . . . . . . . . . . . . . . . . . . .

.

317

.

.

Table 25-4 − cap_flag_value_t Values
Table 25-5 − cap_value_t Values

.

.

.

.

.

.

Table 26-1 − POSIX.1 Functions Covered by MAC File Policies
Table 26-2 − POSIX.1 Functions Covered by MAC Process
Policies . . . . . . . . . . . . . . . . .

.

.

WITHDRAWN DRAFT. All Rights Reserved by IEEE.
Preliminary—Subject to Revision.

ix