optee_utee/object/generic_object.rs
1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements. See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership. The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License. You may obtain a copy of the License at
8//
9// http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied. See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18use core::mem;
19
20use super::{AttributeId, ObjectInfo, UsageFlag};
21use crate::{Result, tee_check};
22
23use optee_utee_sys as raw;
24
25/// A generic trait for an object (transient or persistent).
26pub trait GenericObject {
27 /// Returns the raw handle of the object.
28 ///
29 /// This returns a reference to ensure the `GenericObject` is not dropped,
30 /// which prevents the raw pointer from being cleaned up and the handle
31 /// from becoming a dangling pointer.
32 ///
33 /// # Safety
34 /// Use of a raw C pointer is inherently unsafe, and the caller might modify
35 /// the object through this pointer.
36 unsafe fn as_raw_ref(&self) -> &raw::TEE_ObjectHandle;
37
38 /// Return the characteristics of an object.
39 ///
40 /// # Errors
41 ///
42 /// For [PersistentObject](crate::PersistentObject):
43 ///
44 /// * `CorruptObject`: If the persistent object is corrupt. The object
45 /// handle SHALL behave based on the
46 /// `gpd.ta.doesNotCloseHandleOnCorruptObject` property.
47 /// * `StorageNotAvailable`: If the persistent object is stored in a
48 /// storage area which is currently inaccessible.
49 ///
50 /// # Panics
51 ///
52 /// * If object is not a valid opened object handle.
53 /// * If the implementation detects any other error associated with this
54 /// function that is not explicitly associated with a defined return code
55 /// for this function.
56 fn info(&self) -> Result<ObjectInfo> {
57 let mut raw_info: raw::TEE_ObjectInfo = unsafe { mem::zeroed() };
58 tee_check(unsafe { raw::TEE_GetObjectInfo1(*self.as_raw_ref(), &mut raw_info) })?;
59 Ok(ObjectInfo::from_raw(raw_info))
60 }
61
62 /// Restrict the object usage flags of an object handle to contain at most
63 /// the flags passed in the obj_usage parameter.
64 ///
65 /// # Errors
66 ///
67 /// For [PersistentObject](crate::PersistentObject):
68 ///
69 /// * `CorruptObject`: If the persistent object is corrupt. The object
70 /// handle SHALL behave based on the
71 /// `gpd.ta.doesNotCloseHandleOnCorruptObject` property.
72 /// * `StorageNotAvailable`: If the persistent object is stored in a
73 /// storage area which is currently inaccessible.
74 ///
75 /// # Panics
76 ///
77 /// * If object is not a valid opened object handle.
78 /// * If the implementation detects any other error associated with this
79 /// function that is not explicitly associated with a defined return code
80 /// for this function.
81 fn restrict_usage(&mut self, obj_usage: UsageFlag) -> Result<()> {
82 tee_check(unsafe { raw::TEE_RestrictObjectUsage1(*self.as_raw_ref(), obj_usage.bits()) })
83 }
84
85 /// Extract one buffer attribute from an object. The attribute is
86 /// identified by the argument id.
87 ///
88 /// # Errors
89 ///
90 /// For all:
91 ///
92 /// * `ItemNotFound`: If the attribute is not found on this object.
93 /// * `SHORT_BUFFER`: If buffer is NULL or too small to contain the key
94 /// part.
95 ///
96 /// For [PersistentObject](crate::PersistentObject):
97 ///
98 /// * `CorruptObject`: If the persistent object is corrupt. The object
99 /// handle SHALL behave based on the
100 /// `gpd.ta.doesNotCloseHandleOnCorruptObject` property.
101 /// * `StorageNotAvailable`: If the persistent object is stored in a
102 /// storage area which is currently inaccessible.
103 ///
104 /// # Panics
105 ///
106 /// * If object is not a valid opened object handle.
107 /// * If the object is not initialized.
108 /// * If Bit [29] of attributeID is not set to 0, so the attribute is not a
109 /// buffer attribute.
110 /// * If Bit [28] of attributeID is set to 0, denoting a protected
111 /// attribute, and the object usage does not contain the
112 /// TEE_USAGE_EXTRACTABLE flag.
113 /// * If the implementation detects any other error associated with this
114 /// function that is not explicitly associated with a defined return code
115 /// for this function.
116 fn ref_attribute(&self, id: AttributeId, buffer: &mut [u8]) -> Result<usize> {
117 let mut size = buffer.len();
118 tee_check(unsafe {
119 raw::TEE_GetObjectBufferAttribute(
120 *self.as_raw_ref(),
121 id as u32,
122 buffer as *mut _ as _,
123 &mut size,
124 )
125 })?;
126 Ok(size)
127 }
128
129 /// Extract one value attribute from an object. The attribute is identified
130 /// by the argument id.
131 ///
132 /// # Errors
133 ///
134 /// For all:
135 ///
136 /// * `ItemNotFound`: If the attribute is not found on this object.
137 /// * `SHORT_BUFFER`: If buffer is NULL or too small to contain the key
138 /// part.
139 ///
140 /// For [PersistentObject](crate::PersistentObject):
141 ///
142 /// * `CorruptObject`: If the persistent object is corrupt. The object
143 /// handle SHALL behave based on the
144 /// `gpd.ta.doesNotCloseHandleOnCorruptObject` property.
145 /// * `StorageNotAvailable`: If the persistent object is stored in a
146 /// storage area which is currently inaccessible.
147 ///
148 /// # Panics
149 ///
150 /// * If object is not a valid opened object handle.
151 /// * If the object is not initialized.
152 /// * If Bit [29] of attributeID is not set to 0, so the attribute is not a
153 /// buffer attribute.
154 /// * If Bit [28] of attributeID is set to 0, denoting a protected
155 /// attribute, and the object usage does not contain the
156 /// TEE_USAGE_EXTRACTABLE flag.
157 /// * If the implementation detects any other error associated with this
158 /// function that is not explicitly associated with a defined return code
159 /// for this function.
160 fn value_attribute(&self, id: u32) -> Result<(u32, u32)> {
161 let mut value_a: u32 = 0;
162 let mut value_b: u32 = 0;
163 tee_check(unsafe {
164 raw::TEE_GetObjectValueAttribute(
165 *self.as_raw_ref(),
166 id,
167 &mut value_a as *mut _,
168 &mut value_b as *mut _,
169 )
170 })?;
171 Ok((value_a, value_b))
172 }
173}