.\"-
.\" Copyright (c) 2021 Robert N. M. Watson
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd February 27, 2021
.Dt VOP_SETLABEL 9
.Os
.Sh NAME
.Nm VOP_SETLABEL
.Nd persistently store an updated MAC label on a vnode
.Sh SYNOPSIS
.In sys/param.h
.In sys/vnode.h
.In security/mac.h
.Ft int
.Fn VOP_SETLABEL "struct vnode *vp" "label *label"
.Sh DESCRIPTION
This vnode call is made by
.Xr mac 9
file relabeling operation has been authorized, and the filesystem must now be
updated.
.Ss Single-Label vs. Multi-Label Filesystems
Filesystems that do not implement per-file labels -- known as single-label
filesystems -- can simply leave the
.Xr vnode 9
operation undefined.
These filesystems must not set the
.Dv MNT_MULTLABEL
flag in their
.Vt struct mount .
.Pp
Filesystems that do implement per-vnode label storage -- known as multi-label
filesystems -- will set the
.Dv MNT_MULTILABEL
flag in their
.Vt struct mount .
The UFS filesystem uses a superblock flag to persisently configure whether a
specific filesystem implements a label for each
.Xr vnode 9 ,
and then keys various behaviors on whether that flag is set.
.Ss Extended Attributes
If the filesystem implements extended attributes, then the MAC Framework's
.Fn vop_stdsetlabel_ea
function can be used, and maps operations into a series of
.Xr VOP_OPENEXTATTR 9 ,
.Xr VOP_WRITEEXTATTR 9 ,
and
.Xr VOP_CLOSEEXTATTR 9 .
.Pp
Filesystems will also need to call
.Fn mac_vnode_create_extattr
when a new filesystem object is created, so that suitable extended attributes
can be written out, and
.Fn mac_vnode_associate_extattr
when a
.Xr vnode 9
is associated with a filesystem object for the first time.
These utility functions use
.Xr VOP_OPENEXTATTR 9 ,
.Xr VOP_READEXTATTR 9 ,
.Xr VOP_WRITEEXTATTR 9 ,
and
.Xr VOP_CLOSEEXTATTR 9
as required.
.Pp
.Ss Locking and Crash Safety
In all cases, it is important that exclusive
.Xr vnode 9
locks be held to prevent concurrent access when a MAC label may not yet be
initialized.
It is also important that operations are ordered so that a system crash does
not leave a file improperly labeled.
For example, the extended attribute for a newly created file must be written
to disk before the file is linked by its parent directory, so that there is
no opportunity for a crash to lead to an unlabeled file.
.Sh LOCKS
The vnode will be locked on entry and should remain locked on return.
.Sh RETURN VALUES
If the MAC label is successfully set, then zero is returned.
Otherwise, an appropriate error code is returned.
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er EOPNOTSUPP
The file system does not support
.Fn VOP_SETLABEL .
.It Bq Er ENOSPC
The file system is out of space.
.It Bq Er EROFS
The file system is read-only.
.El
.Pp
Depending on the underlying implementation of
.Fn VOP_SETLABEL ,
other errors may also be possible.
.Sh SEE ALSO
.Xr VOP_CLOSEEXTATTR 9 ,
.Xr VOP_OPENEXTATTR 9 ,
.Xr VOP_READEXTATTR 9 ,
.Xr VOP_WRITEXTATTR 9 ,
.Xr mac 9 ,
.Xr mount 9 ,
.Xr vnode 9 ,
.Sh AUTHORS
This manual page was written by
.An Robert Watson .