Skip to content

Commit

Permalink
Document simulated device and reader interaction for all states and t…
Browse files Browse the repository at this point in the history 
…ransitions (#90)

Documented several members

- `presentation::*`
- `presentation::device::*`
- `presentation::reader::*`
- some from `definitions::device_response`

CI:
- Run `cargo doc` in `ci` to catch warning for `rustdoc`
- Add `workflow_dispatch` so we can manually run on any branch, useful for PR that are to other branches than `main`
  • Loading branch information
@radumarias
radumarias authored Aug 12, 2024
1 parent 9d99da6 commit a017b66
Show file tree
Hide file tree
Showing 20 changed files with 899 additions and 10 deletions.
11 changes: 10 additions & 1 deletion .github/workflows/ci.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ on:
env:
CARGO_TERM_COLOR: always
RUSTFLAGS: "-Dwarnings"
RUSTDOCFLAGS: "-Dwarnings"

jobs:
build:
Expand All @@ -30,4 +31,12 @@ jobs:
run: cargo clippy --all-targets

- name: Fmt
run: cargo fmt --all -- --check
run: cargo fmt --all -- --check
- name: Fmt
run: cargo fmt --all -- --check

- name: Doc
run: |
cargo doc --all-features --no-deps
cd macros
cargo doc --all-features --no-deps
86 changes: 86 additions & 0 deletions docs/on_simulated_device.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
+---------+
| |
| |
| User |
| |
| |
+---+-----+
|
|
+----------------------------------------------------v--------------------------------------------------------------+
| Device |
| |
| +-------------------+ |
| | | |
| |SessionManagerInit | |
| | | |
| +---------------------------------+ +-------------+ |
| | | | | |
| | | | | |
| | +-------------------+ | |
| | | |
| | qr_engagement |
| | | |
| | | |
| qr_engagement | |
| | | |
| | +----------v------------+ |
| | | | |
| | | SessionManagerEngaged <-------------+ |
| | +----------+ | | |
| | | | | | |
| | | +-----------------------+ | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | process_session_establishment | |
| | | | |
| | +--------------------------------------v----------------------------------+ | |
| | | SessionManager | | |
| | | | | |
| | | +--------------------+ | | |
| | | | | | | |
| | | +-----------------------+ AwaitingRequest <----------------+ | | |
| | | | | | | | | |
| | | | +-----------+ | | | | |
| | |prepare_response | +--------------------+ | | | |
| | | | | | | | |
| | | | | | | establish_session |
| | | | | | | | |
| | | | handle_request | | | |
| | | | | | | | |
| | | | | | | | |
| | | +--v-----------v--------+ retrieve_response | | |
| | | | +--------- | | | |
| | | | Signing | get_next_signature_payload | | | |
| | | | <--------- | | | |
| | | +---------+-------------+ | | | |
| | | | | | | |
| | | | | | | |
| | | | | | | |
| | | submit_next_signature | | | |
| | | | | | | |
| | | | +----------------------+ | | | |
| | | | | | | | | |
| | | | | ReadyToRespond | | | | |
| | | +-----------------> +-------------+ | | |
| | | | | | | |
| | | +----------+-----------+ | | |
| | | | | | |
| | +-----------------------------------------+-------------------------------+ | |
| | handle_response | |
+-------+------------------------------------------------+---------------------------------------------+------------+
| | |
| +-------v-------+ |
| | Reader | |
| | | |
| | | |
+----------------------------------------> +-------------------------------------+
| |
| |
| |
+---------------+
29 changes: 29 additions & 0 deletions docs/on_simulated_reader.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
+--------+
| |
| User |
| |
+---+----+
|
|
+---v-----+
| |
| Device |
+---------+ |<----------------+
| | | |
| | | |
| +--+--^---+ |
| | | |
| | | establish_session |
|qr_engagement | | |
| | | | new_request
| | | |
+-v--------------v--+-------------------+---+
| Reader |
| |
| +--------------------+ handle_response |
| | +---------------+ |
| | SessionManager | | |
| | |<--------------+ |
| +--------------------+ |
| |
+-------------------------------------------+
45 changes: 45 additions & 0 deletions docs/simulated_device_and_reader.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
+---------------------+ +----------------------+
| | | |
| | | |
| Device | | Reader |
| | | |
| | | |
+---------+-----------+ +----------+-----------+
| |
Initialize session |
| |
| |
Create QR code engagement |
| |
+-------------+ |
| | |
| | |
<-------------+ |
| |
| Send QR code |
+----------------------------------------------------------------->
| |
| | Establish session
| +-----------+
| | |
| | |
| +-----------+
| Request age_over_21 |
<-----------------------------------------------------------------+
| |
| |
| |
| Send age_over_21 |
+----------------------------------------------------------------->
| |
| |
| | Process age_over_21
| +-----------+
| | |
| | |
| +-----------+
| |
| |
| |
| Session finished |
| |
46 changes: 46 additions & 0 deletions src/definitions/device_engagement.rs
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,9 @@
//! This module contains the definitions for the [DeviceEngagement] struct and related types.
//!
//! The [DeviceEngagement] struct represents a device engagement object, which contains information about a device's engagement with a server.
//! It includes fields such as the `version`, `security details, `device retrieval methods, `server retrieval methods, and `protocol information.
//!
//! The module also provides implementations for conversions between [DeviceEngagement] and [CborValue], as well as other utility functions.
use crate::definitions::helpers::Tag24;
use crate::definitions::helpers::{ByteStr, NonEmptyVec};
use crate::definitions::CoseKey;
Expand All @@ -21,68 +27,108 @@ pub type ProtocolInfo = CborValue;
pub type Oidc = (u64, String, String);
pub type WebApi = (u64, String, String);

/// Represents a device engagement.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(try_from = "CborValue", into = "CborValue", rename_all = "camelCase")]
pub struct DeviceEngagement {
/// The version of the device engagement.
pub version: String,

/// The security settings for the device engagement.
pub security: Security,

/// The optional device retrieval methods for the device engagement.
#[serde(skip_serializing_if = "Option::is_none")]
pub device_retrieval_methods: Option<DeviceRetrievalMethods>,

/// The optional server retrieval methods for the device engagement.
#[serde(skip_serializing_if = "Option::is_none")]
pub server_retrieval_methods: Option<ServerRetrievalMethods>,

/// The optional protocol information for the device engagement.
#[serde(skip_serializing_if = "Option::is_none")]
pub protocol_info: Option<ProtocolInfo>,
}

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(try_from = "CborValue", into = "CborValue")]
pub enum DeviceRetrievalMethod {
/// Represents the options for a WiFi connection.
WIFI(WifiOptions),

/// Represents the BLE options for device engagement.
///
/// This struct is used to configure the BLE options for device engagement.
/// It contains the necessary parameters and settings for BLE communication.
BLE(BleOptions),

/// Represents the options for NFC engagement.
NFC(NfcOptions),
}

