Menambahkan properti sistem

Halaman ini menyediakan metode kanonis untuk menambahkan atau menentukan properti sistem di Android, dengan panduan untuk memfaktorkan ulang properti sistem yang ada. Pastikan Anda menggunakan pedoman saat melakukan refaktorisasi, kecuali jika Anda memiliki masalah kompatibilitas yang berat yang mengharuskan Anda melakukannya.

Langkah 1: Tentukan properti sistem

Saat menambahkan properti sistem, tentukan nama untuk properti, dan kaitkan dengan konteks properti SELinux. Jika tidak ada konteks yang sesuai, buat konteks baru. Nama digunakan saat mengakses properti; konteks properti digunakan untuk mengontrol aksesibilitas dalam hal SELinux. Nama dapat berupa string apa pun, tetapi AOSP merekomendasikan agar Anda mengikuti format terstruktur agar jelas.

Nama properti

Gunakan format ini dengan casing snake_case:

[{prefix}.]{group}[.{subgroup}]*.{name}[.{type}]

Gunakan "" (dihilangkan), ro (untuk properti yang hanya ditetapkan sekali), atau persist (untuk properti yang tetap ada saat perangkat dimulai ulang) untuk elemen prefix.

Peringatan

Gunakan ro hanya jika Anda yakin bahwa Anda tidak memerlukan prefix agar dapat ditulis pada masa mendatang. ** Jangan tentukan awalan ro.** Sebagai gantinya, andalkan sepolicy untuk membuat prefix hanya baca (dengan kata lain, hanya dapat ditulis oleh init).

Gunakan persist hanya jika Anda yakin bahwa nilai harus dipertahankan di seluruh proses mulai ulang, dan bahwa penggunaan properti sistem adalah satu-satunya opsi Anda.

Google secara ketat meninjau properti sistem yang memiliki properti ro atau persist.

Istilah group digunakan untuk menggabungkan properti terkait. Tujuannya adalah menjadi nama subsistem yang serupa dengan audio atau telephony. Jangan gunakan istilah yang ambigu atau kelebihan beban seperti sys, system, dev, default, atau config.

Praktik umumnya adalah menggunakan nama jenis domain dari proses yang memiliki akses baca atau tulis eksklusif ke properti sistem. Misalnya, untuk properti sistem yang memiliki akses tulis ke proses vold, biasanya vold (nama jenis domain untuk proses) digunakan sebagai nama grup.

Jika diperlukan, tambahkan subgroup untuk mengategorikan properti lebih lanjut, tetapi hindari istilah yang ambigu atau berlebihan untuk mendeskripsikan elemen ini. (Anda juga dapat memiliki lebih dari satu subgroup.)

Banyak nama grup telah ditentukan. Periksa file system/sepolicy/private/property_contexts dan gunakan nama grup yang ada jika memungkinkan, alih-alih membuat grup baru. Tabel berikut memberikan contoh nama grup yang sering digunakan.

Berikut ini menentukan penggunaan name dan type dalam contoh regex sebelumnya.

[{prefix}.]{group}[.{subgroup}]*.{name}[.{type}]

• name mengidentifikasi properti sistem dalam grup.

• type adalah elemen opsional yang memperjelas jenis atau maksud properti sistem. Misalnya, daripada memberi nama sysprop sebagai audio.awesome_feature_enabled atau hanya audio.awesome_feature, ganti namanya menjadi audio.awesome_feature.enabled untuk mencerminkan jenis dan maksud properti sistem.

Tidak ada aturan khusus tentang jenis yang harus digunakan; berikut adalah rekomendasi penggunaan:

• enabled: Gunakan jika jenisnya adalah properti sistem boolean yang digunakan untuk mengaktifkan atau menonaktifkan fitur.
• config: Gunakan jika maksudnya adalah untuk mengklarifikasi bahwa properti sistem tidak merepresentasikan status dinamis sistem; properti tersebut merepresentasikan nilai yang telah dikonfigurasi sebelumnya (misalnya, sesuatu yang hanya dapat dibaca).
• List: Gunakan jika properti sistem yang nilainya berupa daftar.
• Timeoutmillis: Gunakan jika ini adalah properti sistem untuk nilai waktu tunggu dalam satuan ms.

