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
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 \
$(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
$(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/$@
$(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; \
$(DESTDIR)$(mandirsu)/visudo.$(mansectsu) \
$(DESTDIR)$(mandirform)/sudo.conf.$(mansectform) \
$(DESTDIR)$(mandirform)/sudoers.$(mansectform) \
+ $(DESTDIR)$(mandirform)/sudoers_timestamp.$(mansectform)
$(DESTDIR)$(mandirform)/sudoers.ldap.$(mansectform)
splint:
s\bsu\bud\bdo\boe\ber\brs\bs 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
- (using a monotonic clock if one is available). The user may then use
- s\bsu\bud\bdo\bo without a password for a short period of time (5 minutes unless
- overridden by the _\bt_\bi_\bm_\be_\bs_\bt_\ba_\bm_\bp_\b__\bt_\bi_\bm_\be_\bo_\bu_\bt option). By default, s\bsu\bud\bdo\boe\ber\brs\bs uses a
- separate record for each terminal, which means that a user's login
- sessions are authenticated separately. The _\bt_\bi_\bm_\be_\bs_\bt_\ba_\bm_\bp_\b__\bt_\by_\bp_\be option can be
- used to select the type of time stamp record s\bsu\bud\bdo\boe\ber\brs\bs will use.
+ that was used to authenticate, the 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 s\bsu\bud\bdo\bo without
+ a password for a short period of time (5 minutes unless overridden by the
+ _\bt_\bi_\bm_\be_\bs_\bt_\ba_\bm_\bp_\b__\bt_\bi_\bm_\be_\bo_\bu_\bt option). By default, s\bsu\bud\bdo\boe\ber\brs\bs uses a separate record
+ for each terminal, which means that a user's login sessions are
+ authenticated separately. The _\bt_\bi_\bm_\be_\bs_\bt_\ba_\bm_\bp_\b__\bt_\by_\bp_\be option can be used to
+ select the type of time stamp record s\bsu\bud\bdo\boe\ber\brs\bs will use.
L\bLo\bog\bgg\bgi\bin\bng\bg
s\bsu\bud\bdo\boe\ber\brs\bs can log both successful and unsuccessful attempts (as well as
S\bSE\bEE\bE A\bAL\bLS\bSO\bO
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)
A\bAU\bUT\bTH\bHO\bOR\bRS\bS
Many people have worked on s\bsu\bud\bdo\bo over the years; this version consists of
file distributed with s\bsu\bud\bdo\bo 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
.\" 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"
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
sudoers.ldap(@mansectform@),
sudo(@mansectsu@),
sudo_plugin(@mansectform@),
+sudoers_timestamp(@mansectform@),
visudo(@mansectsu@)
.SH "AUTHORS"
Many people have worked on
.\" 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
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
.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
--- /dev/null
+SUDOERS_TIMESTAMP(4) File Formats Manual SUDOERS_TIMESTAMP(4)
+
+N\bNA\bAM\bME\bE
+ s\bsu\bud\bdo\boe\ber\brs\bs_\b_t\bti\bim\bme\bes\bst\bta\bam\bmp\bp - Sudoers Time Stamp Format
+
+D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
+ The s\bsu\bud\bdo\boe\ber\brs\bs plugin uses per-user time stamp files for credential caching.
+ Once a user has been authenticated, they may use s\bsu\bud\bdo\bo without a password
+ for a short period of time (5 minutes unless overridden by the
+ _\bt_\bi_\bm_\be_\bs_\bt_\ba_\bm_\bp_\b__\bt_\bi_\bm_\be_\bo_\bu_\bt option). s\bsu\bud\bdo\boe\ber\brs\bs uses a separate record for each
+ terminal, which means that a user's login sessions are authenticated
+ separately. The _\bt_\bi_\bm_\be_\bs_\bt_\ba_\bm_\bp_\b__\bt_\by_\bp_\be option can be used to select the type of
+ time stamp record s\bsu\bud\bdo\boe\ber\brs\bs will use.
+
+ A multi-record time stamp file format was introduced in s\bsu\bud\bdo\bo 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 s\bsu\bud\bdo\bo -\b-k\bk
+ 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 _\br_\bo_\bo_\bt_\bp_\bw, _\br_\bu_\bn_\ba_\bs_\bp_\bw and _\bt_\ba_\br_\bg_\be_\bt_\bp_\bw 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 _\bs_\bt_\ba_\br_\bt_\b__\bt_\bi_\bm_\be
+ 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 _\bs_\bt_\ba_\br_\bt_\b__\bt_\bi_\bm_\be field was added in
+ s\bsu\bud\bdo\boe\ber\brs\bs 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,
+ s\bsu\bud\bdo\boe\ber\brs\bs uses a monotonic timer that increments even while the
+ system is suspended. The value of _\bt_\bs is updated each time a
+ command is run via s\bsu\bud\bdo\bo. If the difference between _\bt_\bs and the
+ current time is less than the value of the _\bt_\bi_\bm_\be_\bs_\bt_\ba_\bm_\bp_\b__\bt_\bi_\bm_\be_\bo_\bu_\bt
+ 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.
+
+L\bLO\bOC\bCK\bKI\bIN\bNG\bG
+ In s\bsu\bud\bdo\boe\ber\brs\bs 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 s\bsu\bud\bdo\boe\ber\brs\bs 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 _\bl_\bo_\bc_\bk record to prevent more than one s\bsu\bud\bdo\bo 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 s\bsu\bud\bdo\boe\ber\brs\bs 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 s\bsu\bud\bdo\bo processes. Instead, a
+ separate lock record is used to prevent multiple s\bsu\bud\bdo\bo processes using the
+ same terminal (or parent process ID) from from prompting for a password
+ as the same time.
+
+H\bHI\bIS\bST\bTO\bOR\bRY\bY
+ Originally, s\bsu\bud\bdo\bo used a single zero-length file per user and the file's
+ modification time was used as the time stamp. Later versions of s\bsu\bud\bdo\bo
+ 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 s\bsu\bud\bdo\bo 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
+ _\bt_\ba_\br_\bg_\be_\bt_\bp_\bw 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.
+
+S\bSE\bEE\bE A\bAL\bLS\bSO\bO
+ sudoers(4), sudo(1m)
+
+A\bAU\bUT\bTH\bHO\bOR\bRS\bS
+ Many people have worked on s\bsu\bud\bdo\bo over the years; this version consists of
+ code written primarily by:
+
+ Todd C. Miller
+
+ See the CONTRIBUTORS file in the s\bsu\bud\bdo\bo distribution
+ (https://www.sudo.ws/contributors.html) for an exhaustive list of people
+ who have contributed to s\bsu\bud\bdo\bo.
+
+B\bBU\bUG\bGS\bS
+ If you feel you have found a bug in s\bsu\bud\bdo\bo, please submit a bug report at
+ https://bugzilla.sudo.ws/
+
+S\bSU\bUP\bPP\bPO\bOR\bRT\bT
+ 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.
+
+D\bDI\bIS\bSC\bCL\bLA\bAI\bIM\bME\bER\bR
+ s\bsu\bud\bdo\bo 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 s\bsu\bud\bdo\bo or https://www.sudo.ws/license.html for
+ complete details.
+
+Sudo 1.8.22 December 19, 2017 Sudo 1.8.22
--- /dev/null
+.\" 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.
--- /dev/null
+.\"
+.\" 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.
#define TS_VERSION 2
/* Time stamp entry types */
-#define TS_GLOBAL 0x01
-#define TS_TTY 0x02
-#define TS_PPID 0x03
-#define TS_LOCKEXCL 0x04
+#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 */
projects / sudo / commitdiff