8:15 p.m.
commit aea290af6d2de6a493e952b9ef8c771ab9014fef
Author: Dmitry V. Levin <ldv(a)altlinux.org>
Date: Tue Oct 19 23:34:52 2010 +0000
pam_selinux.8.xml: update
* modules/pam_selinux/pam_selinux.8.xml (pam_selinux-cmdsynopsis):
Reorder options, add new "restore" option.
pam_selinux-description): Rewrite.
(pam_selinux-options): Reorder options, describe new "restore" option.
(pam_selinux-return_values): Remove PAM_AUTH_ERR, PAM_SESSION_ERR
and PAM_BUF_ERR.
(pam_selinux-see_also): Remove pam.conf(5). Add execve(2), tty(4)
and selinux(8).
modules/pam_selinux/pam_selinux.8.xml | 113 +++++++++++++++++++++-----------
1 files changed, 74 insertions(+), 39 deletions(-)
---
diff --git a/modules/pam_selinux/pam_selinux.8.xml
b/modules/pam_selinux/pam_selinux.8.xml
index 2c1cdb2..28d465f 100644
--- a/modules/pam_selinux/pam_selinux.8.xml
+++ b/modules/pam_selinux/pam_selinux.8.xml
@@ -19,18 +19,21 @@
<cmdsynopsis id="pam_selinux-cmdsynopsis">
<command>pam_selinux.so</command>
<arg choice="opt">
- close
+ open
</arg>
<arg choice="opt">
- debug
+ close
</arg>
<arg choice="opt">
- open
+ restore
</arg>
<arg choice="opt">
nottys
</arg>
<arg choice="opt">
+ debug
+ </arg>
+ <arg choice="opt">
verbose
</arg>
<arg choice="opt">
@@ -48,26 +51,31 @@
<refsect1 id="pam_selinux-description">
<title>DESCRIPTION</title>
<para>
- In a nutshell, pam_selinux sets up the default security context for the
- next execed shell.
+ pam_selinux is a PAM module that sets up the default SELinux security
+ context for the next executed process.
+ </para>
+ <para>
+ When a new session is started, the open_session part of the module
+ computes and sets up the execution security context used for the next
+ <citerefentry>
+
<refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
+ </citerefentry>
+ call, the file security context for the controlling terminal, and
+ the security context used for creating a new kernel keyring.
</para>
<para>
- When an application opens a session using pam_selinux, the shell that
- gets executed will be run in the default security context, or if the
- user chooses and the pam file allows the selected security context.
- Also the controlling tty will have it's security context modified to
- match the users.
+ When the session is ended, the close_session part of the module restores
+ old security contexts that were in effect before the change made
+ by the open_session part of the module.
</para>
<para>
- Adding pam_selinux into a pam file could cause other pam modules to
- change their behavior if the exec another application. The close and
- open option help mitigate this problem. close option will only cause
- the close portion of the pam_selinux to execute, and open will only
- cause the open portion to run. You can add pam_selinux to the config
- file twice. Add the pam_selinux close as the executes the open pass
- through the modules, pam_selinux open_session will happen last.
- When PAM executes the close pass through the modules pam_selinux
- close_session will happen first.
+ Adding pam_selinux into the PAM stack might disrupt behavior of other
+ PAM modules which execute applications. To avoid that,
+ <emphasis>pam_selinux.so open</emphasis> should be placed after such
+ modules in the PAM stack, and <emphasis>pam_selinux.so
close</emphasis>
+ should be placed before them. When such a placement is not feasible,
+ <emphasis>pam_selinux.so restore</emphasis> could be used to temporary
+ restore original security contexts.
</para>
</refsect1>
@@ -76,34 +84,34 @@
<variablelist>
<varlistentry>
<term>
- <option>close</option>
+ <option>open</option>
</term>
<listitem>
<para>
- Only execute the close_session portion of the module.
+ Only execute the open_session part of the module.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <option>debug</option>
+ <option>close</option>
</term>
<listitem>
<para>
- Turns on debugging via
- <citerefentry>
-
<refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
- </citerefentry>.
+ Only execute the close_session part of the module.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <option>open</option>
+ <option>restore</option>
</term>
<listitem>
<para>
- Only execute the open_session portion of the module.
+ In open_session part of the module, temporarily restore the
+ security contexts as they were before the previous call of
+ the module. Another call of this module without the restore
+ option will set up the new security contexts again.
</para>
</listitem>
</varlistentry>
@@ -113,7 +121,20 @@
</term>
<listitem>
<para>
- Do not try to setup the ttys security context.
+ Do not setup security context of the controlling terminal.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>debug</option>
+ </term>
+ <listitem>
+ <para>
+ Turn on debug messages via
+ <citerefentry>
+
<refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
</para>
</listitem>
</varlistentry>
@@ -123,7 +144,7 @@
</term>
<listitem>
<para>
- attempt to inform the user when security context is set.
+ Attempt to inform the user when security context is set.
</para>
</listitem>
</varlistentry>
@@ -134,7 +155,7 @@
<listitem>
<para>
Attempt to ask the user for a custom security context role.
- If MLS is on ask also for sensitivity level.
+ If MLS is on, ask also for sensitivity level.
</para>
</listitem>
</varlistentry>
@@ -145,11 +166,11 @@
<listitem>
<para>
Attempt to obtain a custom security context role from PAM environment.
- If MLS is on obtain also sensitivity level. This option and the
- select_context option are mutually exclusive. The respective PAM
+ If MLS is on, obtain also sensitivity level. This option and the
+ select_context option are mutually exclusive. The respective PAM
environment variables are
<emphasis>SELINUX_ROLE_REQUESTED</emphasis>,
<emphasis>SELINUX_LEVEL_REQUESTED</emphasis>, and
- <emphasis>SELINUX_USE_CURRENT_RANGE</emphasis>. The first two
variables
+ <emphasis>SELINUX_USE_CURRENT_RANGE</emphasis>. The first two
variables
are self describing and the last one if set to 1 makes the PAM module behave
as
if the use_current_range was specified on the command line of the module.
</para>
@@ -181,18 +202,18 @@
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
- <term>PAM_AUTH_ERR</term>
+ <term>PAM_SUCCESS</term>
<listitem>
<para>
- Unable to get or set a valid context.
+ The security context was set successfully.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>PAM_SUCCESS</term>
+ <term>PAM_SESSION_ERR</term>
<listitem>
<para>
- The security context was set successfully.
+ Unable to get or set a valid context.
</para>
</listitem>
</varlistentry>
@@ -204,6 +225,14 @@
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>PAM_BUF_ERR</term>
+ <listitem>
+ <para>
+ Memory allocation error.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
@@ -220,13 +249,19 @@ session optional pam_selinux.so
<title>SEE ALSO</title>
<para>
<citerefentry>
- <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
+ <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>tty</refentrytitle><manvolnum>4</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>selinux</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>