1SUDOERS_TIMESTAMP(5)        BSD File Formats Manual       SUDOERS_TIMESTAMP(5)
2

NAME

4     sudoers_timestamp — Sudoers Time Stamp Format
5

DESCRIPTION

7     The sudoers plugin uses per-user time stamp files for credential caching.
8     Once a user has been authenticated, they may use sudo without a password
9     for a short period of time (5 minutes unless overridden by the
10     timestamp_timeout option).  By default, sudoers uses a separate record
11     for each terminal, which means that a user's login sessions are authenti‐
12     cated separately.  The timestamp_type option can be used to select the
13     type of time stamp record sudoers will use.
14
15     A multi-record time stamp file format was introduced in sudo 1.8.10 that
16     uses a single file per user.  Previously, a separate file was used for
17     each user and terminal combination unless tty-based time stamps were dis‐
18     abled.  The new format is extensible and records of multiple types and
19     versions may coexist within the same file.
20
21     All records, regardless of type or version, begin with a 16-bit version
22     number and a 16-bit record size.
23
24     Time stamp records have the following structure:
25
26     /* Time stamp entry types */
27     #define TS_GLOBAL               0x01    /* not restricted by tty or ppid */
28     #define TS_TTY                  0x02    /* restricted by tty */
29     #define TS_PPID                 0x03    /* restricted by ppid */
30     #define TS_LOCKEXCL             0x04    /* special lock record */
31
32     /* Time stamp flags */
33     #define TS_DISABLED             0x01    /* entry disabled */
34     #define TS_ANYUID               0x02    /* ignore uid, only valid in key */
35
36     struct timestamp_entry {
37         unsigned short version;     /* version number */
38         unsigned short size;        /* entry size */
39         unsigned short type;        /* TS_GLOBAL, TS_TTY, TS_PPID */
40         unsigned short flags;       /* TS_DISABLED, TS_ANYUID */
41         uid_t auth_uid;             /* uid to authenticate as */
42         pid_t sid;                  /* session ID associated with tty/ppid */
43         struct timespec start_time; /* session/ppid start time */
44         struct timespec ts;         /* time stamp (CLOCK_MONOTONIC) */
45         union {
46             dev_t ttydev;           /* tty device number */
47             pid_t ppid;             /* parent pid */
48         } u;
49     };
50
51     The timestamp_entry struct fields are as follows:
52
53     version
54           The version number of the timestamp_entry struct.  New entries are
55           created with a version number of 2.  Records with different version
56           numbers may coexist in the same file but are not inter-operable.
57
58     size  The size of the record in bytes.
59
60     type  The record type, currently TS_GLOBAL, TS_TTY, or TS_PPID.
61
62     flags
63           Zero or more record flags which can be bit-wise ORed together.
64           Supported flags are TS_DISABLED, for records disabled via sudo -k
65           and TS_ANYUID, which is used only when matching records.
66
67     auth_uid
68           The user-ID that was used for authentication.  Depending on the
69           value of the rootpw, runaspw and targetpw options, the user-ID may
70           be that of the invoking user, the root user, the default runas user
71           or the target user.
72
73     sid   The ID of the user's terminal session, if present.  The session ID
74           is only used when matching records of type TS_TTY.
75
76     start_time
77           The start time of the session leader for records of type TS_TTY or
78           of the parent process for records of type TS_PPID.  The start_time
79           is used to help prevent re-use of a time stamp record after a user
80           has logged out.  Not all systems support a method to easily
81           retrieve a process's start time.  The start_time field was added in
82           sudoers version 1.8.22 for the second revision of the time‐
83           stamp_entry struct.
84
85     ts    The actual time stamp.  A monotonic time source (which does not
86           move backward) is used if the system supports it.  Where possible,
87           sudoers uses a monotonic timer that increments even while the sys‐
88           tem is suspended.  The value of ts is updated each time a command
89           is run via sudo.  If the difference between ts and the current time
90           is less than the value of the timestamp_timeout option, no password
91           is required.
92
93     u.ttydev
94           The device number of the terminal associated with the session for
95           records of type TS_TTY.
96
97     u.ppid
98           The ID of the parent process for records of type TS_PPID.
99

