Android changes for NDK developers

Related to other improvements to the Android platform, the dynamic linker in
Android M and N has stricter requirements for writing clean, cross-platform
compatible native code in order to load. It is necessary that an application’s
native code follows the rules and recommendations in order to ensure a smooth
transition to recent Android releases.


Below we outline in detail each individual change related to native code
loading, the consequences and steps you can take to avoid issues.


Required tools: there is an <arch>-linux-android-readelf binary (e.g.
arm-linux-androideabi-readelf or i686-linux-android-readelf) for each
architecture in the NDK (under toolchains/), but you can use readelf for any
architecture, as we will be doing basic inspection only. On Linux you need to
have the “binutils” package installed for readelf, and “pax-utils” for scanelf.

Private API (Enforced since API 24)

Native libraries must use only public API,
and must not link against non-NDK platform libraries. Starting with API 24 this
rule is enforced and applications are no longer able to load non-NDK platform
libraries. The rule is enforced by the dynamic linker, so non-public libraries
are not accessible regardless of the way code tries to load them:
System.loadLibrary(...), DT_NEEDED entries, and direct calls to dlopen(...) will
fail in exactly the same way.


Users should have a consistent app experience across updates, and developers
shouldn’t have to make emergency app updates to handle platform changes. For
that reason, we recommend against using private C/C++ symbols. Private symbols
aren’t tested as part of the Compatibility Test Suite (CTS) that all Android
devices must pass. They may not exist, or they may behave differently. This
makes apps that use them more likely to fail on specific devices, or on future
releases --- as many developers found when Android 6.0 Marshmallow switched from
OpenSSL to BoringSSL.


In order to reduce the user impact of this transition, we’ve identified a set of
libraries that see significant use from Google Play’s most-installed apps, and
that are feasible for us to support in the short term (including
libandroid_runtime.so, libcutils.so, libcrypto.so, and libssl.so). In order to
give you more time to transition, we will temporarily support these libraries;
so if you see a warning that means your code will not work in a future release
-- please fix it now!

$ readelf --dynamic libBroken.so | grep NEEDED
 0x00000001 (NEEDED)                     Shared library: [libnativehelper.so]
 0x00000001 (NEEDED)                     Shared library: [libutils.so]
 0x00000001 (NEEDED)                     Shared library: [libstagefright_foundation.so]
 0x00000001 (NEEDED)                     Shared library: [libmedia_jni.so]
 0x00000001 (NEEDED)                     Shared library: [liblog.so]
 0x00000001 (NEEDED)                     Shared library: [libdl.so]
 0x00000001 (NEEDED)                     Shared library: [libz.so]
 0x00000001 (NEEDED)                     Shared library: [libstdc++.so]
 0x00000001 (NEEDED)                     Shared library: [libm.so]
 0x00000001 (NEEDED)                     Shared library: [libc.so]

Potential problems: starting from API 24 the dynamic linker will not load
private libraries, preventing the application from loading.


Resolution: rewrite your native code to rely only on public API. As a short term
workaround, platform libraries without complex dependencies (libcutils.so) can
be copied to the project. As a long term solution the relevant code must be
copied to the project tree. SSL/Media/JNI internal/binder APIs should not be
accessed from the native code. When necessary, native code should call
appropriate public Java API methods.


A complete list of public libraries is available within the NDK, under
platforms/android-API/usr/lib.


Note: SSL/crypto is a special case, applications must NOT use platform libcrypto
and libssl libraries directly, even on older platforms. All applications should
use GMSSecurity Provider to ensure they are protected from known vulnerabilities.

Missing Section Headers (Enforced since API 24)

Each ELF file has additional information contained in the section headers. These
headers must be present now, because the dynamic linker uses them for sanity
checking. Some developers try to strip them in an attempt to obfuscate the
binary and prevent reverse engineering. (This doesn’t really help because it is
possible to reconstruct the stripped information using widely-available tools.)

$ readelf --header libBroken.so | grep 'section headers'
  Start of section headers:          0 (bytes into file)
  Size of section headers:           0 (bytes)
  Number of section headers:         0
$

Resolution: remove the extra steps from your build that strip section headers.

Text Relocations (Enforced since API 23)

Starting with API 23, shared objects must not contain text relocations. That is,
the code must be loaded as is and must not be modified. Such an approach reduces
load time and improves security.


