.\" Copyright 2016, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Copyright 2016, Eugene Syromyatnikov <evgsyr@gmail.com>
.\" A very few fragments remain from an earlier version of this page
.\" written by David Howells (dhowells@redhat.com)
.\" Copyright 2024, Alejandro Colomar <alx@kernel.org>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH KEYCTL_GET_SECURITY 2const 2024-08-21 "Linux man-pages 6.10"
.SH NAME
KEYCTL_GET_SECURITY
\-
manipulate the kernel's key management facility
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.BR "#include <linux/keyctl.h>" "  /* Definition of " KEY* " constants */"
.BR "#include <sys/syscall.h>" "   /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.P
.BI "long syscall(SYS_keyctl, KEYCTL_GET_SECURITY, key_serial_t " key ,
.BI "             char " buf "[_Nullable ." n "], size_t " n );
.fi
.SH DESCRIPTION
.TP
.BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)"
.\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
Get the LSM (Linux Security Module) security label of the specified key.
.P
The ID of the key whose security label is to be fetched is specified in
.IR key .
The security label (terminated by a null byte)
will be placed in the buffer pointed to by
.I buf
argument;
the size of the buffer must be provided in
.IR n .
.P
If
.I buf
is specified as NULL or the buffer size specified in
.I n
is too small, the full size of the security label string
(including the terminating null byte)
is returned as the function result,
and nothing is copied to the buffer.
.P
The caller must have
.I view
permission on the specified key.
.P
The returned security label string will be rendered in a form appropriate
to the LSM in force.
For example, with SELinux, it may look like:
.P
.in +4n
.EX
unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
.EE
.in
.P
If no LSM is currently in force,
then an empty string is placed in the buffer.
.SH RETURN VALUE
On success,
the size of the LSM security label string
(including the terminating null byte),
irrespective of the provided buffer size.
.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.SH VERSIONS
A wrapper is provided in the
.I libkeyutils
library:
.BR keyctl_get_security (3).
.SH STANDARDS
Linux.
.SH HISTORY
Linux 2.6.26.
.SH SEE ALSO
.BR keyctl (2),
.BR keyctl_get_security (3),
.BR keyctl_get_security_alloc (3)