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/IBinder.h> 20 #include <string> 21 22 namespace android { 23 24 class BpBinder; 25 class ProcessState; 26 27 namespace internal { 28 29 // Stability encodes how a binder changes over time. There are two levels of 30 // stability: 31 // 1). the interface stability - this is how a particular set of API calls (a 32 // particular ordering of things like writeInt32/readInt32) are changed over 33 // time. If one release, we have 'writeInt32' and the next release, we have 34 // 'writeInt64', then this interface doesn't have a very stable 35 // Stability::Level. Usually this ordering is controlled by a .aidl file. 36 // 2). the wire format stability - this is how these API calls map to actual 37 // bytes that are written to the wire (literally, this is how they are written 38 // to the kernel inside of IBinder::transact, but it may be expanded to other 39 // wires in the future). For instance, writeInt32 in binder translates to 40 // writing a 4-byte little-endian integer in two's complement. You can imagine 41 // in the future, we change writeInt32/readInt32 to instead write 8-bytes with 42 // that integer and some check bits. In this case, the wire format changes, 43 // but as long as a client libbinder knows to keep on writing a 4-byte value 44 // to old servers, and new servers know how to interpret the 8-byte result, 45 // they can still communicate. 46 // 47 // Every binder object has a stability level associated with it, and when 48 // communicating with a binder, we make sure that the command we sent is one 49 // that it knows how to process. The summary of stability of a binder is 50 // represented by a Stability::Category object. 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 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 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 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 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 static void markVintf(IBinder* binder); 101 102 // WARNING: for debugging only 103 static void debugLogStability(const std::string& tag, 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 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 static bool requiresVintfDeclaration(const sp<IBinder>& binder); 118 private: 119 // Parcel needs to read/write stability level in an unstable format. 120 friend ::android::Parcel; 121 122 // only expose internal APIs inside of libbinder, for checking stability 123 friend ::android::BpBinder; 124 125 // so that it can mark the context object (only the root object doesn't go 126 // through Parcel) 127 friend ::android::ProcessState; 128 129 static void tryMarkCompilationUnit(IBinder* binder); 130 131 enum Level : uint8_t { 132 UNDECLARED = 0, 133 134 VENDOR = 0b000011, 135 SYSTEM = 0b001100, 136 VINTF = 0b111111, 137 }; 138 139 // This is the format of stability passed on the wire. 140 struct Category { fromReprCategory141 static inline Category fromRepr(int32_t representation) { 142 return *reinterpret_cast<Category*>(&representation); 143 } reprCategory144 int32_t repr() const { 145 return *reinterpret_cast<const int32_t*>(this); 146 } 147 static inline Category currentFromLevel(Level level); 148 149 bool operator== (const Category& o) const { 150 return repr() == o.repr(); 151 } 152 bool operator!= (const Category& o) const { 153 return !(*this == o); 154 } 155 156 std::string debugString(); 157 158 // This is the version of the wire protocol associated with the host 159 // process of a particular binder. As the wire protocol changes, if 160 // sending a transaction to a binder with an old version, the Parcel 161 // class must write parcels according to the version documented here. 162 uint8_t version; 163 164 uint8_t reserved[2]; 165 166 // bitmask of Stability::Level 167 Level level; 168 }; 169 static_assert(sizeof(Category) == sizeof(int32_t)); 170 171 // returns the stability according to how this was built 172 static Level getLocalLevel(); 173 174 // Downgrades binder stability to the specified level. 175 static void forceDowngradeToStability(const sp<IBinder>& binder, Level level); 176 177 enum { 178 REPR_NONE = 0, 179 REPR_LOG = 1, 180 REPR_ALLOW_DOWNGRADE = 2, 181 }; 182 // applies stability to binder if stability level is known 183 __attribute__((warn_unused_result)) 184 static status_t setRepr(IBinder* binder, int32_t representation, uint32_t flags); 185 186 // get stability information as encoded on the wire 187 static Category getCategory(IBinder* binder); 188 189 // whether a transaction on binder is allowed, if the transaction 190 // is done from a context with a specific stability level 191 static bool check(Category provided, Level required); 192 193 static bool isDeclaredLevel(Level level); 194 static std::string levelString(Level level); 195 196 Stability(); 197 }; 198 199 } // namespace internal 200 } // namespace android 201