Debian Codegraph @

upstream/fedora-44/man2const/KEYCTL_GET_SECURITY.2const

raw
1 .\" Copyright 2016, Michael Kerrisk <[email protected]>
2 .\" Copyright 2016, Eugene Syromyatnikov <[email protected]>
3 .\" A very few fragments remain from an earlier version of this page
4 .\" written by David Howells ([email protected])
5 .\" Copyright 2024, Alejandro Colomar <[email protected]>
6 .\"
7 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
8 .\"
9 .TH KEYCTL_GET_SECURITY 2const 2024-08-21 "Linux man-pages 6.13"
10 .SH NAME
11 KEYCTL_GET_SECURITY
12 \-
13 manipulate the kernel's key management facility
14 .SH LIBRARY
15 Standard C library
16 .RI ( libc ,\~ \-lc )
17 .SH SYNOPSIS
18 .nf
19 .BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */"
20 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
21 .B #include <unistd.h>
22 .P
23 .BI "long syscall(SYS_keyctl, KEYCTL_GET_SECURITY, key_serial_t " key ,
24 .BI " char " buf "[_Nullable ." n "], size_t " n );
25 .fi
26 .SH DESCRIPTION
27 .TP
28 .BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)"
29 .\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
30 Get the LSM (Linux Security Module) security label of the specified key.
31 .P
32 The ID of the key whose security label is to be fetched is specified in
33 .IR key .
34 The security label (terminated by a null byte)
35 will be placed in the buffer pointed to by
36 .I buf
37 argument;
38 the size of the buffer must be provided in
39 .IR n .
40 .P
41 If
42 .I buf
43 is specified as NULL or the buffer size specified in
44 .I n
45 is too small, the full size of the security label string
46 (including the terminating null byte)
47 is returned as the function result,
48 and nothing is copied to the buffer.
49 .P
50 The caller must have
51 .I view
52 permission on the specified key.
53 .P
54 The returned security label string will be rendered in a form appropriate
55 to the LSM in force.
56 For example, with SELinux, it may look like:
57 .P
58 .in +4n
59 .EX
60 unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
61 .EE
62 .in
63 .P
64 If no LSM is currently in force,
65 then an empty string is placed in the buffer.
66 .SH RETURN VALUE
67 On success,
68 the size of the LSM security label string
69 (including the terminating null byte),
70 irrespective of the provided buffer size.
71 .P
72 On error, \-1 is returned, and
73 .I errno
74 is set to indicate the error.
75 .SH VERSIONS
76 A wrapper is provided in the
77 .I libkeyutils
78 library:
79 .BR keyctl_get_security (3).
80 .SH STANDARDS
81 Linux.
82 .SH HISTORY
83 Linux 2.6.26.
84 .SH SEE ALSO
85 .BR keyctl (2),
86 .BR keyctl_get_security (3),
87 .BR keyctl_get_security_alloc (3)