man7/rtld-audit.7

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