1RTLD-AUDIT(7)              Linux Programmer's Manual             RTLD-AUDIT(7)
2
3
4

NAME

6       rtld-audit - auditing API for the dynamic linker
7

SYNOPSIS

9       #define _GNU_SOURCE
10
11       #include <link.h>
12

DESCRIPTION

14       The  GNU dynamic linker (run-time linker) provides an auditing API that
15       allows an application to  be  notified  when  various  dynamic  linking
16       events  occur.  This API is very similar to the auditing interface pro‐
17       vided by the Solaris run-time linker.  The necessary constants and pro‐
18       totypes are defined by including <link.h>.
19
20       To  use  this  interface,  the programmer creates a shared library that
21       implements a standard set of function names.  Not all of the  functions
22       need  to be implemented: in most cases, if the programmer is not inter‐
23       ested in a particular class of auditing event, then  no  implementation
24       needs to be provided for the corresponding auditing function.
25
26       To  employ  the  auditing  interface, the environment variable LD_AUDIT
27       must be defined to contain a colon-separated list of shared  libraries,
28       each  of  which  can  implement  (parts  of) the auditing API.  When an
29       auditable event occurs, the corresponding function is invoked  in  each
30       library, in the order that the libraries are listed.
31
32   la_version()
33
34       unsigned int la_version(unsigned int version);
35
36       This  is the only function that must be defined by an auditing library:
37       it performs the initial handshake between the dynamic  linker  and  the
38       auditing  library.   When  invoking  this  function, the dynamic linker
39       passes, in version, the highest version of the auditing interface  that
40       the linker supports.  If necessary, the auditing library can check that
41       this version is sufficient for its requirements.
42
43       As its function result, this function should return the version of  the
44       auditing interface that this auditing library expects to use (returning
45       version is acceptable).  If the returned value is 0, or a version  that
46       is  greater  than  that supported by the dynamic linker, then the audit
47       library is ignored.
48
49   la_objsearch()
50
51       char *la_objsearch(const char *name, uintptr_t *cookie,
52                          unsigned int flag);
53
54       The dynamic linker invokes this function to inform the auditing library
55       that  it  is about to search for a shared object.  The name argument is
56       the filename or pathname that is to be searched for.  cookie identifies
57       the shared object that initiated the search.  flag is set to one of the
58       following values:
59
60       LA_SER_ORIG      This is the original name that is being searched  for.
61                        Typically,  this  name  comes  from  an  ELF DT_NEEDED
62                        entry, or is the filename argument given to dlopen(3).
63
64       LA_SER_LIBPATH   name  was  created  using  a  directory  specified  in
65                        LD_LIBRARY_PATH.
66
67       LA_SER_RUNPATH   name was created using a directory specified in an ELF
68                        DT_RPATH or DT_RUNPATH list.
69
70       LA_SER_CONFIG    name   was   found   via   the    ldconfig(8)    cache
71                        (/etc/ld.so.cache).
72
73       LA_SER_DEFAULT   name  was  found  via  a  search of one of the default
74                        directories.
75
76       LA_SER_SECURE    name is specific to a secure object (unused on Linux).
77
78       As its function result, la_objsearch() returns the  pathname  that  the
79       dynamic linker should use for further processing.  If NULL is returned,
80       then this pathname is ignored for further processing.   If  this  audit
81       library  simply  intends  to  monitor search paths, then name should be
82       returned.
83
84   la_activity()
85
86       void la_activity( uintptr_t *cookie, unsigned int flag);
87
88       The dynamic linker calls this function to inform the  auditing  library
89       that  link-map  activity is occurring.  cookie identifies the object at
90       the head of the link map.  When the dynamic linker invokes  this  func‐
91       tion, flag is set to one of the following values:
92
93       LA_ACT_ADD         New objects are being added to the link map.
94
95       LA_ACT_DELETE      Objects are being removed from the link map.
96
97       LA_ACT_CONSISTENT  Link-map  activity  has  been  completed: the map is
98                          once again consistent.
99
100   la_objopen()
101
102       unsigned int la_objopen(struct link_map *map, Lmid_t lmid,
103                               uintptr_t *cookie);
104
105       The dynamic linker calls this function when  a  new  shared  object  is
106       loaded.   The  map  argument  is a pointer to a link-map structure that
107       describes the object.  The lmid field has one of the following values
108
109       LM_ID_BASE       Link map is part of the initial namespace.
110
111       LM_ID_NEWLM      Link map is part of  a  new  namespace  requested  via
112                        dlmopen(3).
113
114       cookie  is  a pointer to an identifier for this object.  The identifier
115       is provided to later calls to functions  in  the  auditing  library  in
116       order to identify this object.  This identifier is initialized to point
117       to object's link map, but the audit library can change  the  identifier
118       to some other value that it may prefer to use to identify the object.
119
120       As  its  return value, la_objopen() returns a bit mask created by ORing
121       zero or more of the  following  constants,  which  allow  the  auditing
122       library to select the objects to be monitored by la_symbind*():
123
124       LA_FLG_BINDTO    Audit symbol bindings to this object.
125
126       LA_FLG_BINDFROM  Audit symbol bindings from this object.
127
128       A return value of 0 from la_objopen() indicates that no symbol bindings
129       should be audited for this object.
130
131   la_objclose()
132
133       unsigned int la_objclose(uintptr_t *cookie);
134
135       The dynamic linker invokes this function after  any  finalization  code
136       for  the  object has been executed, before the object is unloaded.  The
137       cookie argument is the identifier obtained from a  previous  invocation
138       of la_objopen().
139
140       In  the  current implementation, the value returned by la_objclose() is
141       ignored.
142
143   la_preinit()
144
145       void la_preinit(uintptr_t *cookie);
146
147       The dynamic linker invokes this function after all shared objects  have
148       been  loaded, before control is passed to the application (i.e., before
149       calling main()).  Note that main() may  still  later  dynamically  load
150       objects using dlopen(3).
151
152   la_symbind*()
153
154       uintptr_t la_symbind32(Elf32_Sym *sym, unsigned int ndx,
155                              uintptr_t *refcook, uintptr_t *defcook,
156                              unsigned int *flags, const char *symname);
157       uintptr_t la_symbind64(Elf64_Sym *sym, unsigned int ndx,
158                              uintptr_t *refcook, uintptr_t *defcook,
159                              unsigned int *flags, const char *symname);
160
161       The dynamic linker invokes one of these functions when a symbol binding
162       occurs between two shared objects that have been  marked  for  auditing
163       notification  by la_objopen().  The la_symbind32() function is employed
164       on 32-bit platforms; the la_symbind64() function is employed on  64-bit
165       platforms.
166
167       The  sym argument is a pointer to a structure that provides information
168       about the symbol being bound.  The structure  definition  is  shown  in
169       <elf.h>.   Among  the  fields of this structure, st_value indicates the
170       address to which the symbol is bound.
171
172       The ndx argument gives the index of the symbol in the symbol  table  of
173       the bound shared object.
174
175       The  refcook  argument  identifies the shared object that is making the
176       symbol reference; this is the same identifier that is provided  to  the
177       la_objopen() function that returned LA_FLG_BINDFROM.  The defcook argu‐
178       ment identifies the shared object that defines the  referenced  symbol;
179       this  is the same identifier that is provided to the la_objopen() func‐
180       tion that returned LA_FLG_BINDTO.
181
182       The symname argument points a string containing the name of the symbol.
183
184       The flags argument is a bit mask that both provides  information  about
185       the symbol and can be used to modify further auditing of this PLT (Pro‐
186       cedure Linkage Table) entry.  The dynamic linker may supply the follow‐
187       ing bit values in this argument:
188
189       LA_SYMB_DLSYM         The binding resulted from a call to dlsym(3).
190
191       LA_SYMB_ALTVALUE      A  previous la_symbind*() call returned an alter‐
192                             nate value for this symbol.
193
194       By default,  if  the  auditing  library  implements  la_pltenter()  and
195       la_pltexit()  functions  (see below), then these functions are invoked,
196       after la_symbind(), for PLT entries, each time  the  symbol  is  refer‐
197       enced.   The  following  flags  can  be ORed into *flags to change this
198       default behavior:
199
200       LA_SYMB_NOPLTENTER    Don't call la_pltenter() for this symbol.
201
202       LA_SYMB_NOPLTEXIT     Don't call la_pltexit() for this symbol.
203
204       The return value of la_symbind32() and la_symbind64() is the address to
205       which  control  should  be  passed  after the function returns.  If the
206       auditing library is simply monitoring symbol bindings, then  it  should
207       return  sym->st_name.  A different value may be returned if the library
208       wishes to direct control to an alternate location.
209
210   la_pltenter()
211       The precise name and argument types for this  function  depend  on  the
212       hardware   platform.    (The  appropriate  definition  is  supplied  by
213       <link.h>.)  Here is the definition for x86-32:
214
215       Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx,
216                        uintptr_t *refcook, uintptr_t *defcook,
217                        La_i86_regs *regs, unsigned int *flags,
218                        const char *symname, long int *framesizep);
219
220       This function is invoked just before a PLT entry is called, between two
221       shared objects that have been marked for binding notification.
222
223       The sym, ndx, refcook, defcook, and symname are as for la_symbind*().
224
225       The  regs argument points to a structure (defined in <link.h>) contain‐
226       ing the values of registers to be used for the call to this PLT entry.
227
228       The flags argument points to a bit mask that conveys information about,
229       and  can  be  used to modify subsequent auditing of, this PLT entry, as
230       for la_symbind*().
231
232       The framesizep argument points to a long int buffer that can be used to
233       explicitly  set the frame size used for the call to this PLT entry.  If
234       different la_pltenter() invocations for this  symbol  return  different
235       values,  then  the  maximum  returned value is used.  The la_pltenter()
236       function is only called if this buffer is explicitly set to a  suitable
237       value.
238
239       The return value of la_pltenter() is as for la_symbind*().
240
241   la_pltexit()
242       The  precise  name  and  argument types for this function depend on the
243       hardware  platform.   (The  appropriate  definition  is   supplied   by
244       <link.h>.)  Here is the definition for x86-32:
245
246       unsigned int la_i86_gnu_pltexit(Elf32_Sym *sym, unsigned int ndx,
247                        uintptr_t *refcook, uintptr_t *defcook,
248                        const La_i86_regs *inregs, La_i86_retval *outregs,
249                        const char *symname);
250
251       This  function  is  called  when  a  PLT entry, made between two shared
252       objects that have been marked for binding notification,  returns.   The
253       function is called just before control returns to the caller of the PLT
254       entry.
255
256       The sym, ndx, refcook, defcook, and symname are as for la_symbind*().
257
258       The inregs argument points to a structure (defined  in  <link.h>)  con‐
259       taining  the  values  of registers used for the call to this PLT entry.
260       The outregs argument points to a structure (defined in  <link.h>)  con‐
261       taining return values for the call to this PLT entry.  These values can
262       be modified by the caller, and the changes will be visible to the call‐
263       er of the PLT entry.
264
265       In  the current GNU implementation, the return value of la_pltexit() is
266       ignored.
267

