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