Debian Codegraph @

upstream/debian-unstable/man2/SO_PEERSEC.2const

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH SO_PEERSEC 2const 2025-12-01 "Linux man-pages 6.18"
6 .SH NAME
7 SO_PEERSEC
8 \-
9 get the security context of a peer socker
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <sys/socket.h>
16 .P
17 .BI int\~getsockopt(int\~ sockfd ,\~SOL_SOCKET,\~SO_PEERSEC,
18 .BI " void\~" buf [ size ],\~size_t\~ size );
19 .fi
20 .SH DESCRIPTION
21 If labeled IPSEC or NetLabel is configured on both the sending and
22 receiving hosts, this read-only socket option returns the security
23 context of the peer socket connected to this socket.
24 By default,
25 this will be the same as the security context of the process that created
26 the peer socket unless overridden by the policy or by a process with
27 the required permissions.
28 .P
29 The argument to
30 .BR getsockopt (2)
31 is a pointer to a buffer of the specified length in bytes
32 into which the security context string will be copied.
33 If the buffer length is less than the length of the security
34 context string, then
35 .BR getsockopt (2)
36 returns \-1, sets
37 .I errno
38 to
39 .BR ERANGE ,
40 and returns the required length via
41 .IR size .
42 The caller should allocate at least
43 .B NAME_MAX
44 bytes for the buffer initially, although this is not guaranteed
45 to be sufficient.
46 Resizing the buffer to the returned length
47 and retrying may be necessary.
48 .P
49 The security context string may include a terminating null character
50 in the returned length, but is not guaranteed to do so: a security
51 context "foo" might be represented as either {'f','o','o'} of length 3
52 or {'f','o','o','\[rs]0'} of length 4, which are considered to be
53 interchangeable.
54 The string is printable,
55 does not contain non-terminating null characters,
56 and is in an unspecified encoding
57 (in particular,
58 it is not guaranteed to be ASCII or UTF-8).
59 .SS AF_UNIX
60 The use of this option for sockets in the
61 .B AF_UNIX
62 address family is supported since Linux 2.6.2 for connected stream sockets,
63 and since Linux 4.18
64 .\" commit 0b811db2cb2aabc910e53d34ebb95a15997c33e7
65 also for stream and datagram socket pairs created using
66 .BR socketpair (2).
67 .SS AF_INET
68 For
69 .B AF_INET
70 sockets,
71 labeled IPSEC or NetLabel needs to be configured
72 on both the sending and receiving hosts.
73 .P
74 The use of this option for sockets in the
75 .B AF_INET
76 address family is supported since Linux 2.6.17
77 .\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c
78 for TCP sockets,
79 and since Linux 4.17
80 .\" commit d452930fd3b9031e59abfeddb2fa383f1403d61a
81 for SCTP sockets.
82 .P
83 For SELinux, NetLabel conveys only the MLS portion of the security
84 context of the peer across the wire, defaulting the rest of the
85 security context to the values defined in the policy for the
86 netmsg initial security identifier (SID).
87 However, NetLabel can
88 be configured to pass full security contexts over loopback.
89 Labeled IPSEC always passes full security contexts as part of establishing
90 the security association (SA) and looks them up based on the association
91 for each packet.
92 .SH ERRORS
93 See
94 .BR SOL_SOCKET (2const).
95 See
96 .BR setsockopt (2).
97 See
98 .BR socket (7).
99 .TP
100 .B ERANGE
101 The buffer
102 .I size
103 is not enough.
104 .SH HISTORY
105 Linux 2.6.2.
106 .SH SEE ALSO
107 .BR SOL_SOCKET (2const),
108 .BR setsockopt (2),
109 .BR socket (7)