CONFORMING TO

269       This API is nonstandard, but very similar to the Solaris API, described
270       in  the  Solaris  Linker  and  Libraries  Guide, in the chapter Runtime
271       Linker Auditing Interface.
272

NOTES

274       Note the following differences from the Solaris dynamic linker auditing
275       API:
276
277       *  The  Solaris  la_objfilter()  interface  is not supported by the GNU
278          implementation.
279
280       *  The Solaris la_symbind32() and la_pltexit() functions do not provide
281          a symname argument.
282
283       *  The  Solaris  la_pltexit() function does not provide inregs and out‐
284          regs arguments (but does provide a retval argument with the function
285          return value).
286

EXAMPLE

288       #include <link.h>
289       #include <stdio.h>
290
291       unsigned int
292       la_version(unsigned int version)
293       {
294           printf("la_version(): %d\n", version);
295
296           return version;
297       }
298
299       char *
300       la_objsearch(const char *name, uintptr_t *cookie, unsigned int flag)
301       {
302           printf("la_objsearch(): name = %s; cookie = %x", name, cookie);
303           printf("; flag = %s\n",
304                   (flag == LA_SER_ORIG) ?    "LA_SER_ORIG" :
305                   (flag == LA_SER_LIBPATH) ? "LA_SER_LIBPATH" :
306                   (flag == LA_SER_RUNPATH) ? "LA_SER_RUNPATH" :
307                   (flag == LA_SER_DEFAULT) ? "LA_SER_DEFAULT" :
308                   (flag == LA_SER_CONFIG) ?  "LA_SER_CONFIG" :
309                   (flag == LA_SER_SECURE) ?  "LA_SER_SECURE" :
310                   "???");
311
312           return name;
313       }
314
315       void
316       la_activity (uintptr_t *cookie, unsigned int flag)
317       {
318           printf("la_activity(): cookie = %x; flag = %s\n", cookie,
319                   (flag == LA_ACT_CONSISTENT) ? "LA_ACT_CONSISTENT" :
320                   (flag == LA_ACT_ADD) ?        "LA_ACT_ADD" :
321                   (flag == LA_ACT_DELETE) ?     "LA_ACT_DELETE" :
322                   "???");
323       }
324
325       unsigned int
326       la_objopen(struct link_map *map, Lmid_t lmid, uintptr_t *cookie)
327       {
328           printf("la_objopen(): loading \"%s\"; lmid = %s; cookie=%x\n",
329                   map->l_name,
330                   (lmid == LM_ID_BASE) ?  "LM_ID_BASE" :
331                   (lmid == LM_ID_NEWLM) ? "LM_ID_NEWLM" :
332                   "???",
333                   cookie);
334
335           return LA_FLG_BINDTO | LA_FLG_BINDFROM;
336       }
337
338       unsigned int
339       la_objclose (uintptr_t *cookie)
340       {
341           printf("la_objclose(): %x\n", cookie);
342
343           return 0;
344       }
345
346       void
347       la_preinit(uintptr_t *cookie)
348       {
349           printf("la_preinit(): %x\n", cookie);
350       }
351
352       uintptr_t
353       la_symbind32(Elf32_Sym *sym, unsigned int ndx, uintptr_t *refcook,
354               uintptr_t *defcook, unsigned int *flags, const char *symname)
355       {
356           printf("la_symbind32(): symname = %s; sym->st_value = %p\n",
357                   symname, sym->st_value);
358           printf("        ndx = %d; flags = 0x%x", ndx, *flags);
359           printf("; refcook = %x; defcook = %x\n", refcook, defcook);
360
361           return sym->st_value;
362       }
363
364       uintptr_t
365       la_symbind64(Elf64_Sym *sym, unsigned int ndx, uintptr_t *refcook,
366               uintptr_t *defcook, unsigned int *flags, const char *symname)
367       {
368           printf("la_symbind64(): symname = %s; sym->st_value = %p\n",
369                   symname, sym->st_value);
370           printf("        ndx = %d; flags = 0x%x", ndx, *flags);
371           printf("; refcook = %x; defcook = %x\n", refcook, defcook);
372
373           return sym->st_value;
374       }
375
376       Elf32_Addr
377       la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx,
378               uintptr_t *refcook, uintptr_t *defcook, La_i86_regs *regs,
379               unsigned int *flags, const char *symname, long int *framesizep)
380       {
381           printf("la_i86_gnu_pltenter(): %s (%p)\n", symname, sym->st_value);
382
383           return sym->st_value;
384       }
385

BUGS

387       In glibc versions up to and include 2.9, specifying more than one audit
388       library in LD_AUDIT results in a run-time crash.   This  is  reportedly
389       fixed in glibc 2.10.
390

SEE ALSO

392       ldd(1), dlopen(3), ld.so(8), ldconfig(8)
393

COLOPHON

395       This  page  is  part of release 3.25 of the Linux man-pages project.  A
396       description of the project, and information about reporting  bugs,  can
397       be found at http://www.kernel.org/doc/man-pages/.
398
399
400
401Linux                             2009-03-30                     RTLD-AUDIT(7)
Impressum