0
# Authentication and Security
1

2
PySNMP provides comprehensive authentication and security features supporting SNMP v1/v2c community-based authentication and SNMPv3 User-based Security Model (USM) with multiple authentication and privacy protocols.
3

4
## Capabilities
5

6
### Community-Based Authentication (SNMP v1/v2c)
7

8
Simple community string authentication for SNMP v1 and v2c protocols.
9

10
```python { .api }
11
class CommunityData:
12
    def __init__(
13
        self,
14
        communityIndex: str,
15
        communityName: str | None = None,
16
        mpModel: int | None = None,
17
        contextEngineId: bytes | None = None,
18
        contextName: bytes | None = None,
19
        tag: str | None = None,
20
        securityName: str | None = None
21
    ):
22
        """
23
        Create SNMP v1/v2c community data configuration.
24
        
25
        Parameters:
26
        - communityIndex: Unique community index or community name if single parameter
27
        - communityName: SNMP community string (defaults to communityIndex)
28
        - mpModel: SNMP version (0 for v1, 1 for v2c, defaults to v2c)
29
        - contextEngineId: SNMP context engine identifier
30
        - contextName: SNMP context name
31
        - tag: Transport tag for endpoint selection
32
        - securityName: Security name (defaults to communityIndex)
33
        """
34
    
35
    def clone(self, **kwargs) -> CommunityData:
36
        """
37
        Create a copy with modified parameters.
38
        
39
        Parameters:
40
        - kwargs: Parameters to modify
41
        
42
        Returns:
43
        Modified CommunityData instance
44
        """
45
```
46

47
Usage Examples:
48

49
```python
50
from pysnmp.hlapi.v3arch.asyncio import CommunityData
51

52
# Simple community string (defaults to SNMPv2c)
53
community = CommunityData('public')
54

55
# SNMPv1 community
56
community_v1 = CommunityData('public', mpModel=0)
57

58
# SNMPv2c with explicit parameters
59
community_v2c = CommunityData('monitoring', 
60
                             communityName='community123',
61
                             mpModel=1)
62

63
# Copy with modifications
64
private_community = community.clone(communityName='private')
65
```
66

67
### User-Based Security Model (SNMPv3)
68

69
Advanced authentication and privacy capabilities for SNMPv3 with multiple cryptographic protocols.
70

71
```python { .api }
72
class UsmUserData:
73
    def __init__(
74
        self,
75
        userName: str,
76
        authKey: str | bytes | None = None,
77
        privKey: str | bytes | None = None,
78
        authProtocol: int | None = None,
79
        privProtocol: int | None = None,
80
        securityEngineId: bytes | None = None,
81
        securityName: str | None = None,
82
        authKeyType: int = USM_KEY_TYPE_PASSPHRASE,
83
        privKeyType: int = USM_KEY_TYPE_PASSPHRASE
84
    ):
85
        """
86
        Create SNMPv3 User-based Security Model configuration.
87
        
88
        Parameters:
89
        - userName: USM user name
90
        - authKey: Authentication key/passphrase
91
        - privKey: Privacy key/passphrase  
92
        - authProtocol: Authentication protocol identifier
93
        - privProtocol: Privacy protocol identifier
94
        - securityEngineId: Authoritative SNMP engine ID
95
        - securityName: Security name (defaults to userName)
96
        - authKeyType: Authentication key material type
97
        - privKeyType: Privacy key material type
98
        """
99
    
100
    def clone(self, **kwargs) -> UsmUserData:
101
        """
102
        Create a copy with modified parameters.
103
        
104
        Parameters:
105
        - kwargs: Parameters to modify
106
        
107
        Returns:
108
        Modified UsmUserData instance
109
        """
110
```
111

112
Usage Examples:
113

