1RTLD-AUDIT(7) Linux Programmer's Manual RTLD-AUDIT(7)
2
6 rtld-audit - auditing API for the dynamic linker
7
9 #define _GNU_SOURCE /* See feature_test_macros(7) */
10 #include <link.h>
11
13 The GNU dynamic linker (run-time linker) provides an auditing API that
14 allows an application to be notified when various dynamic linking
15 events occur. This API is very similar to the auditing interface pro‐
16 vided by the Solaris run-time linker. The necessary constants and pro‐
17 totypes are defined by including <link.h>.
18 To use this interface, the programmer creates a shared library that im‐
20 plements a standard set of function names. Not all of the functions
21 need to be implemented: in most cases, if the programmer is not inter‐
22 ested in a particular class of auditing event, then no implementation
23 needs to be provided for the corresponding auditing function.
24 To employ the auditing interface, the environment variable LD_AUDIT
26 must be defined to contain a colon-separated list of shared libraries,
27 each of which can implement (parts of) the auditing API. When an au‐
28 ditable event occurs, the corresponding function is invoked in each li‐
29 brary, in the order that the libraries are listed.
30 la_version()
32 unsigned int la_version(unsigned int version);
34 This is the only function that must be defined by an auditing library:
36 it performs the initial handshake between the dynamic linker and the
37 auditing library. When invoking this function, the dynamic linker
38 passes, in version, the highest version of the auditing interface that
39 the linker supports.
40 A typical implementation of this function simply returns the constant
42 LAV_CURRENT, which indicates the version of <link.h> that was used to
43 build the audit module. If the dynamic linker does not support this
44 version of the audit interface, it will refuse to activate this audit
45 module. If the function returns zero, the dynamic linker also does not
46 activate this audit module.
47 In order to enable backwards compatibility with older dynamic linkers,
49 an audit module can examine the version argument and return an earlier
50 version than LAV_CURRENT, assuming the module can adjust its implemen‐
51 tation to match the requirements of the previous version of the audit
52 interface. The la_version function should not return the value of ver‐
53 sion without further checks because it could correspond to an interface
54 that does not match the <link.h> definitions used to build the audit
55 module.
56 la_objsearch()
58 char *la_objsearch(const char *name, uintptr_t *cookie,
60 unsigned int flag);
61 The dynamic linker invokes this function to inform the auditing library
63 that it is about to search for a shared object. The name argument is
64 the filename or pathname that is to be searched for. cookie identifies
65 the shared object that initiated the search. flag is set to one of the
66 following values:
67 LA_SER_ORIG This is the original name that is being searched for.
69 Typically, this name comes from an ELF DT_NEEDED en‐
70 try, or is the filename argument given to dlopen(3).
71 LA_SER_LIBPATH name was created using a directory specified in LD_LI‐
73 BRARY_PATH.
74 LA_SER_RUNPATH name was created using a directory specified in an ELF
76 DT_RPATH or DT_RUNPATH list.
77 LA_SER_CONFIG name was found via the ldconfig(8) cache
79 (/etc/ld.so.cache).
80 LA_SER_DEFAULT name was found via a search of one of the default di‐
82 rectories.
83 LA_SER_SECURE name is specific to a secure object (unused on Linux).
85 As its function result, la_objsearch() returns the pathname that the
87 dynamic linker should use for further processing. If NULL is returned,
88 then this pathname is ignored for further processing. If this audit
89 library simply intends to monitor search paths, then name should be re‐
90 turned.
91 la_activity()
93 void la_activity( uintptr_t *cookie, unsigned int flag);
95 The dynamic linker calls this function to inform the auditing library
97 that link-map activity is occurring. cookie identifies the object at
98 the head of the link map. When the dynamic linker invokes this func‐
99 tion, flag is set to one of the following values:
100 LA_ACT_ADD New objects are being added to the link map.
102 LA_ACT_DELETE Objects are being removed from the link map.
104 LA_ACT_CONSISTENT Link-map activity has been completed: the map is
106 once again consistent.
107 la_objopen()
109 unsigned int la_objopen(struct link_map *map, Lmid_t lmid,
111 uintptr_t *cookie);
112 The dynamic linker calls this function when a new shared object is
114 loaded. The map argument is a pointer to a link-map structure that de‐
115 scribes the object. The lmid field has one of the following values
116 LM_ID_BASE Link map is part of the initial namespace.
118 LM_ID_NEWLM Link map is part of a new namespace requested via dl‐
120 mopen(3).
121 cookie is a pointer to an identifier for this object. The identifier
123 is provided to later calls to functions in the auditing library in or‐
124 der to identify this object. This identifier is initialized to point
125 to object's link map, but the audit library can change the identifier
126 to some other value that it may prefer to use to identify the object.
127 As its return value, la_objopen() returns a bit mask created by ORing
129 zero or more of the following constants, which allow the auditing li‐
130 brary to select the objects to be monitored by la_symbind*():
131 LA_FLG_BINDTO Audit symbol bindings to this object.
133 LA_FLG_BINDFROM Audit symbol bindings from this object.
135 A return value of 0 from la_objopen() indicates that no symbol bindings
137 should be audited for this object.
138 la_objclose()
140 unsigned int la_objclose(uintptr_t *cookie);
142 The dynamic linker invokes this function after any finalization code
144 for the object has been executed, before the object is unloaded. The
145 cookie argument is the identifier obtained from a previous invocation
146 of la_objopen().
147 In the current implementation, the value returned by la_objclose() is
149 ignored.
150 la_preinit()
152 void la_preinit(uintptr_t *cookie);
154 The dynamic linker invokes this function after all shared objects have
156 been loaded, before control is passed to the application (i.e., before
157 calling main()). Note that main() may still later dynamically load ob‐
158 jects using dlopen(3).
159 la_symbind*()
161 uintptr_t la_symbind32(Elf32_Sym *sym, unsigned int ndx,
163 uintptr_t *refcook, uintptr_t *defcook,
164 unsigned int *flags, const char *symname);
165 uintptr_t la_symbind64(Elf64_Sym *sym, unsigned int ndx,
166 uintptr_t *refcook, uintptr_t *defcook,
167 unsigned int *flags, const char *symname);
168 The dynamic linker invokes one of these functions when a symbol binding
170 occurs between two shared objects that have been marked for auditing
171 notification by la_objopen(). The la_symbind32() function is employed
172 on 32-bit platforms; the la_symbind64() function is employed on 64-bit
173 platforms.
174 The sym argument is a pointer to a structure that provides information
176 about the symbol being bound. The structure definition is shown in
177 <elf.h>. Among the fields of this structure, st_value indicates the
178 address to which the symbol is bound.
179 The ndx argument gives the index of the symbol in the symbol table of
181 the bound shared object.
182 The refcook argument identifies the shared object that is making the
184 symbol reference; this is the same identifier that is provided to the
185 la_objopen() function that returned LA_FLG_BINDFROM. The defcook argu‐
186 ment identifies the shared object that defines the referenced symbol;
187 this is the same identifier that is provided to the la_objopen() func‐
188 tion that returned LA_FLG_BINDTO.
189 The symname argument points a string containing the name of the symbol.
191 The flags argument is a bit mask that both provides information about
193 the symbol and can be used to modify further auditing of this PLT (Pro‐
194 cedure Linkage Table) entry. The dynamic linker may supply the follow‐
195 ing bit values in this argument:
196 LA_SYMB_DLSYM The binding resulted from a call to dlsym(3).
198 LA_SYMB_ALTVALUE A previous la_symbind*() call returned an alter‐
200 nate value for this symbol.
201 By default, if the auditing library implements la_pltenter() and la_pl‐
203 texit() functions (see below), then these functions are invoked, after
204 la_symbind(), for PLT entries, each time the symbol is referenced. The
205 following flags can be ORed into *flags to change this default behav‐
206 ior:
207 LA_SYMB_NOPLTENTER Don't call la_pltenter() for this symbol.
209 LA_SYMB_NOPLTEXIT Don't call la_pltexit() for this symbol.
211 The return value of la_symbind32() and la_symbind64() is the address to
213 which control should be passed after the function returns. If the au‐
214 diting library is simply monitoring symbol bindings, then it should re‐
215 turn sym->st_value. A different value may be returned if the library
216 wishes to direct control to an alternate location.
217 la_pltenter()
219 The precise name and argument types for this function depend on the
220 hardware platform. (The appropriate definition is supplied by
221 <link.h>.) Here is the definition for x86-32:
222 Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx,
224 uintptr_t *refcook, uintptr_t *defcook,
225 La_i86_regs *regs, unsigned int *flags,
226 const char *symname, long *framesizep);
227 This function is invoked just before a PLT entry is called, between two
229 shared objects that have been marked for binding notification.
230 The sym, ndx, refcook, defcook, and symname are as for la_symbind*().
232 The regs argument points to a structure (defined in <link.h>) contain‐
234 ing the values of registers to be used for the call to this PLT entry.
235 The flags argument points to a bit mask that conveys information about,
237 and can be used to modify subsequent auditing of, this PLT entry, as
238 for la_symbind*().
239 The framesizep argument points to a long int buffer that can be used to
241 explicitly set the frame size used for the call to this PLT entry. If
242 different la_pltenter() invocations for this symbol return different
243 values, then the maximum returned value is used. The la_pltexit()
244 function is called only if this buffer is explicitly set to a suitable
245 value.
246 The return value of la_pltenter() is as for la_symbind*().
248 la_pltexit()
250 The precise name and argument types for this function depend on the
251 hardware platform. (The appropriate definition is supplied by
252 <link.h>.) Here is the definition for x86-32:
253 unsigned int la_i86_gnu_pltexit(Elf32_Sym *sym, unsigned int ndx,
255 uintptr_t *refcook, uintptr_t *defcook,
256 const La_i86_regs *inregs, La_i86_retval *outregs,
257 const char *symname);
258 This function is called when a PLT entry, made between two shared ob‐
260 jects that have been marked for binding notification, returns. The
261 function is called just before control returns to the caller of the PLT
262 entry.
263 The sym, ndx, refcook, defcook, and symname are as for la_symbind*().
265 The inregs argument points to a structure (defined in <link.h>) con‐
267 taining the values of registers used for the call to this PLT entry.
268 The outregs argument points to a structure (defined in <link.h>) con‐
269 taining return values for the call to this PLT entry. These values can
270 be modified by the caller, and the changes will be visible to the
271 caller of the PLT entry.
272 In the current GNU implementation, the return value of la_pltexit() is
274 ignored.
275
277 This API is nonstandard, but very similar to the Solaris API, described
278 in the Solaris Linker and Libraries Guide, in the chapter Runtime
279 Linker Auditing Interface.
280
282 Note the following differences from the Solaris dynamic linker auditing
283 API:
284 * The Solaris la_objfilter() interface is not supported by the GNU im‐
286 plementation.
287 * The Solaris la_symbind32() and la_pltexit() functions do not provide
289 a symname argument.
290 * The Solaris la_pltexit() function does not provide inregs and out‐
292 regs arguments (but does provide a retval argument with the function
293 return value).
294
296 In glibc versions up to and include 2.9, specifying more than one audit
297 library in LD_AUDIT results in a run-time crash. This is reportedly
298 fixed in glibc 2.10.
299
301 #include <link.h>
302 #include <stdio.h>
303 unsigned int
305 la_version(unsigned int version)
306 {
307 printf("la_version(): version = %u; LAV_CURRENT = %u\n",
308 version, LAV_CURRENT);
309 return LAV_CURRENT;
311 }
312 char *
314 la_objsearch(const char *name, uintptr_t *cookie, unsigned int flag)
315 {
316 printf("la_objsearch(): name = %s; cookie = %p", name, cookie);
317 printf("; flag = %s\n",
318 (flag == LA_SER_ORIG) ? "LA_SER_ORIG" :
319 (flag == LA_SER_LIBPATH) ? "LA_SER_LIBPATH" :
320 (flag == LA_SER_RUNPATH) ? "LA_SER_RUNPATH" :
321 (flag == LA_SER_DEFAULT) ? "LA_SER_DEFAULT" :
322 (flag == LA_SER_CONFIG) ? "LA_SER_CONFIG" :
323 (flag == LA_SER_SECURE) ? "LA_SER_SECURE" :
324 "???");
325 return name;
327 }
328 void
330 la_activity (uintptr_t *cookie, unsigned int flag)
331 {
332 printf("la_activity(): cookie = %p; flag = %s\n", cookie,
333 (flag == LA_ACT_CONSISTENT) ? "LA_ACT_CONSISTENT" :
334 (flag == LA_ACT_ADD) ? "LA_ACT_ADD" :
335 (flag == LA_ACT_DELETE) ? "LA_ACT_DELETE" :
336 "???");
337 }
338 unsigned int
340 la_objopen(struct link_map *map, Lmid_t lmid, uintptr_t *cookie)
341 {
342 printf("la_objopen(): loading \"%s\"; lmid = %s; cookie=%p\n",
343 map->l_name,
344 (lmid == LM_ID_BASE) ? "LM_ID_BASE" :
345 (lmid == LM_ID_NEWLM) ? "LM_ID_NEWLM" :
346 "???",
347 cookie);
348 return LA_FLG_BINDTO | LA_FLG_BINDFROM;
350 }
351 unsigned int
353 la_objclose (uintptr_t *cookie)
354 {
355 printf("la_objclose(): %p\n", cookie);
356 return 0;
358 }
359 void
361 la_preinit(uintptr_t *cookie)
362 {
363 printf("la_preinit(): %p\n", cookie);
364 }
365 uintptr_t
367 la_symbind32(Elf32_Sym *sym, unsigned int ndx, uintptr_t *refcook,
368 uintptr_t *defcook, unsigned int *flags, const char *symname)
369 {
370 printf("la_symbind32(): symname = %s; sym->st_value = %p\n",
371 symname, sym->st_value);
372 printf(" ndx = %u; flags = %#x", ndx, *flags);
373 printf("; refcook = %p; defcook = %p\n", refcook, defcook);
374 return sym->st_value;
376 }
377 uintptr_t
379 la_symbind64(Elf64_Sym *sym, unsigned int ndx, uintptr_t *refcook,
380 uintptr_t *defcook, unsigned int *flags, const char *symname)
381 {
382 printf("la_symbind64(): symname = %s; sym->st_value = %p\n",
383 symname, sym->st_value);
384 printf(" ndx = %u; flags = %#x", ndx, *flags);
385 printf("; refcook = %p; defcook = %p\n", refcook, defcook);
386 return sym->st_value;
388 }
389 Elf32_Addr
391 la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx,
392 uintptr_t *refcook, uintptr_t *defcook, La_i86_regs *regs,
393 unsigned int *flags, const char *symname, long *framesizep)
394 {
395 printf("la_i86_gnu_pltenter(): %s (%p)\n", symname, sym->st_value);
396 return sym->st_value;
398 }
399
401 ldd(1), dlopen(3), ld.so(8), ldconfig(8)
402
404 This page is part of release 5.13 of the Linux man-pages project. A
405 description of the project, information about reporting bugs, and the
406 latest version of this page, can be found at
407 https://www.kernel.org/doc/man-pages/.
408Linux 2020-11-01 RTLD-AUDIT(7)