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