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