Contoh:

• persist.radio.multisim.config
• drm.service.enabled

Konteks properti

Skema konteks properti SELinux baru memungkinkan perincian yang lebih baik dan nama yang lebih deskriptif. Mirip dengan yang digunakan untuk nama properti, AOSP merekomendasikan format berikut:

{group}[_{subgroup}]*_prop

Istilah-istilah ini didefinisikan sebagai berikut:

group dan subgroup memiliki arti yang sama seperti yang ditentukan untuk regex contoh sebelumnya. Misalnya, vold_config_prop menandakan properti yang merupakan konfigurasi dari vendor dan dimaksudkan untuk ditetapkan oleh vendor_init, sementara vold_status_prop atau hanya vold_prop menandakan properti yang akan menampilkan status vold saat ini.

Saat memberi nama konteks properti, pilih nama yang mencerminkan penggunaan umum properti. Khususnya, hindari jenis istilah berikut:

• Istilah yang terlihat terlalu umum dan ambigu, seperti sys, system, default.
• Istilah yang secara langsung mengenkode aksesibilitas: seperti exported, apponly, ro, public, private.

Lebih memilih penggunaan nama seperti vold_config_prop daripada exported_vold_prop, atau vold_vendor_writable_prop.

Jenis

Jenis properti dapat berupa salah satu dari berikut yang tercantum dalam tabel.

Secara internal, semua properti disimpan sebagai string. Anda dapat menerapkan jenis dengan menentukannya sebagai file property_contexts. Untuk mengetahui informasi selengkapnya, lihat property_contexts di Langkah 3.

Langkah 2: Tentukan tingkat aksesibilitas yang diperlukan

Ada empat makro bantuan yang menentukan properti.

Cakupan akses ke properti sistem harus sekecil mungkin. Sebelumnya, akses luas telah menyebabkan kerusakan aplikasi dan kerentanan keamanan. Pertimbangkan pertanyaan berikut saat menentukan cakupan:

• Apakah properti sistem ini perlu dipertahankan? (jika ya, mengapa?)
• Proses mana yang harus memiliki akses baca ke properti ini?
• Proses mana yang harus memiliki akses tulis ke properti ini?

Gunakan pertanyaan sebelumnya dan pohon keputusan berikut sebagai alat untuk menentukan cakupan yang sesuai untuk akses.

Gambar 1. Pohon keputusan untuk menentukan cakupan akses ke properti sistem

Langkah 3: Tambahkan ke system/sepolicy

Saat mengakses sysprop, SELinux mengontrol aksesibilitas proses. Setelah Anda menentukan tingkat aksesibilitas yang diperlukan, tentukan konteks properti di bagian system/sepolicy, beserta aturan izinkan dan jangan izinkan tambahan tentang apa yang boleh (dan tidak boleh) dibaca atau ditulis oleh proses.

Pertama, tentukan konteks properti dalam file system/sepolicy/public/property.te. Jika properti bersifat internal sistem, tentukan di file system/sepolicy/private/property.te. Gunakan salah satu makrosystem_[accessibility]_prop([context]) yang menyediakan aksesibilitas yang diperlukan dari properti sistem Anda. Berikut adalah contoh untuk file system/sepolicy/public/property.te:

system_public_prop(audio_foo_prop)
system_vendor_config_prop(audio_bar_prop)

Contoh yang akan ditambahkan dalam file system/sepolicy/private/property.te:

system_internal_prop(audio_baz_prop)

Kedua, berikan akses baca dan (atau) tulis ke konteks properti. Gunakan makro set_prop dan get_prop untuk memberikan akses, baik di file system/sepolicy/public/{domain}.te maupun system/sepolicy/private/{domain}.te. Gunakan private jika memungkinkan; public hanya cocok jika makro set_prop atau get_prop memengaruhi domain di luar domain inti.

Contoh, dalam file system/sepolicy/private/audio.te:

set_prop(audio, audio_foo_prop)
set_prop(audio, audio_bar_prop)

Contoh, dalam file system/sepolicy/public/domain.te:

