Adding upstream version 1.8.27.upstream/1.8.27upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 201 insertions, 0 deletions

diff --git a/doc/sudoers_timestamp.cat b/doc/sudoers_timestamp.cat
new file mode 100644
index 0000000..cf87d70
--- /dev/null
+++ b/doc/sudoers_timestamp.cat
@@ -0,0 +1,201 @@
+SUDOERS_TIMESTAMP(4)          File Formats Manual         SUDOERS_TIMESTAMP(4)
+
+NNAAMMEE
+     ssuuddooeerrss__ttiimmeessttaammpp - Sudoers Time Stamp Format
+
+DDEESSCCRRIIPPTTIIOONN
+     The ssuuddooeerrss plugin uses per-user time stamp files for credential caching.
+     Once a user has been authenticated, they may use ssuuddoo without a password
+     for a short period of time (5 minutes unless overridden by the
+     _t_i_m_e_s_t_a_m_p___t_i_m_e_o_u_t option).  By default, ssuuddooeerrss uses a separate record
+     for each terminal, which means that a user's login sessions are
+     authenticated separately.  The _t_i_m_e_s_t_a_m_p___t_y_p_e option can be used to
+     select the type of time stamp record ssuuddooeerrss will use.
+
+     A multi-record time stamp file format was introduced in ssuuddoo 1.8.10 that
+     uses a single file per user.  Previously, a separate file was used for
+     each user and terminal combination unless tty-based time stamps were
+     disabled.  The new format is extensible and records of multiple types and
+     versions may coexist within the same file.
+
+     All records, regardless of type or version, begin with a 16-bit version
+     number and a 16-bit record size.
+
+     Time stamp records have the following structure:
+
+     /* Time stamp entry types */
+     #define TS_GLOBAL               0x01    /* not restricted by tty or ppid */
+     #define TS_TTY                  0x02    /* restricted by tty */
+     #define TS_PPID                 0x03    /* restricted by ppid */
+     #define TS_LOCKEXCL             0x04    /* special lock record */
+
+     /* Time stamp flags */
+     #define TS_DISABLED             0x01    /* entry disabled */
+     #define TS_ANYUID               0x02    /* ignore uid, only valid in key */
+
+     struct timestamp_entry {
+         unsigned short version;     /* version number */
+         unsigned short size;        /* entry size */
+         unsigned short type;        /* TS_GLOBAL, TS_TTY, TS_PPID */
+         unsigned short flags;       /* TS_DISABLED, TS_ANYUID */
+         uid_t auth_uid;             /* uid to authenticate as */
+         pid_t sid;                  /* session ID associated with tty/ppid */
+         struct timespec start_time; /* session/ppid start time */
+         struct timespec ts;         /* time stamp (CLOCK_MONOTONIC) */
+         union {
+             dev_t ttydev;           /* tty device number */
+             pid_t ppid;             /* parent pid */
+         } u;
+     };
+
+     The timestamp_entry struct fields are as follows:
+
+     version
+           The version number of the timestamp_entry struct.  New entries are
+           created with a version number of 2.  Records with different version
+           numbers may coexist in the same file but are not inter-operable.
+
+     size  The size of the record in bytes.
+
+     type  The record type, currently TS_GLOBAL, TS_TTY, or TS_PPID.
+
+     flags
+           Zero or more record flags which can be bit-wise ORed together.
+           Supported flags are TS_DISABLED, for records disabled via ssuuddoo --kk
+           and TS_ANYUID, which is used only when matching records.
+
+     auth_uid
+           The user ID that was used for authentication.  Depending on the
+           value of the _r_o_o_t_p_w, _r_u_n_a_s_p_w and _t_a_r_g_e_t_p_w options, the user ID may
+           be that of the invoking user, the root user, the default runas user
+           or the target user.
+
+     sid   The ID of the user's terminal session, if present.  The session ID
+           is only used when matching records of type TS_TTY.
+
+     start_time
+           The start time of the session leader for records of type TS_TTY or
+           of the parent process for records of type TS_PPID.  The _s_t_a_r_t___t_i_m_e
+           is used to help prevent re-use of a time stamp record after a user
+           has logged out.  Not all systems support a method to easily
+           retrieve a process's start time.  The _s_t_a_r_t___t_i_m_e field was added in
+           ssuuddooeerrss version 1.8.22 for the second revision of the
+           timestamp_entry struct.
+
+     ts    The actual time stamp.  A monotonic time source (which does not
+           move backward) is used if the system supports it.  Where possible,
+           ssuuddooeerrss uses a monotonic timer that increments even while the
+           system is suspended.  The value of _t_s is updated each time a
+           command is run via ssuuddoo.  If the difference between _t_s and the
+           current time is less than the value of the _t_i_m_e_s_t_a_m_p___t_i_m_e_o_u_t
+           option, no password is required.
+
+     u.ttydev
+           The device number of the terminal associated with the session for
+           records of type TS_TTY.
+
+     u.ppid
+           The ID of the parent process for records of type TS_PPID.
+
+LLOOCCKKIINNGG
+     In ssuuddooeerrss versions 1.8.10 through 1.8.14, the entire time stamp file was
+     locked for exclusive access when reading or writing to the file.
+     Starting in ssuuddooeerrss 1.8.15, individual records are locked in the time
+     stamp file instead of the entire file and the lock is held for a longer
+     period of time.  This scheme is described below.
+
+     The first record in the time stamp file is of type TS_LOCKEXCL and is
+     used as a _l_o_c_k record to prevent more than one ssuuddoo process from adding a
+     new record at the same time.  Once the desired time stamp record has been
+     located or created (and locked), the TS_LOCKEXCL record is unlocked.  The
+     lock on the individual time stamp record, however, is held until
+     authentication is complete.  This allows ssuuddooeerrss to avoid prompting for a
+     password multiple times when it is used more than once in a pipeline.
+
+     Records of type TS_GLOBAL cannot be locked for a long period of time
+     since doing so would interfere with other ssuuddoo processes.  Instead, a
+     separate lock record is used to prevent multiple ssuuddoo processes using the
+     same terminal (or parent process ID) from prompting for a password as the
+     same time.
+
+SSEEEE AALLSSOO
+     sudoers(4), sudo(1m)
+
+HHIISSTTOORRYY
+     Originally, ssuuddoo used a single zero-length file per user and the file's
+     modification time was used as the time stamp.  Later versions of ssuuddoo
+     added restrictions on the ownership of the time stamp files and directory
+     as well as sanity checks on the time stamp itself.  Notable changes were
+     introduced in the following ssuuddoo versions:
+
+     1.4.0
+           Support for tty-based time stamp file was added by appending the
+           terminal name to the time stamp file name.
+
+     1.6.2
+           The time stamp file was replaced by a per-user directory which
+           contained any tty-based time stamp files.
+
+     1.6.3p2
+           The target user name was added to the time stamp file name when the
+           _t_a_r_g_e_t_p_w option was set.
+
+     1.7.3
+           Information about the terminal device was stored in tty-based time
+           stamp files for sanity checking.  This included the terminal device
+           numbers, inode number and, on systems where it was not updated when
+           the device was written to, the inode change time.  This helped
+           prevent re-use of the time stamp file after logout.
+
+     1.8.6p7
+           The terminal session ID was added to tty-based time stamp files to
+           prevent re-use of the time stamp by the same user in a different
+           terminal session.  It also helped prevent re-use of the time stamp
+           file on systems where the terminal device's inode change time was
+           updated by writing.
+
+     1.8.10
+           A new, multi-record time stamp file format was introduced that uses
+           a single file per user.  The terminal device's change time was not
+           included since most systems now update the change time after a
+           write is performed as required by POSIX.
+
+     1.8.15
+           Individual records are locked in the time stamp file instead of the
+           entire file and the lock is held until authentication is complete.
+
+     1.8.22
+           The start time of the terminal session leader or parent process is
+           now stored in non-global time stamp records.  This prevents re-use
+           of the time stamp file after logout in most cases.
+
+           Support was added for the kernel-based tty time stamps available in
+           OpenBSD which do not use an on-disk time stamp file.
+
+AAUUTTHHOORRSS
+     Many people have worked on ssuuddoo over the years; this version consists of
+     code written primarily by:
+
+           Todd C. Miller
+
+     See the CONTRIBUTORS file in the ssuuddoo distribution
+     (https://www.sudo.ws/contributors.html) for an exhaustive list of people
+     who have contributed to ssuuddoo.
+
+BBUUGGSS
+     If you feel you have found a bug in ssuuddoo, please submit a bug report at
+     https://bugzilla.sudo.ws/
+
+SSUUPPPPOORRTT
+     Limited free support is available via the sudo-users mailing list, see
+     https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
+     the archives.
+
+DDIISSCCLLAAIIMMEERR
+     ssuuddoo is provided "AS IS" and any express or implied warranties,
+     including, but not limited to, the implied warranties of merchantability
+     and fitness for a particular purpose are disclaimed.  See the LICENSE
+     file distributed with ssuuddoo or https://www.sudo.ws/license.html for
+     complete details.
+
+Sudo 1.8.26                     October 7, 2018                    Sudo 1.8.26