async_snmp/notification/
types.rs

1//! USM configuration types for SNMPv3 authentication.
2//!
3//! These types store authentication and privacy settings for SNMPv3 operations,
4//! used by both the client and notification receiver.
5
6use bytes::Bytes;
7
8use crate::message::SecurityLevel;
9use crate::v3::{AuthProtocol, LocalizedKey, PrivKey, PrivProtocol};
10
11/// USM user credentials for SNMPv3 authentication.
12///
13/// Stores the credentials needed for authenticated and/or encrypted communication.
14/// Keys are derived when the engine ID is discovered.
15///
16/// # Master Key Caching
17///
18/// When polling many engines with shared credentials, use
19/// [`MasterKeys`](crate::MasterKeys) to cache the expensive password-to-key
20/// derivation. When `master_keys` is set, passwords are ignored and keys are
21/// derived from the cached master keys.
22#[derive(Clone)]
23pub struct UsmConfig {
24    /// Username for USM authentication
25    pub username: Bytes,
26    /// Authentication protocol and password
27    pub auth: Option<(AuthProtocol, Vec<u8>)>,
28    /// Privacy protocol and password
29    pub privacy: Option<(PrivProtocol, Vec<u8>)>,
30    /// SNMPv3 context name for VACM context selection.
31    pub context_name: Bytes,
32    /// Pre-computed master keys for efficient key derivation
33    pub master_keys: Option<crate::v3::MasterKeys>,
34}
35
36impl UsmConfig {
37    /// Create a new USM config with just a username (noAuthNoPriv).
38    pub fn new(username: impl Into<Bytes>) -> Self {
39        Self {
40            username: username.into(),
41            auth: None,
42            privacy: None,
43            context_name: Bytes::new(),
44            master_keys: None,
45        }
46    }
47
48    /// Add authentication (authNoPriv or authPriv).
49    pub fn auth(mut self, protocol: AuthProtocol, password: impl AsRef<[u8]>) -> Self {
50        self.auth = Some((protocol, password.as_ref().to_vec()));
51        self
52    }
53
54    /// Add privacy/encryption (authPriv).
55    pub fn privacy(mut self, protocol: PrivProtocol, password: impl AsRef<[u8]>) -> Self {
56        self.privacy = Some((protocol, password.as_ref().to_vec()));
57        self
58    }
59
60    /// Set the SNMPv3 context name for scoped PDUs.
61    pub fn context_name(mut self, context_name: impl Into<Bytes>) -> Self {
62        self.context_name = context_name.into();
63        self
64    }
65
66    /// Use pre-computed master keys for efficient key derivation.
67    ///
68    /// When set, passwords are ignored and keys are derived from the cached
69    /// master keys. This avoids the expensive ~850us password expansion for
70    /// each engine.
71    pub fn with_master_keys(mut self, master_keys: crate::v3::MasterKeys) -> Self {
72        self.master_keys = Some(master_keys);
73        self
74    }
75
76    /// Get the security level based on configured auth/privacy.
77    pub fn security_level(&self) -> SecurityLevel {
78        // Check master_keys first, then fall back to auth/privacy
79        if let Some(ref master_keys) = self.master_keys {
80            if master_keys.priv_protocol().is_some() {
81                return SecurityLevel::AuthPriv;
82            }
83            return SecurityLevel::AuthNoPriv;
84        }
85
86        match (&self.auth, &self.privacy) {
87            (None, _) => SecurityLevel::NoAuthNoPriv,
88            (Some(_), None) => SecurityLevel::AuthNoPriv,
89            (Some(_), Some(_)) => SecurityLevel::AuthPriv,
90        }
91    }
92
93    /// Derive localized keys for a specific engine ID.
94    ///
95    /// If master keys are configured, uses the cached master keys for efficient
96    /// localization (~1us). Otherwise, performs full password-to-key derivation
97    /// (~850us for SHA-256).
98    pub fn derive_keys(&self, engine_id: &[u8]) -> crate::v3::CryptoResult<DerivedKeys> {
99        // Use master keys if available (efficient path)
100        if let Some(ref master_keys) = self.master_keys {
101            tracing::trace!(target: "async_snmp::client", { engine_id_len = engine_id.len(), auth_protocol = ?master_keys.auth_protocol(), priv_protocol = ?master_keys.priv_protocol() }, "localizing from cached master keys");
102            let (auth_key, priv_key) = master_keys.localize(engine_id)?;
103            tracing::trace!(target: "async_snmp::client", "key localization complete");
104            return Ok(DerivedKeys {
105                auth_key: Some(auth_key),
106                priv_key,
107            });
108        }
109
110        // Fall back to password-based derivation
111        tracing::trace!(target: "async_snmp::client", { engine_id_len = engine_id.len(), has_auth = self.auth.is_some(), has_priv = self.privacy.is_some() }, "deriving localized keys from passwords");
112
113        let auth_key = self.auth.as_ref().map(|(protocol, password)| {
114            tracing::trace!(target: "async_snmp::client", { auth_protocol = ?protocol }, "deriving auth key");
115            LocalizedKey::from_password(*protocol, password, engine_id)
116        }).transpose()?;
117
118        let priv_key = match (&self.auth, &self.privacy) {
119            (Some((auth_protocol, _)), Some((priv_protocol, priv_password))) => {
120                tracing::trace!(target: "async_snmp::client", { priv_protocol = ?priv_protocol }, "deriving privacy key");
121                Some(PrivKey::from_password(
122                    *auth_protocol,
123                    *priv_protocol,
124                    priv_password,
125                    engine_id,
126                )?)
127            }
128            _ => None,
129        };
130
131        tracing::trace!(target: "async_snmp::client", "key derivation complete");
132        Ok(DerivedKeys { auth_key, priv_key })
133    }
134}
135
136impl std::fmt::Debug for UsmConfig {
137    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
138        f.debug_struct("UsmConfig")
139            .field("username", &String::from_utf8_lossy(&self.username))
140            .field("auth", &self.auth.as_ref().map(|(p, _)| p))
141            .field("privacy", &self.privacy.as_ref().map(|(p, _)| p))
142            .field("context_name", &String::from_utf8_lossy(&self.context_name))
143            .field(
144                "master_keys",
145                &self.master_keys.as_ref().map(|mk| {
146                    format!(
147                        "MasterKeys({:?}, {:?})",
148                        mk.auth_protocol(),
149                        mk.priv_protocol()
150                    )
151                }),
152            )
153            .finish()
154    }
155}
156
157/// Derived keys for a specific engine ID.
158///
159/// Used internally for V3 authentication in both client and notification receiver.
160#[derive(Debug)]
161pub struct DerivedKeys {
162    /// Localized authentication key
163    pub auth_key: Option<LocalizedKey>,
164    /// Privacy key
165    pub priv_key: Option<PrivKey>,
166}
167
168#[cfg(test)]
169mod tests {
170    use super::*;
171
172    #[test]
173    fn test_usm_user_config_no_auth() {
174        let config = UsmConfig::new(Bytes::from_static(b"testuser"));
175        assert_eq!(config.security_level(), SecurityLevel::NoAuthNoPriv);
176        assert!(config.auth.is_none());
177        assert!(config.privacy.is_none());
178    }
179
180    #[test]
181    fn test_usm_user_config_auth_only() {
182        let config = UsmConfig::new(Bytes::from_static(b"testuser"))
183            .auth(AuthProtocol::Sha1, b"password123");
184        assert_eq!(config.security_level(), SecurityLevel::AuthNoPriv);
185        assert!(config.auth.is_some());
186        assert!(config.privacy.is_none());
187        assert!(config.context_name.is_empty());
188    }
189
190    #[test]
191    fn test_usm_user_config_auth_priv() {
192        let config = UsmConfig::new(Bytes::from_static(b"testuser"))
193            .auth(AuthProtocol::Sha256, b"authpass")
194            .privacy(PrivProtocol::Aes128, b"privpass");
195        assert_eq!(config.security_level(), SecurityLevel::AuthPriv);
196        assert!(config.auth.is_some());
197        assert!(config.privacy.is_some());
198    }
199
200    #[test]
201    fn test_usm_user_config_context_name() {
202        let config = UsmConfig::new(Bytes::from_static(b"testuser")).context_name("ctx");
203        assert_eq!(config.context_name.as_ref(), b"ctx");
204    }
205
206    #[test]
207    fn test_usm_user_config_derive_keys() {
208        let config = UsmConfig::new(Bytes::from_static(b"testuser"))
209            .auth(AuthProtocol::Sha1, b"password123");
210
211        let engine_id = b"test-engine-id";
212        let keys = config.derive_keys(engine_id).unwrap();
213
214        assert!(keys.auth_key.is_some());
215        assert!(keys.priv_key.is_none());
216    }
217
218    #[test]
219    fn test_usm_user_config_derive_keys_with_privacy() {
220        let config = UsmConfig::new(Bytes::from_static(b"testuser"))
221            .auth(AuthProtocol::Sha256, b"authpass")
222            .privacy(PrivProtocol::Aes128, b"privpass");
223
224        let engine_id = b"test-engine-id";
225        let keys = config.derive_keys(engine_id).unwrap();
226
227        assert!(keys.auth_key.is_some());
228        assert!(keys.priv_key.is_some());
229    }
230}
async_snmp/notification/types.rs

async_snmp/notification/
types.rs
