tpm2_protocol/
lib.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2// Copyright (c) 2025 Opinsys Oy
3// Copyright (c) 2024-2025 Jarkko Sakkinen
4
5//! # TPM 2.0 Protocol
6//!
7//! A library for marshaling and unmarshaling TCG TPM 2.0 protocol messages.
8//!
9//! ## Constraints
10//!
11//! * `alloc` is disallowed.
12//! * Dependencies are disallowed.
13//! * Developer dependencies are disallowed.
14//! * Panics are disallowed.
15//!
16//! ## Design Goals
17//!
18//! * The crate must compile with GNU make and rustc without any external
19//!   dependencies.
20
21#![cfg_attr(not(test), no_std)]
22#![deny(unsafe_code)]
23#![deny(clippy::all)]
24#![deny(clippy::pedantic)]
25#![recursion_limit = "256"]
26
27pub mod basic;
28pub mod constant;
29pub mod data;
30#[macro_use]
31pub mod r#macro;
32pub mod frame;
33
34/// A TPM handle, which is a 32-bit unsigned integer.
35#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
36#[repr(transparent)]
37pub struct TpmHandle(pub u32);
38
39impl core::convert::From<u32> for TpmHandle {
40    fn from(val: u32) -> Self {
41        Self(val)
42    }
43}
44
45impl core::convert::From<TpmHandle> for u32 {
46    fn from(val: TpmHandle) -> Self {
47        val.0
48    }
49}
50
51impl TpmMarshal for TpmHandle {
52    fn marshal(&self, writer: &mut TpmWriter) -> TpmResult<()> {
53        TpmMarshal::marshal(&self.0, writer)
54    }
55}
56
57impl TpmUnmarshal for TpmHandle {
58    fn unmarshal(buf: &[u8]) -> TpmResult<(Self, &[u8])> {
59        let (val, buf) = u32::unmarshal(buf)?;
60        Ok((Self(val), buf))
61    }
62}
63
64impl TpmSized for TpmHandle {
65    const SIZE: usize = size_of::<u32>();
66    fn len(&self) -> usize {
67        Self::SIZE
68    }
69}
70
71impl core::fmt::Display for TpmHandle {
72    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
73        core::fmt::Display::fmt(&self.0, f)
74    }
75}
76
77impl core::fmt::LowerHex for TpmHandle {
78    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
79        core::fmt::LowerHex::fmt(&self.0, f)
80    }
81}
82
83impl core::fmt::UpperHex for TpmHandle {
84    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
85        core::fmt::UpperHex::fmt(&self.0, f)
86    }
87}
88
89/// TPM frame marshaling and unmarshaling error type containing variants
90/// for all the possible error conditions.
91#[derive(Debug, PartialEq, Eq)]
92pub enum TpmProtocolError {
93    /// Buffer contains more data than allowed by the TCG specifications.
94    BufferTooLarge,
95    /// An [`TpmAttest`](crate::data::TpmAttest) instance contains an invalid
96    /// magic value.
97    InvalidAttestMagic,
98    /// Boolean value was expected but the value is neither `0` nor `1`.
99    InvalidBoolean,
100    /// Non-existent command code encountered.
101    InvalidCc,
102    /// Tag is neither [`Sessions`](crate::data::TpmSt::Sessions) nor
103    /// [`NoSessions`](crate::data::TpmSt::NoSessions).
104    InvalidTag,
105    /// A cryptographic operation failed.
106    OperationFailed,
107    /// Writer's buffer is full.
108    OutOfMemory,
109    /// List contains more items than allowed by the TCG specifications.
110    TooManyItems,
111    /// Trailing data left after unmarshaling.
112    TrailingData,
113    /// Run out of bytes while unmarshaling.
114    UnexpectedEnd,
115    /// The requested variant is missing.
116    VariantMissing,
117}
118
119impl core::fmt::Display for TpmProtocolError {
120    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
121        match self {
122            Self::BufferTooLarge => write!(f, "buffer is too large"),
123            Self::InvalidAttestMagic => write!(f, "invalid attestation magic"),
124            Self::InvalidBoolean => write!(f, "invalid boolean value"),
125            Self::InvalidCc => write!(f, "invalid command code"),
126            Self::InvalidTag => write!(f, "invalid tag"),
127            Self::OperationFailed => write!(f, "operation failed"),
128            Self::OutOfMemory => write!(f, "out of memory"),
129            Self::TooManyItems => write!(f, "list has too many items"),
130            Self::TrailingData => write!(f, "trailing data"),
131            Self::UnexpectedEnd => write!(f, "unexpected end"),
132            Self::VariantMissing => write!(f, "variant missing"),
133        }
134    }
135}
136
137impl core::error::Error for TpmProtocolError {}
138
139pub type TpmResult<T> = Result<T, TpmProtocolError>;
140
141/// Writes into a mutable byte slice.
142pub struct TpmWriter<'a> {
143    buffer: &'a mut [u8],
144    cursor: usize,
145}
146
147impl<'a> TpmWriter<'a> {
148    /// Creates a new writer for the given buffer.
149    #[must_use]
150    pub fn new(buffer: &'a mut [u8]) -> Self {
151        Self { buffer, cursor: 0 }
152    }
153
154    /// Returns the number of bytes written so far.
155    #[must_use]
156    pub fn len(&self) -> usize {
157        self.cursor
158    }
159
160    /// Returns `true` if no bytes have been written.
161    #[must_use]
162    pub fn is_empty(&self) -> bool {
163        self.cursor == 0
164    }
165
166    /// Appends a slice of bytes to the writer.
167    ///
168    /// # Errors
169    ///
170    /// Returns [`CapacityExceeded`](crate::TpmProtocolError::CapacitExceeded)
171    /// when the capacity of the buffer is exceeded.
172    pub fn write_bytes(&mut self, bytes: &[u8]) -> TpmResult<()> {
173        let end = self.cursor + bytes.len();
174        if end > self.buffer.len() {
175            return Err(TpmProtocolError::OutOfMemory);
176        }
177        self.buffer[self.cursor..end].copy_from_slice(bytes);
178        self.cursor = end;
179        Ok(())
180    }
181}
182
183/// Provides two ways to determine the size of an oBject: a compile-time maximum
184/// and a runtime exact size.
185pub trait TpmSized {
186    /// The estimated size of the object in its serialized form evaluated at
187    /// compile-time (always larger than the realized length).
188    const SIZE: usize;
189
190    /// Returns the exact serialized size of the object.
191    fn len(&self) -> usize;
192
193    /// Returns `true` if the object has a serialized length of zero.
194    fn is_empty(&self) -> bool {
195        self.len() == 0
196    }
197}
198
199pub trait TpmMarshal: TpmSized {
200    /// Marshals the object into the given writer.
201    ///
202    /// # Errors
203    ///
204    /// Returns `Err(TpmProtocolError)` on a marshal failure.
205    fn marshal(&self, writer: &mut TpmWriter) -> TpmResult<()>;
206}
207
208pub trait TpmUnmarshal: Sized + TpmSized {
209    /// Unmarshals an object from the given buffer.
210    ///
211    /// Returns the unmarshald type and the remaining portion of the buffer.
212    ///
213    /// # Errors
214    ///
215    /// Returns `Err(TpmProtocolError)` on a unmarshal failure.
216    fn unmarshal(buf: &[u8]) -> TpmResult<(Self, &[u8])>;
217}
218
219/// Types that are composed of a tag and a value e.g., a union.
220pub trait TpmTagged {
221    /// The type of the tag/discriminant.
222    type Tag: TpmUnmarshal + TpmMarshal + Copy;
223    /// The type of the value/union.
224    type Value;
225}
226
227/// Unmarshals a tagged object from a buffer.
228pub trait TpmUnmarshalTagged: Sized {
229    /// Unmarshals a tagged object from the given buffer using the provided tag.
230    ///
231    /// # Errors
232    ///
233    /// This method can return any error of the underlying type's `TpmUnmarshal` implementation,
234    /// such as a `TpmProtocolError::UnexpectedEnd` if the buffer is too small or an
235    /// `TpmProtocolError::MalformedValue` if the data is malformed.
236    fn unmarshal_tagged(tag: <Self as TpmTagged>::Tag, buf: &[u8]) -> TpmResult<(Self, &[u8])>
237    where
238        Self: TpmTagged,
239        <Self as TpmTagged>::Tag: TpmUnmarshal + TpmMarshal;
240}
241
242tpm_integer!(u8, Unsigned);
243tpm_integer!(i8, Signed);
244tpm_integer!(i32, Signed);
245tpm_integer!(u16, Unsigned);
246tpm_integer!(u32, Unsigned);
247tpm_integer!(u64, Unsigned);
tpm2_protocol/lib.rs

tpm2_protocol/
lib.rs
