mirror of https://github.com/sudo-project/sudo.git
338 lines
10 KiB
Groff
338 lines
10 KiB
Groff
.\" Automatically generated from the sudoers_timestamp.mdoc.in file. Do not edit.
|
|
.\"
|
|
.\" SPDX-License-Identifier: ISC
|
|
.\"
|
|
.\" Copyright (c) 2017-2020, 2022-2023 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@" "November 26, 2023" "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-ID 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 0x01U /* not restricted by tty or ppid */
|
|
#define TS_TTY 0x02U /* restricted by tty */
|
|
#define TS_PPID 0x03U /* restricted by ppid */
|
|
#define TS_LOCKEXCL 0x04U /* special lock record */
|
|
|
|
/* Time stamp flags */
|
|
#define TS_DISABLED 0x01U /* entry disabled */
|
|
#define TS_ANYUID 0x02U /* 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 reuse 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.
|
|
.PP
|
|
The
|
|
\fBtsdump\fR
|
|
utility, included with the sudo source distribution, can be used to
|
|
display the contents of a
|
|
\fIsudoers\fR
|
|
time stamp file.
|
|
.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 reuse 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 reuse of the time stamp by the same user in a different
|
|
terminal session.
|
|
It also helped prevent reuse 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 reuse 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.
|
|
.TP 6n
|
|
1.9.15
|
|
Time stamp file path names are now based on the invoking user-ID
|
|
instead of the user name.
|
|
This avoids problems with user names that include a path separator
|
|
character.
|
|
.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
|
|
\fBsudoers_timestamp\fR,
|
|
you can either file a bug report in the sudo bug database,
|
|
https://bugzilla.sudo.ws/, or open an issue at
|
|
https://github.com/sudo-project/sudo/issues.
|
|
If you would prefer to use email, messages may be sent to the
|
|
sudo-workers mailing list,
|
|
https://www.sudo.ws/mailman/listinfo/sudo-workers (public)
|
|
or <sudo@sudo.ws> (private).
|
|
.PP
|
|
Please not report security vulnerabilities through public GitHub
|
|
issues, Bugzilla or mailing lists.
|
|
Instead, report them via email to <Todd.Miller@sudo.ws>.
|
|
You may encrypt your message with PGP if you would like, using
|
|
the key found at https://www.sudo.ws/dist/PGPKEYS.
|
|
.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.
|