114
```python
115
from pysnmp.hlapi.v3arch.asyncio import (
116
    UsmUserData, USM_AUTH_HMAC96_SHA, USM_PRIV_CFB128_AES
117
)
118

119
# No authentication or privacy (not recommended)
120
user_noauth = UsmUserData('testuser')
121

122
# Authentication only
123
user_auth = UsmUserData('testuser', 
124
                       authKey='myauthpassword',
125
                       authProtocol=USM_AUTH_HMAC96_SHA)
126

127
# Authentication and privacy
128
user_authpriv = UsmUserData('testuser',
129
                           authKey='myauthpassword',
130
                           privKey='myprivpassword', 
131
                           authProtocol=USM_AUTH_HMAC96_SHA,
132
                           privProtocol=USM_PRIV_CFB128_AES)
133

134
# Using master keys instead of passphrases
135
user_master = UsmUserData('testuser',
136
                         authKey=b'\\x12\\x34\\x56\\x78',
137
                         authProtocol=USM_AUTH_HMAC96_SHA,
138
                         authKeyType=USM_KEY_TYPE_MASTER)
139
```
140

141
## Authentication Protocols
142

143
### Authentication Protocol Constants
144

145
```python { .api }
146
USM_AUTH_NONE: int
147
"""No Authentication Protocol"""
148

149
USM_AUTH_HMAC96_MD5: int  
150
"""HMAC-MD5-96 Digest Authentication Protocol (RFC 3414)"""
151

152
USM_AUTH_HMAC96_SHA: int
153
"""HMAC-SHA-96 Digest Authentication Protocol / SHA-1 (RFC 3414)"""
154

155
USM_AUTH_HMAC128_SHA224: int
156
"""HMAC-SHA-2 SHA-224 Digest Authentication Protocol (RFC 7860)"""
157

158
USM_AUTH_HMAC192_SHA256: int
159
"""HMAC-SHA-2 SHA-256 Digest Authentication Protocol (RFC 7860)"""
160

161
USM_AUTH_HMAC256_SHA384: int
162
"""HMAC-SHA-2 SHA-384 Digest Authentication Protocol (RFC 7860)"""
163

164
USM_AUTH_HMAC384_SHA512: int
165
"""HMAC-SHA-2 SHA-512 Digest Authentication Protocol (RFC 7860)"""
166
```
167

168
### Backward-Compatible Authentication Constants
169

170
For compatibility with older code, legacy protocol identifiers are available:
171

172
```python { .api }
173
usmNoAuthProtocol: int
174
usmHMACMD5AuthProtocol: int
175
usmHMACSHAAuthProtocol: int
176
usmHMAC128SHA224AuthProtocol: int
177
usmHMAC192SHA256AuthProtocol: int
178
usmHMAC256SHA384AuthProtocol: int
179
usmHMAC384SHA512AuthProtocol: int
180
```
181

182
**Note**: These constants are deprecated. Use the `USM_AUTH_*` variants instead.
183

184
## Privacy Protocols
185

186
### Privacy Protocol Constants
187

188
```python { .api }
189
USM_PRIV_NONE: int
190
"""No Privacy Protocol"""
191

192
USM_PRIV_CBC56_DES: int
193
"""CBC-DES Symmetric Encryption Protocol (RFC 3414)"""
194

195
USM_PRIV_CBC168_3DES: int
196
"""3DES-EDE Symmetric Encryption Protocol (draft-reeder-snmpv3-usm-3desede-00)"""
197

198
USM_PRIV_CFB128_AES: int
199
"""CFB128-AES-128 Symmetric Encryption Protocol (RFC 3826)"""
200

201
USM_PRIV_CFB192_AES: int
202
"""CFB128-AES-192 Symmetric Encryption Protocol with Reeder key localization (AES-192-Cisco)"""
203

204
USM_PRIV_CFB256_AES: int
205
"""CFB128-AES-256 Symmetric Encryption Protocol with Reeder key localization (AES-256-Cisco)"""
206

207
USM_PRIV_CFB192_AES_BLUMENTHAL: int
208
"""CFB128-AES-192 Symmetric Encryption Protocol (draft-blumenthal-aes-usm-04)"""
209

210
USM_PRIV_CFB256_AES_BLUMENTHAL: int
211
"""CFB128-AES-256 Symmetric Encryption Protocol (draft-blumenthal-aes-usm-04)"""
212
```
213

