spacedls 0.4.0

no_std CCSDS 355.0-B-2 (SDLS) Space Data Link Security implementation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196

//! # spacedls
//!
//! `no_std` implementation of **CCSDS 355.0-B-2** and **CCSDS 355.1-B-1** — Space Data Link Security (SDLS) protocol.
//!
//! This crate provides the cryptographic framing layer defined by the Consultative Committee
//! for Space Data Systems for securing telecommand (TC), telemetry (TM), Advanced Orbiting Systems (AOS)
//! and Unified Space Data Link Protocol (USLP) transfer frames.
//!
//! ## Standards
//!
//! - [CCSDS 355.0-B-2 — SDLS standard procedures](https://public.ccsds.org/Pubs/355x0b2.pdf)
//! - [CCSDS 355.1-B-1 — SDLS extended procedures](https://public.ccsds.org/Pubs/355x1b1.pdf)
//!
//! ## Feature flags
//!
//! | Flag | Default | Description |
//! |------|---------|-------------|
//! | `softcrypto` | yes | Software AES-CBC, AES-GCM, and HMAC-SHA providers. |
//! | `extended` | yes | `ManagedSa`, `ManagedKey` lifecycle state machines, SA store, and Keyring proc macros. |
//! | `std` | no | Enables `std` (for testing / non-embedded targets). |
//! | `defmt` | no | Derives `defmt::Format` on public error and state types. |
//!
//! ## Architecture
//!
//! The central type is [`SecurityAssociation`](protocol::SecurityAssociation), parameterized
//! over a service provider, a frame format, and a counter-length:
//!
//! ```text
//! SecurityAssociation<'a, S, F, N>
//!   'a — key lifetime
//!   S  — service wrapper (AsEnc, AsAuth, or AsAuthEnc)
//!   F  — SDLSFrameFormat (compile-time field lengths)
//!   N  — counter array size (sequence number or IV-as-counter)
//! ```
//!
//! Three service kinds map to CCSDS 355.0-B-2 Section 2.3.1.3:
//!
//! - **Encryption-only** (`AsEnc`) — confidentiality without authentication
//! - **Authentication-only** (`AsAuth`) — integrity via MAC, no encryption
//! - **Authenticated encryption** (`AsAuthEnc`) — confidentiality + integrity (AEAD)
//!
//! Frame formats are defined at the type level via [`SDLSFrameFormat`](protocol::SDLSFrameFormat).
//! Each associated type (`SNLen`, `IVLen`, `PLLen`, `MacLen`, `HeaderLen`) is a `typenum`
//! unsigned integer, enforced at compile time to be within valid CCSDS ranges.
//!
//! ## Quick start
//!
//! ```rust,ignore
//! use spacedls::consts::{BIT128, BYTE0, BYTE4, BYTE12, BYTE16, BYTE18};
//! use spacedls::crypto::{AesGcm, VerifyMacResult};
//! use spacedls::key::ConstKey;
//! use spacedls::protocol::{SDLSFrameFormat, SecurityAssociation};
//! use spacedls::service::AsAuthEnc;
//!
//! // Define a frame format matching your mission's SDLS configuration
//! struct MyFmt;
//! impl SDLSFrameFormat for MyFmt {
//!     type SNLen  = BYTE4;
//!     type IVLen  = BYTE12;
//!     type PLLen  = BYTE0;
//!     type MacLen = BYTE16;
//!     type HeaderLen = BYTE18; // 2 (SPI) + 12 (IV) + 4 (SN) + 0 (PL)
//! }
//!
//! let key = ConstKey::<BIT128>::new([0u8; 16]);
//!
//! let mut sa = SecurityAssociation::new_authenc(
//!     AesGcm::<aes::Aes128>::default(), 0x0001, &key, 16, None,
//! );
//!
//! let iv = [0u8; 12].into();
//! let prefix = b"TC-HDR";
//! let plain = b"payload";
//! let mut cipher = [0u8; 7];
//! let (written, hdr, trlr) = sa.seal(iv, prefix, plain, &mut cipher).unwrap();
//! ```
//!
//! ## Modules
//!
//! - [`consts`] — Byte/bit-width type aliases (`BYTE4`, `BIT128`, etc.)
//! - [`key`] — Key trait and implementations (`ConstKey`, `EmptyKey`, `ManagedKey`)
//! - [`service`] — Service provider traits and parameter types
//! - [`protocol`] — Frame format, security association, sequence numbers, errors
//! - [`crypto`] — MAC type and software crypto providers (feature-gated)

#![no_std]
#![recursion_limit = "512"]

#[cfg(any(test, feature = "std"))]
extern crate std;

#[allow(clippy::type_complexity)]
pub(crate) mod core;

#[cfg(feature = "extended")]
pub(crate) mod extended;

#[cfg(feature = "softcrypto")]
pub(crate) mod softcrypto;

#[doc(hidden)]
#[cfg(any(test, feature = "std"))]
pub mod testfmt;

