Systemeigenschaften hinzufügen

Auf dieser Seite wird eine kanonische Methode zum Hinzufügen oder Definieren von Systemeigenschaften in Android beschrieben. Außerdem finden Sie hier Richtlinien zum Refaktorieren vorhandener Systemeigenschaften. Halten Sie sich beim Refaktorieren an die Richtlinien, es sei denn, es gibt ein schwerwiegendes Kompatibilitätsproblem, das etwas anderes erfordert.

Schritt 1: Systemeigenschaft definieren

Wenn Sie eine Systemeigenschaft hinzufügen, legen Sie einen Namen für die Eigenschaft fest und verknüpfen Sie sie mit einem SELinux-Eigenschaftskontext. Wenn kein geeigneter Kontext vorhanden ist, erstellen Sie einen neuen. Der Name wird beim Zugriff auf das Attribut verwendet. Der Attributkontext wird verwendet, um die Zugänglichkeit in Bezug auf SELinux zu steuern. Namen können beliebige Strings sein. AOSP empfiehlt jedoch, ein strukturiertes Format zu verwenden, um sie eindeutig zu gestalten.

Name der Eigenschaft

Verwenden Sie dieses Format mit Snake-Case:

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

Verwenden Sie für das Element prefix entweder „“ (ausgelassen), ro (für Properties, die nur einmal festgelegt werden) oder persist (für Properties, die auch nach einem Neustart beibehalten werden).

Einschränkungen

Verwenden Sie ro nur, wenn Sie sicher sind, dass prefix in Zukunft nicht beschreibbar sein muss. ** Geben Sie nicht das Präfix ro an.** Verlassen Sie sich stattdessen auf sepolicy, um prefix schreibgeschützt zu machen (d. h. nur von init beschreibbar).

Verwenden Sie persist nur, wenn Sie sicher sind, dass der Wert über Neustarts hinweg beibehalten werden muss und die Verwendung der Systemeigenschaften Ihre einzige Option ist.

Google prüft die Systemeigenschaften, die entweder ro- oder persist-Attribute haben, sehr genau.

Der Begriff group wird verwendet, um zusammengehörige Properties zusammenzufassen. Es soll ein Subsystemname sein, der ähnlich wie audio oder telephony verwendet wird. Verwenden Sie keine mehrdeutigen oder überladenen Begriffe wie sys, system, dev, default oder config.

Es ist üblich, den Namen des Domänentyps eines Prozesses zu verwenden, der exklusiven Lese- oder Schreibzugriff auf die Systemeigenschaften hat. Für die Systemeigenschaften, auf die der vold-Prozess Schreibzugriff hat, wird häufig vold (der Name des Domaintyps für den Prozess) als Gruppenname verwendet.

Fügen Sie bei Bedarf subgroup hinzu, um Properties weiter zu kategorisieren. Vermeiden Sie jedoch mehrdeutige oder überladene Begriffe zur Beschreibung dieses Elements. Sie können auch mehrere subgroup haben.

Viele Gruppennamen sind bereits definiert. Prüfen Sie die Datei system/sepolicy/private/property_contexts und verwenden Sie nach Möglichkeit vorhandene Gruppennamen, anstatt neue zu erstellen. In der folgenden Tabelle finden Sie Beispiele für häufig verwendete Gruppennamen.

Im Folgenden wird die Verwendung von name und type im vorherigen Regex-Beispiel definiert.

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

• name identifiziert eine Systemeigenschaft innerhalb einer Gruppe.

• type ist ein optionales Element, das den Typ oder die Absicht der Systemeigenschaft verdeutlicht. Anstatt eine System-Property beispielsweise als audio.awesome_feature_enabled oder nur audio.awesome_feature zu benennen, benennen Sie sie in audio.awesome_feature.enabled um, um den Typ und die Absicht der System-Property widerzuspiegeln.

Es gibt keine spezifische Regel dafür, welcher Typ verwendet werden muss. Hier sind einige Empfehlungen:

