path: root/docs/sudoers_timestamp.mdoc.in

.\"
.\" 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.
.\"
.Dd September 13, 2022
.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
.Em @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
.Dv TS_GLOBAL ,
.Dv TS_TTY ,
or
.Dv TS_PPID .
.It flags
Zero or more record flags which can be bit-wise ORed together.
Supported flags are
.Dv TS_DISABLED ,
for records disabled via
.Nm sudo
.Fl k
and
.Dv 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
.Dv TS_TTY .
.It start_time
The start time of the session leader for records of type
.Dv TS_TTY
or of the parent process for records of type
.Dv 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
.Dv TS_TTY .
.It u.ppid
The ID of the parent process for records of type
.Dv 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
.Dv 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
.Dv 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
.Dv 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
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 checks on the validity of 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 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.
.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
.Ox
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.md file in the
.Nm sudo
distribution (https://www.sudo.ws/about/contributors/) for an
exhaustive list of people who have contributed to
.Nm sudo .
.Sh BUGS
If you believe you have found a bug in
.Nm sudo ,
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
.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.md file distributed with
.Nm sudo
or https://www.sudo.ws/about/license/ for complete details.