2 .\" Copyright (c) 2021 Robert N. M. Watson
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd persistently store an updated MAC label on a vnode
39 .Fn VOP_SETLABEL "struct vnode *vp" "label *label"
41 This vnode call is made by
43 file relabeling operation has been authorized, and the filesystem must now be
45 .Ss Single-Label vs. Multi-Label Filesystems
46 Filesystems that do not implement per-file labels -- known as single-label
47 filesystems -- can simply leave the
50 These filesystems must not set the
55 Filesystems that do implement per-vnode label storage -- known as multi-label
56 filesystems -- will set the
60 The UFS filesystem uses a superblock flag to persisently configure whether a
61 specific filesystem implements a label for each
63 and then keys various behaviors on whether that flag is set.
64 .Ss Extended Attributes
65 If the filesystem implements extended attributes, then the MAC Framework's
66 .Fn vop_stdsetlabel_ea
67 function can be used, and maps operations into a series of
68 .Xr VOP_OPENEXTATTR 9 ,
69 .Xr VOP_WRITEEXTATTR 9 ,
71 .Xr VOP_CLOSEEXTATTR 9 .
73 Filesystems will also need to call
74 .Fn mac_vnode_create_extattr
75 when a new filesystem object is created, so that suitable extended attributes
76 can be written out, and
77 .Fn mac_vnode_associate_extattr
80 is associated with a filesystem object for the first time.
81 These utility functions use
82 .Xr VOP_OPENEXTATTR 9 ,
83 .Xr VOP_READEXTATTR 9 ,
84 .Xr VOP_WRITEEXTATTR 9 ,
86 .Xr VOP_CLOSEEXTATTR 9
89 .Ss Locking and Crash Safety
90 In all cases, it is important that exclusive
92 locks be held to prevent concurrent access when a MAC label may not yet be
94 It is also important that operations are ordered so that a system crash does
95 not leave a file improperly labeled.
96 For example, the extended attribute for a newly created file must be written
97 to disk before the file is linked by its parent directory, so that there is
98 no opportunity for a crash to lead to an unlabeled file.
100 The vnode will be locked on entry and should remain locked on return.
102 If the MAC label is successfully set, then zero is returned.
103 Otherwise, an appropriate error code is returned.
107 The file system does not support
110 The file system is out of space.
112 The file system is read-only.
115 Depending on the underlying implementation of
117 other errors may also be possible.
119 .Xr VOP_CLOSEEXTATTR 9 ,
120 .Xr VOP_OPENEXTATTR 9 ,
121 .Xr VOP_READEXTATTR 9 ,
122 .Xr VOP_WRITEXTATTR 9 ,
127 This manual page was written by