Document the sudoers time stamp file format.

MANIFEST

@@ -40,6 +40,9 @@ doc/sudoers.ldap.man.in
 doc/sudoers.ldap.mdoc.in
 doc/sudoers.man.in
 doc/sudoers.mdoc.in
+doc/sudoers_timestamp.cat
+doc/sudoers_timestamp.man.in
+doc/sudoers_timestamp.mdoc.in
 doc/sudoreplay.cat
 doc/sudoreplay.man.in
 doc/sudoreplay.mdoc.in

doc/Makefile.in

@@ -70,6 +70,7 @@ SHELL = @SHELL@
 DOCS =	$(mansrcdir)/sudo.$(mantype) $(mansrcdir)/visudo.$(mantype) \
 	$(mansrcdir)/sudo.conf.$(mantype) $(mansrcdir)/sudoers.$(mantype) \
 	$(mansrcdir)/sudoers.ldap.$(mantype) $(mansrcdir)/sudoers.$(mantype) \
+	$(mansrcdir)/sudoers_timestamp.$(mantype) \
 	$(mansrcdir)/sudoreplay.$(mantype) $(mansrcdir)/sudo_plugin.$(mantype)
 
 DEVDOCS = $(srcdir)/sudo.man.in $(srcdir)/sudo.cat \
@@ -78,6 +79,7 @@ DEVDOCS = $(srcdir)/sudo.man.in $(srcdir)/sudo.cat \
 	  $(srcdir)/sudoers.man.in $(srcdir)/sudoers.cat \
 	  $(srcdir)/sudoers.ldap.man.in $(srcdir)/sudoers.ldap.cat \
 	  $(srcdir)/sudoers.man.in $(srcdir)/sudoers.cat \
+	  $(srcdir)/sudoers_timestamp.man.in $(srcdir)/sudoers_timestamp.cat \
 	  $(srcdir)/sudoreplay.man.in $(srcdir)/sudoreplay.cat \
 	  $(srcdir)/sudo_plugin.man.in $(srcdir)/sudo_plugin.cat
 
@@ -252,6 +254,40 @@ $(srcdir)/sudoreplay.man.in: $(srcdir)/sudoreplay.mdoc.in
 	    $(SED) -e "s/$$mansectsu/8/g" -e "s/$$mansectform/5/g" $(srcdir)/sudoreplay.mdoc.in | $(MANDOC) -Tman | $(SED) -e 's/^\(\.TH "SUDOREPLAY" \)"8"\(.*"\)OpenBSD \(.*\)/\1"'$$mansectsu'"\2\3/' -e "s/(5)/($$mansectform)/g" -e "s/(8)/($$mansectsu)/g" >> $@; \
 	fi
 