get_prop(domain, audio_bar_prop)

Ketiga, tambahkan beberapa aturan neverallow untuk lebih mengurangi aksesibilitas yang dicakup oleh makro. Misalnya, asumsikan bahwa Anda telah menggunakan system_restricted_prop karena properti sistem Anda harus dibaca oleh proses vendor. Jika akses baca tidak diperlukan oleh semua proses vendor, dan hanya diperlukan oleh serangkaian proses tertentu (seperti vendor_init), larang proses vendor yang tidak memerlukan akses baca.

Gunakan sintaksis berikut untuk membatasi akses tulis dan baca:

Untuk membatasi akses tulis:

neverallow [domain] [context]:property_service set;

Untuk membatasi akses baca:

neverallow [domain] [context]:file no_rw_file_perms;

Tempatkan aturan neverallow dalam file system/sepolicy/private/{domain}.te jika aturan neverallow terikat ke domain tertentu. Untuk aturan neverallow yang lebih luas, gunakan domain umum seperti berikut jika sesuai:

• system/sepolicy/private/property.te
• system/sepolicy/private/coredomain.te
• system/sepolicy/private/domain.te

Dalam file system/sepolicy/private/audio.te, tempatkan kode berikut:

neverallow {
    domain -init -audio
} {audio_foo_prop audio_bar_prop}:property_service set;

Dalam file system/sepolicy/private/property.te, tempatkan kode berikut:

neverallow {
    domain -coredomain -vendor_init
} audio_prop:file no_rw_file_perms;

Perhatikan bahwa {domain -coredomain} mencakup semua proses vendor. Jadi, {domain -coredomain -vendor_init} berarti "semua proses vendor kecuali vendor_init."

Terakhir, kaitkan properti sistem dengan konteks properti. Hal ini memastikan bahwa akses yang diberikan dan aturan neverallow yang diterapkan ke konteks properti diterapkan ke properti sebenarnya. Untuk melakukannya, tambahkan entri ke file property_contexts, file yang menjelaskan pemetaan antara properti sistem dan konteks properti. Dalam file ini, Anda dapat menentukan satu properti, atau awalan untuk properti yang akan dipetakan ke dalam konteks.

Berikut sintaksis untuk memetakan satu properti:

[property_name] u:object_r:[context_name]:s0 exact [type]

Berikut adalah sintaksis untuk memetakan awalan:

[property_name_prefix] u:object_r:[context_name]:s0 prefix [type]

Secara opsional, Anda dapat menentukan jenis properti, yang dapat berupa salah satu dari berikut:

• bool
• int
• uint
• double
• enum [list of possible values...]
• string (Gunakan string untuk properti daftar.)

Pastikan setiap entri memiliki jenis yang ditetapkan jika memungkinkan, karena type diterapkan saat menetapkan property. Contoh berikut menunjukkan cara menulis pemetaan:

# binds a boolean property "ro.audio.status.enabled"
# to the context "audio_foo_prop"
ro.audio.status.enabled u:object_r:audio_foo_prop:s0 exact bool

# binds a boolean property "vold.decrypt.status"
# to the context "vold_foo_prop"
# The property can only be set to one of these: on, off, unknown
vold.decrypt.status u:object_r:vold_foo_prop:s0 exact enum on off unknown

# binds any properties starting with "ro.audio.status."
# to the context "audio_bar_prop", such as
# "ro.audio.status.foo", or "ro.audio.status.bar.baz", and so on.
ro.audio.status. u:object_r:audio_bar_prop:s0 prefix

Jika entri persis dan entri awalan bertentangan, entri persis akan diprioritaskan. Untuk contoh lainnya, lihat system/sepolicy/private/property_contexts.

Langkah 4: Tentukan persyaratan stabilitas

Stabilitas adalah aspek lain dari properti sistem, dan berbeda dengan aksesibilitas. Stabilitas adalah tentang apakah properti sistem dapat diubah (misalnya, diganti namanya, atau bahkan dihapus) di masa mendatang. Hal ini sangat penting karena OS Android menjadi modular. Dengan Treble, partisi sistem, vendor, dan produk dapat diupdate secara terpisah satu sama lain. Dengan Mainline, beberapa bagian OS dimodularisasi sebagai modul yang dapat diupdate (dalam APEX atau APK).

