se05x/
lib.rs

1// Copyright (C) 2023 Nitrokey GmbH
2// SPDX-License-Identifier: LGPL-3.0-only
3#![cfg_attr(not(test), no_std)]
4
5//! SE05X driver
6//! ===========
7//!
8//! This crate contains a Rust driver for the SE05x series of secure elements from NXP.
9//! It contains an implementation of the T=1 protocol and the ISO7816-4 APDUs that are used to communicate with the se05x.
10//!
11//! ```rust,no_run
12//! # include!("doc_utils.rs");
13//! # #[cfg(feature = "builder")]
14//! # fn main() -> Result<(), se05x::se05x::Error> {
15//! use se05x::se05x::commands::*;
16//! use se05x::se05x::policies::*;
17//! use se05x::se05x::*;
18//! let i2c = get_i2c();
19//! let delay = get_delay();
20//! let address = 0x48;
21//! let mut se05x = Se05X::new(i2c, address, delay);
22//! let user_id = ObjectId([0x01, 0x00, 0x00, 0x00]);
23//! let object_id = ObjectId([0x01, 0x02, 0x03, 0x04]);
24//! let buf = &mut [0; 128];
25//!
26//! let atr = se05x.enable();
27//!
28//! // Running a WriteUserId command:
29//! se05x.run_command(
30//!     &WriteUserId::builder()
31//!         .object_id(user_id)
32//!         .data(b"Some value")
33//!         .build(),
34//!     buf,
35//! )?;
36//!
37//! // Creating a file with a policy
38//! let policy = &[Policy {
39//!     object_id: user_id,
40//!     access_rule: ObjectAccessRule::from_flags(ObjectPolicyFlags::ALLOW_READ),
41//! }];
42//!
43//! se05x.run_command(
44//!     &WriteBinary::builder()
45//!         .policy(PolicySet(policy))
46//!         .object_id(object_id)
47//!         .file_length(9.into())
48//!         .data(b"Some data")
49//!         .build(),
50//!     buf,
51//! )?;
52//!
53//! // Opening a session with teh UserID
54//! let session_id = se05x
55//!     .run_command(&CreateSession { object_id: user_id }, buf)?
56//!     .session_id;
57//!
58//! // Verifying the UserId
59//! se05x.run_session_command(
60//!     session_id,
61//!     &VerifySessionUserId {
62//!         user_id: b"Some value",
63//!     },
64//!     buf,
65//! )?;
66//! // Reading the data with the verified session
67//! let data = se05x.run_session_command(
68//!     session_id,
69//!     &ReadObject::builder()
70//!         .object_id(object_id)
71//!         .offset(0.into())
72//!         .length(9.into())
73//!         .build(),
74//!     buf,
75//! )?;
76//! # Ok(())
77//! # }
78//! # #[cfg(not(feature = "builder"))]
79//! # fn main() {}
80//! ```
81//!
82//! Architecture
83//! ------------
84//!
85//! ### T=1
86//!
87//! This driver communicates with the se05x over the T=1 protocol over I2C, as described in [UM11225](https://www.nxp.com/webapp/Download?colCode=UM11225).
88//!
89//! To do so and be compatible with most embedded controlers, it depends on the I2C [Read](https://docs.rs/embedded-hal/latest/embedded_hal/blocking/i2c/trait.Read.html) and [Write](https://docs.rs/embedded-hal/latest/embedded_hal/blocking/i2c/trait.Write.html) from [embedded-hal](https://docs.rs/embedded-hal/latest/embedded_hal).
90//!
91//! #### Embedded HAL v0.2
92//!
93//! The traits do not expose the protocol enough, as the T=1 protocol requires detecting I2C NACKs, which are not exposed in this version.
94//!
95//! Nacks are exposed in the `Error` types for each `HAL` crate. As such an extension to the embedded-hal traits is defined as `I2CErrorNack`, exposing the missing information.
96//! It is implemented for the NRF and LPC55 Hals in `src/t1/i2cimpl.rs`, gated by the features `nrf` and `lpc55` respectively.
97//!
98//! #### Embedded HAL v1.0
99//!
100//! This version exposes the required I2C NACKs. There is no need to use the `nrf` and `lpc55` features.
101//!
102//! ### Iso7816
103//!
104//! This driver uses the [`iso7816`](https://docs.rs/iso7816/latest/iso7816/) crate to implement serialization of APDUs.
105//!
106//! ### Generation of commands
107//!
108//! To simplify implementation, all supported se05x APDUs are described in `src/se05x/commands.toml`.
109//! The python script `generate_commands.py` parses the `command.toml` file and generates `src/se05x/commands.rs`, which implements all the APDUs.
110//!
111//! Funding
112//! -------
113//!
114//! [<img src="https://nlnet.nl/logo/banner.svg" width="200" alt="Logo NLnet: abstract logo of four people seen from above" hspace="20">](https://nlnet.nl/)
115//! [<img src="https://nlnet.nl/image/logos/NGIAssure_tag.svg" width="200" alt="Logo NGI Assure: letterlogo shaped like a tag" hspace="20">](https://nlnet.nl/assure/)
116//!
117//! This project was funded through the [NGI Assure](https://nlnet.nl/assure/) Fund, a fund established by [NLnet](https://nlnet.nl/) with financial support from the European Commission's [Next Generation Internet programme](https://ngi.eu/), under the aegis of DG Communications Networks, Content and Technology under grant agreement No 957073.
118
119extern crate delog;
120delog::generate_macros!();
121
122pub mod embedded_hal;
123mod macros;
124
125pub mod se05x;
126pub mod t1;
se05x/lib.rs

se05x/
lib.rs
