granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/security_label.sgml

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