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