1.\"- 2.\" Copyright (c) 2021 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 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. 13.\" 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 24.\" SUCH DAMAGE. 25.\" 26.Dd February 27, 2021 27.Dt VOP_SETLABEL 9 28.Os 29.Sh NAME 30.Nm VOP_SETLABEL 31.Nd persistently store an updated MAC label on a vnode 32.Sh SYNOPSIS 33.In sys/param.h 34.In sys/vnode.h 35.In security/mac.h 36.Ft int 37.Fn VOP_SETLABEL "struct vnode *vp" "label *label" 38.Sh DESCRIPTION 39This vnode call is made by 40.Xr mac 9 41file relabeling operation has been authorized, and the filesystem must now be 42updated. 43.Ss Single-Label vs. Multi-Label Filesystems 44Filesystems that do not implement per-file labels -- known as single-label 45filesystems -- can simply leave the 46.Xr vnode 9 47operation undefined. 48These filesystems must not set the 49.Dv MNT_MULTLABEL 50flag in their 51.Vt struct mount . 52.Pp 53Filesystems that do implement per-vnode label storage -- known as multi-label 54filesystems -- will set the 55.Dv MNT_MULTILABEL 56flag in their 57.Vt struct mount . 58The UFS filesystem uses a superblock flag to persisently configure whether a 59specific filesystem implements a label for each 60.Xr vnode 9 , 61and then keys various behaviors on whether that flag is set. 62.Ss Extended Attributes 63If the filesystem implements extended attributes, then the MAC Framework's 64.Fn vop_stdsetlabel_ea 65function can be used, and maps operations into a series of 66.Xr VOP_OPENEXTATTR 9 , 67.Xr VOP_WRITEEXTATTR 9 , 68and 69.Xr VOP_CLOSEEXTATTR 9 . 70.Pp 71Filesystems will also need to call 72.Fn mac_vnode_create_extattr 73when a new filesystem object is created, so that suitable extended attributes 74can be written out, and 75.Fn mac_vnode_associate_extattr 76when a 77.Xr vnode 9 78is associated with a filesystem object for the first time. 79These utility functions use 80.Xr VOP_OPENEXTATTR 9 , 81.Xr VOP_READEXTATTR 9 , 82.Xr VOP_WRITEEXTATTR 9 , 83and 84.Xr VOP_CLOSEEXTATTR 9 85as required. 86.Ss Locking and Crash Safety 87In all cases, it is important that exclusive 88.Xr vnode 9 89locks be held to prevent concurrent access when a MAC label may not yet be 90initialized. 91It is also important that operations are ordered so that a system crash does 92not leave a file improperly labeled. 93For example, the extended attribute for a newly created file must be written 94to disk before the file is linked by its parent directory, so that there is 95no opportunity for a crash to lead to an unlabeled file. 96.Sh LOCKS 97The vnode will be locked on entry and should remain locked on return. 98.Sh RETURN VALUES 99If the MAC label is successfully set, then zero is returned. 100Otherwise, an appropriate error code is returned. 101.Sh ERRORS 102.Bl -tag -width Er 103.It Bq Er EOPNOTSUPP 104The file system does not support 105.Fn VOP_SETLABEL . 106.It Bq Er ENOSPC 107The file system is out of space. 108.It Bq Er EROFS 109The file system is read-only. 110.El 111.Pp 112Depending on the underlying implementation of 113.Fn VOP_SETLABEL , 114other errors may also be possible. 115.Sh SEE ALSO 116.Xr VOP_CLOSEEXTATTR 9 , 117.Xr VOP_OPENEXTATTR 9 , 118.Xr VOP_READEXTATTR 9 , 119.Xr VOP_WRITEXTATTR 9 , 120.Xr mac 9 , 121.Xr mount 9 , 122.Xr vnode 9 123.Sh AUTHORS 124This manual page was written by 125.An Robert Watson . 126