Skip to main content

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:

APIAnnotated functionsPermission
SpecsAudioRecordSpecsAudioRecord_streamOpen, SpecsAudioRecord_startMICROPHONE_RAW
SpecsCameraSpecsCameraStream_add, SpecsCameraStream_captureOnce, SpecsCameraStream_setupCaptureCAMERA_RAW
SpecsCaptureSpecsCapture_prewarm, SpecsCapture_startCAMERA_RAW, MICROPHONE_RAW
SpecsLocationSpecsLocation_getCachedLocationGPS_RAW
SpecsPlayerSpecsPlayer_open, SpecsPlayer_openWithOptionsINTERNET
SpecsRecorderSpecsRecorder_streamStartCAMERA_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:

LibraryFunctionsPermission
libcurl (libcurl.so.4)curl_easy_perform, curl_easy_recv, curl_easy_send, curl_multi_perform, curl_multi_socket_action, curl_multi_socket_allINTERNET
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_transferINTERNET
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, socketINTERNET

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.