214
### Backward-Compatible Privacy Constants
215

216
For compatibility with older code, legacy protocol identifiers are available:
217

218
```python { .api }
219
usmNoPrivProtocol: int
220
usmDESPrivProtocol: int
221
usm3DESEDEPrivProtocol: int
222
usmAesCfb128Protocol: int
223
usmAesCfb192Protocol: int
224
usmAesCfb256Protocol: int
225
usmAesBlumenthalCfb192Protocol: int
226
usmAesBlumenthalCfb256Protocol: int
227
```
228

229
**Note**: These constants are deprecated. Use the `USM_PRIV_*` variants instead.
230

231
## Key Material Types
232

233
### Key Type Constants
234

235
```python { .api }
236
USM_KEY_TYPE_PASSPHRASE: int
237
"""USM key material type - plain-text pass phrase (RFC 3414)"""
238

239
USM_KEY_TYPE_MASTER: int
240
"""USM key material type - hashed pass-phrase AKA master key (RFC 3414)"""
241

242
USM_KEY_TYPE_LOCALIZED: int
243
"""USM key material type - localized key (hashed with Context SNMP Engine ID) (RFC 3414)"""
244
```
245

246
### Backward-Compatible Key Type Constants
247

248
```python { .api }
249
usmKeyTypePassphrase: int
250
usmKeyTypeMaster: int
251
usmKeyTypeLocalized: int
252
```
253

254
**Note**: These constants are deprecated. Use the `USM_KEY_TYPE_*` variants instead.
255

256
## Security Configuration Examples
257

258
### SNMPv3 Security Levels
259

260
```python
261
from pysnmp.hlapi.v3arch.asyncio import *
262

263
# No authentication, no privacy (noAuthNoPriv)
264
user_none = UsmUserData('testuser')
265

266
# Authentication only (authNoPriv)
267
user_auth = UsmUserData('testuser',
268
                       authKey='mypassword',
269
                       authProtocol=USM_AUTH_HMAC96_SHA)
270

271
# Authentication and privacy (authPriv) 
272
user_full = UsmUserData('testuser',
273
                       authKey='myauthpassword',
274
                       privKey='myprivpassword',
275
                       authProtocol=USM_AUTH_HMAC96_SHA,
276
                       privProtocol=USM_PRIV_CFB128_AES)
277
```
278

279
### Different Authentication Algorithms
280

281
```python
282
from pysnmp.hlapi.v3arch.asyncio import *
283

284
# MD5 authentication (less secure, avoid if possible)
285
user_md5 = UsmUserData('user1',
286
                      authKey='password123',
287
                      authProtocol=USM_AUTH_HMAC96_MD5)
288

289
# SHA-1 authentication  
290
user_sha1 = UsmUserData('user2',
291
                       authKey='password123',
292
                       authProtocol=USM_AUTH_HMAC96_SHA)
293

294
# SHA-256 authentication (recommended)
295
user_sha256 = UsmUserData('user3',
296
                         authKey='password123',
297
                         authProtocol=USM_AUTH_HMAC192_SHA256)
298

299
# SHA-512 authentication (highest security)
300
user_sha512 = UsmUserData('user4',
301
                         authKey='password123',
302
                         authProtocol=USM_AUTH_HMAC384_SHA512)
303
```
304

305
### Different Privacy Algorithms
306

