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").unwrap()
17//!     .with_privacy(PrivProtocol::Aes128, b"privpassword").unwrap();
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.
157#[derive(Debug)]
158pub struct UsmBuilder {
159    username: String,
160    auth: Option<(AuthProtocol, String)>,
161    privacy: Option<(PrivProtocol, String)>,
162    context_name: Option<String>,
163    master_keys: Option<MasterKeys>,
164}
165
166impl UsmBuilder {
167    /// Create a new USM builder with the given username.
168    ///
169    /// # Example
170    ///
171    /// ```rust
172    /// use async_snmp::Auth;
173    ///
174    /// let builder = Auth::usm("admin");
175    /// ```
176    pub fn new(username: impl Into<String>) -> Self {
177        Self {
178            username: username.into(),
179            auth: None,
180            privacy: None,
181            context_name: None,
182            master_keys: None,
183        }
184    }
185
186    /// Add authentication (authNoPriv or authPriv).
187    ///
188    /// This method performs the full key derivation (~850us for SHA-256) when
189    /// the client connects. When polling many engines with shared credentials,
190    /// consider using [`with_master_keys`](Self::with_master_keys) instead.
191    ///
192    /// # Supported Protocols
193    ///
194    /// - `AuthProtocol::Md5` - HMAC-MD5-96 (legacy)
195    /// - `AuthProtocol::Sha1` - HMAC-SHA-96 (legacy)
196    /// - `AuthProtocol::Sha224` - HMAC-SHA-224
197    /// - `AuthProtocol::Sha256` - HMAC-SHA-256
198    /// - `AuthProtocol::Sha384` - HMAC-SHA-384
199    /// - `AuthProtocol::Sha512` - HMAC-SHA-512
200    ///
201    /// # Example
202    ///
203    /// ```rust
204    /// use async_snmp::{Auth, AuthProtocol};
205    ///
206    /// let auth: Auth = Auth::usm("admin")
207    ///     .auth(AuthProtocol::Sha256, "mypassword")
208    ///     .into();
209    /// ```
210    pub fn auth(mut self, protocol: AuthProtocol, password: impl Into<String>) -> Self {
211        self.auth = Some((protocol, password.into()));
212        self
213    }
214
215    /// Add privacy/encryption (authPriv).
216    ///
217    /// Privacy requires authentication; this is validated at connection time.
218    ///
219    /// # Supported Protocols
220    ///
221    /// - `PrivProtocol::Des` - DES-CBC (legacy, insecure)
222    /// - `PrivProtocol::Aes128` - AES-128-CFB
223    /// - `PrivProtocol::Aes192` - AES-192-CFB
224    /// - `PrivProtocol::Aes256` - AES-256-CFB
225    ///
226    /// # Example
227    ///
228    /// ```rust
229    /// use async_snmp::{Auth, AuthProtocol, PrivProtocol};
230    ///
231    /// let auth: Auth = Auth::usm("admin")
232    ///     .auth(AuthProtocol::Sha256, "authpassword")
233    ///     .privacy(PrivProtocol::Aes128, "privpassword")
234    ///     .into();
235    /// ```
236    pub fn privacy(mut self, protocol: PrivProtocol, password: impl Into<String>) -> Self {
237        self.privacy = Some((protocol, password.into()));
238        self
239    }
240
241    /// Use pre-computed master keys for authentication and privacy.
242    ///
243    /// This is the efficient path when polling many engines with shared
244    /// credentials. The expensive password-to-key derivation
245    /// (~850μs) is done once when creating the [`MasterKeys`], and only the
246    /// cheap localization (~1μs) is performed per engine.
247    ///
248    /// When master keys are set, the [`auth`](Self::auth) and
249    /// [`privacy`](Self::privacy) methods are ignored.
250    ///
251    /// # Example
252    ///
253    /// ```rust
254    /// use async_snmp::{Auth, AuthProtocol, PrivProtocol, MasterKeys};
255    ///
256    /// // Derive master keys once
257    /// let master_keys = MasterKeys::new(AuthProtocol::Sha256, b"authpassword").unwrap()
258    ///     .with_privacy(PrivProtocol::Aes128, b"privpassword").unwrap();
259    ///
260    /// // Use with multiple clients
261    /// let auth: Auth = Auth::usm("admin")
262    ///     .with_master_keys(master_keys)
263    ///     .into();
264    /// ```
265    pub fn with_master_keys(mut self, master_keys: MasterKeys) -> Self {
266        self.master_keys = Some(master_keys);
267        self
268    }
269
270    /// Set the SNMPv3 context name for VACM context selection.
271    ///
272    /// The context name allows selecting different MIB views on the same agent.
273    /// Most deployments use empty string (default).
274    ///
275    /// # Example
276    ///
277    /// ```rust
278    /// use async_snmp::{Auth, AuthProtocol};
279    ///
280    /// let auth: Auth = Auth::usm("admin")
281    ///     .auth(AuthProtocol::Sha256, "password")
282    ///     .context_name("vlan100")
283    ///     .into();
284    /// ```
285    pub fn context_name(mut self, name: impl Into<String>) -> Self {
286        self.context_name = Some(name.into());
287        self
288    }
289}
290
291impl From<UsmBuilder> for Auth {
292    fn from(b: UsmBuilder) -> Auth {
293        Auth::Usm(UsmAuth {
294            username: b.username,
295            auth_protocol: b
296                .master_keys
297                .as_ref()
298                .map(|m| m.auth_protocol())
299                .or(b.auth.as_ref().map(|(p, _)| *p)),
300            auth_password: b.auth.map(|(_, pw)| pw),
301            priv_protocol: b
302                .master_keys
303                .as_ref()
304                .and_then(|m| m.priv_protocol())
305                .or(b.privacy.as_ref().map(|(p, _)| *p)),
306            priv_password: b.privacy.map(|(_, pw)| pw),
307            context_name: b.context_name,
308            master_keys: b.master_keys,
309        })
310    }
311}
312
313#[cfg(test)]
314mod tests {
315    use super::*;
316
317    #[test]
318    fn test_default_auth() {
319        let auth = Auth::default();
320        match auth {
321            Auth::Community { version, community } => {
322                assert_eq!(version, CommunityVersion::V2c);
323                assert_eq!(community, "public");
324            }
325            _ => panic!("expected Community variant"),
326        }
327    }
328
329    #[test]
330    fn test_v1_auth() {
331        let auth = Auth::v1("private");
332        match auth {
333            Auth::Community { version, community } => {
334                assert_eq!(version, CommunityVersion::V1);
335                assert_eq!(community, "private");
336            }
337            _ => panic!("expected Community variant"),
338        }
339    }
340
341    #[test]
342    fn test_v2c_auth() {
343        let auth = Auth::v2c("secret");
344        match auth {
345            Auth::Community { version, community } => {
346                assert_eq!(version, CommunityVersion::V2c);
347                assert_eq!(community, "secret");
348            }
349            _ => panic!("expected Community variant"),
350        }
351    }
352
353    #[test]
354    fn test_community_version_default() {
355        let version = CommunityVersion::default();
356        assert_eq!(version, CommunityVersion::V2c);
357    }
358
359    #[test]
360    fn test_usm_no_auth_no_priv() {
361        let auth: Auth = Auth::usm("readonly").into();
362        match auth {
363            Auth::Usm(usm) => {
364                assert_eq!(usm.username, "readonly");
365                assert!(usm.auth_protocol.is_none());
366                assert!(usm.auth_password.is_none());
367                assert!(usm.priv_protocol.is_none());
368                assert!(usm.priv_password.is_none());
369                assert!(usm.context_name.is_none());
370            }
371            _ => panic!("expected Usm variant"),
372        }
373    }
374
375    #[test]
376    fn test_usm_auth_no_priv() {
377        let auth: Auth = Auth::usm("admin")
378            .auth(AuthProtocol::Sha256, "authpass123")
379            .into();
380        match auth {
381            Auth::Usm(usm) => {
382                assert_eq!(usm.username, "admin");
383                assert_eq!(usm.auth_protocol, Some(AuthProtocol::Sha256));
384                assert_eq!(usm.auth_password, Some("authpass123".to_string()));
385                assert!(usm.priv_protocol.is_none());
386                assert!(usm.priv_password.is_none());
387            }
388            _ => panic!("expected Usm variant"),
389        }
390    }
391
392    #[test]
393    fn test_usm_auth_priv() {
394        let auth: Auth = Auth::usm("admin")
395            .auth(AuthProtocol::Sha256, "authpass")
396            .privacy(PrivProtocol::Aes128, "privpass")
397            .into();
398        match auth {
399            Auth::Usm(usm) => {
400                assert_eq!(usm.username, "admin");
401                assert_eq!(usm.auth_protocol, Some(AuthProtocol::Sha256));
402                assert_eq!(usm.auth_password, Some("authpass".to_string()));
403                assert_eq!(usm.priv_protocol, Some(PrivProtocol::Aes128));
404                assert_eq!(usm.priv_password, Some("privpass".to_string()));
405            }
406            _ => panic!("expected Usm variant"),
407        }
408    }
409
410    #[test]
411    fn test_usm_with_context_name() {
412        let auth: Auth = Auth::usm("admin")
413            .auth(AuthProtocol::Sha256, "authpass")
414            .context_name("vlan100")
415            .into();
416        match auth {
417            Auth::Usm(usm) => {
418                assert_eq!(usm.username, "admin");
419                assert_eq!(usm.context_name, Some("vlan100".to_string()));
420            }
421            _ => panic!("expected Usm variant"),
422        }
423    }
424
425    #[test]
426    fn test_usm_builder_chaining() {
427        // Verify all methods can be chained
428        let auth: Auth = Auth::usm("user")
429            .auth(AuthProtocol::Sha512, "auth")
430            .privacy(PrivProtocol::Aes256, "priv")
431            .context_name("ctx")
432            .into();
433
434        match auth {
435            Auth::Usm(usm) => {
436                assert_eq!(usm.username, "user");
437                assert_eq!(usm.auth_protocol, Some(AuthProtocol::Sha512));
438                assert_eq!(usm.auth_password, Some("auth".to_string()));
439                assert_eq!(usm.priv_protocol, Some(PrivProtocol::Aes256));
440                assert_eq!(usm.priv_password, Some("priv".to_string()));
441                assert_eq!(usm.context_name, Some("ctx".to_string()));
442            }
443            _ => panic!("expected Usm variant"),
444        }
445    }
446}
async_snmp/client/auth.rs

async_snmp/client/
auth.rs
