x_contexts(5)

1selabel_x(5)               SELinux API documentation              selabel_x(5)
2
3
4

NAME

6       selabel_x - userspace SELinux labeling interface and configuration file
7       format for the X Window System contexts backend. This backend  is  also
8       used to determine the default context for labeling remotely connected X
9       clients
10

SYNOPSIS

12       #include <selinux/label.h>
13
14       int selabel_lookup(struct selabel_handle *hnd,
15                          char **context,
16                          const char *object_name, int object_type);
17
18       int selabel_lookup_raw(struct selabel_handle *hnd,
19                          char **context,
20                          const char *object_name, int object_type);
21

DESCRIPTION

23       The X contexts backend maps from X  Window  System  object  names  into
24       security  contexts.  It  is  used to find the appropriate context for X
25       Window System objects whose significance  and/or  usage  semantics  are
26       determined  primarily by name. The returned context must be freed using
27       freecon(3).
28       selabel_lookup(3) describes the function  with  its  return  and  error
29       codes.
30
31       This backend is also used to determine the default context for labeling
32       remotely connected X clients.
33
34       The object_type argument should be set to one of the following values:
35
36              SELABEL_X_PROP
37                     The object_name argument specifies the name of  a  window
38                     property, such as "WM_NAME".
39
40              SELABEL_X_SELN
41                     The  object_name  argument specifies the name of a selec‐
42                     tion, such as "PRIMARY".
43
44              SELABEL_X_EXT
45                     The object_name argument specifies the name of a protocol
46                     extension, such as "RENDER".
47
48              SELABEL_X_EVENT
49                     The  object_name  argument specifies the name of an event
50                     type, such as "X11:ButtonPress".
51
52              SELABEL_X_CLIENT
53                     The object_name argument is ignored, however it should be
54                     set  to  either  *  (an  asterisk or 'wildcard' that will
55                     select the default entry) or a  specific  entry  such  as
56                     "remote"  in  the X contexts file as shown in the EXAMPLE
57                     section.  The  default  context  for  labeling  remote  X
58                     clients is then returned.
59
60              SELABEL_X_POLYPROP
61                     Like  SELABEL_X_PROP,  but  checks  if  the  property was
62                     marked as being polyinstantiated. See NOTES below.
63
64              SELABEL_X_POLYSELN
65                     Like SELABEL_X_SELN, but  checks  if  the  selection  was
66                     marked as being polyinstantiated. See NOTES below.
67
68       Any  messages  generated  by  selabel_lookup(3)  are  sent to stderr by
69       default, although this can be changed by selinux_set_callback(3).
70
71       selabel_lookup_raw behaves identically to selabel_lookup but  does  not
72       perform context translation.
73
74       The FILES section details the configuration files used to determine the
75       X object context.
76

OPTIONS

78       In addition to the global options described  in  selabel_open(3),  this
79       backend recognizes the following options:
80
81              SELABEL_OPT_PATH
82                     A  non-null  value  for this option specifies a path to a
83                     file that will be opened in lieu of the standard  X  con‐
84                     texts file (see the FILES section for details).
85

FILES

87       The  X  context  file used to retrieve a default context depends on the
88       SELABEL_OPT_PATH parameter passed to selabel_open(3). If NULL, then the
89       SELABEL_OPT_PATH  value  will  default  to the active policy X contexts
90       location (as  returned  by  selinux_x_context_path(3)),  otherwise  the
91       actual SELABEL_OPT_PATH value specified is used.
92
93       The default X object contexts file is:
94              /etc/selinux/{SELINUXTYPE}/contexts/x_contexts
95
96       Where  {SELINUXTYPE}  is  the entry from the selinux configuration file
97       config (see selinux_config(5)).
98
99       The entries within the X contexts file are shown  in  the  Object  Name
100       String Values and FILE FORMAT sections.
101

Object Name String Values

103       The  string  name  assigned  to  each  object_type argument that can be
104       present in the X contexts file are:
105
106                        ┌───────────────────┬────────────────┐
107                        │object_type        │ Text Name      │
108                        ├───────────────────┼────────────────┤
109                        │SELABEL_X_PROP     │ property       │
110                        ├───────────────────┼────────────────┤
111                        │SELABEL_X_SELN     │ selection      │
112                        ├───────────────────┼────────────────┤
113                        │SELABEL_X_EXT      │ extension      │
114                        ├───────────────────┼────────────────┤
115                        │SELABEL_X_EVENT    │ event          │
116                        ├───────────────────┼────────────────┤
117                        │SELABEL_X_CLIENT   │ client         │
118                        ├───────────────────┼────────────────┤
119                        │SELABEL_X_POLYPROP │ poly_property  │
120                        ├───────────────────┼────────────────┤
121                        │SELABEL_X_POLYSELN │ poly_selection │
122                        └───────────────────┴────────────────┘

FILE FORMAT

124       Each line within the X contexts file is as follows:
125              object_type object_name context
126
127       Where:
128              object_type
129                     This is the string  representation  of  the  object  type
130                     shown  in  the  Object Name String Values section.  There
131                     can be multiple lines with the  same  object_type  string
132                     that  will form a block of entries (each with a different
133                     object_name entry).
134              object_name
135                     These are the  object  names  of  the  specific  X-server
136                     resource  such as PRIMARY, CUT_BUFFER0 etc. They are gen‐
137                     erally defined in the X-server source code  (protocol.txt
138                     and  BuiltInAtoms in the dix directory of the xorg-server
139                     source package).  The entry can contain '*' for  wildcard
140                     matching  or  '?' for substitution.  Note that if the '*'
141                     is used, then be aware that the order of entries  in  the
142                     file is important. The '*' on its own is used to ensure a
143                     default fallback context is assigned and  should  be  the
144                     last entry in the object_type block.
145              context
146                     The security context that will be applied to the object.
147
148       Example 1:
149
150       # object_type  object_name  context
151       selection      PRIMARY      system_u:object_r:clipboard_xselection_t:s0
152       selection      *            system_u:object_r:xselection_t:s0
153
154       Example  2 - This example shows how a client entry can be configured to
155       ensure an entry is always found:
156
157       # object_type  object_name  context
158       client         *            system_u:object_r:remote_t:s0
159

NOTES

161       1.  Properties and selections are marked as either polyinstantiated  or
162           not.  For  these  name  types,  the "POLY" option searches only the
163           names marked as being  polyinstantiated,  while  the  other  option
164           searches only the names marked as not being polyinstantiated. Users
165           of the interface should  check  both  mappings,  optionally  taking
166           action based on the result (e.g. polyinstantiating the object).
167
168       2.  If  contexts  are  to  be  validated,  then the global option SELA‐
169           BEL_OPT_VALIDATE must be set  before  calling  selabel_open(3).  If
170           this  is  not set, then it is possible for an invalid context to be
171           returned.
172