granicus.if.org Git - sudo/blob - doc/sudoers_timestamp.man.in

   1 .\" Automatically generated from an mdoc input file.  Do not edit.
   2 .\"
   3 .\" Copyright (c) 2017-2018 Todd C. Miller <Todd.Miller@sudo.ws>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .TH "SUDOERS_TIMESTAMP" "@mansectform@" "October 7, 2018" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
  18 .nh
  19 .if n .ad l
  20 .SH "NAME"
  21 \fBsudoers_timestamp\fR
  22 \- Sudoers Time Stamp Format
  23 .SH "DESCRIPTION"
  24 The
  25 \fBsudoers\fR
  26 plugin uses per-user time stamp files for credential caching.
  27 Once a user has been authenticated, they may use
  28 \fBsudo\fR
  29 without a password for a short period of time
  30 (\fR@timeout@\fR
  31 minutes unless overridden by the
  32 \fItimestamp_timeout\fR
  33 option)
  34 \&.
  35 By default,
  36 \fBsudoers\fR
  37 uses a separate record for each terminal, which means that
  38 a user's login sessions are authenticated separately.
  39 The
  40 \fItimestamp_type\fR
  41 option can be used to select the type of time stamp record
  42 \fBsudoers\fR
  43 will use.
  44 .PP
  45 A multi-record time stamp file format was introduced in
  46 \fBsudo\fR
  47 1.8.10 that uses a single file per user.
  48 Previously, a separate file was used for each user and terminal
  49 combination unless tty-based time stamps were disabled.
  50 The new format is extensible and records of multiple types and versions
  51 may coexist within the same file.
  52 .PP
  53 All records, regardless of type or version, begin with a 16-bit version
  54 number and a 16-bit record size.
  55 .PP
  56 Time stamp records have the following structure:
  57 .nf
  58 .sp
  59 .RS 0n
  60 /* Time stamp entry types */
  61 #define TS_GLOBAL               0x01    /* not restricted by tty or ppid */
  62 #define TS_TTY                  0x02    /* restricted by tty */
  63 #define TS_PPID                 0x03    /* restricted by ppid */
  64 #define TS_LOCKEXCL             0x04    /* special lock record */
  65
  66 /* Time stamp flags */
  67 #define TS_DISABLED             0x01    /* entry disabled */
  68 #define TS_ANYUID               0x02    /* ignore uid, only valid in key */
  69
  70 struct timestamp_entry {
  71     unsigned short version;     /* version number */
  72     unsigned short size;        /* entry size */
  73     unsigned short type;        /* TS_GLOBAL, TS_TTY, TS_PPID */
  74     unsigned short flags;       /* TS_DISABLED, TS_ANYUID */
  75     uid_t auth_uid;             /* uid to authenticate as */
  76     pid_t sid;                  /* session ID associated with tty/ppid */
  77     struct timespec start_time; /* session/ppid start time */
  78     struct timespec ts;         /* time stamp (CLOCK_MONOTONIC) */
  79     union {
  80         dev_t ttydev;           /* tty device number */
  81         pid_t ppid;             /* parent pid */
  82     } u;
  83 };
  84 .RE
  85 .fi
  86 .PP
  87 The timestamp_entry struct fields are as follows:
  88 .TP 6n
  89 version
  90 The version number of the timestamp_entry struct.
  91 New entries are created with a version number of 2.
  92 Records with different version numbers may coexist in the
  93 same file but are not inter-operable.
  94 .TP 6n
  95 size
  96 The size of the record in bytes.
  97 .TP 6n
  98 type
  99 The record type, currently
 100 \fRTS_GLOBAL\fR,
 101 \fRTS_TTY\fR,
 102 or
 103 \fRTS_PPID\fR.
 104 .TP 6n
 105 flags
 106 .br
 107 Zero or more record flags which can be bit-wise ORed together.
 108 Supported flags are
 109 \fRTS_DISABLED\fR,
 110 for records disabled via
 111 \fBsudo\fR
 112 \fB\-k\fR
 113 and
 114 \fRTS_ANYUID\fR,
 115 which is used only when matching records.
 116 .TP 6n
 117 auth_uid
 118 The user ID that was used for authentication.
 119 Depending on the value of the
 120 \fIrootpw\fR,
 121 \fIrunaspw\fR
 122 and
 123 \fItargetpw\fR
 124 options, the user ID may be that of the invoking user, the root user,
 125 the default runas user or the target user.
 126 .TP 6n
 127 sid
 128 The ID of the user's terminal session, if present.
 129 The session ID is only used when matching records of type
 130 \fRTS_TTY\fR.
 131 .TP 6n
 132 start_time
 133 The start time of the session leader for records of type
 134 \fRTS_TTY\fR
 135 or of the parent process for records of type
 136 \fRTS_PPID\fR.
 137 The
 138 \fIstart_time\fR
 139 is used to help prevent re-use of a time stamp record after a
 140 user has logged out.
 141 Not all systems support a method to easily retrieve a process's
 142 start time.
 143 The
 144 \fIstart_time\fR
 145 field was added in
 146 \fBsudoers\fR
 147 version 1.8.22 for the second revision of the timestamp_entry struct.
 148 .TP 6n
 149 ts
 150 The actual time stamp.
 151 A monotonic time source (which does not move backward) is used if the
 152 system supports it.
 153 Where possible,
 154 \fBsudoers\fR
 155 uses a monotonic timer that increments even while the system
 156 is suspended.
 157 The value of
 158 \fIts\fR
 159 is updated each time a command is run via
 160 \fBsudo\fR.
 161 If the difference between
 162 \fIts\fR
 163 and the current time is less than the value of the
 164 \fItimestamp_timeout\fR
 165 option, no password is required.
 166 .TP 6n
 167 u.ttydev
 168 The device number of the terminal associated with the session for
 169 records of type
 170 \fRTS_TTY\fR.
 171 .TP 6n
 172 u.ppid
 173 The ID of the parent process for records of type
 174 \fRTS_PPID\fR.
 175 .SH "LOCKING"
 176 In
 177 \fBsudoers\fR
 178 versions 1.8.10 through 1.8.14, the entire time stamp file was
 179 locked for exclusive access when reading or writing to the file.
 180 Starting in
 181 \fBsudoers\fR
 182 1.8.15, individual records are locked in the time stamp file instead
 183 of the entire file and the lock is held for a longer period of time.
 184 This scheme is described below.
 185 .PP
 186 The first record in the time stamp file is of type
 187 \fRTS_LOCKEXCL\fR
 188 and is used as a
 189 \fIlock\fR
 190 record to prevent more than one
 191 \fBsudo\fR
 192 process from adding a new record at the same time.
 193 Once the desired time stamp record has been located or created (and
 194 locked), the
 195 \fRTS_LOCKEXCL\fR
 196 record is unlocked.
 197 The lock on the individual time stamp record, however, is held until
 198 authentication is complete.
 199 This allows
 200 \fBsudoers\fR
 201 to avoid prompting for a password multiple times when it
 202 is used more than once in a pipeline.
 203 .PP
 204 Records of type
 205 \fRTS_GLOBAL\fR
 206 cannot be locked for a long period of time since doing so would
 207 interfere with other
 208 \fBsudo\fR
 209 processes.
 210 Instead, a separate lock record is used to prevent multiple
 211 \fBsudo\fR
 212 processes using the same terminal (or parent process ID) from
 213 prompting for a password as the same time.
 214 .SH "SEE ALSO"
 215 sudoers(@mansectform@),
 216 sudo(@mansectsu@)
 217 .SH "HISTORY"
 218 Originally,
 219 \fBsudo\fR
 220 used a single zero-length file per user and the file's modification
 221 time was used as the time stamp.
 222 Later versions of
 223 \fBsudo\fR
 224 added restrictions on the ownership of the time stamp files and
 225 directory as well as sanity checks on the time stamp itself.
 226 Notable changes were introduced in the following
 227 \fBsudo\fR
 228 versions:
 229 .TP 6n
 230 1.4.0
 231 .br
 232 Support for tty-based time stamp file was added
 233 by appending the terminal name to the time stamp file name.
 234 .TP 6n
 235 1.6.2
 236 .br
 237 The time stamp file was replaced by a per-user directory which
 238 contained any tty-based time stamp files.
 239 .TP 6n
 240 1.6.3p2
 241 The target user name was added to the time stamp file name when the
 242 \fItargetpw\fR
 243 option was set.
 244 .TP 6n
 245 1.7.3
 246 .br
 247 Information about the terminal device was stored in
 248 tty-based time stamp files for sanity checking.
 249 This included the terminal device numbers, inode number and, on systems
 250 where it was not updated when the device was written to, the inode change time.
 251 This helped prevent re-use of the time stamp file after logout.
 252 .TP 6n
 253 1.8.6p7
 254 The terminal session ID was added to tty-based time stamp files to
 255 prevent re-use of the time stamp by the same user in a different
 256 terminal session.
 257 It also helped prevent re-use of the time stamp file on systems where
 258 the terminal device's inode change time was updated by writing.
 259 .TP 6n
 260 1.8.10
 261 A new, multi-record time stamp file format was introduced that uses a
 262 single file per user.
 263 The terminal device's change time was not included since most
 264 systems now update the change time after a write is performed
 265 as required by POSIX.
 266 .TP 6n
 267 1.8.15
 268 Individual records are locked in the time stamp file instead of the
 269 entire file and the lock is held until authentication is complete.
 270 .TP 6n
 271 1.8.22
 272 The start time of the terminal session leader or parent process is
 273 now stored in non-global time stamp records.
 274 This prevents re-use of the time stamp file after logout in most cases.
 275 .sp
 276 Support was added for the kernel-based tty time stamps available in
 277 OpenBSD
 278 which do not use an on-disk time stamp file.
 279 .SH "AUTHORS"
 280 Many people have worked on
 281 \fBsudo\fR
 282 over the years; this version consists of code written primarily by:
 283 .sp
 284 .RS 6n
 285 Todd C. Miller
 286 .RE
 287 .PP
 288 See the CONTRIBUTORS file in the
 289 \fBsudo\fR
 290 distribution (https://www.sudo.ws/contributors.html) for an
 291 exhaustive list of people who have contributed to
 292 \fBsudo\fR.
 293 .SH "BUGS"
 294 If you feel you have found a bug in
 295 \fBsudo\fR,
 296 please submit a bug report at https://bugzilla.sudo.ws/
 297 .SH "SUPPORT"
 298 Limited free support is available via the sudo-users mailing list,
 299 see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
 300 search the archives.
 301 .SH "DISCLAIMER"
 302 \fBsudo\fR
 303 is provided
 304 \(lqAS IS\(rq
 305 and any express or implied warranties, including, but not limited
 306 to, the implied warranties of merchantability and fitness for a
 307 particular purpose are disclaimed.
 308 See the LICENSE file distributed with
 309 \fBsudo\fR
 310 or https://www.sudo.ws/license.html for complete details.