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::{Error, Result};
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        match unsafe { raw::TEE_GetObjectInfo1(*self.as_raw_ref(), &mut raw_info) } {
59            raw::TEE_SUCCESS => Ok(ObjectInfo::from_raw(raw_info)),
60            code => Err(Error::from_raw_error(code)),
61        }
62    }
63
64    /// Restrict the object usage flags of an object handle to contain at most
65    /// the flags passed in the obj_usage parameter.
66    ///
67    /// # Errors
68    ///
69    /// For [PersistentObject](crate::PersistentObject):
70    ///
71    /// * `CorruptObject`: If the persistent object is corrupt. The object
72    ///   handle SHALL behave based on the
73    ///   `gpd.ta.doesNotCloseHandleOnCorruptObject` property.
74    /// * `StorageNotAvailable`: If the persistent object is stored in a
75    ///   storage area which is currently inaccessible.
76    ///
77    /// # Panics
78    ///
79    /// * If object is not a valid opened object handle.
80    /// * If the implementation detects any other error associated with this
81    ///   function that is not explicitly associated with a defined return code
82    ///   for this function.
83    fn restrict_usage(&mut self, obj_usage: UsageFlag) -> Result<()> {
84        match unsafe { raw::TEE_RestrictObjectUsage1(*self.as_raw_ref(), obj_usage.bits()) } {
85            raw::TEE_SUCCESS => Ok(()),
86            code => Err(Error::from_raw_error(code)),
87        }
88    }
89
90    /// Extract one buffer attribute from an object. The attribute is
91    /// identified by the argument id.
92    ///
93    /// # Errors
94    ///
95    /// For all:
96    ///
97    /// * `ItemNotFound`: If the attribute is not found on this object.
98    /// * `SHORT_BUFFER`: If buffer is NULL or too small to contain the key
99    ///   part.
100    ///
101    /// For [PersistentObject](crate::PersistentObject):
102    ///
103    /// * `CorruptObject`: If the persistent object is corrupt. The object
104    ///   handle SHALL behave based on the
105    ///   `gpd.ta.doesNotCloseHandleOnCorruptObject` property.
106    /// * `StorageNotAvailable`: If the persistent object is stored in a
107    ///   storage area which is currently inaccessible.
108    ///
109    /// # Panics
110    ///
111    /// * If object is not a valid opened object handle.
112    /// * If the object is not initialized.
113    /// * If Bit [29] of attributeID is not set to 0, so the attribute is not a
114    ///   buffer attribute.
115    /// * If Bit [28] of attributeID is set to 0, denoting a protected
116    ///   attribute, and the object usage does not contain the
117    ///   TEE_USAGE_EXTRACTABLE flag.
118    /// * If the implementation detects any other error associated with this
119    ///   function that is not explicitly associated with a defined return code
120    ///   for this function.
121    fn ref_attribute(&self, id: AttributeId, buffer: &mut [u8]) -> Result<usize> {
122        let mut size = buffer.len();
123        match unsafe {
124            raw::TEE_GetObjectBufferAttribute(
125                *self.as_raw_ref(),
126                id as u32,
127                buffer as *mut _ as _,
128                &mut size,
129            )
130        } {
131            raw::TEE_SUCCESS => Ok(size),
132            code => Err(Error::from_raw_error(code)),
133        }
134    }
135
136    /// Extract one value attribute from an object. The attribute is identified
137    /// by the argument id.
138    ///
139    /// # Errors
140    ///
141    /// For all:
142    ///
143    /// * `ItemNotFound`: If the attribute is not found on this object.
144    /// * `SHORT_BUFFER`: If buffer is NULL or too small to contain the key
145    ///   part.
146    ///
147    /// For [PersistentObject](crate::PersistentObject):
148    ///
149    /// * `CorruptObject`: If the persistent object is corrupt. The object
150    ///   handle SHALL behave based on the
151    ///   `gpd.ta.doesNotCloseHandleOnCorruptObject` property.
152    /// * `StorageNotAvailable`: If the persistent object is stored in a
153    ///   storage area which is currently inaccessible.
154    ///
155    /// # Panics
156    ///
157    /// * If object is not a valid opened object handle.
158    /// * If the object is not initialized.
159    /// * If Bit [29] of attributeID is not set to 0, so the attribute is not a
160    ///   buffer attribute.
161    /// * If Bit [28] of attributeID is set to 0, denoting a protected
162    ///   attribute, and the object usage does not contain the
163    ///   TEE_USAGE_EXTRACTABLE flag.
164    /// * If the implementation detects any other error associated with this
165    ///   function that is not explicitly associated with a defined return code
166    ///   for this function.
167    fn value_attribute(&self, id: u32) -> Result<(u32, u32)> {
168        let mut value_a: u32 = 0;
169        let mut value_b: u32 = 0;
170        match unsafe {
171            raw::TEE_GetObjectValueAttribute(
172                *self.as_raw_ref(),
173                id,
174                &mut value_a as *mut _,
175                &mut value_b as *mut _,
176            )
177        } {
178            raw::TEE_SUCCESS => Ok((value_a, value_b)),
179            code => Err(Error::from_raw_error(code)),
180        }
181    }
182}
optee_utee/object/generic_object.rs

optee_utee/object/
generic_object.rs
