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