• enabled: Verwenden Sie diesen Wert, wenn der Typ eine boolesche Systemeigenschaft ist, mit der eine Funktion aktiviert oder deaktiviert wird.
• config: Verwenden Sie diese Option, wenn Sie klarstellen möchten, dass die Systemeigenschaft keinen dynamischen Status des Systems darstellt, sondern einen vorkonfigurierten Wert (z. B. ein schreibgeschütztes Element).
• List: Verwenden Sie diese Option, wenn es sich um eine Systemeigenschaft handelt, deren Wert eine Liste ist.
• Timeoutmillis: Verwenden Sie diese Option, wenn es sich um eine Systemeigenschaft für einen Zeitlimitwert in Millisekunden handelt.

Beispiele:

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

Unterkunftskontext

Das neue SELinux-Attributkontextschema ermöglicht eine feinere Granularität und aussagekräftigere Namen. Ähnlich wie bei Attributnamen empfiehlt AOSP das folgende Format:

{group}[_{subgroup}]*_prop

Die Begriffe sind so definiert:

group und subgroup haben dieselbe Bedeutung wie im vorherigen Beispiel für reguläre Ausdrücke definiert. vold_config_prop steht beispielsweise für Eigenschaften, die Konfigurationen eines Anbieters sind und von vendor_init festgelegt werden sollen, während vold_status_prop oder nur vold_prop für Eigenschaften steht, die den aktuellen Status von vold offenlegen sollen.

Wählen Sie für den Namen eines Property-Kontexts Namen aus, die die allgemeine Verwendung der Properties widerspiegeln. Vermeiden Sie insbesondere die folgenden Arten von Begriffen:

• Begriffe, die zu allgemein und mehrdeutig sind, z. B. sys, system, default.
• Begriffe, die die Barrierefreiheit direkt codieren, z. B. exported, apponly, ro, public, private.

Verwenden Sie Namen wie vold_config_prop statt exported_vold_prop oder vold_vendor_writable_prop.

Eingeben

Ein Property-Typ kann einer der folgenden sein (siehe Tabelle).

Intern werden alle Eigenschaften als Strings gespeichert. Sie können den Typ erzwingen, indem Sie ihn als property_contexts-Datei angeben. Weitere Informationen finden Sie unter property_contexts in Schritt 3.

Schritt 2: Erforderliche Barrierefreiheitsstufen festlegen

Es gibt vier Hilfsmakros, mit denen eine Property definiert wird.

Beschränken Sie den Zugriff auf Systemeigenschaften so weit wie möglich. In der Vergangenheit hat ein breiter Zugriff zu App-Fehlern und Sicherheitslücken geführt. Berücksichtigen Sie bei der Eingrenzung folgende Fragen:

• Muss diese Systemeigenschaft beibehalten werden? Falls ja, warum?
• Welcher Prozess sollte Lesezugriff auf diese Property haben?
• Welcher Prozess sollte Schreibzugriff auf diese Property haben?

Anhand der vorherigen Fragen und des folgenden Entscheidungsbaums können Sie den angemessenen Umfang für den Zugriff ermitteln.

Abbildung 1: Entscheidungsbaum zur Bestimmung des Umfangs des Zugriffs auf Systemeigenschaften

Schritt 3: In „system/sepolicy“ hinzufügen

Beim Zugriff auf „sysprop“ steuert SELinux die Zugänglichkeit von Prozessen. Nachdem Sie festgelegt haben, welches Maß an Barrierefreiheit erforderlich ist, definieren Sie unter system/sepolicy Eigenschaftskontexte sowie zusätzliche allow- und neverallow-Regeln, die festlegen, was die Prozesse lesen oder schreiben dürfen und was nicht.

Definieren Sie zuerst den Attributkontext in der Datei system/sepolicy/public/property.te. Wenn das Attribut systemintern ist, definieren Sie es in der Datei system/sepolicy/private/property.te. Verwenden Sie eines der system_[accessibility]_prop([context])-Makros, das die für Ihre Systemeigenschaft erforderliche Barrierefreiheit bietet. Hier sehen Sie ein Beispiel für die system/sepolicy/public/property.te-Datei:

