1 # Android changes for NDK developers
3 This document details important changes related to native code
4 loading in various Android releases.
6 Required tools: the NDK has an _arch_-linux-android-readelf binary
7 (e.g. arm-linux-androideabi-readelf or i686-linux-android-readelf)
8 for each architecture (under toolchains/), but you can use readelf for
9 any architecture, as we will be doing basic inspection only. On Linux
10 you need to have the “binutils” package installed for readelf,
11 and “pax-utils” for scanelf.
14 ## Changes to library search order
16 We have made various fixes to library search order when resolving symbols.
18 With API 22, load order switched from depth-first to breadth-first to
21 Before API 23, the default search order was to try the main executable,
22 LD_PRELOAD libraries, the library itself, and its DT_NEEDED libraries
23 in that order. For API 23 and later, for any given library, the dynamic
24 linker divides other libraries into the global group and the local
25 group. The global group is shared by all libraries and contains the main
26 executable, LD_PRELOAD libraries, and any library with the DF_1_GLOBAL
27 flag set (by passing “-z global” to ld(1)). The local group is
28 the breadth-first transitive closure of the library and its DT_NEEDED
29 libraries. The M dynamic linker searches the global group followed by
30 the local group. This allows ASAN, for example, to ensure that it can
34 ## RTLD_LOCAL (Available in API level >= 23)
36 The dlopen(3) RTLD_LOCAL flag used to be ignored but is implemented
37 correctly in API 23 and later. Note that RTLD_LOCAL is the default,
38 so even calls to dlopen(3) that didn’t explicitly use RTLD_LOCAL will
39 be affected (unless they explicitly used RTLD_GLOBAL). With RTLD_LOCAL,
40 symbols will not be made available to libraries loaded by later calls
41 to dlopen(3) (as opposed to being referenced by DT_NEEDED entries).
44 ## GNU hashes (Availible in API level >= 23)
46 The GNU hash style available with --hash-style=gnu allows faster
47 symbol lookup and is now supported by the dynamic linker in API 23 and
48 above. (Use --hash-style=both if you want to build code that uses this
49 feature >= Android M but still works on older releases.)
52 ## Correct soname/path handling (Available in API level >= 23)
54 The dynamic linker now understands the difference
55 between a library’s soname and its path (public bug
56 https://code.google.com/p/android/issues/detail?id=6670). API level 23
57 is the first release where search by soname is implemented. Earlier
58 releases would assume that the basename of the library was the soname,
59 and used that to search for already-loaded libraries. For example,
60 `dlopen("/this/directory/does/not/exist/libc.so", RTLD_NOW)` would
61 find `/system/lib/libc.so` because it’s already loaded. This also meant
62 that it was impossible to have two libraries `"dir1/libx.so"` and
63 `"dir2/libx.so"` --- the dynamic linker couldn’t tell the difference
64 and would always use whichever was loaded first, even if you explicitly
65 tried to load both. This also applied to DT_NEEDED entries.
67 Some apps have bad DT_NEEDED entries (usually absolute paths on the build
68 machine’s file system) that used to work because we ignored everything
69 but the basename. These apps will fail to load on API level 23 and above.
72 ## Symbol versioning (Available in API level >= 23)
74 Symbol versioning allows libraries to provide better backwards
75 compatibility. For example, if a library author knowingly changes
76 the behavior of a function, they can provide two versions in the same
77 library so that old code gets the old version and new code gets the new
78 version. This is supported in API level 23 and above.
81 ## Opening shared libraries directly from an APK
83 In API level 23 and above, it’s possible to open a .so file directly from
84 your APK. Just use `System.loadLibrary("foo")` exactly as normal but set
85 `android:extractNativeLibs="false"` in your `AndroidManifest.xml`. In
86 older releases, the .so files were extracted from the APK file
87 at install time. This meant that they took up space in your APK and
88 again in your installation directory (and this was counted against you
89 and reported to the user as space taken up by your app). Any .so file
90 that you want to load directly from your APK must be page aligned
91 (on a 4096-byte boundary) in the zip file and stored uncompressed.
92 Current versions of the zipalign tool take care of alignment.
94 Note that in API level 23 and above dlopen(3) will open a library from
95 any zip file, not just your APK. Just give dlopen(3) a path of the form
96 "my_zip_file.zip!/libs/libstuff.so". As with APKs, the library must be
97 page-aligned and stored uncompressed for this to work.
100 ## Private API (Enforced for API level >= 24)
102 Native libraries must use only public API, and must not link against
103 non-NDK platform libraries. Starting with API 24 this rule is enforced and
104 applications are no longer able to load non-NDK platform libraries. The
105 rule is enforced by the dynamic linker, so non-public libraries
106 are not accessible regardless of the way code tries to load them:
107 System.loadLibrary, DT_NEEDED entries, and direct calls to dlopen(3)
108 will all work exactly the same.
110 Users should have a consistent app experience across updates,
111 and developers shouldn't have to make emergency app updates to
112 handle platform changes. For that reason, we recommend against using
113 private C/C++ symbols. Private symbols aren't tested as part of the
114 Compatibility Test Suite (CTS) that all Android devices must pass. They
115 may not exist, or they may behave differently. This makes apps that use
116 them more likely to fail on specific devices, or on future releases ---
117 as many developers found when Android 6.0 Marshmallow switched from
118 OpenSSL to BoringSSL.
120 In order to reduce the user impact of this transition, we've identified
121 a set of libraries that see significant use from Google Play's
122 most-installed apps, and that are feasible for us to support in the
123 short term (including libandroid_runtime.so, libcutils.so, libcrypto.so,
124 and libssl.so). In order to give you more time to transition, we will
125 temporarily support these libraries; so if you see a warning that means
126 your code will not work in a future release -- please fix it now!
129 $ readelf --dynamic libBroken.so | grep NEEDED
130 0x00000001 (NEEDED) Shared library: [libnativehelper.so]
131 0x00000001 (NEEDED) Shared library: [libutils.so]
132 0x00000001 (NEEDED) Shared library: [libstagefright_foundation.so]
133 0x00000001 (NEEDED) Shared library: [libmedia_jni.so]
134 0x00000001 (NEEDED) Shared library: [liblog.so]
135 0x00000001 (NEEDED) Shared library: [libdl.so]
136 0x00000001 (NEEDED) Shared library: [libz.so]
137 0x00000001 (NEEDED) Shared library: [libstdc++.so]
138 0x00000001 (NEEDED) Shared library: [libm.so]
139 0x00000001 (NEEDED) Shared library: [libc.so]
142 *Potential problems*: starting from API 24 the dynamic linker will not
143 load private libraries, preventing the application from loading.
145 *Resolution*: rewrite your native code to rely only on public API. As a
146 short term workaround, platform libraries without complex dependencies
147 (libcutils.so) can be copied to the project. As a long term solution
148 the relevant code must be copied to the project tree. SSL/Media/JNI
149 internal/binder APIs should not be accessed from the native code. When
150 necessary, native code should call appropriate public Java API methods.
152 A complete list of public libraries is available within the NDK, under
153 platforms/android-API/usr/lib.
155 Note: SSL/crypto is a special case, applications must NOT use platform
156 libcrypto and libssl libraries directly, even on older platforms. All
157 applications should use GMS Security Provider to ensure they are protected
158 from known vulnerabilities.
161 ## Missing Section Headers (Enforced for API level >= 24)
163 Each ELF file has additional information contained in the section
164 headers. These headers must be present now, because the dynamic linker
165 uses them for sanity checking. Some developers strip them in an
166 attempt to obfuscate the binary and prevent reverse engineering. (This
167 doesn't really help because it is possible to reconstruct the stripped
168 information using widely-available tools.)
171 $ readelf --header libBroken.so | grep 'section headers'
172 Start of section headers: 0 (bytes into file)
173 Size of section headers: 0 (bytes)
174 Number of section headers: 0
177 *Resolution*: remove the extra steps from your build that strip section
180 ## Text Relocations (Enforced for API level >= 23)
182 Starting with API 23, shared objects must not contain text
183 relocations. That is, the code must be loaded as is and must not be
184 modified. Such an approach reduces load time and improves security.
186 The usual reason for text relocations is non-position independent
187 hand-written assembler. This is not common. Use the scanelf tool as
188 described in our documentation for further diagnostics:
191 $ scanelf -qT libTextRel.so
192 libTextRel.so: (memory/data?) [0x15E0E2] in (optimized out: previous simd_broken_op1) [0x15E0E0]
193 libTextRel.so: (memory/data?) [0x15E3B2] in (optimized out: previous simd_broken_op2) [0x15E3B0]
197 If you have no scanelf tool available, it is possible to do a basic
198 check with readelf instead, look for either a TEXTREL entry or the
199 TEXTREL flag. Either alone is sufficient. (The value corresponding to the
200 TEXTREL entry is irrelevant and typically 0 --- simply the presence of
201 the TEXTREL entry declares that the .so contains text relocations). This
202 example has both indicators present:
205 $ readelf --dynamic libTextRel.so | grep TEXTREL
206 0x00000016 (TEXTREL) 0x0
207 0x0000001e (FLAGS) SYMBOLIC TEXTREL BIND_NOW
210 Note: it is technically possible to have a shared object with the TEXTREL
211 entry/flag but without any actual text relocations. This doesn't happen
212 with the NDK, but if you're generating ELF files yourself make sure
213 you're not generating ELF files that claim to have text relocations,
214 because the Android dynamic linker trusts the entry/flag.
216 *Potential problems*: Relocations enforce code pages being writable, and
217 wastefully increase the number of dirty pages in memory. The dynamic
218 linker has issued warnings about text relocations since Android K
219 (API 19), but on API 23 and above it refuses to load code with text
222 *Resolution*: rewrite assembler to be position independent to ensure
223 no text relocations are necessary. The
224 [Gentoo Textrels guide](https://wiki.gentoo.org/wiki/Hardened/Textrels_Guide)
225 has instructions for fixing text relocations, and more detailed
226 [scanelf documentation](https://wiki.gentoo.org/wiki/Hardened/PaX_Utilities).
229 ## Invalid DT_NEEDED Entries (Enforced for API level >= 23)
231 While library dependencies (DT_NEEDED entries in the ELF headers) can be
232 absolute paths, that doesn't make sense on Android because you have
233 no control over where your library will be installed by the system. A
234 DT_NEEDED entry should be the same as the needed library's SONAME,
235 leaving the business of finding the library at runtime to the dynamic
238 Before API 23, Android's dynamic linker ignored the full path, and
239 used only the basename (the part after the last ‘/') when looking
240 up the required libraries. Since API 23 the runtime linker will honor
241 the DT_NEEDED exactly and so it won't be able to load the library if
242 it is not present in that exact location on the device.
244 Even worse, some build systems have bugs that cause them to insert
245 DT_NEEDED entries that point to a file on the build host, something that
246 cannot be found on the device.
249 $ readelf --dynamic libSample.so | grep NEEDED
250 0x00000001 (NEEDED) Shared library: [libm.so]
251 0x00000001 (NEEDED) Shared library: [libc.so]
252 0x00000001 (NEEDED) Shared library: [libdl.so]
253 0x00000001 (NEEDED) Shared library:
254 [C:\Users\build\Android\ci\jni\libBroken.so]
257 *Potential problems*: before API 23 the DT_NEEDED entry's basename was
258 used, but starting from API 23 the Android runtime will try to load the
259 library using the path specified, and that path won't exist on the
260 device. There are broken third-party toolchains/build systems that use
261 a path on a build host instead of the SONAME.
263 *Resolution*: make sure all required libraries are referenced by SONAME
264 only. It is better to let the runtime linker to find and load those
265 libraries as the location may change from device to device.
268 ## Missing SONAME (Enforced for API level >= 23)
270 Each ELF shared object (“native library”) must have a SONAME (Shared
271 Object Name) attribute. The NDK toolchain adds this attribute by default,
272 so its absence indicates either a misconfigured alternative toolchain
273 or a misconfiguration in your build system. A missing SONAME may lead
274 to runtime issues such as the wrong library being loaded: the filename
275 is used instead when this attribute is missing.
278 $ readelf --dynamic libWithSoName.so | grep SONAME
279 0x0000000e (SONAME) Library soname: [libWithSoName.so]
282 *Potential problems*: namespace conflicts may lead to the wrong library
283 being loaded at runtime, which leads to crashes when required symbols
284 are not found, or you try to use an ABI-incompatible library that isn't
285 the library you were expecting.
287 *Resolution*: the current NDK generates the correct SONAME by
288 default. Ensure you're using the current NDK and that you haven't
289 configured your build system to generate incorrect SONAME entries (using
290 the -soname linker option).
293 ## Writable and Executable Segments (Enforced for API level >= 26)
295 Each segment in an ELF file has associated flags that tell the
296 dynamic linker what permissions to give the corresponding page in
297 memory. For security, data shouldn't be executable and code shouldn't be
298 writable. This means that the W (for Writable) and E (for Executable)
299 flags should be mutually exclusive. This wasn't historically enforced,
303 $ readelf --program-headers -W libBadFlags.so | grep WE
304 LOAD 0x000000 0x00000000 0x00000000 0x4c01d 0x4c01d RWE 0x1000
307 *Resolution*: we're aware of one middleware product that introduces these
308 into your app. The middleware vendor is aware of the problem and has a fix
311 ## Invalid ELF header/section headers (Enforced for API level >= 26)
313 In API level 26 and above the dynamic linker checks more values in
314 the ELF header and section headers and fails if they are invalid.
318 dlopen failed: "/data/data/com.example.bad/lib.so" has unsupported e_shentsize: 0x0 (expected 0x28)
321 *Resolution*: don't use tools that produce invalid/malformed
322 ELF files. Note that using them puts application under high risk of
323 being incompatible with future versions of Android.