LOCKING

101     In sudoers versions 1.8.10 through 1.8.14, the entire time stamp file was
102     locked for exclusive access when reading or writing to the file.  Start‐
103     ing in sudoers 1.8.15, individual records are locked in the time stamp
104     file instead of the entire file and the lock is held for a longer period
105     of time.  This scheme is described below.
106
107     The first record in the time stamp file is of type TS_LOCKEXCL and is
108     used as a lock record to prevent more than one sudo process from adding a
109     new record at the same time.  Once the desired time stamp record has been
110     located or created (and locked), the TS_LOCKEXCL record is unlocked.  The
111     lock on the individual time stamp record, however, is held until authen‐
112     tication is complete.  This allows sudoers to avoid prompting for a pass‐
113     word multiple times when it is used more than once in a pipeline.
114
115     Records of type TS_GLOBAL cannot be locked for a long period of time
116     since doing so would interfere with other sudo processes.  Instead, a
117     separate lock record is used to prevent multiple sudo processes using the
118     same terminal (or parent process ID) from prompting for a password as the
119     same time.
120

SEE ALSO

122     sudoers(5), sudo(8)
123

HISTORY

125     Originally, sudo used a single zero-length file per user and the file's
126     modification time was used as the time stamp.  Later versions of sudo
127     added restrictions on the ownership of the time stamp files and directory
128     as well as checks on the validity of the time stamp itself.  Notable
129     changes were introduced in the following sudo versions:
130
131     1.4.0
132           Support for tty-based time stamp file was added by appending the
133           terminal name to the time stamp file name.
134
135     1.6.2
136           The time stamp file was replaced by a per-user directory which con‐
137           tained any tty-based time stamp files.
138
139     1.6.3p2
140           The target user name was added to the time stamp file name when the
141           targetpw option was set.
142
143     1.7.3
144           Information about the terminal device was stored in tty-based time
145           stamp files for validity checks.  This included the terminal device
146           numbers, inode number and, on systems where it was not updated when
147           the device was written to, the inode change time.  This helped pre‐
148           vent re-use of the time stamp file after logout.
149
150     1.8.6p7
151           The terminal session ID was added to tty-based time stamp files to
152           prevent re-use of the time stamp by the same user in a different
153           terminal session.  It also helped prevent re-use of the time stamp
154           file on systems where the terminal device's inode change time was
155           updated by writing.
156
157     1.8.10
158           A new, multi-record time stamp file format was introduced that uses
159           a single file per user.  The terminal device's change time was not
160           included since most systems now update the change time after a
161           write is performed as required by POSIX.
162
163     1.8.15
164           Individual records are locked in the time stamp file instead of the
165           entire file and the lock is held until authentication is complete.
166
167     1.8.22
168           The start time of the terminal session leader or parent process is
169           now stored in non-global time stamp records.  This prevents re-use
170           of the time stamp file after logout in most cases.
171
172           Support was added for the kernel-based tty time stamps available in
173           OpenBSD which do not use an on-disk time stamp file.
174

AUTHORS

176     Many people have worked on sudo over the years; this version consists of
177     code written primarily by:
178
179           Todd C. Miller
180
181     See the CONTRIBUTORS file in the sudo distribution
182     (https://www.sudo.ws/contributors.html) for an exhaustive list of people
183     who have contributed to sudo.
184

BUGS

186     If you feel you have found a bug in sudo, please submit a bug report at
187     https://bugzilla.sudo.ws/
188

SUPPORT

190     Limited free support is available via the sudo-users mailing list, see
191     https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
192     the archives.
193

DISCLAIMER

195     sudo is provided “AS IS” and any express or implied warranties, includ‐
196     ing, but not limited to, the implied warranties of merchantability and
197     fitness for a particular purpose are disclaimed.  See the LICENSE file
198     distributed with sudo or https://www.sudo.ws/license.html for complete
199     details.
200
201Sudo 1.9.5p2                   October 20, 2019                   Sudo 1.9.5p2
Impressum