1 /* 2 * Copyright (C) 2019 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #pragma once 18 19 #include <binder/Common.h> 20 #include <binder/IBinder.h> 21 #include <string> 22 23 namespace android { 24 25 class BpBinder; 26 class ProcessState; 27 28 namespace internal { 29 30 // Stability encodes how a binder changes over time. There are two levels of 31 // stability: 32 // 1). the interface stability - this is how a particular set of API calls (a 33 // particular ordering of things like writeInt32/readInt32) are changed over 34 // time. If one release, we have 'writeInt32' and the next release, we have 35 // 'writeInt64', then this interface doesn't have a very stable 36 // Stability::Level. Usually this ordering is controlled by a .aidl file. 37 // 2). the wire format stability - this is how these API calls map to actual 38 // bytes that are written to the wire (literally, this is how they are written 39 // to the kernel inside of IBinder::transact, but it may be expanded to other 40 // wires in the future). For instance, writeInt32 in binder translates to 41 // writing a 4-byte little-endian integer in two's complement. You can imagine 42 // in the future, we change writeInt32/readInt32 to instead write 8-bytes with 43 // that integer and some check bits. In this case, the wire format changes, 44 // but as long as a client libbinder knows to keep on writing a 4-byte value 45 // to old servers, and new servers know how to interpret the 8-byte result, 46 // they can still communicate. 47 // 48 // This class is specifically about (1). (2) is not currently tracked by 49 // libbinder for regular binder calls, and everything on the system uses the 50 // same copy of libbinder. 51 52 class Stability final { 53 public: 54 // Given a binder interface at a certain stability, there may be some 55 // requirements associated with that higher stability level. For instance, a 56 // VINTF stability binder is required to be in the VINTF manifest. This API 57 // can be called to use that same interface within the local partition. 58 LIBBINDER_EXPORTED static void forceDowngradeToLocalStability(const sp<IBinder>& binder); 59 60 // WARNING: Below APIs are only ever expected to be called by auto-generated code. 61 // Instead of calling them, you should set the stability of a .aidl interface 62 63 // WARNING: The only client of 64 // - forceDowngradeToSystemStability() and; 65 // - korceDowngradeToVendorStability() 66 // should be AIBinder_forceDowngradeToLocalStability(). 67 // 68 // getLocalLevel() in libbinder returns Level::SYSTEM when called 69 // from libbinder_ndk (even on vendor partition). So we explicitly provide 70 // these methods for use by the NDK API: 71 // AIBinder_forceDowngradeToLocalStability(). 72 // 73 // This allows correctly downgrading the binder's stability to either system/vendor, 74 // depending on the partition. 75 76 // Given a binder interface at a certain stability, there may be some 77 // requirements associated with that higher stability level. For instance, a 78 // VINTF stability binder is required to be in the VINTF manifest. This API 79 // can be called to use that same interface within the vendor partition. 80 LIBBINDER_EXPORTED static void forceDowngradeToVendorStability(const sp<IBinder>& binder); 81 82 // Given a binder interface at a certain stability, there may be some 83 // requirements associated with that higher stability level. For instance, a 84 // VINTF stability binder is required to be in the VINTF manifest. This API 85 // can be called to use that same interface within the system partition. 86 LIBBINDER_EXPORTED static void forceDowngradeToSystemStability(const sp<IBinder>& binder); 87 88 // WARNING: This is only ever expected to be called by auto-generated code. You likely want to 89 // change or modify the stability class of the interface you are using. 90 // This must be called as soon as the binder in question is constructed. No thread safety 91 // is provided. 92 // E.g. stability is according to libbinder compilation unit 93 LIBBINDER_EXPORTED static void markCompilationUnit(IBinder* binder); 94 // WARNING: This is only ever expected to be called by auto-generated code. You likely want to 95 // change or modify the stability class of the interface you are using. 96 // This must be called as soon as the binder in question is constructed. No thread safety 97 // is provided. 98 // E.g. stability is according to libbinder_ndk or Java SDK AND the interface 99 // expressed here is guaranteed to be stable for multiple years (Stable AIDL) 100 LIBBINDER_EXPORTED static void markVintf(IBinder* binder); 101 102 // WARNING: for debugging only 103 LIBBINDER_EXPORTED static std::string debugToString(const sp<IBinder>& binder); 104 105 // WARNING: This is only ever expected to be called by auto-generated code or tests. 106 // You likely want to change or modify the stability of the interface you are using. 107 // This must be called as soon as the binder in question is constructed. No thread safety 108 // is provided. 109 // E.g. stability is according to libbinder_ndk or Java SDK AND the interface 110 // expressed here is guaranteed to be stable for multiple years (Stable AIDL) 111 // If this is called when __ANDROID_VNDK__ is not defined, then it is UB and will likely 112 // break the device during GSI or other tests. 113 LIBBINDER_EXPORTED static void markVndk(IBinder* binder); 114 115 // Returns true if the binder needs to be declared in the VINTF manifest or 116 // else false if the binder is local to the current partition. 117 LIBBINDER_EXPORTED static bool requiresVintfDeclaration(const sp<IBinder>& binder); 118 119 private: 120 // Parcel needs to read/write stability level in an unstable format. 121 friend ::android::Parcel; 122 123 // only expose internal APIs inside of libbinder, for checking stability 124 friend ::android::BpBinder; 125 126 // so that it can mark the context object (only the root object doesn't go 127 // through Parcel) 128 friend ::android::ProcessState; 129 130 static void tryMarkCompilationUnit(IBinder* binder); 131 132 // Currently, we use int16_t for Level so that it can fit in BBinder. 133 // However, on the wire, we have 4 bytes reserved for stability, so whenever 134 // we ingest a Level, we always accept an int32_t. 135 enum Level : int16_t { 136 UNDECLARED = 0, 137 138 VENDOR = 0b000011, 139 SYSTEM = 0b001100, 140 VINTF = 0b111111, 141 }; 142 143 // returns the stability according to how this was built 144 static Level getLocalLevel(); 145 146 // Downgrades binder stability to the specified level. 147 static void forceDowngradeToStability(const sp<IBinder>& binder, Level level); 148 149 enum { 150 REPR_NONE = 0, 151 REPR_LOG = 1, 152 REPR_ALLOW_DOWNGRADE = 2, 153 }; 154 // applies stability to binder if stability level is known 155 __attribute__((warn_unused_result)) static status_t setRepr(IBinder* binder, int32_t setting, 156 uint32_t flags); 157 158 // get stability information as encoded on the wire 159 static int16_t getRepr(IBinder* binder); 160 161 // whether a transaction on binder is allowed, if the transaction 162 // is done from a context with a specific stability level 163 static bool check(int16_t provided, Level required); 164 165 static bool isDeclaredLevel(int32_t level); 166 static std::string levelString(int32_t level); 167 168 Stability(); 169 }; 170 171 } // namespace internal 172 } // namespace android 173