+$(srcdir)/sudoers_timestamp.man.in: $(srcdir)/sudoers_timestamp.mdoc.in
+	@if [ -n "$(DEVEL)" ]; then \
+	    echo "Generating $@"; \
+	    mansectsu=`echo @MANSECTSU@|$(TR) A-Z a-z`; \
+	    mansectform=`echo @MANSECTFORM@|$(TR) A-Z a-z`; \
+	    printf '.\\" DO NOT EDIT THIS FILE, IT IS NOT THE MASTER!\n' > $@; \
+	    printf '.\\" IT IS GENERATED AUTOMATICALLY FROM sudoers_timestamp.mdoc.in\n' >> $@; \
+	    $(SED) -n -e '/^.Dd/q' -e '/^\.\\/p' $(srcdir)/sudoers_timestamp.mdoc.in >> $@; \
+	    $(SED) -e "s/$$mansectsu/8/g" -e "s/$$mansectform/5/g" $(srcdir)/sudoers_timestamp.mdoc.in | $(MANDOC) -Tman | $(SED) -e 's/^\(\.TH "SUDOERS.LDAP" \)"5"\(.*"\)OpenBSD \(.*\)/\1"'$$mansectsu'"\2\3/' -e "s/(5)/($$mansectform)/g" -e "s/(8)/($$mansectsu)/g" >> $@; \
+	fi
+
+$(mansrcdir)/sudoers_timestamp.man: $(top_builddir)/config.status $(srcdir)/sudoers_timestamp.man.in
+	cd $(top_builddir) && $(SHELL) config.status --file=doc/$@
+
+$(mansrcdir)/sudoers_timestamp.mdoc: $(top_builddir)/config.status $(srcdir)/sudoers_timestamp.mdoc.in
+	cd $(top_builddir) && $(SHELL) config.status --file=doc/$@
+
+$(srcdir)/sudoers_timestamp.cat: varsub $(srcdir)/sudoers_timestamp.mdoc.in
+	@if [ -n "$(DEVEL)" ]; then \
+	    echo "Generating $@"; \
+	    $(SED) -f varsub $(srcdir)/sudoers_timestamp.mdoc.in | $(MANDOC) -Tascii -mdoc | $(SED) -e 's/ OpenBSD \([^ ].*  \)/     \1    /' -e 's/(5)/(4)/g' -e 's/(8)/(1m)/g' > $@; \
+	fi
+
+$(srcdir)/sudoreplay.man.in: $(srcdir)/sudoreplay.mdoc.in
+	@if [ -n "$(DEVEL)" ]; then \
+	    echo "Generating $@"; \
+	    mansectsu=`echo @MANSECTSU@|$(TR) A-Z a-z`; \
+	    mansectform=`echo @MANSECTFORM@|$(TR) A-Z a-z`; \
+	    printf '.\\" DO NOT EDIT THIS FILE, IT IS NOT THE MASTER!\n' > $@; \
+	    printf '.\\" IT IS GENERATED AUTOMATICALLY FROM sudoreplay.mdoc.in\n' >> $@; \
+	    $(SED) -n -e '/^.Dd/q' -e '/^\.\\/p' $(srcdir)/sudoreplay.mdoc.in >> $@; \
+	    $(SED) -e "s/$$mansectsu/8/g" -e "s/$$mansectform/5/g" $(srcdir)/sudoreplay.mdoc.in | $(MANDOC) -Tman | $(SED) -e 's/^\(\.TH "SUDOREPLAY" \)"8"\(.*"\)OpenBSD \(.*\)/\1"'$$mansectsu'"\2\3/' -e "s/(5)/($$mansectform)/g" -e "s/(8)/($$mansectsu)/g" >> $@; \
+	fi
+
 $(mansrcdir)/sudoreplay.man: $(top_builddir)/config.status $(srcdir)/sudoreplay.man.in
 	cd $(top_builddir) && $(SHELL) config.status --file=doc/$@
 
