Skip to main content

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}