system_public_prop(audio_foo_prop)
system_vendor_config_prop(audio_bar_prop)

Beispiel für das Hinzufügen in der Datei system/sepolicy/private/property.te:

system_internal_prop(audio_baz_prop)

Gewähren Sie als Nächstes Lese- und/oder Schreibzugriff auf den Property-Kontext. Verwenden Sie die Makros set_prop und get_prop, um Zugriff zu gewähren, entweder in der Datei system/sepolicy/public/{domain}.te oder system/sepolicy/private/{domain}.te. Verwenden Sie nach Möglichkeit private. public ist nur geeignet, wenn sich das Makro set_prop oder get_prop auf Domains außerhalb der Hauptdomain auswirkt.

Beispiel in der Datei system/sepolicy/private/audio.te:

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

Beispiel in der Datei system/sepolicy/public/domain.te:

get_prop(domain, audio_bar_prop)

Drittens: Fügen Sie einige „neverallow“-Regeln hinzu, um die durch das Makro eingeschränkte Zugänglichkeit weiter zu reduzieren. Angenommen, Sie haben system_restricted_prop verwendet, weil Ihre Systemeigenschaften von Anbieterprozessen gelesen werden müssen. Wenn der Lesezugriff nicht für alle Anbieterprozesse erforderlich ist, sondern nur für bestimmte Prozesse (z. B. vendor_init), verbieten Sie die Anbieterprozesse, die den Lesezugriff nicht benötigen.

Verwenden Sie die folgende Syntax, um den Schreib- und Lesezugriff einzuschränken:

So schränken Sie den Schreibzugriff ein:

neverallow [domain] [context]:property_service set;

So schränken Sie den Lesezugriff ein:

neverallow [domain] [context]:file no_rw_file_perms;

Platzieren Sie „neverallow“-Regeln in der Datei system/sepolicy/private/{domain}.te, wenn die „neverallow“-Regel an eine bestimmte Domain gebunden ist. Verwenden Sie für allgemeinere „neverallow“-Regeln nach Möglichkeit allgemeine Domains wie die folgenden:

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

Fügen Sie in der Datei system/sepolicy/private/audio.te Folgendes ein:

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

Fügen Sie in der Datei system/sepolicy/private/property.te Folgendes ein:

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

{domain -coredomain} umfasst alle Anbieterprozesse. {domain -coredomain -vendor_init} bedeutet also „alle Anbieterprozesse außer vendor_init“.

Verknüpfen Sie schließlich eine Systemeigenschaft mit dem Property-Kontext. So wird sichergestellt, dass der gewährte Zugriff und die „neverallow“-Regeln, die auf Property-Kontexte angewendet werden, auf tatsächliche Properties angewendet werden. Fügen Sie dazu einen Eintrag in die Datei property_contexts ein. Diese Datei beschreibt die Zuordnung zwischen Systemeigenschaften und Eigenschaftskontexten. In dieser Datei können Sie entweder eine einzelne Property oder ein Präfix für Properties angeben, die einem Kontext zugeordnet werden sollen.

So ordnen Sie eine einzelne Property zu:

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

So ordnen Sie ein Präfix zu:

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

Sie können optional den Typ der Property angeben. Folgende Typen sind möglich:

• bool
• int
• uint
• double
• enum [list of possible values...]
• string (Verwenden Sie string für Listeneigenschaften.)

Achten Sie darauf, dass jeder Eintrag nach Möglichkeit den entsprechenden Typ hat, da type beim Festlegen von property erzwungen wird. Das folgende Beispiel zeigt, wie eine Zuordnung geschrieben wird:

# 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

Bei Konflikten zwischen einem genauen Eintrag und einem Präfixeintrag hat der genaue Eintrag Vorrang. Weitere Beispiele finden Sie unter system/sepolicy/private/property_contexts.

Schritt 4: Stabilitätsanforderungen festlegen