307
```python
308
from pysnmp.hlapi.v3arch.asyncio import *
309

310
# DES encryption (legacy, avoid if possible)
311
user_des = UsmUserData('user1',
312
                      authKey='authpass',
313
                      privKey='privpass',
314
                      authProtocol=USM_AUTH_HMAC96_SHA,
315
                      privProtocol=USM_PRIV_CBC56_DES)
316

317
# 3DES encryption
318
user_3des = UsmUserData('user2',
319
                       authKey='authpass',
320
                       privKey='privpass',
321
                       authProtocol=USM_AUTH_HMAC96_SHA,
322
                       privProtocol=USM_PRIV_CBC168_3DES)
323

324
# AES-128 encryption (recommended)
325
user_aes128 = UsmUserData('user3',
326
                         authKey='authpass',
327
                         privKey='privpass',
328
                         authProtocol=USM_AUTH_HMAC96_SHA,
329
                         privProtocol=USM_PRIV_CFB128_AES)
330

331
# AES-256 encryption (highest security)
332
user_aes256 = UsmUserData('user4',
333
                         authKey='authpass',
334
                         privKey='privpass',
335
                         authProtocol=USM_AUTH_HMAC192_SHA256,
336
                         privProtocol=USM_PRIV_CFB256_AES)
337
```
338

339
### Using Pre-computed Keys
340

341
For performance or security reasons, you may want to use pre-computed master or localized keys:
342

343
```python
344
from pysnmp.hlapi.v3arch.asyncio import *
345

346
# Using master key (pre-hashed passphrase)
347
user_master = UsmUserData('testuser',
348
                         authKey=bytes.fromhex('0123456789abcdef0123456789abcdef'),
349
                         authProtocol=USM_AUTH_HMAC96_MD5,
350
                         authKeyType=USM_KEY_TYPE_MASTER)
351

352
# Using localized key (master key localized to engine ID)
353
user_localized = UsmUserData('testuser',
354
                            authKey=bytes.fromhex('fedcba9876543210fedcba9876543210'),
355
                            authProtocol=USM_AUTH_HMAC96_MD5,
356
                            authKeyType=USM_KEY_TYPE_LOCALIZED,
357
                            securityEngineId=bytes.fromhex('80001f8880e9630000d61ff449'))
358
```
359

360
## Complete Authentication Examples
361

362
### SNMPv2c with Community
363

364
```python
365
import asyncio
366
from pysnmp.hlapi.v3arch.asyncio import *
367

368
async def snmpv2c_example():
369
    errorIndication, errorStatus, errorIndex, varBinds = await get_cmd(
370
        SnmpEngine(),
371
        CommunityData('public'),  # Community string
372
        await UdpTransportTarget.create(('demo.pysnmp.com', 161)),
373
        ContextData(),
374
        ObjectType(ObjectIdentity('1.3.6.1.2.1.1.1.0'))  # sysDescr
375
    )
376
    
377
    if not errorIndication and not errorStatus:
378
        for varBind in varBinds:
379
            print(f"{varBind[0]} = {varBind[1]}")
380

381
asyncio.run(snmpv2c_example())
382
```
383

384
### SNMPv3 with Authentication and Privacy
385

386
```python
387
import asyncio
388
from pysnmp.hlapi.v3arch.asyncio import *
389

390
async def snmpv3_authpriv_example():
391
    errorIndication, errorStatus, errorIndex, varBinds = await get_cmd(
392
        SnmpEngine(),
393
        UsmUserData('testuser',
394
                   authKey='myauthpassphrase',
395
                   privKey='myprivacypassphrase',
396
                   authProtocol=USM_AUTH_HMAC192_SHA256,
397
                   privProtocol=USM_PRIV_CFB128_AES),
398
        await UdpTransportTarget.create(('demo.pysnmp.com', 161)),
399
        ContextData(),
400
        ObjectType(ObjectIdentity('1.3.6.1.2.1.1.1.0'))  # sysDescr
401
    )
402
    
403
    if not errorIndication and not errorStatus:
404
        for varBind in varBinds:
405
            print(f"{varBind[0]} = {varBind[1]}")
406

407
asyncio.run(snmpv3_authpriv_example())
408
```