man7/rtld-audit.7

   1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" 2009-01-12, mtk, Created
   7 .\"
   8 .TH RTLD-AUDIT 7 (date) "Linux man-pages (unreleased)"
   9 .SH NAME
  10 rtld-audit \- auditing API for the dynamic linker
  11 .SH SYNOPSIS
  12 .nf
  13 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  14 .B #include <link.h>
  15 .fi
  16 .SH DESCRIPTION
  17 The GNU dynamic linker (run-time linker)
  18 provides an auditing API that allows an application
  19 to be notified when various dynamic linking events occur.
  20 This API is very similar to the auditing interface provided by the
  21 Solaris run-time linker.
  22 The necessary constants and prototypes are defined by including
  23 .IR <link.h> .
  24 .PP
  25 To use this interface, the programmer creates a shared library
  26 that implements a standard set of function names.
  27 Not all of the functions need to be implemented: in most cases,
  28 if the programmer is not interested in a particular class of auditing event,
  29 then no implementation needs to be provided for the corresponding
  30 auditing function.
  31 .PP
  32 To employ the auditing interface, the environment variable
  33 .B LD_AUDIT
  34 must be defined to contain a colon-separated list of shared libraries,
  35 each of which can implement (parts of) the auditing API.
  36 When an auditable event occurs,
  37 the corresponding function is invoked in each library,
  38 in the order that the libraries are listed.
  39 .SS la_version()
  40 \&
  41 .nf
  42 .BI "unsigned int la_version(unsigned int " version );
  43 .fi
  44 .PP
  45 This is the only function that
  46 .I must
  47 be defined by an auditing library:
  48 it performs the initial handshake between the dynamic linker and
  49 the auditing library.
  50 When invoking this function, the dynamic linker passes, in
  51 .IR version ,
  52 the highest version of the auditing interface that the linker supports.
  53 .PP
  54 A typical implementation of this function simply returns the constant
  55 .BR LAV_CURRENT ,
  56 which indicates the version of
  57 .I <link.h>
  58 that was used to build the audit module.
  59 If the dynamic linker does
  60 not support this version of the audit interface, it will refuse to
  61 activate this audit module.
  62 If the function returns zero, the dynamic
  63 linker also does not activate this audit module.
  64 .PP
  65 In order to enable backwards compatibility with older dynamic linkers,
  66 an audit module can examine the
  67 .I version
  68 argument and return an earlier version than
  69 .BR LAV_CURRENT ,
  70 assuming the module can adjust its implementation to match the
  71 requirements of the previous version of the audit interface.
  72 The
  73 .B la_version
  74 function should not return the value of
  75 .I version
  76 without further checks because it could correspond to an interface
  77 that does not match the
  78 .I <link.h>
  79 definitions used to build the audit module.
  80 .SS la_objsearch()
  81 \&
  82 .nf
  83 .BI "char *la_objsearch(const char *" name ", uintptr_t *" cookie ,
  84 .BI "                   unsigned int " flag );
  85 .fi
  86 .PP
  87 The dynamic linker invokes this function to inform the auditing library
  88 that it is about to search for a shared object.
  89 The
  90 .I name
  91 argument is the filename or pathname that is to be searched for.
  92 .I cookie
  93 identifies the shared object that initiated the search.
  94 .I flag
  95 is set to one of the following values:
  96 .TP 17
  97 .B LA_SER_ORIG
  98 This is the original name that is being searched for.
  99 Typically, this name comes from an ELF
 100 .B DT_NEEDED
 101 entry, or is the
 102 .I filename
 103 argument given to
 104 .BR dlopen (3).
 105 .TP
 106 .B LA_SER_LIBPATH
 107 .I name
 108 was created using a directory specified in
 109 .BR LD_LIBRARY_PATH .
 110 .TP
 111 .B LA_SER_RUNPATH
 112 .I name
 113 was created using a directory specified in an ELF
 114 .B DT_RPATH
 115 or
 116 .B DT_RUNPATH
 117 list.
 118 .TP
 119 .B LA_SER_CONFIG
 120 .I name
 121 was found via the
 122 .BR ldconfig (8)
 123 cache
 124 .RI ( /etc/ld.so.cache ).
 125 .TP
 126 .B LA_SER_DEFAULT
 127 .I name
 128 was found via a search of one of the default directories.
 129 .TP
 130 .B LA_SER_SECURE
 131 .I name
 132 is specific to a secure object (unused on Linux).
 133 .PP
 134 As its function result,
 135 .BR la_objsearch ()
 136 returns the pathname that the dynamic linker should use
 137 for further processing.
 138 If NULL is returned, then this pathname is ignored for further processing.
 139 If this audit library simply intends to monitor search paths, then
 140 .I name
 141 should be returned.
 142 .SS la_activity()
 143 \&
 144 .nf
 145 .BI "void la_activity( uintptr_t *" cookie ", unsigned int "flag  );
 146 .fi
 147 .PP
 148 The dynamic linker calls this function to inform the auditing library
 149 that link-map activity is occurring.
 150 .I cookie
 151 identifies the object at the head of the link map.
 152 When the dynamic linker invokes this function,
 153 .I flag
 154 is set to one of the following values:
 155 .TP 19
 156 .B LA_ACT_ADD
 157 New objects are being added to the link map.
 158 .TP
 159 .B LA_ACT_DELETE
 160 Objects are being removed from the link map.
 161 .TP
 162 .B LA_ACT_CONSISTENT
 163 Link-map activity has been completed: the map is once again consistent.
 164 .SS la_objopen()
 165 \&
 166 .nf
 167 .BI "unsigned int la_objopen(struct link_map *" map ", Lmid_t " lmid ,
 168 .BI "                        uintptr_t *" cookie );
 169 .fi
 170 .PP
 171 The dynamic linker calls this function when a new shared object is loaded.
 172 The
 173 .I map
 174 argument is a pointer to a link-map structure that describes the object.
 175 The
 176 .I lmid
 177 field has one of the following values
 178 .TP 17
 179 .B LM_ID_BASE
 180 Link map is part of the initial namespace.
 181 .TP
 182 .B LM_ID_NEWLM
 183 Link map is part of a new namespace requested via
 184 .BR dlmopen (3).
 185 .PP
 186 .I cookie
 187 is a pointer to an identifier for this object.
 188 The identifier is provided to later calls to functions
 189 in the auditing library in order to identify this object.
 190 This identifier is initialized to point to object's link map,
 191 but the audit library can change the identifier to some other value
 192 that it may prefer to use to identify the object.
 193 .PP
 194 As its return value,
 195 .BR la_objopen ()
 196 returns a bit mask created by ORing zero or more of the
 197 following constants,
 198 which allow the auditing library to select the objects to be monitored by
 199 .BR la_symbind* ():
 200 .TP 17
 201 .B LA_FLG_BINDTO
 202 Audit symbol bindings to this object.
 203 .TP
 204 .B LA_FLG_BINDFROM
 205 Audit symbol bindings from this object.
 206 .PP
 207 A return value of 0 from
 208 .BR la_objopen ()
 209 indicates that no symbol bindings should be audited for this object.
 210 .SS la_objclose()
 211 \&
 212 .nf
 213 .BI "unsigned int la_objclose(uintptr_t *" cookie );
 214 .fi
 215 .PP
 216 The dynamic linker invokes this function after any finalization
 217 code for the object has been executed,
 218 before the object is unloaded.
 219 The
 220 .I cookie
 221 argument is the identifier obtained from a previous invocation of
 222 .BR la_objopen ().
 223 .PP
 224 In the current implementation, the value returned by
 225 .BR la_objclose ()
 226 is ignored.
 227 .SS la_preinit()
 228 \&
 229 .nf
 230 .BI "void la_preinit(uintptr_t *" cookie );
 231 .fi
 232 .PP
 233 The dynamic linker invokes this function after all shared objects
 234 have been loaded, before control is passed to the application
 235 (i.e., before calling
 236 .IR main ()).
 237 Note that
 238 .IR main ()
 239 may still later dynamically load objects using
 240 .BR dlopen (3).
 241 .SS la_symbind*()
 242 \&
 243 .nf
 244 .BI "uintptr_t la_symbind32(Elf32_Sym *" sym ", unsigned int " ndx ,
 245 .BI "                       uintptr_t *" refcook ", uintptr_t *" defcook ,
 246 .BI "                       unsigned int *" flags ", const char *" symname );
 247 .BI "uintptr_t la_symbind64(Elf64_Sym *" sym ", unsigned int " ndx ,
 248 .BI "                       uintptr_t *" refcook ", uintptr_t *" defcook ,
 249 .BI "                       unsigned int *" flags ", const char *" symname );
 250 .fi
 251 .PP
 252 The dynamic linker invokes one of these functions
 253 when a symbol binding occurs between two shared objects
 254 that have been marked for auditing notification by
 255 .BR la_objopen ().
 256 The
 257 .BR la_symbind32 ()
 258 function is employed on 32-bit platforms;
 259 the
 260 .BR la_symbind64 ()
 261 function is employed on 64-bit platforms.
 262 .PP
 263 The
 264 .I sym
 265 argument is a pointer to a structure
 266 that provides information about the symbol being bound.
 267 The structure definition is shown in
 268 .IR <elf.h> .
 269 Among the fields of this structure,
 270 .I st_value
 271 indicates the address to which the symbol is bound.
 272 .PP
 273 The
 274 .I ndx
 275 argument gives the index of the symbol in the symbol table
 276 of the bound shared object.
 277 .PP
 278 The
 279 .I refcook
 280 argument identifies the shared object that is making the symbol reference;
 281 this is the same identifier that is provided to the
 282 .BR la_objopen ()
 283 function that returned
 284 .BR LA_FLG_BINDFROM .
 285 The
 286 .I defcook
 287 argument identifies the shared object that defines the referenced symbol;
 288 this is the same identifier that is provided to the
 289 .BR la_objopen ()
 290 function that returned
 291 .BR LA_FLG_BINDTO .
 292 .PP
 293 The
 294 .I symname
 295 argument points a string containing the name of the symbol.
 296 .PP
 297 The
 298 .I flags
 299 argument is a bit mask that both provides information about the symbol
 300 and can be used to modify further auditing of this
 301 PLT (Procedure Linkage Table) entry.
 302 The dynamic linker may supply the following bit values in this argument:
 303 .\" LA_SYMB_STRUCTCALL appears to be unused
 304 .TP 22
 305 .B LA_SYMB_DLSYM
 306 The binding resulted from a call to
 307 .BR dlsym (3).
 308 .TP
 309 .B LA_SYMB_ALTVALUE
 310 A previous
 311 .BR la_symbind* ()
 312 call returned an alternate value for this symbol.
 313 .PP
 314 By default, if the auditing library implements
 315 .BR la_pltenter ()
 316 and
 317 .BR la_pltexit ()
 318 functions (see below), then these functions are invoked, after
 319 .BR la_symbind (),
 320 for PLT entries, each time the symbol is referenced.
 321 .\" pltenter/pltexit are called for non-dynamically loaded libraries,
 322 .\" but don't seem to be called for dynamically loaded libs?
 323 .\" Is this the same on Solaris?
 324 The following flags can be ORed into
 325 .I *flags
 326 to change this default behavior:
 327 .TP 22
 328 .B LA_SYMB_NOPLTENTER
 329 Don't call
 330 .BR la_pltenter ()
 331 for this symbol.
 332 .TP 22
 333 .B LA_SYMB_NOPLTEXIT
 334 Don't call
 335 .BR la_pltexit ()
 336 for this symbol.
 337 .PP
 338 The return value of
 339 .BR la_symbind32 ()
 340 and
 341 .BR la_symbind64 ()
 342 is the address to which control should be passed after the function returns.
 343 If the auditing library is simply monitoring symbol bindings,
 344 then it should return
 345 .IR sym\->st_value .
 346 A different value may be returned if the library wishes to direct control
 347 to an alternate location.
 348 .SS la_pltenter()
 349 The precise name and argument types for this function
 350 depend on the hardware platform.
 351 (The appropriate definition is supplied by
 352 .IR <link.h> .)
 353 Here is the definition for x86-32:
 354 .PP
 355 .nf
 356 .BI "Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *" sym ", unsigned int " ndx ,
 357 .BI "                 uintptr_t *" refcook ", uintptr_t *" defcook ,
 358 .BI "                 La_i86_regs *" regs ", unsigned int *" flags ,
 359 .BI "                 const char *" symname ", long *" framesizep );
 360 .fi
 361 .PP
 362 This function is invoked just before a PLT entry is called,
 363 between two shared objects that have been marked for binding notification.
 364 .PP
 365 The
 366 .IR sym ,
 367 .IR ndx ,
 368 .IR refcook ,
 369 .IR defcook ,
 370 and
 371 .I symname
 372 are as for
 373 .BR la_symbind* ().
 374 .PP
 375 The
 376 .I regs
 377 argument points to a structure (defined in
 378 .IR <link.h> )
 379 containing the values of registers to be used for
 380 the call to this PLT entry.
 381 .PP
 382 The
 383 .I flags
 384 argument points to a bit mask that conveys information about,
 385 and can be used to modify subsequent auditing of, this PLT entry, as for
 386 .BR la_symbind* ().
 387 .PP
 388 .\" FIXME . Is the following correct?
 389 The
 390 .I framesizep
 391 argument points to a
 392 .I long\~int
 393 buffer that can be used to explicitly set the frame size
 394 used for the call to this PLT entry.
 395 If different
 396 .BR la_pltenter ()
 397 invocations for this symbol return different values,
 398 then the maximum returned value is used.
 399 The
 400 .BR la_pltexit ()
 401 function is called only if this buffer is
 402 explicitly set to a suitable value.
 403 .PP
 404 The return value of
 405 .BR la_pltenter ()
 406 is as for
 407 .BR la_symbind* ().
 408 .SS la_pltexit()
 409 The precise name and argument types for this function
 410 depend on the hardware platform.
 411 (The appropriate definition is supplied by
 412 .IR <link.h> .)
 413 Here is the definition for x86-32:
 414 .PP
 415 .nf
 416 .BI "unsigned int la_i86_gnu_pltexit(Elf32_Sym *" sym ", unsigned int " ndx ,
 417 .BI "                 uintptr_t *" refcook ", uintptr_t *" defcook ,
 418 .BI "                 const La_i86_regs *" inregs ", La_i86_retval *" outregs ,
 419 .BI "                 const char *" symname );
 420 .fi
 421 .PP
 422 This function is called when a PLT entry,
 423 made between two shared objects that have been marked
 424 for binding notification, returns.
 425 The function is called just before control returns to the caller
 426 of the PLT entry.
 427 .PP
 428 The
 429 .IR sym ,
 430 .IR ndx ,
 431 .IR refcook ,
 432 .IR defcook ,
 433 and
 434 .I symname
 435 are as for
 436 .BR la_symbind* ().
 437 .PP
 438 The
 439 .I inregs
 440 argument points to a structure (defined in
 441 .IR <link.h> )
 442 containing the values of registers used for the call to this PLT entry.
 443 The
 444 .I outregs
 445 argument points to a structure (defined in
 446 .IR <link.h> )
 447 containing return values for the call to this PLT entry.
 448 These values can be modified by the caller,
 449 and the changes will be visible to the caller of the PLT entry.
 450 .PP
 451 In the current GNU implementation, the return value of
 452 .BR la_pltexit ()
 453 is ignored.
 454 .\" This differs from Solaris, where an audit library that monitors
 455 .\" symbol binding should return the value of the 'retval' argument
 456 .\" (not provided by GNU, but equivalent to returning outregs->lrv_eax
 457 .\" on (say) x86-32).
 458 .SH STANDARDS
 459 This API is nonstandard, but very similar to the Solaris API,
 460 described in the Solaris
 461 .IR "Linker and Libraries Guide" ,
 462 in the chapter
 463 .IR "Runtime Linker Auditing Interface" .
 464 .SH NOTES
 465 Note the following differences from the Solaris dynamic linker
 466 auditing API:
 467 .IP \[bu] 3
 468 The Solaris
 469 .BR la_objfilter ()
 470 interface is not supported by the GNU implementation.
 471 .IP \[bu]
 472 The Solaris
 473 .BR la_symbind32 ()
 474 and
 475 .BR la_pltexit ()
 476 functions do not provide a
 477 .I symname
 478 argument.
 479 .IP \[bu]
 480 The Solaris
 481 .BR la_pltexit ()
 482 function does not provide
 483 .I inregs
 484 and
 485 .I outregs
 486 arguments (but does provide a
 487 .I retval
 488 argument with the function return value).
 489 .SH BUGS
 490 In glibc versions up to and include 2.9,
 491 specifying more than one audit library in
 492 .B LD_AUDIT
 493 results in a run-time crash.
 494 This is reportedly fixed in glibc 2.10.
 495 .\" FIXME . Specifying multiple audit libraries doesn't work on GNU.
 496 .\" My simple tests on Solaris work okay, but not on Linux -- mtk, Jan 2009
 497 .\" glibc bug filed: http://sourceware.org/bugzilla/show_bug.cgi?id=9733
 498 .\" Reportedly, this is fixed on 16 Mar 2009 (i.e., for glibc 2.10)
 499 .SH EXAMPLES
 500 .EX
 501 #include <link.h>
 502 #include <stdio.h>
 503
 504 unsigned int
 505 la_version(unsigned int version)
 506 {
 507     printf("la_version(): version = %u; LAV_CURRENT = %u\en",
 508             version, LAV_CURRENT);
 509
 510     return LAV_CURRENT;
 511 }
 512
 513 char *
 514 la_objsearch(const char *name, uintptr_t *cookie, unsigned int flag)
 515 {
 516     printf("la_objsearch(): name = %s; cookie = %p", name, cookie);
 517     printf("; flag = %s\en",
 518             (flag == LA_SER_ORIG) ?    "LA_SER_ORIG" :
 519             (flag == LA_SER_LIBPATH) ? "LA_SER_LIBPATH" :
 520             (flag == LA_SER_RUNPATH) ? "LA_SER_RUNPATH" :
 521             (flag == LA_SER_DEFAULT) ? "LA_SER_DEFAULT" :
 522             (flag == LA_SER_CONFIG) ?  "LA_SER_CONFIG" :
 523             (flag == LA_SER_SECURE) ?  "LA_SER_SECURE" :
 524             "???");
 525
 526     return name;
 527 }
 528
 529 void
 530 la_activity (uintptr_t *cookie, unsigned int flag)
 531 {
 532     printf("la_activity(): cookie = %p; flag = %s\en", cookie,
 533             (flag == LA_ACT_CONSISTENT) ? "LA_ACT_CONSISTENT" :
 534             (flag == LA_ACT_ADD) ?        "LA_ACT_ADD" :
 535             (flag == LA_ACT_DELETE) ?     "LA_ACT_DELETE" :
 536             "???");
 537 }
 538
 539 unsigned int
 540 la_objopen(struct link_map *map, Lmid_t lmid, uintptr_t *cookie)
 541 {
 542     printf("la_objopen(): loading \e"%s\e"; lmid = %s; cookie=%p\en",
 543             map\->l_name,
 544             (lmid == LM_ID_BASE) ?  "LM_ID_BASE" :
 545             (lmid == LM_ID_NEWLM) ? "LM_ID_NEWLM" :
 546             "???",
 547             cookie);
 548
 549     return LA_FLG_BINDTO | LA_FLG_BINDFROM;
 550 }
 551
 552 unsigned int
 553 la_objclose (uintptr_t *cookie)
 554 {
 555     printf("la_objclose(): %p\en", cookie);
 556
 557     return 0;
 558 }
 559
 560 void
 561 la_preinit(uintptr_t *cookie)
 562 {
 563     printf("la_preinit(): %p\en", cookie);
 564 }
 565
 566 uintptr_t
 567 la_symbind32(Elf32_Sym *sym, unsigned int ndx, uintptr_t *refcook,
 568         uintptr_t *defcook, unsigned int *flags, const char *symname)
 569 {
 570     printf("la_symbind32(): symname = %s; sym\->st_value = %p\en",
 571             symname, sym\->st_value);
 572     printf("        ndx = %u; flags = %#x", ndx, *flags);
 573     printf("; refcook = %p; defcook = %p\en", refcook, defcook);
 574
 575     return sym\->st_value;
 576 }
 577
 578 uintptr_t
 579 la_symbind64(Elf64_Sym *sym, unsigned int ndx, uintptr_t *refcook,
 580         uintptr_t *defcook, unsigned int *flags, const char *symname)
 581 {
 582     printf("la_symbind64(): symname = %s; sym\->st_value = %p\en",
 583             symname, sym\->st_value);
 584     printf("        ndx = %u; flags = %#x", ndx, *flags);
 585     printf("; refcook = %p; defcook = %p\en", refcook, defcook);
 586
 587     return sym\->st_value;
 588 }
 589
 590 Elf32_Addr
 591 la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx,
 592         uintptr_t *refcook, uintptr_t *defcook, La_i86_regs *regs,
 593         unsigned int *flags, const char *symname, long *framesizep)
 594 {
 595     printf("la_i86_gnu_pltenter(): %s (%p)\en", symname, sym\->st_value);
 596
 597     return sym\->st_value;
 598 }
 599 .EE
 600 .SH SEE ALSO
 601 .BR ldd (1),
 602 .BR dlopen (3),
 603 .BR ld.so (8),
 604 .BR ldconfig (8)