/// Byte-width and bit-width type aliases for `typenum` unsigned integers.
///
/// `BYTE0`..`BYTE64` map to `typenum::U0`..`typenum::U64`. `BIT128`, `BIT256`, etc.
/// map to the corresponding byte counts (e.g., `BIT128 = U16`). Used as generic
/// parameters for key sizes, IV lengths, MAC lengths and other SDLS field dimensions.
pub mod consts {
    seq_macro::seq!(N in 0..=64 {
        #(pub use crate::core::BYTE~N;)*
    });
    pub use crate::core::{BIT128, BIT192, BIT256, BIT384, BIT512, BIT1024, BIT2048, BIT4096};
}

/// Cryptographic key abstractions.
///
/// The [`Key`](self::key::Key) trait provides a uniform interface for key retrieval.
/// [`ConstKey`](self::key::ConstKey) holds immutable key material for static configurations.
/// [`EmptyKey`](self::key::EmptyKey) is a placeholder that always returns `None`, used by
/// [`ManagedSa`](self::protocol::ManagedSa) before a real key is assigned. With the `extended` feature,
/// [`ManagedKey`](self::key::ManagedKey) adds lifecycle state management
/// (CCSDS 355.1-B-1 Section 2.3.2).
pub mod key {
    pub use crate::core::{ConstKey, EmptyKey, Key};

    #[cfg(feature = "extended")]
    pub use crate::extended::{KeyManagementError, KeyState, ManagedKey};
}

/// Service provider traits and parameter types.
///
/// Defines the three SDLS service kinds (CCSDS 355.0-B-2 Section 2.3.1.3):
/// - [`EncProvider`](self::service::EncProvider) / [`AsEnc`](self::service::AsEnc) — encryption-only
/// - [`AuthProvider`](self::service::AuthProvider) / [`AsAuth`](self::service::AsAuth) — authentication-only
/// - [`AuthEncProvider`](self::service::AuthEncProvider) / [`AsAuthEnc`](self::service::AsAuthEnc) — authenticated encryption
///
/// Each provider trait has an associated [`EncSpec`](self::service::EncSpec),
/// [`AuthSpec`](self::service::AuthSpec), or [`AuthEncSpec`](self::service::AuthEncSpec)
/// that declares key, IV, and MAC sizes at the type level. The `As*` wrappers are sealed
/// and cannot be implemented outside this crate.
pub mod service {
    pub use crate::core::{
        AsAuth, AsAuthEnc, AsEnc, AuthEncParams, AuthEncProvider, AuthEncSpec, AuthParams,
        AuthProvider, AuthSpec, EncParams, EncProvider, EncSpec, ServiceKind,
    };
}

/// SDLS protocol types: frame format, security association, sequence numbers, and errors.
///
/// [`SDLSFrameFormat`](self::protocol::SDLSFrameFormat) is the central trait for compile-time
/// frame layout definition. [`SecurityAssociation`](self::protocol::SecurityAssociation) ties
/// together a service provider, frame format, key, and sequence number into the stateful object
/// that performs `encrypt`/`decrypt`, `sign`/`verify`, or `seal`/`open` operations.
/// With the `extended` feature, [`ManagedSa`](self::protocol::ManagedSa) wraps a
/// [`SecurityAssociation`](self::protocol::SecurityAssociation) with a lifecycle
/// state machine (Provisioned / Operational / Retired) per CCSDS 355.1-B-1 Section 2.3.3.
pub mod protocol {
    pub use crate::core::{
        ReplayInfo, SDLSFrameFormat, SaOperationError, SecurityAssociation, SecurityHeader,
        SecurityTrailer, SequenceNumber, ValidIVLen, ValidMacLen, ValidPLLen, ValidSNLen,
    };

    #[cfg(feature = "extended")]
    pub use crate::extended::{ManagedSa, SaManagementError, SaState};
}

#[cfg(feature = "extended")]
#[doc(hidden)]
pub use spacedls_macros::make_static_keyring_impl as __make_static_keyring_impl;

#[cfg(feature = "extended")]
#[doc(hidden)]
pub use spacedls_macros::make_static_sastore_impl as __make_static_sastore_impl;

/// MAC types and software cryptographic providers.
///
/// Always available: [`Mac`](self::crypto::Mac) newtype and
/// [`VerifyMacResult`](self::crypto::VerifyMacResult) for MAC verification outcomes.
///
/// With the `softcrypto` feature, this module re-exports pure-software implementations:
/// - [`AesCbc`](self::crypto::AesCbc) / [`AesCbcSpec`](self::crypto::AesCbcSpec) — AES-CBC with configurable padding
/// - [`AesGcm`](self::crypto::AesGcm) / [`AesGcmSpec`](self::crypto::AesGcmSpec) — AES-GCM AEAD
/// - [`HmacSha`](self::crypto::HmacSha) / [`HmacShaSpec`](self::crypto::HmacShaSpec) — HMAC-SHA MAC
///
/// Hardware-accelerated providers can be implemented by implementing
/// the corresponding traits in [`service`].
pub mod crypto {
    pub use crate::core::{Mac, VerifyMacResult};

    #[cfg(feature = "softcrypto")]
    pub use crate::core::{GenericDecryptError, GenericEncryptError};
    #[cfg(feature = "softcrypto")]
    pub use crate::softcrypto::{AesCbc, AesCbcSpec, AesGcm, AesGcmSpec, HmacSha, HmacShaSpec};
}