@@ -308,9 +344,10 @@ install-doc: install-dirs
 	$(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/visudo.$(mantype) $(DESTDIR)$(mandirsu)/visudo.$(mansectsu)
 	$(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/sudo.conf.$(mantype) $(DESTDIR)$(mandirform)/sudo.conf.$(mansectform)
 	$(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/sudoers.$(mantype) $(DESTDIR)$(mandirform)/sudoers.$(mansectform)
+	$(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/sudoers_timestamp.$(mantype) $(DESTDIR)$(mandirform)/sudoers_timestamp.$(mansectform)
 	@LDAP@$(INSTALL) $(INSTALL_OWNER) -m 0644 $(mansrcdir)/sudoers.ldap.$(mantype) $(DESTDIR)$(mandirform)/sudoers.ldap.$(mansectform)
 	@if test -n "$(MANCOMPRESS)"; then \
-	    for f in $(mandirsu)/sudo.$(mansectsu) $(mandirsu)/sudo_plugin.$(mansectsu) $(mandirsu)/sudoreplay.$(mansectsu) $(mandirsu)/visudo.$(mansectsu) $(mandirform)/sudo.conf.$(mansectform) $(mandirform)/sudoers.$(mansectform) $(mandirform)/sudoers.ldap.$(mansectform); do \
+	    for f in $(mandirsu)/sudo.$(mansectsu) $(mandirsu)/sudo_plugin.$(mansectsu) $(mandirsu)/sudoreplay.$(mansectsu) $(mandirsu)/visudo.$(mansectsu) $(mandirform)/sudo.conf.$(mansectform) $(mandirform)/sudoers.$(mansectform) $(mandirform)/sudoers_timestamp.$(mansectform) $(mandirform)/sudoers.ldap.$(mansectform); do \
 		if test -f $(DESTDIR)$$f; then \
 		    echo $(MANCOMPRESS) -f $(DESTDIR)$$f; \
 		    $(MANCOMPRESS) -f $(DESTDIR)$$f; \
@@ -336,6 +373,7 @@ uninstall:
 		$(DESTDIR)$(mandirsu)/visudo.$(mansectsu) \
 		$(DESTDIR)$(mandirform)/sudo.conf.$(mansectform) \
 		$(DESTDIR)$(mandirform)/sudoers.$(mansectform) \
+		$(DESTDIR)$(mandirform)/sudoers_timestamp.$(mansectform)
 		$(DESTDIR)$(mandirform)/sudoers.ldap.$(mansectform)
 
 splint:

doc/sudoers.cat

@@ -92,13 +92,14 @@ DDEESSCCRRIIPPTTIIOONN
 
      ssuuddooeerrss uses per-user time stamp files for credential caching.  Once a
      user has been authenticated, a record is written containing the user ID
-     that was used to authenticate, the terminal session ID, and a time stamp
+     that was used to authenticate, the terminal session ID, the start time of
-     (using a monotonic clock if one is available).  The user may then use
+     the session leader (or parent proccess) and a time stamp (using a
-     ssuuddoo without a password for a short period of time (5 minutes unless
+     monotonic clock if one is available).  The user may then use ssuuddoo without
-     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
+     a password for a short period of time (5 minutes unless overridden by the
-     separate record for each terminal, which means that a user's login
+     _t_i_m_e_s_t_a_m_p___t_i_m_e_o_u_t option).  By default, ssuuddooeerrss uses a separate record
-     sessions are authenticated separately.  The _t_i_m_e_s_t_a_m_p___t_y_p_e option can be
+     for each terminal, which means that a user's login sessions are
-     used to select the type of time stamp record ssuuddooeerrss will use.
+     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.
 
    LLooggggiinngg
      ssuuddooeerrss can log both successful and unsuccessful attempts (as well as
@@ -2849,7 +2850,7 @@ DDEEBBUUGGGGIINNGG
 
 SSEEEE AALLSSOO
      ssh(1), su(1), fnmatch(3), glob(3), mktemp(3), strftime(3), sudo.conf(4),
-     sudoers.ldap(4), sudo(1m), sudo_plugin(4), visudo(1m)
+     sudoers.ldap(4), sudo(1m), sudo_plugin(4), sudoers_timestamp(4), visudo(1m)
 
 AAUUTTHHOORRSS
      Many people have worked on ssuuddoo over the years; this version consists of
@@ -2888,4 +2889,4 @@ DDIISSCCLLAAIIMMEERR
      file distributed with ssuuddoo or https://www.sudo.ws/license.html for
      complete details.
 
-Sudo 1.8.22                    December 15, 2017                   Sudo 1.8.22
+Sudo 1.8.22                    December 20, 2017                   Sudo 1.8.22

doc/sudoers.man.in

@@ -21,7 +21,7 @@
 .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
 .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
 .\"
-.TH "SUDOERS" "5" "December 15, 2017" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
+.TH "SUDOERS" "5" "December 20, 2017" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
 .nh
 .if n .ad l
 .SH "NAME"
@@ -217,7 +217,8 @@ file lookup is still done for root, not the user specified by
 uses per-user time stamp files for credential caching.
 Once a user has been authenticated, a record is written
 containing the user ID that was used to authenticate, the
-terminal session ID, and a time stamp
+terminal session ID, the start time of the session leader
+(or parent proccess) and a time stamp
 (using a monotonic clock if one is available).
 The user may then use
 \fBsudo\fR
@@ -5651,6 +5652,7 @@ sudo.conf(@mansectform@),
 sudoers.ldap(@mansectform@),
 sudo(@mansectsu@),
 sudo_plugin(@mansectform@),
+sudoers_timestamp(@mansectform@),
 visudo(@mansectsu@)
 .SH "AUTHORS"
 Many people have worked on

doc/sudoers.mdoc.in

@@ -19,7 +19,7 @@
 .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
 .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
 .\"
-.Dd December 15, 2017
+.Dd December 20, 2017
 .Dt SUDOERS @mansectform@
 .Os Sudo @PACKAGE_VERSION@
 .Sh NAME
@@ -205,7 +205,8 @@ file lookup is still done for root, not the user specified by
 uses per-user time stamp files for credential caching.
 Once a user has been authenticated, a record is written
 containing the user ID that was used to authenticate, the
-terminal session ID, and a time stamp
+terminal session ID, the start time of the session leader
+(or parent proccess) and a time stamp
 (using a monotonic clock if one is available).
 The user may then use
 .Nm sudo
@@ -5221,6 +5222,7 @@ manual.
 .Xr sudoers.ldap @mansectform@ ,
 .Xr sudo @mansectsu@ ,
 .Xr sudo_plugin @mansectform@ ,
+.Xr sudoers_timestamp @mansectform@ ,
 .Xr visudo @mansectsu@
 .Sh AUTHORS
 Many people have worked on

doc/sudoers_timestamp.cat

@@ -0,0 +1,196 @@
+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).  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 co-exist 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;         /* timestamp (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 from prompting for a password
+     as the same time.
+
+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.
+           This 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.
+
+     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.
+
+SSEEEE AALLSSOO
+     sudoers(4), sudo(1m)
+
+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.22                    December 19, 2017                   Sudo 1.8.22

doc/sudoers_timestamp.man.in

@@ -0,0 +1,305 @@
+.\" DO NOT EDIT THIS FILE, IT IS NOT THE MASTER!
+.\" IT IS GENERATED AUTOMATICALLY FROM sudoers_timestamp.mdoc.in
+.\"
+.\" Copyright (c) 2017 Todd C. Miller <Todd.Miller@sudo.ws>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.TH "SUDOERS_TIMESTAMP" "5" "December 19, 2017" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
+.nh
+.if n .ad l
+.SH "NAME"
+\fBsudoers_timestamp\fR
+\- Sudoers Time Stamp Format
+.SH "DESCRIPTION"
+The
+\fBsudoers\fR
+plugin uses per-user time stamp files for credential caching.
+Once a user has been authenticated, they may use
+\fBsudo\fR
+without a password for a short period of time
+(\fR@timeout@\fR
+minutes unless overridden by the
+\fItimestamp_timeout\fR
+option)
+\&.
+\fBsudoers\fR
+uses a separate record for each terminal, which means that
+a user's login sessions are authenticated separately.
+The
+\fItimestamp_type\fR
+option can be used to select the type of time stamp record
+\fBsudoers\fR
+will use.
+.PP
+A multi-record time stamp file format was introduced in
+\fBsudo\fR
+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
+co-exist within the same file.
+.PP
+All records, regardless of type or version, begin with a 16-bit version
+number and a 16-bit record size.
+.PP
+Time stamp records have the following structure:
+.nf
+.sp
+.RS 0n
+/* 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;         /* timestamp (CLOCK_MONOTONIC) */
+    union {
+        dev_t ttydev;           /* tty device number */
+        pid_t ppid;             /* parent pid */
+    } u;
+};
+.RE
+.fi
+.PP
+The timestamp_entry struct fields are as follows:
+.TP 6n
+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.
+.TP 6n
+size
+The size of the record in bytes.
+.TP 6n
+type
+The record type, currently
+\fRTS_GLOBAL\fR,
+\fRTS_TTY\fR,
+or
+\fRTS_PPID\fR.
+.TP 6n
+flags
+.br
+Zero or more record flags which can be bit-wise ORed together.
+Supported flags are
+\fRTS_DISABLED\fR,
+for records disabled via
+\fBsudo\fR
+\fB\-k\fR
+and
+\fRTS_ANYUID\fR,
+which is used only when matching records.
+.TP 6n
+auth_uid
+The user ID that was used for authentication.
+Depending on the value of the
+\fIrootpw\fR,
+\fIrunaspw\fR
+and
+\fItargetpw\fR
+options, the user ID may be that of the invoking user, the root user,
+the default runas user or the target user.
+.TP 6n
+sid
+The ID of the user's terminal session, if present.
+The session ID is only used when matching records of type
+\fRTS_TTY\fR.
+.TP 6n
+start_time
+The start time of the session leader for records of type
+\fRTS_TTY\fR
+or of the parent process for records of type
+\fRTS_PPID\fR.
+The
+\fIstart_time\fR
+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
+\fIstart_time\fR
+field was added in
+\fBsudoers\fR
+version 1.8.22 for the second revision of the timestamp_entry struct.
+.TP 6n
+ts
+The actual time stamp.
+A monotonic time source (which does not move backward) is used if the
+system supports it.
+Where possible,
+\fBsudoers\fR
+uses a monotonic timer that increments even while the system
+is suspended.
+The value of
+\fIts\fR
+is updated each time a command is run via
+\fBsudo\fR.
+If the difference between
+\fIts\fR
+and the current time is less than the value of the
+\fItimestamp_timeout\fR
+option, no password is required.
+.TP 6n
+u.ttydev
+The device number of the terminal associated with the session for
+records of type
+\fRTS_TTY\fR.
+.TP 6n
+u.ppid
+The ID of the parent process for records of type
+\fRTS_PPID\fR.
+.SH "LOCKING"
+In
+\fBsudoers\fR
+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
+\fBsudoers\fR
+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.
+.PP
+The first record in the time stamp file is of type
+\fRTS_LOCKEXCL\fR
+and is used as a
+\fIlock\fR
+record to prevent more than one
+\fBsudo\fR
+process from adding a new record at the same time.
+Once the desired time stamp record has been located or created (and
+locked), the
+\fRTS_LOCKEXCL\fR
+record is unlocked.
+The lock on the individual time stamp record, however, is held until
+authentication is complete.
+This allows
+\fBsudoers\fR
+to avoid prompting for a password multiple times when it
+is used more than once in a pipeline.
+.PP
+Records of type
+\fRTS_GLOBAL\fR
+cannot be locked for a long period of time since doing so would
+interfere with other
+\fBsudo\fR
+processes.
+Instead, a separate lock record is used to prevent multiple
+\fBsudo\fR
+processes using the same terminal (or parent process ID) from
+from prompting for a password as the same time.
+.SH "HISTORY"
+Originally,
+\fBsudo\fR
+used a single zero-length file per user and the file's modification
+time was used as the time stamp.
+Later versions of
+\fBsudo\fR
+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
+\fBsudo\fR
+versions:
+.TP 6n
+1.4.0
+.br
+Support for tty-based time stamp file was added
+by appending the terminal name to the time stamp file name.
+.TP 6n
+1.6.2
+.br
+The time stamp file was replaced by a per-user directory which
+contained any tty-based time stamp files.
+.TP 6n
+1.6.3p2
+The target user name was added to the time stamp file name when the
+\fItargetpw\fR
+option was set.
+.TP 6n
+1.7.3
+.br
+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.
+.TP 6n
+1.8.6p7
+The terminal session ID was added to tty-based time stamp files.
+This helped prevent re-use of the time stamp file on systems where
+the terminal device's inode change time was updated by writing.
+.TP 6n
+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.
+.TP 6n
+1.8.15
+Individual records are locked in the time stamp file instead of the
+entire file.
+.TP 6n
+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.
+.SH "SEE ALSO"
+sudoers(@mansectform@),
+sudo(@mansectsu@)
+.SH "AUTHORS"
+Many people have worked on
+\fBsudo\fR
+over the years; this version consists of code written primarily by:
+.sp
+.RS 6n
+Todd C. Miller
+.RE
+.PP
+See the CONTRIBUTORS file in the
+\fBsudo\fR
+distribution (https://www.sudo.ws/contributors.html) for an
+exhaustive list of people who have contributed to
+\fBsudo\fR.
+.SH "BUGS"
+If you feel you have found a bug in
+\fBsudo\fR,
+please submit a bug report at https://bugzilla.sudo.ws/
+.SH "SUPPORT"
+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.
+.SH "DISCLAIMER"
+\fBsudo\fR
+is provided
+\(LqAS IS\(Rq
+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
+\fBsudo\fR
+or https://www.sudo.ws/license.html for complete details.

doc/sudoers_timestamp.mdoc.in

@@ -0,0 +1,282 @@
+.\"
+.\" Copyright (c) 2017 Todd C. Miller <Todd.Miller@sudo.ws>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd December 19, 2017
+.Dt SUDOERS_TIMESTAMP @mansectform@
+.Os Sudo @PACKAGE_VERSION@
+.Sh NAME
+.Nm sudoers_timestamp
+.Nd Sudoers Time Stamp Format
+.Sh DESCRIPTION
+The
+.Nm sudoers
+plugin uses per-user time stamp files for credential caching.
+Once a user has been authenticated, they may use
+.Nm sudo
+without a password for a short period of time
+.Po
+.Li @timeout@
+minutes unless overridden by the
+.Em timestamp_timeout
+option
+.Pc .
+.Nm sudoers
+uses a separate record for each terminal, which means that
+a user's login sessions are authenticated separately.
+The
+.Em timestamp_type
+option can be used to select the type of time stamp record
+.Nm sudoers
+will use.
+.Pp
+A multi-record time stamp file format was introduced in
+.Nm sudo
+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
+co-exist within the same file.
+.Pp
+All records, regardless of type or version, begin with a 16-bit version
+number and a 16-bit record size.
+.Pp
+Time stamp records have the following structure:
+.Bd -literal
+/* 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;         /* timestamp (CLOCK_MONOTONIC) */
+    union {
+        dev_t ttydev;           /* tty device number */
+        pid_t ppid;             /* parent pid */
+    } u;
+};
+.Ed
+.Pp
+The timestamp_entry struct fields are as follows:
+.Bl -tag -width 4n
+.It 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.
+.It size
+The size of the record in bytes.
+.It type
+The record type, currently
+.Li TS_GLOBAL ,
+.Li TS_TTY ,
+or
+.Li TS_PPID .
+.It flags
+Zero or more record flags which can be bit-wise ORed together.
+Supported flags are
+.Li TS_DISABLED ,
+for records disabled via
+.Nm sudo
+.Fl k
+and
+.Li TS_ANYUID ,
+which is used only when matching records.
+.It auth_uid
+The user ID that was used for authentication.
+Depending on the value of the
+.Em rootpw ,
+.Em runaspw
+and
+.Em targetpw
+options, the user ID may be that of the invoking user, the root user,
+the default runas user or the target user.
+.It sid
+The ID of the user's terminal session, if present.
+The session ID is only used when matching records of type
+.Li TS_TTY .
+.It start_time
+The start time of the session leader for records of type
+.Li TS_TTY
+or of the parent process for records of type
+.Li TS_PPID .
+The
+.Em start_time
+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
+.Em start_time
+field was added in
+.Nm sudoers
+version 1.8.22 for the second revision of the timestamp_entry struct.
+.It ts
+The actual time stamp.
+A monotonic time source (which does not move backward) is used if the
+system supports it.
+Where possible,
+.Nm sudoers
+uses a monotonic timer that increments even while the system
+is suspended.
+The value of
+.Em ts
+is updated each time a command is run via
+.Nm sudo .
+If the difference between
+.Em ts
+and the current time is less than the value of the
+.Em timestamp_timeout
+option, no password is required.
+.It u.ttydev
+The device number of the terminal associated with the session for
+records of type
+.Li TS_TTY .
+.It u.ppid
+The ID of the parent process for records of type
+.Li TS_PPID .
+.El
+.Sh LOCKING
+In
+.Nm sudoers
+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
+.Nm sudoers
+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.
+.Pp
+The first record in the time stamp file is of type
+.Li TS_LOCKEXCL
+and is used as a
+.Em lock
+record to prevent more than one
+.Nm sudo
+process from adding a new record at the same time.
+Once the desired time stamp record has been located or created (and
+locked), the
+.Li TS_LOCKEXCL
+record is unlocked.
+The lock on the individual time stamp record, however, is held until
+authentication is complete.
+This allows
+.Nm sudoers
+to avoid prompting for a password multiple times when it
+is used more than once in a pipeline.
+.Pp
+Records of type
+.Li TS_GLOBAL
+cannot be locked for a long period of time since doing so would
+interfere with other
+.Nm sudo
+processes.
+Instead, a separate lock record is used to prevent multiple
+.Nm sudo
+processes using the same terminal (or parent process ID) from
+from prompting for a password as the same time.
+.Sh HISTORY
+Originally,
+.Nm sudo
+used a single zero-length file per user and the file's modification
+time was used as the time stamp.
+Later versions of
+.Nm sudo
+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
+.Nm sudo
+versions:
+.Bl -tag -width 4n
+.It 1.4.0
+Support for tty-based time stamp file was added
+by appending the terminal name to the time stamp file name.
+.It 1.6.2
+The time stamp file was replaced by a per-user directory which
+contained any tty-based time stamp files.
+.It 1.6.3p2
+The target user name was added to the time stamp file name when the
+.Em targetpw
+option was set.
+.It 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.
+.It 1.8.6p7
+The terminal session ID was added to tty-based time stamp files.
+This helped prevent re-use of the time stamp file on systems where
+the terminal device's inode change time was updated by writing.
+.It 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.
+.It 1.8.15
+Individual records are locked in the time stamp file instead of the
+entire file.
+.It 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.
+.El
+.Sh SEE ALSO
+.Xr sudoers @mansectform@ ,
+.Xr sudo @mansectsu@
+.Sh AUTHORS
+Many people have worked on
+.Nm sudo
+over the years; this version consists of code written primarily by:
+.Bd -ragged -offset indent
+.An Todd C. Miller
+.Ed
+.Pp
+See the CONTRIBUTORS file in the
+.Nm sudo
+distribution (https://www.sudo.ws/contributors.html) for an
+exhaustive list of people who have contributed to
+.Nm sudo .
+.Sh BUGS
+If you feel you have found a bug in
+.Nm sudo ,
+please submit a bug report at https://bugzilla.sudo.ws/
+.Sh SUPPORT
+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.
+.Sh DISCLAIMER
+.Nm sudo
+is provided
+.Dq 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
+.Nm sudo
+or https://www.sudo.ws/license.html for complete details.

plugins/sudoers/check.h

@@ -37,10 +37,10 @@
 #define	TS_VERSION		2
 
 /* Time stamp entry types */
-#define TS_GLOBAL		0x01
+#define TS_GLOBAL		0x01	/* not restricted by tty or ppid */
-#define TS_TTY			0x02
+#define TS_TTY			0x02	/* restricted by tty */
-#define TS_PPID			0x03
+#define TS_PPID			0x03	/* restricted by ppid */
-#define TS_LOCKEXCL		0x04
+#define TS_LOCKEXCL		0x04	/* special lock record */
 
 /* Time stamp flags */
 #define TS_DISABLED		0x01	/* entry disabled */