The usual reason for text relocations is non-position independent hand-written
assembler. This is not common. Use the scanelftool as described in ourdocumentation for further diagnostics:

$ scanelf -qT libTextRel.so
  libTextRel.so: (memory/data?) [0x15E0E2] in (optimized out: previous simd_broken_op1) [0x15E0E0]
  libTextRel.so: (memory/data?) [0x15E3B2] in (optimized out: previous simd_broken_op2) [0x15E3B0]
[skipped the rest]

If you have no scanelf tool available, it is possible to do a basic check with
readelf instead, look for either a TEXTREL entry or the TEXTREL flag. Either
alone is sufficient. (The value corresponding to the TEXTREL entry is irrelevant
and typically 0 --- simply the presence of the TEXTREL entry declares that the
.so contains text relocations). This example has both indicators present:

$ readelf --dynamic libTextRel.so | grep TEXTREL
 0x00000016 (TEXTREL)                    0x0
 0x0000001e (FLAGS)                      SYMBOLIC TEXTREL BIND_NOW
$

Note: it is technically possible to have a shared object with the TEXTREL
entry/flag but without any actual text relocations. This doesn’t happen with the
NDK, but if you’re generating ELF files yourself make sure you’re not generating
ELF files that claim to have text relocations, because the Android dynamic
linker trusts the entry/flag.


Potential problems: Relocations enforce code pages being writable, and
wastefully increase the number of dirty pages in memory. The dynamic linker has
issued warnings about text relocations since Android K (API 19), but on API 23
and above it refuses to load code with text relocations.


Resolution: rewrite assembler to be position independent to ensure no text
relocations are necessary. Check the Gentoodocumentation for cookbook recipes.

Invalid DT_NEEDED Entries (Enforced since API 23)

While library dependencies (DT_NEEDED entries in the ELF headers) can be
absolute paths, that doesn’t make sense on Android because you have no control
over where your library will be installed by the system. A DT_NEEDED entry
should be the same as the needed library’s SONAME, leaving the business of
finding the library at runtime to the dynamic linker.


Before API 23, Android’s dynamic linker ignored the full path, and used only the
basename (the part after the last ‘/’) when looking up the required libraries.
Since API 23 the runtime linker will honor the DT_NEEDED exactly and so it won’t
be able to load the library if it is not present in that exact location on the
device.


Even worse, some build systems have bugs that cause them to insert DT_NEEDED
entries that point to a file on the build host, something that
cannot be found on the device.

$ readelf --dynamic libSample.so | grep NEEDED
 0x00000001 (NEEDED)                     Shared library: [libm.so]
 0x00000001 (NEEDED)                     Shared library: [libc.so]
 0x00000001 (NEEDED)                     Shared library: [libdl.so]
 0x00000001 (NEEDED)                     Shared library:
[C:\Users\build\Android\ci\jni\libBroken.so]
$

Potential problems: before API 23 the DT_NEEDED entry’s basename was used, but
starting from API 23 the Android runtime will try to load the library using the path
specified, and that path won’t exist on the device. There are broken third-party
toolchains/build systems that use a path on a build host instead of the SONAME.


Resolution: make sure all required libraries are referenced by SONAME only. It
is better to let the runtime linker to find and load those libraries as the
location may change from device to device.

Missing SONAME (Used since API 23)

Each ELF shared object (“native library”) must have a SONAME (Shared Object
Name) attribute. The NDK toolchain adds this attribute by default, so its
absence indicates either a misconfigured alternative toolchain or a
misconfiguration in your build system. A missing SONAME may lead to runtime
issues such as the wrong library being loaded: the filename is used instead when
this attribute is missing.

$ readelf --dynamic libWithSoName.so | grep SONAME
 0x0000000e (SONAME)                     Library soname: [libWithSoName.so]
$

Potential problems: namespace conflicts may lead to the wrong library being
loaded at runtime, which leads to crashes when required symbols are not found,
or you try to use an ABI-incompatible library that isn’t the library you were
expecting.


Resolution: the current NDK generates the correct SONAME by default. Ensure
you’re using the current NDK and that you haven’t configured your build system
to generate incorrect SONAME entries (using the -soname linker
option).


Please remember, clean, cross-platform code built with a current NDK should have
no issues on Android N. We encourage you to revise your native code build so
that it produces correct binaries.