289 lines
9.2 KiB
Plaintext
289 lines
9.2 KiB
Plaintext
.\"
|
|
.\" 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 21, 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 .
|
|
By default,
|
|
.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 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:
|
|
.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; /* time stamp (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 SEE ALSO
|
|
.Xr sudoers @mansectform@ ,
|
|
.Xr sudo @mansectsu@
|
|
.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 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.
|
|
.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 and the lock is held until authentication is complete.
|
|
.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.
|
|
.Pp
|
|
Support was added for the kernel-based tty time stamps available in
|
|
OpenBSD which do not use an on-disk time stamp file.
|
|
.El
|
|
.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.
|