/// Represents the bytes of an EDevice key.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
pub struct Security(pub u64, pub EDeviceKeyBytes);

/// Represents the server retrieval methods for device engagement.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct ServerRetrievalMethods {
/// The `web API retrieval method. This field is optional and will be skipped during serialization if it is [None].
#[serde(skip_serializing_if = "Option::is_none")]
web_api: Option<WebApi>,

/// The `OIDC`` retrieval method. This field is optional and will be skipped during serialization if it is [None].
#[serde(skip_serializing_if = "Option::is_none")]
oidc: Option<Oidc>,
}

/// Represents the options for `Bluetooth Low Energy` (BLE) device engagement.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(try_from = "CborValue", into = "CborValue")]
pub struct BleOptions {
/// The peripheral server mode for `BLE` device engagement.
#[serde(skip_serializing_if = "Option::is_none")]
pub peripheral_server_mode: Option<PeripheralServerMode>,

/// The central client mode for `BLE` device engagement.
#[serde(skip_serializing_if = "Option::is_none")]
pub central_client_mode: Option<CentralClientMode>,
}

/// Represents a peripheral server mode.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct PeripheralServerMode {
/// The 'UUID' of the peripheral server.
pub uuid: Uuid,

/// The 'BLE' device address of the peripheral server, if available.
pub ble_device_address: Option<ByteStr>,
}

/// Represents the central client mode for device engagement.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CentralClientMode {
pub uuid: Uuid,
}

/// Represents the options for a `WiFi` device engagement.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(try_from = "CborValue", into = "CborValue")]
pub struct WifiOptions {
/// The passphrase for the `WiFi connection. If [None], no passphrase is required.
#[serde(skip_serializing_if = "Option::is_none")]
pass_phrase: Option<String>,

/// The operating class of the `WiFi` channel. If [None], the operating class is not specified.
#[serde(skip_serializing_if = "Option::is_none")]
channel_info_operating_class: Option<u64>,

/// The channel number of the `WiFi` channel. If [None], the channel number is not specified.
#[serde(skip_serializing_if = "Option::is_none")]
channel_info_channel_number: Option<u64>,

/// The band information of the `WiFi channel. If [None], the band information is not specified.
#[serde(skip_serializing_if = "Option::is_none")]
band_info: Option<ByteStr>,
}
Expand Down
Loading

0 comments on commit a017b66

Please sign in to comment.