Stabilität ist ein weiterer Aspekt von Systemeigenschaften und unterscheidet sich von der Barrierefreiheit. Bei der Stabilität geht es darum, ob eine Systemeigenschaft in Zukunft geändert (z. B. umbenannt oder sogar entfernt) werden kann. Das ist besonders wichtig, da das Android-Betriebssystem modular wird. Mit Treble können die System-, Anbieter- und Produktpartitionen unabhängig voneinander aktualisiert werden. Bei Mainline werden einige Teile des Betriebssystems als aktualisierbare Module (in APEXes oder APKs) modularisiert.

Wenn eine Systemeigenschaft für die Verwendung in aktualisierbaren Softwarekomponenten vorgesehen ist, z. B. in System- und Anbieterpartitionen, muss sie stabil sein. Wenn sie jedoch nur in einem bestimmten Mainline-Modul verwendet wird, können Sie ihren Namen, Typ oder ihre Property-Kontexte ändern und sie sogar entfernen.

Stellen Sie sich die folgenden Fragen, um die Stabilität einer Systemeigenschaft zu bestimmen:

• Soll dieses Systemattribut von Partnern konfiguriert werden (oder für jedes Gerät unterschiedlich konfiguriert werden)? Wenn ja, muss sie stabil sein.
• Soll diese AOSP-definierte Systemeigenschaft in Code (nicht Prozess) geschrieben oder daraus gelesen werden, der sich auf Nicht-Systempartitionen wie vendor.img oder product.img befindet? Wenn ja, muss sie stabil sein.
• Wird auf diese Systemeigenschaft über Mainline-Module oder über ein Mainline-Modul und den nicht aktualisierbaren Teil der Plattform zugegriffen? Wenn ja, muss sie stabil sein.

Definieren Sie für die stabilen Systemeigenschaften jede als API und verwenden Sie die API, um auf die Systemeigenschaft zuzugreifen, wie in Schritt 6 beschrieben.

Schritt 5: Eigenschaften zur Build-Zeit festlegen

Attribute zur Build-Zeit mit Makefile-Variablen festlegen Die Werte sind technisch gesehen in {partition}/build.prop integriert. Dann wird init gelesen und die Eigenschaften werden auf {partition}/build.prop festgelegt. Es gibt zwei Gruppen solcher Variablen: PRODUCT_{PARTITION}_PROPERTIES und TARGET_{PARTITION}_PROP.

PRODUCT_{PARTITION}_PROPERTIES enthält eine Liste von Attributwerten. Die Syntax lautet {prop}={value} oder {prop}?={value}.

{prop}={value} ist eine normale Zuweisung, mit der sichergestellt wird, dass {prop} auf {value} festgelegt ist. Pro Property ist nur eine solche Zuweisung möglich.

{prop}?={value} ist eine optionale Zuweisung. {prop} wird nur dann auf {value} gesetzt, wenn keine {prop}={value}-Zuweisungen vorhanden sind. Wenn mehrere optionale Zuweisungen vorhanden sind, wird die erste verwendet.

# 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 enthält eine Liste von Dateien, die direkt an {partition}/build.prop ausgegeben wird. Jede Datei enthält eine Liste von {prop}={value}-Paaren.

# 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

Weitere Informationen finden Sie unter build/make/core/sysprop.mk.

Schritt 6: Auf Eigenschaften zur Laufzeit zugreifen

Properties können zur Laufzeit gelesen und geschrieben werden.

Init-Scripts

In Init-Skriptdateien (in der Regel *.rc-Dateien) kann eine Eigenschaft mit ${prop} oder ${prop:-default} gelesen, eine Aktion festgelegt werden, die ausgeführt wird, wenn eine Eigenschaft einen bestimmten Wert annimmt, und die Eigenschaften können mit dem Befehl setprop geschrieben werden.

# 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}

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

# 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);

BOARD_VENDOR_SEPOLICY_DIRS := device/google/coral-sepolicy

vendor_internal_prop(vendor_faceauth_prop)

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

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"
}

// 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);