Jika properti sistem digunakan di seluruh bagian software yang dapat diupdate, misalnya di seluruh partisi sistem dan vendor, properti tersebut harus stabil. Namun, jika digunakan hanya dalam, misalnya, modul Mainline tertentu, Anda dapat mengubah nama, jenis, atau konteks propertinya, dan bahkan menghapusnya.

Ajukan pertanyaan berikut untuk menentukan stabilitas properti sistem:

• Apakah properti sistem ini dimaksudkan untuk dikonfigurasi oleh partner (atau dikonfigurasi secara berbeda per perangkat)? Jika ya, ID tersebut harus stabil.
• Apakah properti sistem yang ditentukan AOSP ini dimaksudkan untuk ditulis atau dibaca dari kode (bukan proses) yang ada di partisi non-sistem seperti vendor.img atau product.img? Jika ya, ID tersebut harus stabil.
• Apakah properti sistem ini diakses di seluruh modul Mainline atau di seluruh modul Mainline dan bagian platform yang tidak dapat diupdate? Jika ya, ID tersebut harus stabil.

Untuk properti sistem yang stabil, tentukan setiap properti secara formal sebagai API dan gunakan API untuk mengakses properti sistem, seperti yang dijelaskan dalam Langkah 6.

Langkah 5: Tetapkan properti pada waktu build

Tetapkan properti pada waktu build dengan variabel makefile. Secara teknis, nilai dibuat ke dalam {partition}/build.prop. Kemudian, init membaca {partition}/build.prop untuk menetapkan properti. Ada dua set variabel tersebut: PRODUCT_{PARTITION}_PROPERTIES dan TARGET_{PARTITION}_PROP.

PRODUCT_{PARTITION}_PROPERTIES berisi daftar nilai properti. Sintaksisnya adalah {prop}={value} atau {prop}?={value}.

{prop}={value} adalah penetapan normal yang memastikan bahwa {prop} ditetapkan ke {value}; hanya satu penetapan tersebut yang dapat dilakukan per satu properti.

{prop}?={value} adalah tugas opsional; {prop} ditetapkan ke {value} hanya jika tidak ada tugas {prop}={value}. Jika ada beberapa penetapan opsional, penetapan pertama yang akan menang.

# sets persist.traced.enable to 1 with system/build.prop
PRODUCT_SYSTEM_PROPERTIES += persist.traced.enable=1

# sets ro.zygote to zygote32 with system/build.prop
# but only when there are no other assignments to ro.zygote
# optional are useful when giving a default value to a property
PRODUCT_SYSTEM_PROPERTIES += ro.zygote?=zygote32

# sets ro.config.low_ram to true with vendor/build.prop
PRODUCT_VENDOR_PROPERTIES += ro.config.low_ram=true

TARGET_{PARTITION}_PROP berisi daftar file, yang langsung dikeluarkan ke {partition}/build.prop. Setiap file berisi daftar pasangan {prop}={value}.

# example.prop

ro.cp_system_other_odex=0
ro.adb.secure=0
ro.control_privapp_permissions=disable

# emits example.prop to system/build.prop
TARGET_SYSTEM_PROP += example.prop

Untuk mengetahui detail selengkapnya, lihat build/make/core/sysprop.mk.

Langkah 6: Mengakses properti saat runtime

Properti dapat dibaca dan ditulis saat runtime.

Skrip init

File skrip init (biasanya file *.rc) dapat membaca properti dengan ${prop} atau ${prop:-default}, dapat menyetel tindakan yang dijalankan setiap kali properti menjadi nilai tertentu, dan dapat menulis properti menggunakan perintah setprop.

# when persist.device_config.global_settings.sys_traced becomes 1,
# set persist.traced.enable to 1
on property:persist.device_config.global_settings.sys_traced=1
    setprop persist.traced.enable 1

