]>
Commit | Line | Data |
---|---|---|
d56bebb0 MK |
1 | .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
d56bebb0 MK |
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. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
d56bebb0 MK |
25 | .\" |
26 | .\" 2009-01-12, mtk, Created | |
27 | .\" | |
6f3c74a8 | 28 | .TH RTLD-AUDIT 7 2015-12-05 "Linux" "Linux Programmer's Manual" |
d56bebb0 MK |
29 | .SH NAME |
30 | rtld-audit \- auditing API for the dynamic linker | |
31 | .SH SYNOPSIS | |
86b91fdf | 32 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
d56bebb0 MK |
33 | |
34 | .B #include <link.h> | |
35 | .SH DESCRIPTION | |
36 | The GNU dynamic linker (run-time linker) | |
37 | provides an auditing API that allows an application | |
38 | to be notified when various dynamic linking events occur. | |
39 | This API is very similar to the auditing interface provided by the | |
40 | Solaris run-time linker. | |
41 | The necessary constants and prototypes are defined by including | |
42 | .IR <link.h> . | |
43 | ||
44 | To use this interface, the programmer creates a shared library | |
45 | that implements a standard set of function names. | |
46 | Not all of the functions need to be implemented: in most cases, | |
47 | if the programmer is not interested in a particular class of auditing event, | |
36dc0d7c | 48 | then no implementation needs to be provided for the corresponding |
d56bebb0 MK |
49 | auditing function. |
50 | ||
51 | To employ the auditing interface, the environment variable | |
52 | .BR LD_AUDIT | |
53 | must be defined to contain a colon-separated list of shared libraries, | |
54 | each of which can implement (parts of) the auditing API. | |
d56bebb0 MK |
55 | When an auditable event occurs, |
56 | the corresponding function is invoked in each library, | |
57 | in the order that the libraries are listed. | |
58 | .SS la_version() | |
59 | \& | |
60 | .nf | |
61 | .BI "unsigned int la_version(unsigned int " version ); | |
62 | .fi | |
63 | .PP | |
64 | This is the only function that | |
65 | .I must | |
66 | be defined by an auditing library: | |
67 | it performs the initial handshake between the dynamic linker and | |
68 | the auditing library. | |
69 | When invoking this function, the dynamic linker passes, in | |
70 | .IR version , | |
71 | the highest version of the auditing interface that the linker supports. | |
72 | If necessary, the auditing library can check that this version | |
73 | is sufficient for its requirements. | |
74 | ||
75 | As its function result, | |
76 | this function should return the version of the auditing interface | |
77 | that this auditing library expects to use (returning | |
78 | .I version | |
79 | is acceptable). | |
80 | If the returned value is 0, | |
81 | or a version that is greater than that supported by the dynamic linker, | |
82 | then the audit library is ignored. | |
83 | .SS la_objsearch() | |
84 | \& | |
85 | .nf | |
86 | .BI "char *la_objsearch(const char *" name ", uintptr_t *" cookie , | |
87 | .BI " unsigned int " flag ); | |
88 | .fi | |
89 | .PP | |
90 | The dynamic linker invokes this function to inform the auditing library | |
91 | that it is about to search for a shared object. | |
92 | The | |
93 | .I name | |
94 | argument is the filename or pathname that is to be searched for. | |
95 | .I cookie | |
96 | identifies the shared object that initiated the search. | |
97 | .I flag | |
98 | is set to one of the following values: | |
99 | .TP 17 | |
100 | .B LA_SER_ORIG | |
101 | This is the original name that is being searched for. | |
102 | Typically, this name comes from an ELF | |
103 | .B DT_NEEDED | |
104 | entry, or is the | |
105 | .I filename | |
106 | argument given to | |
107 | .BR dlopen (3). | |
108 | .TP | |
109 | .B LA_SER_LIBPATH | |
110 | .I name | |
111 | was created using a directory specified in | |
112 | .BR LD_LIBRARY_PATH . | |
113 | .TP | |
114 | .B LA_SER_RUNPATH | |
115 | .I name | |
116 | was created using a directory specified in an ELF | |
117 | .B DT_RPATH | |
118 | or | |
119 | .B DT_RUNPATH | |
120 | list. | |
121 | .TP | |
122 | .B LA_SER_CONFIG | |
123 | .I name | |
124 | was found via the | |
125 | .BR ldconfig (8) | |
126 | cache | |
127 | .RI ( /etc/ld.so.cache ). | |
128 | .TP | |
129 | .B LA_SER_DEFAULT | |
130 | .I name | |
131 | was found via a search of one of the default directories. | |
132 | .TP | |
133 | .B LA_SER_SECURE | |
134 | .I name | |
135 | is specific to a secure object (unused on Linux). | |
136 | .PP | |
137 | As its function result, | |
138 | .BR la_objsearch () | |
139 | returns the pathname that the dynamic linker should use | |
140 | for further processing. | |
141 | If NULL is returned, then this pathname is ignored for further processing. | |
142 | If this audit library simply intends to monitor search paths, then | |
143 | .I name | |
144 | should be returned. | |
145 | .SS la_activity() | |
146 | \& | |
147 | .nf | |
148 | .BI "void la_activity( uintptr_t *" cookie ", unsigned int "flag ); | |
149 | .fi | |
150 | .PP | |
151 | The dynamic linker calls this function to inform the auditing library | |
152 | that link-map activity is occurring. | |
153 | .I cookie | |
154 | identifies the object at the head of the link map. | |
155 | When the dynamic linker invokes this function, | |
156 | .I flag | |
157 | is set to one of the following values: | |
158 | .TP 19 | |
159 | .B LA_ACT_ADD | |
160 | New objects are being added to the link map. | |
161 | .TP | |
162 | .B LA_ACT_DELETE | |
163 | Objects are being removed from the link map. | |
164 | .TP | |
165 | .B LA_ACT_CONSISTENT | |
166 | Link-map activity has been completed: the map is once again consistent. | |
167 | .SS la_objopen() | |
168 | \& | |
169 | .nf | |
170 | .BI "unsigned int la_objopen(struct link_map *" map ", Lmid_t " lmid , | |
171 | .BI " uintptr_t *" cookie ); | |
172 | .fi | |
173 | .PP | |
174 | The dynamic linker calls this function when a new shared object is loaded. | |
175 | The | |
176 | .I map | |
177 | argument is a pointer to a link-map structure that describes the object. | |
178 | The | |
179 | .I lmid | |
180 | field has one of the following values | |
181 | .TP 17 | |
182 | .B LM_ID_BASE | |
183 | Link map is part of the initial namespace. | |
184 | .TP | |
185 | .B LM_ID_NEWLM | |
186 | Link map is part of a new namespace requested via | |
187 | .BR dlmopen (3). | |
188 | .PP | |
189 | .I cookie | |
190 | is a pointer to an identifier for this object. | |
191 | The identifier is provided to later calls to functions | |
192 | in the auditing library in order to identify this object. | |
193 | This identifier is initialized to point to object's link map, | |
194 | but the audit library can change the identifier to some other value | |
195 | that it may prefer to use to identify the object. | |
196 | .PP | |
197 | As its return value, | |
198 | .BR la_objopen () | |
199 | returns a bit mask created by ORing zero or more of the | |
200 | following constants, | |
201 | which allow the auditing library to select the objects to be monitored by | |
202 | .BR la_symbind* (): | |
203 | .TP 17 | |
204 | .B LA_FLG_BINDTO | |
205 | Audit symbol bindings to this object. | |
206 | .TP | |
207 | .B LA_FLG_BINDFROM | |
208 | Audit symbol bindings from this object. | |
209 | .PP | |
210 | A return value of 0 from | |
211 | .BR la_objopen () | |
212 | indicates that no symbol bindings should be audited for this object. | |
213 | .SS la_objclose() | |
214 | \& | |
215 | .nf | |
a6e08809 | 216 | .BI "unsigned int la_objclose(uintptr_t *" cookie ); |
d56bebb0 MK |
217 | .fi |
218 | .PP | |
219 | The dynamic linker invokes this function after any finalization | |
220 | code for the object has been executed, | |
221 | before the object is unloaded. | |
222 | The | |
223 | .I cookie | |
224 | argument is the identifier obtained from a previous invocation of | |
225 | .BR la_objopen (). | |
226 | ||
227 | In the current implementation, the value returned by | |
228 | .BR la_objclose () | |
229 | is ignored. | |
230 | .SS la_preinit() | |
231 | \& | |
232 | .nf | |
233 | .BI "void la_preinit(uintptr_t *" cookie ); | |
234 | .fi | |
235 | .PP | |
236 | The dynamic linker invokes this function after all shared objects | |
237 | have been loaded, before control is passed to the application | |
238 | (i.e., before calling | |
239 | .IR main ()). | |
240 | Note that | |
241 | .IR main () | |
242 | may still later dynamically load objects using | |
243 | .BR dlopen (3). | |
244 | .SS la_symbind*() | |
245 | \& | |
246 | .nf | |
247 | .BI "uintptr_t la_symbind32(Elf32_Sym *" sym ", unsigned int " ndx , | |
248 | .BI " uintptr_t *" refcook ", uintptr_t *" defcook , | |
249 | .BI " unsigned int *" flags ", const char *" symname ); | |
250 | .BI "uintptr_t la_symbind64(Elf64_Sym *" sym ", unsigned int " ndx , | |
251 | .BI " uintptr_t *" refcook ", uintptr_t *" defcook , | |
252 | .BI " unsigned int *" flags ", const char *" symname ); | |
36dc0d7c | 253 | .fi |
d56bebb0 MK |
254 | .PP |
255 | The dynamic linker invokes one of these functions | |
256 | when a symbol binding occurs between two shared objects | |
257 | that have been marked for auditing notification by | |
258 | .BR la_objopen (). | |
259 | The | |
260 | .BR la_symbind32 () | |
261 | function is employed on 32-bit platforms; | |
262 | the | |
263 | .BR la_symbind64 () | |
264 | function is employed on 64-bit platforms. | |
265 | ||
266 | The | |
267 | .I sym | |
268 | argument is a pointer to a structure | |
269 | that provides information about the symbol being bound. | |
270 | The structure definition is shown in | |
271 | .IR <elf.h> . | |
272 | Among the fields of this structure, | |
273 | .I st_value | |
274 | indicates the address to which the symbol is bound. | |
275 | ||
276 | The | |
277 | .I ndx | |
278 | argument gives the index of the symbol in the symbol table | |
279 | of the bound shared object. | |
280 | ||
281 | The | |
282 | .I refcook | |
283 | argument identifies the shared object that is making the symbol reference; | |
284 | this is the same identifier that is provided to the | |
285 | .BR la_objopen () | |
286 | function that returned | |
287 | .BR LA_FLG_BINDFROM . | |
288 | The | |
289 | .I defcook | |
290 | argument identifies the shared object that defines the referenced symbol; | |
291 | this is the same identifier that is provided to the | |
292 | .BR la_objopen () | |
293 | function that returned | |
294 | .BR LA_FLG_BINDTO . | |
295 | ||
296 | The | |
297 | .I symname | |
298 | argument points a string containing the name of the symbol. | |
299 | ||
300 | The | |
301 | .I flags | |
302 | argument is a bit mask that both provides information about the symbol | |
303 | and can be used to modify further auditing of this | |
304 | PLT (Procedure Linkage Table) entry. | |
305 | The dynamic linker may supply the following bit values in this argument: | |
306 | .\" LA_SYMB_STRUCTCALL appears to be unused | |
307 | .TP 22 | |
308 | .B LA_SYMB_DLSYM | |
309 | The binding resulted from a call to | |
310 | .BR dlsym (3). | |
311 | .TP | |
312 | .B LA_SYMB_ALTVALUE | |
313 | A previous | |
314 | .BR la_symbind* () | |
315 | call returned an alternate value for this symbol. | |
316 | .PP | |
317 | By default, if the auditing library implements | |
318 | .BR la_pltenter () | |
319 | and | |
320 | .BR la_pltexit () | |
321 | functions (see below), then these functions are invoked, after | |
322 | .BR la_symbind (), | |
323 | for PLT entries, each time the symbol is referenced. | |
324 | .\" pltenter/pltexit are called for non-dynamically loaded libraries, | |
325 | .\" but don't seem to be called for dynamically loaded libs? | |
326 | .\" Is this the same on Solaris? | |
327 | The following flags can be ORed into | |
328 | .IR *flags | |
329 | to change this default behavior: | |
330 | .TP 22 | |
331 | .B LA_SYMB_NOPLTENTER | |
332 | Don't call | |
333 | .BR la_pltenter () | |
334 | for this symbol. | |
335 | .TP 22 | |
336 | .B LA_SYMB_NOPLTEXIT | |
337 | Don't call | |
338 | .BR la_pltexit () | |
339 | for this symbol. | |
340 | .PP | |
341 | The return value of | |
342 | .BR la_symbind32 () | |
343 | and | |
344 | .BR la_symbind64 () | |
345 | is the address to which control should be passed after the function returns. | |
346 | If the auditing library is simply monitoring symbol bindings, | |
347 | then it should return | |
d68a52c4 | 348 | .IR sym\->st_value . |
d56bebb0 MK |
349 | A different value may be returned if the library wishes to direct control |
350 | to an alternate location. | |
351 | .SS la_pltenter() | |
352 | The precise name and argument types for this function | |
353 | depend on the hardware platform. | |
354 | (The appropriate definition is supplied by | |
355 | .IR <link.h> .) | |
356 | Here is the definition for x86-32: | |
357 | .nf | |
358 | ||
359 | .BI "Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *" sym ", unsigned int " ndx , | |
360 | .BI " uintptr_t *" refcook ", uintptr_t *" defcook , | |
361 | .BI " La_i86_regs *" regs ", unsigned int *" flags , | |
362 | .BI " const char *" symname ", long int *" framesizep ); | |
363 | .fi | |
364 | ||
365 | This function is invoked just before a PLT entry is called, | |
366 | between two shared objects that have been marked for binding notification. | |
367 | ||
368 | The | |
369 | .IR sym , | |
370 | .IR ndx , | |
371 | .IR refcook , | |
372 | .IR defcook , | |
373 | and | |
374 | .IR symname | |
375 | are as for | |
376 | .BR la_symbind* (). | |
377 | ||
378 | The | |
379 | .I regs | |
380 | argument points to a structure (defined in | |
381 | .IR <link.h> ) | |
382 | containing the values of registers to be used for | |
383 | the call to this PLT entry. | |
384 | ||
385 | The | |
386 | .I flags | |
387 | argument points to a bit mask that conveys information about, | |