Debian Codegraph @

doc/src/sgml/ref/security_label.sgml

raw
1 <!--
2 doc/src/sgml/ref/security_label.sgml
3 PostgreSQL documentation
4 -->
5
6 <refentry id="sql-security-label">
7 <indexterm zone="sql-security-label">
8 <primary>SECURITY LABEL</primary>
9 </indexterm>
10
11 <refmeta>
12 <refentrytitle>SECURITY LABEL</refentrytitle>
13 <manvolnum>7</manvolnum>
14 <refmiscinfo>SQL - Language Statements</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18 <refname>SECURITY LABEL</refname>
19 <refpurpose>define or change a security label applied to an object</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23 <synopsis>
24 SECURITY LABEL [ FOR <replaceable class="parameter">provider</replaceable> ] ON
25 {
26 TABLE <replaceable class="parameter">object_name</replaceable> |
27 COLUMN <replaceable class="parameter">table_name</replaceable>.<replaceable class="parameter">column_name</replaceable> |
28 AGGREGATE <replaceable class="parameter">aggregate_name</replaceable> ( <replaceable>aggregate_signature</replaceable> ) |
29 DATABASE <replaceable class="parameter">object_name</replaceable> |
30 DOMAIN <replaceable class="parameter">object_name</replaceable> |
31 EVENT TRIGGER <replaceable class="parameter">object_name</replaceable> |
32 FOREIGN TABLE <replaceable class="parameter">object_name</replaceable> |
33 FUNCTION <replaceable class="parameter">function_name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] |
34 LARGE OBJECT <replaceable class="parameter">large_object_oid</replaceable> |
35 MATERIALIZED VIEW <replaceable class="parameter">object_name</replaceable> |
36 [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">object_name</replaceable> |
37 PROCEDURE <replaceable class="parameter">procedure_name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] |
38 PUBLICATION <replaceable class="parameter">object_name</replaceable> |
39 ROLE <replaceable class="parameter">object_name</replaceable> |
40 ROUTINE <replaceable class="parameter">routine_name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] |
41 SCHEMA <replaceable class="parameter">object_name</replaceable> |
42 SEQUENCE <replaceable class="parameter">object_name</replaceable> |
43 SUBSCRIPTION <replaceable class="parameter">object_name</replaceable> |
44 TABLESPACE <replaceable class="parameter">object_name</replaceable> |
45 TYPE <replaceable class="parameter">object_name</replaceable> |
46 VIEW <replaceable class="parameter">object_name</replaceable>
47 } IS { <replaceable class="parameter">string_literal</replaceable> | NULL }
48
49 <phrase>where <replaceable>aggregate_signature</replaceable> is:</phrase>
50
51 * |
52 [ <replaceable>argmode</replaceable> ] [ <replaceable>argname</replaceable> ] <replaceable>argtype</replaceable> [ , ... ] |
53 [ [ <replaceable>argmode</replaceable> ] [ <replaceable>argname</replaceable> ] <replaceable>argtype</replaceable> [ , ... ] ] ORDER BY [ <replaceable>argmode</replaceable> ] [ <replaceable>argname</replaceable> ] <replaceable>argtype</replaceable> [ , ... ]
54 </synopsis>
55 </refsynopsisdiv>
56
57 <refsect1>
58 <title>Description</title>
59
60 <para>
61 <command>SECURITY LABEL</command> applies a security label to a database
62 object. An arbitrary number of security labels, one per label provider, can
63 be associated with a given database object. Label providers are loadable
64 modules which register themselves by using the function
65 <function>register_label_provider</function>.
66 </para>
67
68 <note>
69 <para>
70 <function>register_label_provider</function> is not an SQL function; it can
71 only be called from C code loaded into the backend.
72 </para>
73 </note>
74
75 <para>
76 The label provider determines whether a given label is valid and whether
77 it is permissible to assign that label to a given object. The meaning of a
78 given label is likewise at the discretion of the label provider.
79 <productname>PostgreSQL</productname> places no restrictions on whether or how a
80 label provider must interpret security labels; it merely provides a
81 mechanism for storing them. In practice, this facility is intended to allow
82 integration with label-based mandatory access control (MAC) systems such as
83 <productname>SELinux</productname>. Such systems make all access control decisions
84 based on object labels, rather than traditional discretionary access control
85 (DAC) concepts such as users and groups.
86 </para>
87
88 <para>
89 You must own the database object to use <command>SECURITY LABEL</command>.
90 </para>
91 </refsect1>
92
93 <refsect1>
94 <title>Parameters</title>
95
96 <variablelist>
97 <varlistentry>
98 <term><replaceable class="parameter">object_name</replaceable></term>
99 <term><replaceable class="parameter">table_name.column_name</replaceable></term>
100 <term><replaceable class="parameter">aggregate_name</replaceable></term>
101 <term><replaceable class="parameter">function_name</replaceable></term>
102 <term><replaceable class="parameter">procedure_name</replaceable></term>
103 <term><replaceable class="parameter">routine_name</replaceable></term>
104 <listitem>
105 <para>
106 The name of the object to be labeled. Names of objects that reside in
107 schemas (tables, functions, etc.) can be schema-qualified.
108 </para>
109 </listitem>
110 </varlistentry>
111
112 <varlistentry>
113 <term><replaceable class="parameter">provider</replaceable></term>
114 <listitem>
115 <para>
116 The name of the provider with which this label is to be associated. The
117 named provider must be loaded and must consent to the proposed labeling
118 operation. If exactly one provider is loaded, the provider name may be
119 omitted for brevity.
120 </para>
121 </listitem>
122 </varlistentry>
123
124 <varlistentry>
125 <term><replaceable class="parameter">argmode</replaceable></term>
126
127 <listitem>
128 <para>
129 The mode of a function, procedure, or aggregate
130 argument: <literal>IN</literal>, <literal>OUT</literal>,
131 <literal>INOUT</literal>, or <literal>VARIADIC</literal>.
132 If omitted, the default is <literal>IN</literal>.
133 Note that <command>SECURITY LABEL</command> does not actually
134 pay any attention to <literal>OUT</literal> arguments, since only the input
135 arguments are needed to determine the function's identity.
136 So it is sufficient to list the <literal>IN</literal>, <literal>INOUT</literal>,
137 and <literal>VARIADIC</literal> arguments.
138 </para>
139 </listitem>
140 </varlistentry>
141
142 <varlistentry>
143 <term><replaceable class="parameter">argname</replaceable></term>
144
145 <listitem>
146 <para>
147 The name of a function, procedure, or aggregate argument.
148 Note that <command>SECURITY LABEL</command> does not actually
149 pay any attention to argument names, since only the argument data
150 types are needed to determine the function's identity.
151 </para>
152 </listitem>
153 </varlistentry>
154
155 <varlistentry>
156 <term><replaceable class="parameter">argtype</replaceable></term>
157
158 <listitem>
159 <para>
160 The data type of a function, procedure, or aggregate argument.
161 </para>
162 </listitem>
163 </varlistentry>
164
165 <varlistentry>
166 <term><replaceable class="parameter">large_object_oid</replaceable></term>
167 <listitem>
168 <para>
169 The OID of the large object.
170 </para>
171 </listitem>
172 </varlistentry>
173
174 <varlistentry>
175 <term><literal>PROCEDURAL</literal></term>
176
177 <listitem>
178 <para>
179 This is a noise word.
180 </para>
181 </listitem>
182 </varlistentry>
183
184 <varlistentry>
185 <term><replaceable class="parameter">string_literal</replaceable></term>
186 <listitem>
187 <para>
188 The new setting of the security label, written as a string literal.
189 </para>
190 </listitem>
191 </varlistentry>
192
193 <varlistentry>
194 <term><literal>NULL</literal></term>
195 <listitem>
196 <para>
197 Write <literal>NULL</literal> to drop the security label.
198 </para>
199 </listitem>
200 </varlistentry>
201 </variablelist>
202 </refsect1>
203
204 <refsect1>
205 <title>Examples</title>
206
207 <para>
208 The following example shows how the security label of a table could
209 be set or changed:
210
211 <programlisting>
212 SECURITY LABEL FOR selinux ON TABLE mytable IS 'system_u:object_r:sepgsql_table_t:s0';
213 </programlisting>
214
215 To remove the label:
216
217 <programlisting>
218 SECURITY LABEL FOR selinux ON TABLE mytable IS NULL;
219 </programlisting>
220 </para>
221 </refsect1>
222
223 <refsect1>
224 <title>Compatibility</title>
225 <para>
226 There is no <command>SECURITY LABEL</command> command in the SQL standard.
227 </para>
228 </refsect1>
229
230 <refsect1>
231 <title>See Also</title>
232 <simplelist type="inline">
233 <member><xref linkend="sepgsql"/></member>
234 <member><filename>src/test/modules/dummy_seclabel</filename></member>
235 </simplelist>
236 </refsect1>
237 </refentry>