diff options
Diffstat (limited to 'docs/sudoers_timestamp.man.in')
| -rw-r--r-- | docs/sudoers_timestamp.man.in | 312 |
1 files changed, 312 insertions, 0 deletions
diff --git a/docs/sudoers_timestamp.man.in b/docs/sudoers_timestamp.man.in new file mode 100644 index 0000000..e824029 --- /dev/null +++ b/docs/sudoers_timestamp.man.in @@ -0,0 +1,312 @@ +.\" Automatically generated from an mdoc input file. Do not edit. +.\" +.\" SPDX-License-Identifier: ISC +.\" +.\" Copyright (c) 2017-2020, 2022 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. +.\" +.TH "SUDOERS_TIMESTAMP" "@mansectform@" "September 13, 2022" "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 +(\fI@timeout@\fR +minutes unless overridden by the +\fItimestamp_timeout\fR +option) +\&. +By default, +\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 coexist 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; /* time stamp (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 +prompting for a password as the same time. +.SH "SEE ALSO" +sudoers(@mansectform@), +sudo(@mansectsu@) +.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 checks on the validity of 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 validity checks. +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 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. +.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 and the lock is held until authentication is complete. +.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. +.sp +Support was added for the kernel-based tty time stamps available in +OpenBSD +which do not use an on-disk time stamp file. +.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.md file in the +\fBsudo\fR +distribution (https://www.sudo.ws/about/contributors/) for an +exhaustive list of people who have contributed to +\fBsudo\fR. +.SH "BUGS" +If you believe you have found a bug in +\fBsudo\fR, +you can 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.md file distributed with +\fBsudo\fR +or https://www.sudo.ws/about/license/ for complete details. |