Permission Annotations and Manifest Embedding
How the SPECS NDK maps APIs to OS permissions and embeds the required .snap.permissions manifest into every application .so.
SPECS APIs that touch sensitive device capabilities are annotated with the OS permission they require, network functions in the bundled open-source libraries are mapped to INTERNET, and every application .so must carry a .snap.permissions ELF section declaring the permissions it uses. SPECS reads this manifest at import time and fails closed: a SPECS-importing .so with no .snap.permissions section is rejected.
API permission requirements
The public headers annotate the relevant functions with SPECS_REQUIRES_PERMISSION(<PERMISSION_ID>) (defined in SpecsPermissions.h, shipped beside the other SPECS headers). The annotation is a codegen no-op (__attribute__((annotate(...))) under Clang, empty under other compilers), so it changes nothing about the ABI. Current annotations:
| API | Annotated functions | Permission |
|---|---|---|
SpecsAudioRecord | SpecsAudioRecord_streamOpen, SpecsAudioRecord_start | MICROPHONE_RAW |
SpecsCamera | SpecsCameraStream_add, SpecsCameraStream_captureOnce, SpecsCameraStream_setupCapture | CAMERA_RAW |
SpecsCapture | SpecsCapture_prewarm, SpecsCapture_start | CAMERA_RAW, MICROPHONE_RAW |
SpecsLocation | SpecsLocation_getCachedLocation | GPS_RAW |
SpecsPlayer | SpecsPlayer_open, SpecsPlayer_openWithOptions | INTERNET |
SpecsRecorder | SpecsRecorder_streamStart | CAMERA_RAW |
Permission ids come verbatim from the SPECS permissions list (for example CAMERA_RAW); the NDK build validates every annotated name against that list.
Network functions in open-source libraries
Network access through the supported open-source libraries also requires INTERNET. Their headers are not annotated; instead the NDK's permission map (sysroots/armv8a-snap-linux/usr/share/specsndk/specs-permissions.json) lists the network-facing functions of each library, and specs-perm-embed adds INTERNET to the manifest of any .so that imports one of them:
| Library | Functions | Permission |
|---|---|---|
libcurl (libcurl.so.4) | curl_easy_perform, curl_easy_recv, curl_easy_send, curl_multi_perform, curl_multi_socket_action, curl_multi_socket_all | INTERNET |
OpenSSL (libcrypto) (libcrypto.so.3) | BIO_connect, BIO_lookup, BIO_lookup_ex, BIO_new_connect, BIO_s_connect, BIO_s_datagram, BIO_socket, OSSL_HTTP_get, OSSL_HTTP_open, OSSL_HTTP_transfer | INTERNET |
libc (sockets, DNS) (libc.so.6) | __res_nquery, __res_nquerydomain, __res_nsearch, __res_nsend, __res_query, __res_querydomain, __res_search, __res_send, bind, connect, getaddrinfo, gethostbyaddr, gethostbyaddr_r, gethostbyname, gethostbyname2, gethostbyname2_r, gethostbyname_r, getnameinfo, res_nquery, res_nquerydomain, res_nsearch, res_nsend, res_query, res_querydomain, res_search, res_send, socket | INTERNET |
This applies to every native library .so, including one that calls no SPECS C APIs: a library that links libcurl and calls curl_easy_perform(), or opens a socket, gets INTERNET in its manifest automatically. Functions that do not touch the network (for example curl_easy_init(), curl_easy_setopt(), TLS/crypto primitives) add no permission.
Detection works on the library's imported dynamic symbols (the same llvm-nm -uD scan used for SPECS APIs). Functions looked up at run time with dlsym() are not seen, so they contribute no permission.
Automatic embedding in CMake builds
SpecsNDK-Toolchain-Clang.cmake wires usr/share/specsndk/SpecsPostLink.cmake into your project via CMAKE_PROJECT_TOP_LEVEL_INCLUDES. After every SHARED/MODULE library links, including targets created in add_subdirectory()/FetchContent trees, it runs specs-perm-embed <lib.so> as a POST_BUILD step to write the .snap.permissions section. No changes to your CMakeLists.txt are needed.
CMAKE_PROJECT_TOP_LEVEL_INCLUDES is silently ignored by older CMake versions: the hook vanishes with no diagnostic, and the failure only surfaces later as the OS-side fail-closed import error. Use CMake ≥ 3.24, or run the embedder manually as described in Manual embedding for Makefile and non-CMake builds.
Manual embedding for non-CMake build systems
Run the embedder on each output library after linking:
<install>/sysroots/<HOST>/usr/bin/specs-perm-embed build/libmylens.so
<HOST> is x86_64-specsndk-darwin21 on macOS or x86_64-w64-mingw32 on Windows (specs-perm-embed.exe).
Inspect the permissions manifest
The section is NUL-separated printable text: a SNAP_PERMS_V1 version marker followed by sorted, de-duplicated permission ids. Read it with standard ELF tooling or the bundled reference reader:
# Stock binutils
readelf -p .snap.permissions build/libmylens.so
# Bundled reference reader (documents the format; exit 0 = valid,
# 3 = section absent, 4 = malformed)
python3 <install>/sysroots/<HOST>/usr/share/specsndk/specs-perm-read.py build/libmylens.so
A present section with the marker and zero permission tokens is valid: it means the library was processed and genuinely needs no permissions.