# when security.perf_harden becomes 0,
# write /proc/sys/kernel/sample_rate to the value of
# debug.sample_rate. If it's empty, write -100000 instead
on property:security.perf_harden=0
    write /proc/sys/kernel/sample_rate ${debug.sample_rate:-100000}

Perintah shell getprop dan setprop

Anda dapat menggunakan perintah shell getprop atau setprop untuk membaca atau menulis properti. Untuk mengetahui detail selengkapnya, panggil getprop --help atau setprop --help.

$ adb shell getprop ro.vndk.version
$
$ adb shell setprop security.perf_harden 0

Sysprop sebagai API untuk C++/Java/Rust

Dengan sysprop sebagai API, Anda dapat menentukan properti sistem dan menggunakan API yang dibuat otomatis, yang konkret dan diketik. Menetapkan scope dengan Public juga membuat API yang dihasilkan tersedia untuk modul di seluruh batas, dan memastikan stabilitas API. Berikut contoh file .sysprop, modul Android.bp, dan kode C++, Java, dan Rust yang menggunakannya.

# AudioProps.sysprop
# module becomes static class (Java) / namespace (C++) for serving API
module: "android.sysprop.AudioProps"
# owner can be Platform or Vendor or Odm
owner: Platform
# one prop defines one property
prop {
    prop_name: "ro.audio.volume.level"
    type: Integer
    scope: Public
    access: ReadWrite
    api_name: "volume_level"
}
…

// Android.bp
sysprop_library {
    name: "AudioProps",
    srcs: ["android/sysprop/AudioProps.sysprop"],
    property_owner: "Platform",
}

// Rust, Java and C++ modules can link against the sysprop_library
rust_binary {
    rustlibs: ["libaudioprops_rust"],
    …
}

java_library {
    static_libs: ["AudioProps"],
    …
}

cc_binary {
    static_libs: ["libAudioProps"],
    …
}

// Rust code accessing generated API.
// Get volume. Use 50 as the default value.
let vol = audioprops::volume_level()?.unwrap_or_else(50);

// Java codes accessing generated API
// get volume. use 50 as the default value.
int vol = android.sysprop.AudioProps.volume_level().orElse(50);
// add 10 to the volume level.
android.sysprop.AudioProps.volume_level(vol + 10);

// C++ codes accessing generated API
// get volume. use 50 as the default value.
int vol = android::sysprop::AudioProps::volume_level().value_or(50);
// add 10 to the volume level.
android::sysprop::AudioProps::volume_level(vol + 10);

Untuk mengetahui informasi selengkapnya, lihat Menerapkan properti sistem sebagai API.

Fungsi dan metode properti tingkat rendah C/C++, Java, dan Rust

Jika memungkinkan, gunakan Sysprop sebagai API meskipun fungsi C/C++ atau Rust tingkat rendah atau metode Java tingkat rendah tersedia untuk Anda.

libc, libbase, dan libcutils menawarkan fungsi properti sistem C++. libc memiliki API yang mendasarinya, sedangkan fungsi libbase dan libcutils adalah wrapper. Jika memungkinkan, gunakan fungsi sysprop libbase; fungsi ini adalah yang paling mudah, dan biner host dapat menggunakan fungsi libbase. Untuk mengetahui detail selengkapnya, lihat sys/system_properties.h (libc), android-base/properties.h (libbase), dan cutils/properties.h (libcutils).

Class android.os.SystemProperties menawarkan metode properti sistem Java.

Modul rustutils::system_properties menawarkan fungsi dan jenis properti sistem Rust.

Lampiran: Menambahkan properti khusus vendor

Partner (termasuk karyawan Google yang bekerja dalam konteks pengembangan Pixel) ingin menentukan properti sistem khusus hardware (atau khusus perangkat). Properti khusus vendor adalah properti milik partner yang unik untuk hardware atau perangkat mereka sendiri, bukan untuk platform. Karena bergantung pada hardware atau perangkat, fitur ini dimaksudkan untuk digunakan dalam partisi /vendor atau /odm.

Sejak Project Treble, properti platform dan properti vendor telah dipisahkan sepenuhnya untuk mencegah terjadinya konflik. Berikut ini menjelaskan cara menentukan properti vendor, dan memberi tahu properti vendor mana yang harus selalu digunakan.

