From 5f3797c7544191f8bcc678bf4d95609e45319800 Mon Sep 17 00:00:00 2001 From: "Todd C. Miller" Date: Wed, 20 Dec 2017 13:01:06 -0700 Subject: [PATCH] Document the sudoers time stamp file format. --- MANIFEST | 3 + doc/Makefile.in | 40 ++++- doc/sudoers.cat | 19 ++- doc/sudoers.man.in | 6 +- doc/sudoers.mdoc.in | 6 +- doc/sudoers_timestamp.cat | 196 ++++++++++++++++++++++ doc/sudoers_timestamp.man.in | 305 ++++++++++++++++++++++++++++++++++ doc/sudoers_timestamp.mdoc.in | 282 +++++++++++++++++++++++++++++++ plugins/sudoers/check.h | 8 +- 9 files changed, 847 insertions(+), 18 deletions(-) create mode 100644 doc/sudoers_timestamp.cat create mode 100644 doc/sudoers_timestamp.man.in create mode 100644 doc/sudoers_timestamp.mdoc.in diff --git a/MANIFEST b/MANIFEST index 1f6e64daf..4bd2e85ab 100644 --- a/MANIFEST +++ b/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 diff --git a/doc/Makefile.in b/doc/Makefile.in index d1b69903c..7655ae739 100644 --- a/doc/Makefile.in +++ b/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: diff --git a/doc/sudoers.cat b/doc/sudoers.cat index bf3d7c654..a7b0041c5 100644 --- a/doc/sudoers.cat +++ b/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 - (using a monotonic clock if one is available). The user may then 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. + 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 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. 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 diff --git a/doc/sudoers.man.in b/doc/sudoers.man.in index f0729d290..30d571955 100644 --- a/doc/sudoers.man.in +++ b/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 diff --git a/doc/sudoers.mdoc.in b/doc/sudoers.mdoc.in index b41265423..0aeea7f05 100644 --- a/doc/sudoers.mdoc.in +++ b/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 diff --git a/doc/sudoers_timestamp.cat b/doc/sudoers_timestamp.cat new file mode 100644 index 000000000..6189f5e04 --- /dev/null +++ b/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 diff --git a/doc/sudoers_timestamp.man.in b/doc/sudoers_timestamp.man.in new file mode 100644 index 000000000..ca1005e07 --- /dev/null +++ b/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 +.\" +.\" 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. diff --git a/doc/sudoers_timestamp.mdoc.in b/doc/sudoers_timestamp.mdoc.in new file mode 100644 index 000000000..e2f0d076e --- /dev/null +++ b/doc/sudoers_timestamp.mdoc.in @@ -0,0 +1,282 @@ +.\" +.\" Copyright (c) 2017 Todd C. Miller +.\" +.\" 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. diff --git a/plugins/sudoers/check.h b/plugins/sudoers/check.h index 15a0dc706..4da3f50e1 100644 --- a/plugins/sudoers/check.h +++ b/plugins/sudoers/check.h @@ -37,10 +37,10 @@ #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 */ -- 2.50.1