async_snmp/client/
auth.rs

1//! Authentication configuration types for the SNMP client.
2//!
3//! This module provides the [`Auth`] enum for specifying authentication
4//! configuration, supporting SNMPv1/v2c community strings and SNMPv3 USM.
5//!
6//! # Master Key Caching
7//!
8//! When polling many engines with shared credentials, use
9//! [`MasterKeys`] to cache the expensive password-to-key
10//! derivation:
11//!
12//! ```rust
13//! use async_snmp::{Auth, AuthProtocol, PrivProtocol, MasterKeys};
14//!
15//! // Derive master keys once (expensive: ~850μs for SHA-256)
16//! let master_keys = MasterKeys::new(AuthProtocol::Sha256, b"authpassword")
17//!     .with_privacy(PrivProtocol::Aes128, b"privpassword");
18//!
19//! // Use with USM builder - localization is cheap (~1μs per engine)
20//! let auth: Auth = Auth::usm("admin")
21//!     .with_master_keys(master_keys)
22//!     .into();
23//! ```
24
25use crate::v3::{AuthProtocol, MasterKeys, PrivProtocol};
26
27/// SNMP version for community-based authentication.
28#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
29pub enum CommunityVersion {
30    /// SNMPv1
31    V1,
32    /// SNMPv2c
33    #[default]
34    V2c,
35}
36
37/// Authentication configuration for SNMP clients.
38#[derive(Debug, Clone)]
39pub enum Auth {
40    /// Community string authentication (SNMPv1 or v2c).
41    Community {
42        /// SNMP version (V1 or V2c)
43        version: CommunityVersion,
44        /// Community string
45        community: String,
46    },
47    /// User-based Security Model (SNMPv3).
48    Usm(UsmAuth),
49}
50
51impl Default for Auth {
52    /// Returns `Auth::v2c("public")`.
53    fn default() -> Self {
54        Auth::v2c("public")
55    }
56}
57
58impl Auth {
59    /// SNMPv1 community authentication.
60    ///
61    /// Creates authentication configuration for SNMPv1, which only supports
62    /// community string authentication without encryption.
63    ///
64    /// # Example
65    ///
66    /// ```rust
67    /// use async_snmp::Auth;
68    ///
69    /// // Create SNMPv1 authentication with "private" community
70    /// let auth = Auth::v1("private");
71    /// ```
72    pub fn v1(community: impl Into<String>) -> Self {
73        Auth::Community {
74            version: CommunityVersion::V1,
75            community: community.into(),
76        }
77    }
78
79    /// SNMPv2c community authentication.
80    ///
81    /// Creates authentication configuration for SNMPv2c, which supports
82    /// community string authentication without encryption but adds GETBULK
83    /// and improved error handling over SNMPv1.
84    ///
85    /// # Example
86    ///
87    /// ```rust
88    /// use async_snmp::Auth;
89    ///
90    /// // Create SNMPv2c authentication with "public" community
91    /// let auth = Auth::v2c("public");
92    ///
93    /// // Auth::default() is equivalent to Auth::v2c("public")
94    /// let auth = Auth::default();
95    /// ```
96    pub fn v2c(community: impl Into<String>) -> Self {
97        Auth::Community {
98            version: CommunityVersion::V2c,
99            community: community.into(),
100        }
101    }
102
103    /// Start building SNMPv3 USM authentication.
104    ///
105    /// Returns a builder that allows configuring authentication and privacy
106    /// protocols. SNMPv3 supports three security levels:
107    /// - noAuthNoPriv: username only (no security)
108    /// - authNoPriv: username with authentication (integrity)
109    /// - authPriv: username with authentication and encryption (confidentiality)
110    ///
111    /// # Example
112    ///
113    /// ```rust
114    /// use async_snmp::{Auth, AuthProtocol, PrivProtocol};
115    ///
116    /// // noAuthNoPriv: username only
117    /// let auth: Auth = Auth::usm("readonly").into();
118    ///
119    /// // authNoPriv: with authentication
120    /// let auth: Auth = Auth::usm("admin")
121    ///     .auth(AuthProtocol::Sha256, "authpassword")
122    ///     .into();
123    ///
124    /// // authPriv: with authentication and encryption
125    /// let auth: Auth = Auth::usm("admin")
126    ///     .auth(AuthProtocol::Sha256, "authpassword")
127    ///     .privacy(PrivProtocol::Aes128, "privpassword")
128    ///     .into();
129    /// ```
130    pub fn usm(username: impl Into<String>) -> UsmBuilder {
131        UsmBuilder::new(username)
132    }
133}
134
135/// SNMPv3 USM authentication parameters.
136#[derive(Debug, Clone)]
137pub struct UsmAuth {
138    /// SNMPv3 username
139    pub username: String,
140    /// Authentication protocol (None for noAuthNoPriv)
141    pub auth_protocol: Option<AuthProtocol>,
142    /// Authentication password
143    pub auth_password: Option<String>,
144    /// Privacy protocol (None for noPriv)
145    pub priv_protocol: Option<PrivProtocol>,
146    /// Privacy password
147    pub priv_password: Option<String>,
148    /// SNMPv3 context name for VACM context selection.
149    /// Most deployments use empty string (default).
150    pub context_name: Option<String>,
151    /// Pre-computed master keys for caching.
152    /// When set, passwords are ignored and keys are derived from master keys.
153    pub master_keys: Option<MasterKeys>,
154}
155
156/// Builder for SNMPv3 USM authentication.
157pub struct UsmBuilder {
158    username: String,
159    auth: Option<(AuthProtocol, String)>,
160    privacy: Option<(PrivProtocol, String)>,
161    context_name: Option<String>,
162    master_keys: Option<MasterKeys>,
163}
164
165impl UsmBuilder {
166    /// Create a new USM builder with the given username.
167    ///
168    /// # Example
169    ///
170    /// ```rust
171    /// use async_snmp::Auth;
172    ///
173    /// let builder = Auth::usm("admin");
174    /// ```
175    pub fn new(username: impl Into<String>) -> Self {
176        Self {
177            username: username.into(),
178            auth: None,
179            privacy: None,
180            context_name: None,
181            master_keys: None,
182        }
183    }
184
185    /// Add authentication (authNoPriv or authPriv).
186    ///
187    /// This method performs the full key derivation (~850us for SHA-256) when
188    /// the client connects. When polling many engines with shared credentials,
189    /// consider using [`with_master_keys`](Self::with_master_keys) instead.
190    ///
191    /// # Supported Protocols
192    ///
193    /// - `AuthProtocol::Md5` - HMAC-MD5-96 (legacy)
194    /// - `AuthProtocol::Sha1` - HMAC-SHA-96 (legacy)
195    /// - `AuthProtocol::Sha224` - HMAC-SHA-224
196    /// - `AuthProtocol::Sha256` - HMAC-SHA-256
197    /// - `AuthProtocol::Sha384` - HMAC-SHA-384
198    /// - `AuthProtocol::Sha512` - HMAC-SHA-512
199    ///
200    /// # Example
201    ///
202    /// ```rust
203    /// use async_snmp::{Auth, AuthProtocol};
204    ///
205    /// let auth: Auth = Auth::usm("admin")
206    ///     .auth(AuthProtocol::Sha256, "mypassword")
207    ///     .into();
208    /// ```
209    pub fn auth(mut self, protocol: AuthProtocol, password: impl Into<String>) -> Self {
210        self.auth = Some((protocol, password.into()));
211        self
212    }
213
214    /// Add privacy/encryption (authPriv).
215    ///
216    /// Privacy requires authentication; this is validated at connection time.
217    ///
218    /// # Supported Protocols
219    ///
220    /// - `PrivProtocol::Des` - DES-CBC (legacy, insecure)
221    /// - `PrivProtocol::Aes128` - AES-128-CFB
222    /// - `PrivProtocol::Aes192` - AES-192-CFB
223    /// - `PrivProtocol::Aes256` - AES-256-CFB
224    ///
225    /// # Example
226    ///
227    /// ```rust
228    /// use async_snmp::{Auth, AuthProtocol, PrivProtocol};
229    ///
230    /// let auth: Auth = Auth::usm("admin")
231    ///     .auth(AuthProtocol::Sha256, "authpassword")
232    ///     .privacy(PrivProtocol::Aes128, "privpassword")
233    ///     .into();
234    /// ```
235    pub fn privacy(mut self, protocol: PrivProtocol, password: impl Into<String>) -> Self {
236        self.privacy = Some((protocol, password.into()));
237        self
238    }
239
240    /// Use pre-computed master keys for authentication and privacy.
241    ///
242    /// This is the efficient path when polling many engines with shared
243    /// credentials. The expensive password-to-key derivation
244    /// (~850μs) is done once when creating the [`MasterKeys`], and only the
245    /// cheap localization (~1μs) is performed per engine.
246    ///
247    /// When master keys are set, the [`auth`](Self::auth) and
248    /// [`privacy`](Self::privacy) methods are ignored.
249    ///
250    /// # Example
251    ///
252    /// ```rust
253    /// use async_snmp::{Auth, AuthProtocol, PrivProtocol, MasterKeys};
254    ///
255    /// // Derive master keys once
256    /// let master_keys = MasterKeys::new(AuthProtocol::Sha256, b"authpassword")
257    ///     .with_privacy(PrivProtocol::Aes128, b"privpassword");
258    ///
259    /// // Use with multiple clients
260    /// let auth: Auth = Auth::usm("admin")
261    ///     .with_master_keys(master_keys)
262    ///     .into();
263    /// ```
264    pub fn with_master_keys(mut self, master_keys: MasterKeys) -> Self {
265        self.master_keys = Some(master_keys);
266        self
267    }
268
269    /// Set the SNMPv3 context name for VACM context selection.
270    ///
271    /// The context name allows selecting different MIB views on the same agent.
272    /// Most deployments use empty string (default).
273    ///
274    /// # Example
275    ///
276    /// ```rust
277    /// use async_snmp::{Auth, AuthProtocol};
278    ///
279    /// let auth: Auth = Auth::usm("admin")
280    ///     .auth(AuthProtocol::Sha256, "password")
281    ///     .context_name("vlan100")
282    ///     .into();
283    /// ```
284    pub fn context_name(mut self, name: impl Into<String>) -> Self {
285        self.context_name = Some(name.into());
286        self
287    }
288}
289
290impl From<UsmBuilder> for Auth {
291    fn from(b: UsmBuilder) -> Auth {
292        Auth::Usm(UsmAuth {
293            username: b.username,
294            auth_protocol: b
295                .master_keys
296                .as_ref()
297                .map(|m| m.auth_protocol())
298                .or(b.auth.as_ref().map(|(p, _)| *p)),
299            auth_password: b.auth.map(|(_, pw)| pw),
300            priv_protocol: b
301                .master_keys
302                .as_ref()
303                .and_then(|m| m.priv_protocol())
304                .or(b.privacy.as_ref().map(|(p, _)| *p)),
305            priv_password: b.privacy.map(|(_, pw)| pw),
306            context_name: b.context_name,
307            master_keys: b.master_keys,
308        })
309    }
310}
311
312#[cfg(test)]
313mod tests {
314    use super::*;
315
316    #[test]
317    fn test_default_auth() {
318        let auth = Auth::default();
319        match auth {
320            Auth::Community { version, community } => {
321                assert_eq!(version, CommunityVersion::V2c);
322                assert_eq!(community, "public");
323            }
324            _ => panic!("expected Community variant"),
325        }
326    }
327
328    #[test]
329    fn test_v1_auth() {
330        let auth = Auth::v1("private");
331        match auth {
332            Auth::Community { version, community } => {
333                assert_eq!(version, CommunityVersion::V1);
334                assert_eq!(community, "private");
335            }
336            _ => panic!("expected Community variant"),
337        }
338    }
339
340    #[test]
341    fn test_v2c_auth() {
342        let auth = Auth::v2c("secret");
343        match auth {
344            Auth::Community { version, community } => {
345                assert_eq!(version, CommunityVersion::V2c);
346                assert_eq!(community, "secret");
347            }
348            _ => panic!("expected Community variant"),
349        }
350    }
351
352    #[test]
353    fn test_community_version_default() {
354        let version = CommunityVersion::default();
355        assert_eq!(version, CommunityVersion::V2c);
356    }
357
358    #[test]
359    fn test_usm_no_auth_no_priv() {
360        let auth: Auth = Auth::usm("readonly").into();
361        match auth {
362            Auth::Usm(usm) => {
363                assert_eq!(usm.username, "readonly");
364                assert!(usm.auth_protocol.is_none());
365                assert!(usm.auth_password.is_none());
366                assert!(usm.priv_protocol.is_none());
367                assert!(usm.priv_password.is_none());
368                assert!(usm.context_name.is_none());
369            }
370            _ => panic!("expected Usm variant"),
371        }
372    }
373
374    #[test]
375    fn test_usm_auth_no_priv() {
376        let auth: Auth = Auth::usm("admin")
377            .auth(AuthProtocol::Sha256, "authpass123")
378            .into();
379        match auth {
380            Auth::Usm(usm) => {
381                assert_eq!(usm.username, "admin");
382                assert_eq!(usm.auth_protocol, Some(AuthProtocol::Sha256));
383                assert_eq!(usm.auth_password, Some("authpass123".to_string()));
384                assert!(usm.priv_protocol.is_none());
385                assert!(usm.priv_password.is_none());
386            }
387            _ => panic!("expected Usm variant"),
388        }
389    }
390
391    #[test]
392    fn test_usm_auth_priv() {
393        let auth: Auth = Auth::usm("admin")
394            .auth(AuthProtocol::Sha256, "authpass")
395            .privacy(PrivProtocol::Aes128, "privpass")
396            .into();
397        match auth {
398            Auth::Usm(usm) => {
399                assert_eq!(usm.username, "admin");
400                assert_eq!(usm.auth_protocol, Some(AuthProtocol::Sha256));
401                assert_eq!(usm.auth_password, Some("authpass".to_string()));
402                assert_eq!(usm.priv_protocol, Some(PrivProtocol::Aes128));
403                assert_eq!(usm.priv_password, Some("privpass".to_string()));
404            }
405            _ => panic!("expected Usm variant"),
406        }
407    }
408
409    #[test]
410    fn test_usm_with_context_name() {
411        let auth: Auth = Auth::usm("admin")
412            .auth(AuthProtocol::Sha256, "authpass")
413            .context_name("vlan100")
414            .into();
415        match auth {
416            Auth::Usm(usm) => {
417                assert_eq!(usm.username, "admin");
418                assert_eq!(usm.context_name, Some("vlan100".to_string()));
419            }
420            _ => panic!("expected Usm variant"),
421        }
422    }
423
424    #[test]
425    fn test_usm_builder_chaining() {
426        // Verify all methods can be chained
427        let auth: Auth = Auth::usm("user")
428            .auth(AuthProtocol::Sha512, "auth")
429            .privacy(PrivProtocol::Aes256, "priv")
430            .context_name("ctx")
431            .into();
432
433        match auth {
434            Auth::Usm(usm) => {
435                assert_eq!(usm.username, "user");
436                assert_eq!(usm.auth_protocol, Some(AuthProtocol::Sha512));
437                assert_eq!(usm.auth_password, Some("auth".to_string()));
438                assert_eq!(usm.priv_protocol, Some(PrivProtocol::Aes256));
439                assert_eq!(usm.priv_password, Some("priv".to_string()));
440                assert_eq!(usm.context_name, Some("ctx".to_string()));
441            }
442            _ => panic!("expected Usm variant"),
443        }
444    }
445}
async_snmp/client/auth.rs

async_snmp/client/
auth.rs