Namespace pada nama properti dan konteks

Semua properti vendor harus dimulai dengan salah satu awalan berikut untuk mencegah konflik antara properti tersebut dan properti partisi lainnya.

• ctl.odm.
• ctl.vendor.
• ctl.start$odm.
• ctl.start$vendor.
• ctl.stop$odm.
• ctl.stop$vendor.
• init.svc.odm.
• init.svc.vendor.
• ro.odm.
• ro.vendor.
• odm.
• persist.odm.
• persist.vendor.
• vendor.

Perhatikan bahwa ro.hardware. diizinkan sebagai awalan, tetapi hanya untuk kompatibilitas. Jangan gunakan untuk properti biasa.

Semua contoh berikut menggunakan salah satu awalan yang tercantum di atas:

• vendor.display.primary_red
• persist.vendor.faceauth.use_disk_cache
• ro.odm.hardware.platform

Semua konteks properti vendor harus dimulai dengan vendor_. Hal ini juga untuk kompatibilitas. Berikut adalah contohnya:

• vendor_radio_prop.
• vendor_faceauth_prop.
• vendor_usb_prop.

Vendor bertanggung jawab untuk memberi nama dan mengelola properti, jadi ikuti format yang disarankan di Langkah 2, selain persyaratan namespace vendor.

Aturan SEPolicy dan property_contexts khusus vendor

Properti vendor dapat ditentukan oleh makro vendor_internal_prop. Tempatkan aturan khusus vendor yang Anda tentukan di direktori BOARD_VENDOR_SEPOLICY_DIRS. Misalnya, anggaplah Anda menentukan properti faceauth vendor di coral.

Dalam file BoardConfig.mk (atau dalam include BoardConfig.mk apa pun), masukkan berikut:

BOARD_VENDOR_SEPOLICY_DIRS := device/google/coral-sepolicy

Dalam file device/google/coral-sepolicy/private/property.te, masukkan berikut:

vendor_internal_prop(vendor_faceauth_prop)

Dalam file device/google/coral-sepolicy/private/property_contexts, masukkan berikut:

vendor.faceauth.trace u:object_r:vendor_faceauth_prop:s0 exact bool

Batasan properti vendor

Karena partisi sistem dan produk tidak dapat bergantung pada vendor, jangan pernah mengizinkan properti vendor diakses dari partisi system, system-ext, atau product.

Lampiran: Mengganti nama properti yang ada

Jika Anda harus menghentikan penggunaan properti dan beralih ke properti baru, gunakan Sysprop sebagai API untuk mengganti nama properti yang ada. Hal ini mempertahankan kompatibilitas mundur dengan menentukan nama lama dan nama properti baru. Secara khusus, Anda dapat menetapkan nama lama dengan kolom legacy_prop_name di file .sysprop. API yang dihasilkan mencoba membaca prop_name, dan menggunakan legacy_prop_name jika prop_name tidak ada.

Misalnya, langkah-langkah berikut mengganti nama awesome_feature_foo_enabled menjadi foo.awesome_feature.enabled.

Dalam file foo.sysprop

module: "android.sysprop.foo"
owner: Platform
prop {
    api_name: "is_awesome_feature_enabled"
    type: Boolean
    scope: Public
    access: Readonly
    prop_name: "foo.awesome_feature.enabled"
    legacy_prop_name: "awesome_feature_foo_enabled"
}

Dalam kode C++

// is_awesome_feature_enabled() reads "foo.awesome_feature.enabled".
// If it doesn't exist, reads "awesome_feature_foo_enabled" instead
using android::sysprop::foo;

bool enabled = foo::is_awesome_feature_enabled().value_or(false);

Perhatikan peringatan berikut:

• Pertama, Anda tidak dapat mengubah jenis sysprop. Misalnya, Anda tidak dapat membuat properti int menjadi properti string. Anda hanya dapat mengubah namanya.

• Kedua, hanya API baca yang kembali ke nama lama. API tulis tidak melakukan penggantian. Jika sysprop dapat ditulis, Anda tidak dapat mengganti namanya.