[PATCH 22/22] shell: Documentation

[Sebastian Huber]

---
 doc/shell/Makefile.am |   2 +-
 doc/shell/confinit.t  | 132 +++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 131 insertions(+), 3 deletions(-)

diff --git a/doc/shell/Makefile.am b/doc/shell/Makefile.am
index a811f73..a16c886 100644
--- a/doc/shell/Makefile.am
+++ b/doc/shell/Makefile.am
@@ -24,7 +24,7 @@ confinit.texi: confinit.t
 	    -n "General Commands" < $< > $@
 
 general.texi: general.t
-	$(BMENU2) -p "Configuration and Initialization rtems_shell_init - initialize the shell" \
+	$(BMENU2) -p "Configuration and Initialization rtems_shell_login_check - Default login check handler" \
 	    -u "Top" \
 	    -n "File and Directory Commands" < $< > $@
 
diff --git a/doc/shell/confinit.t b/doc/shell/confinit.t
index eb85fe1..5ec9732 100644
--- a/doc/shell/confinit.t
+++ b/doc/shell/confinit.t
@@ -8,7 +8,7 @@
 @section Introduction
 
 This chapter provides information on how the application
-configures and intializes the RTEMS shell.
+configures and initializes the RTEMS shell.
 
 @c
 @c
@@ -213,13 +213,97 @@ is exited by the user, then control returns to the caller.
 
 TBD
 
+ at c
+ at c
+ at c
+ at section Access Control
+
+ at subsection Login Checks
+
+Login checks are optional for the RTEMS shell and can be configured via a login
+check handler passed to @code{rtems_shell_init()}.  One login check handler is
+ at code{rtems_shell_login_check()}.
+
+ at subsection Configuration Files
+
+The following files are used by the login check handler
+ at code{rtems_shell_login_check()} to validate a passphrase for a user and to set
+up the user environment for the shell command execution.
+
+ at table @file
+
+ at item /etc/passwd
+The format for each line is
+ at code{user_name:password:UID:GID:GECOS:directory:shell} with colon separated
+fields.  For more information refer to the Linux PASSWD(5) man page.  Use a
+ at code{password} of @code{*} to disable login of the user.  An empty password
+allows login without a password for this user.  In contrast to standard UNIX
+systems, this file is only readable and writeable for the user with an UID of
+zero by default.  The @code{directory} is used to perform a filesystem change
+root operation in @code{rtems_shell_login_check()} in contrast to a normal
+usage as the HOME directory of the user.
+
+ at item /etc/group
+The format for each line is @code{group_name:password:GID:user_list} with colon
+separated fields.  The @code{user_list} is comma separated.  For more
+information refer to the Linux GROUP(5) man page.  In contrast to standard UNIX
+systems, this file is only readable and writeable for the user with an UID of
+zero by default.
+
+ at end table
+
+ at subsection Command Visibility and Execution Permission
+
+Each command has
+
+ at itemize @bullet
+ at item an owner,
+ at item a group, and
+ at item a read permission flag for the owner, the group and all other users, and
+ at item an execution permission flag for the owner, the group and all other
+users.
+ at end itemize
+
+The read and write permission flags are stored in the command mode.  The read
+permission flags determine the visibility of the command for the current user.
+The execution permission flags determine the ability to execute a command for
+the current user.  The access is determined by the effective UID, the effective
+GID and the supplementary group IDs of the current user and follows the
+standard filesystem access procedure.
+
+ at subsection Add CRYPT(3) Formats
+
+By default the @code{crypt_r()} function used by
+ at code{rtems_shell_login_check()} supports only plain text passphrases.  Use
+ at code{crypt_add_format()} to add more formats.  The following formats are
+available out of the box
+
+ at itemize @bullet
+ at item @code{crypt_md5_format},
+ at item @code{crypt_sha256_format}, and
+ at item @code{crypt_sha512_format}.
+ at end itemize
+
+An example follows.
+
+ at findex crypt_add_format
+ at example
+#include <crypt.h>
+
+void add_formats( void )
+@{
+  crypt_add_format( &crypt_md5_format );
+  crypt_add_format( &crypt_sha512_format );
+@}
+ at end example
+
 @section Functions
 
 This section describes the Shell related C functions which are 
 publicly available related to initialization and configuration.
 
 @page
- at subsection rtems_shell_init - initialize the shell
+ at subsection rtems_shell_init - Initialize the shell
 
 @cindex initialization
 
@@ -255,3 +339,47 @@ may return.
 There is one POSIX key necessary for all shell instances together and one POSIX
 key value pair per instance. You should make sure that your RTEMS configuration
 accounts for these resources.
+
+ at page
+ at subsection rtems_shell_login_check - Default login check handler
+
+ at cindex initialization
+
+ at subheading CALLING SEQUENCE:
+
+ at findex rtems_shell_login_check
+ at example
+bool rtems_shell_login_check(
+  const char *user,
+  const char *passphrase
+);
+ at end example
+
+ at subheading DIRECTIVE STATUS CODES:
+ at code{true} - login is allowed, and@*
+ at code{false} - otherwise.
+
+ at subheading DESCRIPTION:
+
+This function checks if the specified passphrase is valid for the specified user.
+
+ at subheading NOTES:
+
+As a side-effect if the specified passphrase is valid for the specified user,
+this function
+
+ at itemize @bullet
+ at item performs a filesystem change root operation to the directory of the
+specified user if the directory path is non-empty,
+ at item changes the owner of the current shell device to the UID of the specified
+user,
+ at item sets the real and effective UID of the current user environment to the
+UID of the specified user,
+ at item sets the real and effective GID of the current user environment to the
+GID of the specified user, and
+ at item sets the supplementary group IDs of the current user environment to the
+supplementary group IDs of the specified user.
+ at end itemize
+
+In case the filesystem change root operation fails, then the environment setup
+is aborted and @code{false} is returned.
-- 
1.8.4.5