idnits 2.17.1 draft-ietf-opsawg-tlstm-update-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 64 instances of too long lines in the document, the longest one being 3 characters in excess of 72. -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? -- The draft header indicates that this document updates RFC6353, but the abstract doesn't seem to directly say this. It does mention RFC6353 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (5 March 2022) is 783 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'I-D.ietf-tls-dtls13' is defined on line 1343, but no explicit reference was found in the text == Unused Reference: 'RFC3584' is defined on line 1356, but no explicit reference was found in the text == Unused Reference: 'RFC5591' is defined on line 1368, but no explicit reference was found in the text == Unused Reference: 'STD58' is defined on line 1428, but no explicit reference was found in the text -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force K. Vaughn, Ed. 3 Internet-Draft Trevilon LLC 4 Updates: 6353 (if approved) 5 March 2022 5 Intended status: Standards Track 6 Expires: 6 September 2022 8 Transport Layer Security Version 1.3 (TLS 1.3) Transport Model for the 9 Simple Network Management Protocol Version 3 (SNMPv3) 10 draft-ietf-opsawg-tlstm-update-01 12 Abstract 14 This document updates the TLS Transport Model (TLSTM), as defined in 15 RFC 6353 to support Transport Layer Security Version 1.3 (TLS) and 16 Datagram Transport Layer Security Version 1.3 (DTLS), which are 17 jointly known as "(D)TLS". This document may be applicable to future 18 versions of SNMP and (D)TLS. 20 This document updates the SNMP-TLS-TM-MIB as defined in RFC 6353. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on 6 September 2022. 39 Copyright Notice 41 Copyright (c) 2022 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 46 license-info) in effect on the date of publication of this document. 47 Please review these documents carefully, as they describe your rights 48 and restrictions with respect to this document. Code Components 49 extracted from this document must include Revised BSD License text as 50 described in Section 4.e of the Trust Legal Provisions and are 51 provided without warranty as described in the Revised BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Conventions . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Changes from RFC 6353 . . . . . . . . . . . . . . . . . . . . 4 58 2.1. TLSTM Fingerprint . . . . . . . . . . . . . . . . . . . . 4 59 2.2. Security Level . . . . . . . . . . . . . . . . . . . . . 4 60 2.3. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 5 61 3. Additional Rules for TLS 1.3 . . . . . . . . . . . . . . . . 5 62 3.1. Zero Round Trip Time Resumption (0-RTT) . . . . . . . . . 5 63 3.2. TLS ciphersuites, extensions and protocol invariants . . 6 64 4. MIB Module Definition . . . . . . . . . . . . . . . . . . . . 6 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . 28 66 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 67 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 29 68 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 69 8.1. Normative References . . . . . . . . . . . . . . . . . . 29 70 8.2. Informative References . . . . . . . . . . . . . . . . . 30 71 Appendix A. Target and Notification Configuration Example . . . 31 72 A.1. Configuring a Notification Originator . . . . . . . . . . 31 73 A.2. Configuring TLSTM to Utilize a Simple Derivation of 74 tmSecurityName . . . . . . . . . . . . . . . . . . . . . 32 75 A.3. Configuring TLSTM to Utilize Table-Driven Certificate 76 Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 32 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 33 79 1. Introduction 81 This document updates and clarifies how the rules of [RFC6353] apply 82 when using Transport Layer Security Version 1.3 (TLS) or Datagram 83 Transport Layer Security Version 1.3 (DTLS), which are jointly known 84 as "(D)TLS". The update also incorporates the [RFC8996] update, 85 which prohibits the use of TLS versions prior to TLS 1.2. Although 86 the title and text of this document specifically reference SNMPv3 and 87 (D)TLS 1.3, this document may be applicable to future versions of 88 these protocols and is backwards compatible with (D)TLS 1.2. 90 1.1. Conventions 92 Within this document the terms "TLS", "DTLS", "(D)TLS", "SNMP", and 93 "TLSTM" mean "TLS 1.3", "DTLS 1.3", "TLS 1.3 and/or DTLS 1.3", 94 "SMNPv3", and "TLSTM 1.3", respectively. These version numbers are 95 only used when the text needs to emphasize version numbers, such as 96 within the title. When this document refers to any other version of 97 these protocols, it always explicitly states the version intended. 99 For consistency with SNMP-related specifications, this document 100 favors terminology as defined in [STD62], rather than favoring 101 terminology that is consistent with non-SNMP specifications. This is 102 consistent with the IESG decision to not require the SNMPv3 103 terminology be modified to match the usage of other non-SNMP 104 specifications when SNMPv3 was advanced to a Full Standard. 105 "Authentication" in this document typically refers to the English 106 meaning of "serving to prove the authenticity of" the message, not 107 data source authentication or peer identity authentication. The 108 terms "manager" and "agent" are not used in this document because, in 109 the RFC3411 architecture, all SNMP entities have the capability of 110 acting as manager, agent, or both depending on the SNMP application 111 types supported in the implementation. Where distinction is 112 necessary, the application names of command generator, command 113 responder, notification originator, notification receiver, and proxy 114 forwarder are used. See "SNMP Applications" (RFC3411) for further 115 information. 117 Throughout this document, the terms "client" and "server" are used to 118 refer to the two ends of the TLS transport connection. The client 119 actively opens the TLS connection, and the server passively listens 120 for the incoming TLS connection. An SNMP entity MAY act as a TLS 121 client or server or both, depending on the SNMP applications 122 supported. 124 While TLS frequently refers to a user, the terminology preferred in 125 RFC3411 and in this memo is "principal". A principal is the "who" on 126 whose behalf services are provided or processing takes place. A 127 principal can be, among other things, an individual acting in a 128 particular role; a set of individuals, with each acting in a 129 particular role; an application or a set of applications, or a 130 combination of these within an administrative domain. 132 Throughout this document, the term "session" is used to refer to a 133 secure association between two TLS Transport Models that permits the 134 transmission of one or more SNMP messages within the lifetime of the 135 session. The TLS protocol also has an internal notion of a session 136 and although these two concepts of a session are related, when the 137 term "session" is used this document is referring to the TLSTM's 138 specific session and not directly to the TLS protocol's session. 140 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 141 "SHOULD", "SHOULD NOT", "RECOMMENDED", NOT RECOMMENDED, "MAY", and 142 "OPTIONAL" in this document are to be interpreted as described in 143 [RFC2119]. 145 2. Changes from RFC 6353 147 This document updates [RFC6353]. The changes from [RFC6353] are 148 defined in the following clauses. 150 2.1. TLSTM Fingerprint 152 [RFC6353] defines a fingerprint algorithm that references the one- 153 octet TLS 1.2 hash algorithm identifier. TLS 1.3 replaced the one- 154 octet hash algorithm identifier with a two-octet TLS 1.3 cipher suite 155 identifier. The TLS 1.3 cipher suite still includes a hashing 156 algorithm but new hashing algorithms (e.g., for use in TLS 1.3) will 157 not be assigned values in the IANA TLS HashAlgorithm Registry, as 158 defined in RFC 5246. 160 This document updates the definition of SnmpTLSFingerprint to clarify 161 that the one-octet identifier in the fingerprint algorithm uses a 162 registry that is consistent with the IANA TLS HashAlgorithm Registry 163 for its initial values but one that can be extended to support new 164 hashing algorithms that might be used for TLS versions after version 165 1.2. This change allows the reuse of the existing fingerprint 166 TEXTUAL-CONVENTION and minimizes the impact to RFC 6353. 168 2.2. Security Level 170 The RFC3411 architecture recognizes three levels of security: 172 * without authentication and without privacy (noAuthNoPriv) 174 * with authentication but without privacy (authNoPriv) 176 * with authentication and with privacy (authPriv) 177 With (D)TLS 1.3, authentication and privacy are always provided. 178 Hence, all exchanges conforming to the rules of this document will 179 include authentication and privacy, regardless of the security level 180 requested. 181 // This is consistent with what was prescribed in RFC6353, where a 182 // TLS Transport Model is expected to provide for outgoing 183 // connections with a security level at least that of the requested 184 // security level. 186 2.3. TLS Version 188 [RFC6353] stated that TLSTM clients and servers MUST NOT request, 189 offer, or use SSL 2.0. [RFC8996] prohibits the use of (D)TLS 190 versions prior to version 1.2. TLSTMv1.3 MUST only be used with 191 (D)TLS version 1.2 and later. 193 3. Additional Rules for TLS 1.3 195 This document specifies additional rules and clarifications for the 196 use of TLS 1.3. 198 3.1. Zero Round Trip Time Resumption (0-RTT) 200 TLS 1.3 implementations for SNMPv3 MUST NOT enable the 0-RTT mode of 201 session resumption (either sending or accepting) and MUST NOT 202 automatically resend 0-RTT data if it is rejected by the server. The 203 reason 0-RTT is disallowed is that there are no "safe" messages that 204 if replayed will be guaranteed to cause no harm at a server side: all 205 incoming notification or command responses are meant to be acted upon 206 only once. See Security considerations section for further details. 208 TLS TM clients and servers MUST NOT request, offer or use the 0-RTT 209 mode of TLS 1.3. [RFC8446] removed the renegotiation supported in 210 TLS 1.2 [RFC5246]; for session resumption, it introduced a zero-RTT 211 (0-RTT) mode, saving a round-trip at connection setup at the cost of 212 increased risk of replay attacks (it is possible for servers to guard 213 against this attack by keeping track of all the messages received). 214 [RFC8446] requires a profile be written for any application that 215 wants to use 0-RTT, specifying which messages are "safe to use" on 216 this mode. The reason 0-RTT is disallowed here is that there are no 217 "safe" SNMPv3 messages that if replayed will be sure to cause no harm 218 at a server side: all incoming notification or command responses have 219 consequences and are to be acted upon only once. 221 Renegotiation of sessions is not supported as it is not supported by 222 TLS 1.3. 224 3.2. TLS ciphersuites, extensions and protocol invariants 226 [RFC8446] section 9 requires that, in the absence of application 227 profiles, certain cipher suites, TLS extensions, and TLS protocol 228 invariants are mandatory to implement. This document does not 229 specify an application profile, hence all of the compliance 230 requirements in [RFC8446] apply. 232 4. MIB Module Definition 234 SNMP-TLS-TM-MIB DEFINITIONS ::= BEGIN 236 IMPORTS 237 MODULE-IDENTITY, OBJECT-TYPE, 238 OBJECT-IDENTITY, mib-2, snmpDomains, 239 Counter32, Unsigned32, Gauge32, NOTIFICATION-TYPE 240 FROM SNMPv2-SMI -- RFC 2578 or any update thereof 241 TEXTUAL-CONVENTION, TimeStamp, RowStatus, StorageType, 242 AutonomousType 243 FROM SNMPv2-TC -- RFC 2579 or any update thereof 244 MODULE-COMPLIANCE, OBJECT-GROUP, NOTIFICATION-GROUP 245 FROM SNMPv2-CONF -- RFC 2580 or any update thereof 246 SnmpAdminString 247 FROM SNMP-FRAMEWORK-MIB -- RFC 3411 or any update thereof 248 snmpTargetParamsName, snmpTargetAddrName 249 FROM SNMP-TARGET-MIB -- RFC 3413 or any update thereof 250 ; 252 snmpTlstmMIB MODULE-IDENTITY 253 LAST-UPDATED "202203050000Z" 255 ORGANIZATION "OPSA Working Group" 256 CONTACT-INFO "WG-EMail: opsawg@ietf.org 257 Mailing list subscription info: 258 https://www.ietf.org/mailman/listinfo/opsawg 260 Kenneth Vaughn 261 Trevilon LLC 262 6606 FM 1488 RD, STE 503 263 Magnolia, TX 77354 264 United States 265 Phone: +1 571 331 5670 266 Email: kvaughn@trevilon.com" 267 DESCRIPTION " 268 The TLS Transport Model MIB 270 Copyright (c) 2010-2022 IETF Trust and the persons identified 271 as authors of the code. All rights reserved. 273 Redistribution and use in source and binary forms, with or 274 without modification, is permitted pursuant to, and subject 275 to the license terms contained in, the Revised BSD License 276 set forth in Section 4.c of the IETF Trust's Legal Provisions 277 Relating to IETF Documents 278 (http://trustee.ietf.org/license-info)." 280 REVISION "202203050000Z" 281 DESCRIPTION "This version of this MIB module is part of 282 RFC XXXX; see the RFC itself for full legal 283 notices. This version: 284 1. Updates the definition of SnmpTLSFingerprint 285 to clarify the registry used for the one-octet 286 hash algorithm identifier. 287 2. Capitalizes key words in conformance with 288 BCP 14 289 3. Replaces 'may not' with 'MUST NOT' to clarify 290 intent in several locations." 292 REVISION "201107190000Z" 293 DESCRIPTION "This version of this MIB module is part of 294 RFC 6353; see the RFC itself for full legal 295 notices. The only change was to introduce 296 new wording to reflect require changes for 297 IDNA addresses in the SnmpTLSAddress TC." 299 REVISION "201005070000Z" 300 DESCRIPTION "This version of this MIB module is part of 301 RFC 5953; see the RFC itself for full legal 302 notices." 303 ::= { mib-2 198 } 305 -- ************************************************ 306 -- subtrees of the SNMP-TLS-TM-MIB 307 -- ************************************************ 309 snmpTlstmNotifications OBJECT IDENTIFIER ::= { snmpTlstmMIB 0 } 310 snmpTlstmIdentities OBJECT IDENTIFIER ::= { snmpTlstmMIB 1 } 311 snmpTlstmObjects OBJECT IDENTIFIER ::= { snmpTlstmMIB 2 } 312 snmpTlstmConformance OBJECT IDENTIFIER ::= { snmpTlstmMIB 3 } 314 -- ************************************************ 315 -- snmpTlstmObjects - Objects 316 -- ************************************************ 318 snmpTLSTCPDomain OBJECT-IDENTITY 319 STATUS current 320 DESCRIPTION 321 "The SNMP over TLS via TCP transport domain. The 322 corresponding transport address is of type SnmpTLSAddress. 324 The securityName prefix to be associated with the 325 snmpTLSTCPDomain is 'tls'. This prefix MAY be used by 326 security models or other components to identify which secure 327 transport infrastructure authenticated a securityName." 328 REFERENCE 329 "RFC 2579: Textual Conventions for SMIv2" 330 ::= { snmpDomains 8 } 332 snmpDTLSUDPDomain OBJECT-IDENTITY 333 STATUS current 334 DESCRIPTION 335 "The SNMP over DTLS via UDP transport domain. The 336 corresponding transport address is of type SnmpTLSAddress. 338 The securityName prefix to be associated with the 339 snmpDTLSUDPDomain is 'dtls'. This prefix MAY be used by 340 security models or other components to identify which secure 341 transport infrastructure authenticated a securityName." 342 REFERENCE 343 "RFC 2579: Textual Conventions for SMIv2" 344 ::= { snmpDomains 9 } 346 SnmpTLSAddress ::= TEXTUAL-CONVENTION 347 DISPLAY-HINT "1a" 348 STATUS current 349 DESCRIPTION 350 "Represents an IPv4 address, an IPv6 address, or a 351 US-ASCII-encoded hostname and port number. 353 An IPv4 address MUST be in dotted decimal format followed by a 354 colon ':' (US-ASCII character 0x3A) and a decimal port number 355 in US-ASCII. 357 An IPv6 address MUST be a colon-separated format (as described 358 in RFC 5952), surrounded by square brackets ('[', US-ASCII 359 character 0x5B, and ']', US-ASCII character 0x5D), followed by 360 a colon ':' (US-ASCII character 0x3A) and a decimal port number 361 in US-ASCII. 363 A hostname is always in US-ASCII (as per RFC 1123); 364 internationalized hostnames are encoded as A-labels as specified 365 in RFC 5890. The hostname is followed by a 366 colon ':' (US-ASCII character 0x3A) and a decimal port number 367 in US-ASCII. The name SHOULD be fully qualified whenever 368 possible. 370 Values of this textual convention MUST NOT be directly usable 371 as transport-layer addressing information, and may require 372 run-time resolution. As such, applications that write them 373 MUST be prepared for handling errors if such values are not 374 supported, or cannot be resolved (if resolution occurs at the 375 time of the management operation). 377 The DESCRIPTION clause of TransportAddress objects that may 378 have SnmpTLSAddress values MUST fully describe how (and 379 when) such names are to be resolved to IP addresses and vice 380 versa. 382 This textual convention SHOULD NOT be used directly in object 383 definitions since it restricts addresses to a specific 384 format. However, if it is used, it MAY be used either on its 385 own or in conjunction with TransportAddressType or 386 TransportDomain as a pair. 388 When this textual convention is used as a syntax of an index 389 object, there may be issues with the limit of 128 390 sub-identifiers specified in SMIv2 (STD 58). It is RECOMMENDED 391 that all MIB documents using this textual convention make 392 explicit any limitations on index component lengths that 393 management software MUST observe. This MAY be done either by 395 including SIZE constraints on the index components or by 396 specifying applicable constraints in the conceptual row 397 DESCRIPTION clause or in the surrounding documentation." 398 REFERENCE 399 "RFC 1123: Requirements for Internet Hosts - Application and 400 Support 401 RFC 5890: Internationalized Domain Names for Applications (IDNA): 402 Definitions and Document Framework 403 RFC 5952: A Recommendation for IPv6 Address Text Representation 404 " 405 SYNTAX OCTET STRING (SIZE (1..255)) 407 SnmpTLSFingerprint ::= TEXTUAL-CONVENTION 408 DISPLAY-HINT "1x:1x" 409 STATUS current 410 DESCRIPTION 411 "A fingerprint value that can be used to uniquely reference 412 other data of potentially arbitrary length. 414 An SnmpTLSFingerprint value is composed of a 1-octet hashing 415 algorithm identifier followed by the fingerprint value. The 416 octet value encoded is based on the IANA TLS HashAlgorithm 417 Registry (RFC 5246), However, this registry is only applicable 418 to (D)TLS protocol versions prior to 1.3, which are now 419 designated as "obsolete" and are not expected to ever support 420 additional values. To allow the fingerprint algorithm to support 421 additional hashing algorithms that might be used by later 422 versions of (D)TLS, the octet value encoded is taken from IANA 423 SnmpTLSFingerprintAlgorithm Registry, The initial values within 424 this registry are identical to the values in the TLS 425 HashAlgorithm registry but can be extended to support new 426 hashing algorithms as needed. 428 This TEXTUAL-CONVENTION allows for a zero-length (blank) 429 SnmpTLSFingerprint value for use in tables where the 430 fingerprint value MAY be optional. MIB definitions or 431 implementations MAY refuse to accept a zero-length value as 432 appropriate." 433 REFERENCE "http://www.iana.org/assignments/tlstm-parameters/" 434 SYNTAX OCTET STRING (SIZE (0..255)) 436 -- Identities for use in the snmpTlstmCertToTSNTable 438 snmpTlstmCertToTSNMIdentities OBJECT IDENTIFIER 439 ::= { snmpTlstmIdentities 1 } 441 snmpTlstmCertSpecified OBJECT-IDENTITY 442 STATUS current 443 DESCRIPTION "Directly specifies the tmSecurityName to be used for 444 this certificate. The value of the tmSecurityName 445 to use is specified in the snmpTlstmCertToTSNData 446 column. The snmpTlstmCertToTSNData column MUST 447 contain a non-zero length SnmpAdminString compliant 449 value or the mapping described in this row MUST be 450 considered a failure." 451 ::= { snmpTlstmCertToTSNMIdentities 1 } 453 snmpTlstmCertSANRFC822Name OBJECT-IDENTITY 454 STATUS current 455 DESCRIPTION "Maps a subjectAltName's rfc822Name to a 456 tmSecurityName. The local part of the rfc822Name is 457 passed unaltered but the host-part of the name MUST 458 be passed in lowercase. This mapping results in a 459 1:1 correspondence between equivalent subjectAltName 460 rfc822Name values and tmSecurityName values except 461 that the host-part of the name MUST be passed in 462 lowercase. 464 Example rfc822Name Field: FooBar@Example.COM 465 is mapped to tmSecurityName: FooBar@example.com." 467 ::= { snmpTlstmCertToTSNMIdentities 2 } 469 snmpTlstmCertSANDNSName OBJECT-IDENTITY 470 STATUS current 471 DESCRIPTION "Maps a subjectAltName's dNSName to a 472 tmSecurityName after first converting it to all 473 lowercase (RFC 5280 does not specify converting to 474 lowercase so this involves an extra step). This 475 mapping results in a 1:1 correspondence between 476 subjectAltName dNSName values and the tmSecurityName 477 values." 478 REFERENCE "RFC 5280 - Internet X.509 Public Key Infrastructure 479 Certificate and Certificate Revocation 480 List (CRL) Profile." 481 ::= { snmpTlstmCertToTSNMIdentities 3 } 483 snmpTlstmCertSANIpAddress OBJECT-IDENTITY 484 STATUS current 485 DESCRIPTION "Maps a subjectAltName's iPAddress to a 486 tmSecurityName by transforming the binary encoded 487 address as follows: 489 1) for IPv4, the value is converted into a 490 decimal-dotted quad address (e.g., '192.0.2.1'). 492 2) for IPv6 addresses, the value is converted into a 493 32-character all lowercase hexadecimal string 494 without any colon separators. 496 This mapping results in a 1:1 correspondence between 497 subjectAltName iPAddress values and the 498 tmSecurityName values. 500 The resulting length of an encoded IPv6 address is 501 the maximum length supported by the View-Based 502 Access Control Model (VACM). Using both the 503 Transport Security Model's support for transport 504 prefixes (see the SNMP-TSM-MIB's 505 snmpTsmConfigurationUsePrefix object for details) 506 will result in securityName lengths that exceed what 507 VACM can handle." 508 ::= { snmpTlstmCertToTSNMIdentities 4 } 510 snmpTlstmCertSANAny OBJECT-IDENTITY 511 STATUS current 512 DESCRIPTION "Maps any of the following fields using the 513 corresponding mapping algorithms: 515 |------------+----------------------------| 516 | Type | Algorithm | 517 |------------+----------------------------| 518 | rfc822Name | snmpTlstmCertSANRFC822Name | 519 | dNSName | snmpTlstmCertSANDNSName | 520 | iPAddress | snmpTlstmCertSANIpAddress | 521 |------------+----------------------------| 523 The first matching subjectAltName value found in the 524 certificate of the above types MUST be used when 525 deriving the tmSecurityName. The mapping algorithm 526 specified in the 'Algorithm' column MUST be used to 527 derive the tmSecurityName. 529 This mapping results in a 1:1 correspondence between 530 subjectAltName values and tmSecurityName values. The 531 three sub-mapping algorithms produced by this 532 combined algorithm cannot produce conflicting 533 results between themselves." 534 ::= { snmpTlstmCertToTSNMIdentities 5 } 536 snmpTlstmCertCommonName OBJECT-IDENTITY 537 STATUS current 538 DESCRIPTION "Maps a certificate's CommonName to a tmSecurityName 539 after converting it to a UTF-8 encoding. The usage 540 of CommonNames is deprecated and users are 541 encouraged to use subjectAltName mapping methods 542 instead. This mapping results in a 1:1 544 correspondence between certificate CommonName values 545 and tmSecurityName values." 546 ::= { snmpTlstmCertToTSNMIdentities 6 } 548 -- The snmpTlstmSession Group 550 snmpTlstmSession OBJECT IDENTIFIER ::= { snmpTlstmObjects 1 } 552 snmpTlstmSessionOpens OBJECT-TYPE 553 SYNTAX Counter32 554 MAX-ACCESS read-only 555 STATUS current 556 DESCRIPTION 557 "The number of times an openSession() request has been executed 558 as a (D)TLS client, regardless of whether it succeeded or 559 failed." 560 ::= { snmpTlstmSession 1 } 562 snmpTlstmSessionClientCloses OBJECT-TYPE 563 SYNTAX Counter32 564 MAX-ACCESS read-only 565 STATUS current 566 DESCRIPTION 567 "The number of times a closeSession() request has been 568 executed as a (D)TLS client, regardless of whether it 569 succeeded or failed." 570 ::= { snmpTlstmSession 2 } 572 snmpTlstmSessionOpenErrors OBJECT-TYPE 573 SYNTAX Counter32 574 MAX-ACCESS read-only 575 STATUS current 576 DESCRIPTION 577 "The number of times an openSession() request failed to open a 578 session as a (D)TLS client, for any reason." 579 ::= { snmpTlstmSession 3 } 581 snmpTlstmSessionAccepts OBJECT-TYPE 582 SYNTAX Counter32 583 MAX-ACCESS read-only 584 STATUS current 585 DESCRIPTION 586 "The number of times a (D)TLS server has accepted a new 587 connection from a client and has received at least one SNMP 588 message through it." 589 ::= { snmpTlstmSession 4 } 591 snmpTlstmSessionServerCloses OBJECT-TYPE 592 SYNTAX Counter32 593 MAX-ACCESS read-only 594 STATUS current 595 DESCRIPTION 596 "The number of times a closeSession() request has been 597 executed as a (D)TLS server, regardless of whether it 598 succeeded or failed." 599 ::= { snmpTlstmSession 5 } 601 snmpTlstmSessionNoSessions OBJECT-TYPE 602 SYNTAX Counter32 603 MAX-ACCESS read-only 604 STATUS current 605 DESCRIPTION 606 "The number of times an outgoing message was dropped because 607 the session associated with the passed tmStateReference was no 608 longer (or was never) available." 609 ::= { snmpTlstmSession 6 } 611 snmpTlstmSessionInvalidClientCertificates OBJECT-TYPE 612 SYNTAX Counter32 613 MAX-ACCESS read-only 614 STATUS current 615 DESCRIPTION 616 "The number of times an incoming session was not established 617 on a (D)TLS server because the presented client certificate 618 was invalid. Reasons for invalidation include, but are not 619 limited to, cryptographic validation failures or lack of a 620 suitable mapping row in the snmpTlstmCertToTSNTable." 621 ::= { snmpTlstmSession 7 } 623 snmpTlstmSessionUnknownServerCertificate OBJECT-TYPE 624 SYNTAX Counter32 625 MAX-ACCESS read-only 626 STATUS current 627 DESCRIPTION 628 "The number of times an outgoing session was not established 629 on a (D)TLS client because the server certificate presented 630 by an SNMP over (D)TLS server was invalid because no 631 configured fingerprint or Certification Authority (CA) was 632 acceptable to validate it. 633 This may result because there was no entry in the 634 snmpTlstmAddrTable or because no path could be found to a 635 known CA." 636 ::= { snmpTlstmSession 8 } 638 snmpTlstmSessionInvalidServerCertificates OBJECT-TYPE 639 SYNTAX Counter32 640 MAX-ACCESS read-only 641 STATUS current 642 DESCRIPTION 643 "The number of times an outgoing session was not established 644 on a (D)TLS client because the server certificate presented 645 by an SNMP over (D)TLS server could not be validated even if 646 the fingerprint or expected validation path was known. That 647 is, a cryptographic validation error occurred during 648 certificate validation processing. 650 Reasons for invalidation include, but are not 651 limited to, cryptographic validation failures." 652 ::= { snmpTlstmSession 9 } 654 snmpTlstmSessionInvalidCaches OBJECT-TYPE 655 SYNTAX Counter32 656 MAX-ACCESS read-only 657 STATUS current 658 DESCRIPTION 659 "The number of outgoing messages dropped because the 660 tmStateReference referred to an invalid cache." 661 ::= { snmpTlstmSession 10 } 663 -- Configuration Objects 665 snmpTlstmConfig OBJECT IDENTIFIER ::= { snmpTlstmObjects 2 } 667 -- Certificate mapping 669 snmpTlstmCertificateMapping OBJECT IDENTIFIER ::= { snmpTlstmConfig 1 } 671 snmpTlstmCertToTSNCount OBJECT-TYPE 672 SYNTAX Gauge32 673 MAX-ACCESS read-only 674 STATUS current 675 DESCRIPTION 676 "A count of the number of entries in the 677 snmpTlstmCertToTSNTable." 678 ::= { snmpTlstmCertificateMapping 1 } 680 snmpTlstmCertToTSNTableLastChanged OBJECT-TYPE 681 SYNTAX TimeStamp 682 MAX-ACCESS read-only 683 STATUS current 684 DESCRIPTION 685 "The value of sysUpTime.0 when the snmpTlstmCertToTSNTable was 686 last modified through any means, or 0 if it has not been 687 modified since the command responder was started." 688 ::= { snmpTlstmCertificateMapping 2 } 690 snmpTlstmCertToTSNTable OBJECT-TYPE 691 SYNTAX SEQUENCE OF SnmpTlstmCertToTSNEntry 692 MAX-ACCESS not-accessible 693 STATUS current 694 DESCRIPTION 695 "This table is used by a (D)TLS server to map the (D)TLS 696 client's presented X.509 certificate to a tmSecurityName. 698 On an incoming (D)TLS/SNMP connection, the client's presented 699 certificate MUST either be validated based on an established 700 trust anchor, or it MUST directly match a fingerprint in this 701 table. This table does not provide any mechanisms for 702 configuring the trust anchors; the transfer of any needed 703 trusted certificates for path validation is expected to occur 704 through an out-of-band transfer. 706 Once the certificate has been found acceptable (either by path 707 validation or directly matching a fingerprint in this table), 708 this table is consulted to determine the appropriate 709 tmSecurityName to identify with the remote connection. This 710 is done by considering each active row from this table in 711 prioritized order according to its snmpTlstmCertToTSNID value. 712 Each row's snmpTlstmCertToTSNFingerprint value determines 713 whether the row is a match for the incoming connection: 715 1) If the row's snmpTlstmCertToTSNFingerprint value 716 identifies the presented certificate, then consider the 717 row as a successful match. 719 2) If the row's snmpTlstmCertToTSNFingerprint value 720 identifies a locally held copy of a trusted CA 721 certificate and that CA certificate was used to 722 validate the path to the presented certificate, then 723 consider the row as a successful match. 725 Once a matching row has been found, the 726 snmpTlstmCertToTSNMapType value can be used to determine how 727 the tmSecurityName to associate with the session should be 728 determined. See the snmpTlstmCertToTSNMapType column's 729 DESCRIPTION for details on determining the tmSecurityName 730 value. If it is impossible to determine a tmSecurityName from 731 the row's data combined with the data presented in the 733 certificate, then additional rows MUST be searched looking for 734 another potential match. If a resulting tmSecurityName mapped 735 from a given row is not compatible with the needed 736 requirements of a tmSecurityName (e.g., VACM imposes a 737 32-octet-maximum length and the certificate derived 738 securityName could be longer), then it MUST be considered an 739 invalid match and additional rows MUST be searched looking for 740 another potential match. 742 If no matching and valid row can be found, the connection MUST 743 be closed and SNMP messages MUST NOT be accepted over it. 745 Missing values of snmpTlstmCertToTSNID are acceptable and 746 implementations SHOULD continue to the next highest numbered 747 row. It is RECOMMENDED that administrators skip index values 748 to leave room for the insertion of future rows (for example, 749 use values of 10 and 20 when creating initial rows). 751 Users are encouraged to make use of certificates with 752 subjectAltName fields that can be used as tmSecurityNames so 753 that a single root CA certificate can allow all child 754 certificate's subjectAltName to map directly to a 755 tmSecurityName via a 1:1 transformation. However, this table 756 is flexible to allow for situations where existing deployed 757 certificate infrastructures do not provide adequate 758 subjectAltName values for use as tmSecurityNames. 759 Certificates MAY also be mapped to tmSecurityNames using the 760 CommonName portion of the Subject field. However, the usage 761 of the CommonName field is deprecated and thus this usage is 762 NOT RECOMMENDED. Direct mapping from each individual 763 certificate fingerprint to a tmSecurityName is also possible 764 but requires one entry in the table per tmSecurityName and 765 requires more management operations to completely configure a 766 device." 767 ::= { snmpTlstmCertificateMapping 3 } 769 snmpTlstmCertToTSNEntry OBJECT-TYPE 770 SYNTAX SnmpTlstmCertToTSNEntry 771 MAX-ACCESS not-accessible 772 STATUS current 773 DESCRIPTION 774 "A row in the snmpTlstmCertToTSNTable that specifies a mapping 775 for an incoming (D)TLS certificate to a tmSecurityName to use 776 for a connection." 777 INDEX { snmpTlstmCertToTSNID } 778 ::= { snmpTlstmCertToTSNTable 1 } 780 SnmpTlstmCertToTSNEntry ::= SEQUENCE { 781 snmpTlstmCertToTSNID Unsigned32, 782 snmpTlstmCertToTSNFingerprint SnmpTLSFingerprint, 783 snmpTlstmCertToTSNMapType AutonomousType, 784 snmpTlstmCertToTSNData OCTET STRING, 785 snmpTlstmCertToTSNStorageType StorageType, 786 snmpTlstmCertToTSNRowStatus RowStatus 787 } 789 snmpTlstmCertToTSNID OBJECT-TYPE 790 SYNTAX Unsigned32 (1..4294967295) 791 MAX-ACCESS not-accessible 792 STATUS current 793 DESCRIPTION 794 "A unique, prioritized index for the given entry. Lower 795 numbers indicate a higher priority." 796 ::= { snmpTlstmCertToTSNEntry 1 } 798 snmpTlstmCertToTSNFingerprint OBJECT-TYPE 799 SYNTAX SnmpTLSFingerprint (SIZE(1..255)) 800 MAX-ACCESS read-create 801 STATUS current 802 DESCRIPTION 803 "A cryptographic hash of an X.509 certificate. The results of 804 a successful matching fingerprint to either the trusted CA in 805 the certificate validation path or to the certificate itself 806 is dictated by the snmpTlstmCertToTSNMapType column." 807 ::= { snmpTlstmCertToTSNEntry 2 } 809 snmpTlstmCertToTSNMapType OBJECT-TYPE 810 SYNTAX AutonomousType 811 MAX-ACCESS read-create 812 STATUS current 813 DESCRIPTION 814 "Specifies the mapping type for deriving a tmSecurityName from 815 a certificate. Details for mapping of a particular type SHALL 816 be specified in the DESCRIPTION clause of the OBJECT-IDENTITY 817 that describes the mapping. If a mapping succeeds it will 818 return a tmSecurityName for use by the TLSTM model and 819 processing stops. 821 If the resulting mapped value is not compatible with the 822 needed requirements of a tmSecurityName (e.g., VACM imposes a 823 32-octet-maximum length and the certificate derived 824 securityName could be longer), then future rows MUST be 825 searched for additional snmpTlstmCertToTSNFingerprint matches 826 to look for a mapping that succeeds. 828 Suitable values for assigning to this object that are defined 829 within the SNMP-TLS-TM-MIB can be found in the 830 snmpTlstmCertToTSNMIdentities portion of the MIB tree." 831 DEFVAL { snmpTlstmCertSpecified } 832 ::= { snmpTlstmCertToTSNEntry 3 } 834 snmpTlstmCertToTSNData OBJECT-TYPE 835 SYNTAX OCTET STRING (SIZE(0..1024)) 836 MAX-ACCESS read-create 837 STATUS current 838 DESCRIPTION 839 "Auxiliary data used as optional configuration information for 840 a given mapping specified by the snmpTlstmCertToTSNMapType 841 column. Only some mapping systems will make use of this 842 column. The value in this column MUST be ignored for any 843 mapping type that does not require data present in this 844 column." 845 DEFVAL { "" } 846 ::= { snmpTlstmCertToTSNEntry 4 } 848 snmpTlstmCertToTSNStorageType OBJECT-TYPE 849 SYNTAX StorageType 850 MAX-ACCESS read-create 851 STATUS current 852 DESCRIPTION 853 "The storage type for this conceptual row. Conceptual rows 854 having the value 'permanent' need not allow write-access to 855 any columnar objects in the row." 856 DEFVAL { nonVolatile } 857 ::= { snmpTlstmCertToTSNEntry 5 } 859 snmpTlstmCertToTSNRowStatus OBJECT-TYPE 860 SYNTAX RowStatus 861 MAX-ACCESS read-create 862 STATUS current 863 DESCRIPTION 864 "The status of this conceptual row. This object MAY be used 865 to create or remove rows from this table. 867 To create a row in this table, an administrator MUST set this 868 object to either createAndGo(4) or createAndWait(5). 870 Until instances of all corresponding columns are appropriately 871 configured, the value of the corresponding instance of the 872 snmpTlstmParamsRowStatus column is notReady(3). 874 In particular, a newly created row cannot be made active until 875 the corresponding snmpTlstmCertToTSNFingerprint, 876 snmpTlstmCertToTSNMapType, and snmpTlstmCertToTSNData columns 877 have been set. 879 The following objects MUST NOT be modified while the 880 value of this object is active(1): 881 - snmpTlstmCertToTSNFingerprint 882 - snmpTlstmCertToTSNMapType 883 - snmpTlstmCertToTSNData 884 An attempt to set these objects while the value of 885 snmpTlstmParamsRowStatus is active(1) will result in 886 an inconsistentValue error." 887 ::= { snmpTlstmCertToTSNEntry 6 } 889 -- Maps tmSecurityNames to certificates for use by the SNMP-TARGET-MIB 891 snmpTlstmParamsCount OBJECT-TYPE 892 SYNTAX Gauge32 893 MAX-ACCESS read-only 894 STATUS current 895 DESCRIPTION 896 "A count of the number of entries in the snmpTlstmParamsTable." 897 ::= { snmpTlstmCertificateMapping 4 } 899 snmpTlstmParamsTableLastChanged OBJECT-TYPE 900 SYNTAX TimeStamp 901 MAX-ACCESS read-only 902 STATUS current 903 DESCRIPTION 904 "The value of sysUpTime.0 when the snmpTlstmParamsTable 905 was last modified through any means, or 0 if it has not been 906 modified since the command responder was started." 907 ::= { snmpTlstmCertificateMapping 5 } 909 snmpTlstmParamsTable OBJECT-TYPE 910 SYNTAX SEQUENCE OF SnmpTlstmParamsEntry 911 MAX-ACCESS not-accessible 912 STATUS current 913 DESCRIPTION 914 "This table is used by a (D)TLS client when a (D)TLS 915 connection is being set up using an entry in the 916 SNMP-TARGET-MIB. It extends the SNMP-TARGET-MIB's 917 snmpTargetParamsTable with a fingerprint of a certificate to 918 use when establishing such a (D)TLS connection." 919 ::= { snmpTlstmCertificateMapping 6 } 921 snmpTlstmParamsEntry OBJECT-TYPE 922 SYNTAX SnmpTlstmParamsEntry 923 MAX-ACCESS not-accessible 924 STATUS current 925 DESCRIPTION 926 "A conceptual row containing a fingerprint hash of a locally 927 held certificate for a given snmpTargetParamsEntry. The 928 values in this row SHOULD be ignored if the connection that 929 needs to be established, as indicated by the SNMP-TARGET-MIB 930 infrastructure, is not a certificate and (D)TLS based 931 connection. The connection SHOULD NOT be established if the 932 certificate fingerprint stored in this entry does not point to 933 a valid locally held certificate or if it points to an 934 unusable certificate (such as might happen when the 935 certificate's expiration date has been reached)." 936 INDEX { IMPLIED snmpTargetParamsName } 937 ::= { snmpTlstmParamsTable 1 } 939 SnmpTlstmParamsEntry ::= SEQUENCE { 940 snmpTlstmParamsClientFingerprint SnmpTLSFingerprint, 941 snmpTlstmParamsStorageType StorageType, 942 snmpTlstmParamsRowStatus RowStatus 943 } 945 snmpTlstmParamsClientFingerprint OBJECT-TYPE 946 SYNTAX SnmpTLSFingerprint 947 MAX-ACCESS read-create 948 STATUS current 949 DESCRIPTION 950 "This object stores the hash of the public portion of a 951 locally held X.509 certificate. The X.509 certificate, its 952 public key, and the corresponding private key will be used 953 when initiating a (D)TLS connection as a (D)TLS client." 954 ::= { snmpTlstmParamsEntry 1 } 956 snmpTlstmParamsStorageType OBJECT-TYPE 957 SYNTAX StorageType 958 MAX-ACCESS read-create 959 STATUS current 960 DESCRIPTION 961 "The storage type for this conceptual row. Conceptual rows 962 having the value 'permanent' need not allow write-access to 963 any columnar objects in the row." 964 DEFVAL { nonVolatile } 965 ::= { snmpTlstmParamsEntry 2 } 967 snmpTlstmParamsRowStatus OBJECT-TYPE 968 SYNTAX RowStatus 969 MAX-ACCESS read-create 970 STATUS current 971 DESCRIPTION 972 "The status of this conceptual row. This object MAY be used 973 to create or remove rows from this table. 975 To create a row in this table, an administrator MUST set this 976 object to either createAndGo(4) or createAndWait(5). 978 Until instances of all corresponding columns are appropriately 979 configured, the value of the corresponding instance of the 980 snmpTlstmParamsRowStatus column is notReady(3). 982 In particular, a newly created row cannot be made active until 983 the corresponding snmpTlstmParamsClientFingerprint column has 984 been set. 986 The snmpTlstmParamsClientFingerprint object MUST NOT be modified 987 while the value of this object is active(1). 989 An attempt to set these objects while the value of 990 snmpTlstmParamsRowStatus is active(1) will result in 991 an inconsistentValue error." 992 ::= { snmpTlstmParamsEntry 3 } 994 snmpTlstmAddrCount OBJECT-TYPE 995 SYNTAX Gauge32 996 MAX-ACCESS read-only 997 STATUS current 998 DESCRIPTION 999 "A count of the number of entries in the snmpTlstmAddrTable." 1000 ::= { snmpTlstmCertificateMapping 7 } 1002 snmpTlstmAddrTableLastChanged OBJECT-TYPE 1003 SYNTAX TimeStamp 1004 MAX-ACCESS read-only 1005 STATUS current 1006 DESCRIPTION 1007 "The value of sysUpTime.0 when the snmpTlstmAddrTable 1008 was last modified through any means, or 0 if it has not been 1009 modified since the command responder was started." 1010 ::= { snmpTlstmCertificateMapping 8 } 1012 snmpTlstmAddrTable OBJECT-TYPE 1013 SYNTAX SEQUENCE OF SnmpTlstmAddrEntry 1014 MAX-ACCESS not-accessible 1015 STATUS current 1016 DESCRIPTION 1017 "This table is used by a (D)TLS client when a (D)TLS 1018 connection is being set up using an entry in the 1019 SNMP-TARGET-MIB. It extends the SNMP-TARGET-MIB's 1021 snmpTargetAddrTable so that the client can verify that the 1022 correct server has been reached. This verification can use 1023 either a certificate fingerprint, or an identity 1024 authenticated via certification path validation. 1026 If there is an active row in this table corresponding to the 1027 entry in the SNMP-TARGET-MIB that was used to establish the 1028 connection, and the row's snmpTlstmAddrServerFingerprint 1029 column has non-empty value, then the server's presented 1030 certificate is compared with the 1031 snmpTlstmAddrServerFingerprint value (and the 1032 snmpTlstmAddrServerIdentity column is ignored). If the 1033 fingerprint matches, the verification has succeeded. If the 1034 fingerprint does not match, then the connection MUST be 1035 closed. 1037 If the server's presented certificate has passed 1038 certification path validation [RFC5280] to a configured 1039 trust anchor, and an active row exists with a zero-length 1040 snmpTlstmAddrServerFingerprint value, then the 1041 snmpTlstmAddrServerIdentity column contains the expected 1042 host name. This expected host name is then compared against 1043 the server's certificate as follows: 1045 - Implementations MUST support matching the expected host 1046 name against a dNSName in the subjectAltName extension 1047 field and MAY support checking the name against the 1048 CommonName portion of the subject distinguished name. 1050 - The '*' (ASCII 0x2a) wildcard character is allowed in the 1051 dNSName of the subjectAltName extension (and in common 1052 name, if used to store the host name), but only as the 1053 left-most (least significant) DNS label in that value. 1054 This wildcard matches any left-most DNS label in the 1055 server name. That is, the subject *.example.com matches 1056 the server names a.example.com and b.example.com, but does 1057 not match example.com or a.b.example.com. Implementations 1058 MUST support wildcards in certificates as specified above, 1059 but MAY provide a configuration option to disable them. 1061 - If the locally configured name is an internationalized 1062 domain name, conforming implementations MUST convert it to 1063 the ASCII Compatible Encoding (ACE) format for performing 1064 comparisons, as specified in Section 7 of [RFC5280]. 1066 If the expected host name fails these conditions then the 1067 connection MUST be closed. 1069 If there is no row in this table corresponding to the entry 1070 in the SNMP-TARGET-MIB and the server can be authorized by 1071 another, implementation-dependent means, then the connection 1072 MAY still proceed." 1073 ::= { snmpTlstmCertificateMapping 9 } 1075 snmpTlstmAddrEntry OBJECT-TYPE 1076 SYNTAX SnmpTlstmAddrEntry 1077 MAX-ACCESS not-accessible 1078 STATUS current 1079 DESCRIPTION 1080 "A conceptual row containing a copy of a certificate's 1081 fingerprint for a given snmpTargetAddrEntry. The values in 1082 this row SHOULD be ignored if the connection that needs to be 1083 established, as indicated by the SNMP-TARGET-MIB 1084 infrastructure, is not a (D)TLS based connection. If an 1085 snmpTlstmAddrEntry exists for a given snmpTargetAddrEntry, then 1086 the presented server certificate MUST match or the connection 1087 MUST NOT be established. If a row in this table does not 1088 exist to match an snmpTargetAddrEntry row, then the connection 1089 SHOULD still proceed if some other certificate validation path 1090 algorithm (e.g., RFC 5280) can be used." 1092 INDEX { IMPLIED snmpTargetAddrName } 1093 ::= { snmpTlstmAddrTable 1 } 1095 SnmpTlstmAddrEntry ::= SEQUENCE { 1096 snmpTlstmAddrServerFingerprint SnmpTLSFingerprint, 1097 snmpTlstmAddrServerIdentity SnmpAdminString, 1098 snmpTlstmAddrStorageType StorageType, 1099 snmpTlstmAddrRowStatus RowStatus 1100 } 1102 snmpTlstmAddrServerFingerprint OBJECT-TYPE 1103 SYNTAX SnmpTLSFingerprint 1104 MAX-ACCESS read-create 1105 STATUS current 1106 DESCRIPTION 1107 "A cryptographic hash of a public X.509 certificate. This 1108 object should store the hash of the public X.509 certificate 1109 that the remote server should present during the (D)TLS 1110 connection setup. The fingerprint of the presented 1111 certificate and this hash value MUST match exactly or the 1112 connection MUST NOT be established." 1113 DEFVAL { "" } 1114 ::= { snmpTlstmAddrEntry 1 } 1116 snmpTlstmAddrServerIdentity OBJECT-TYPE 1117 SYNTAX SnmpAdminString 1118 MAX-ACCESS read-create 1119 STATUS current 1120 DESCRIPTION 1121 "The reference identity to check against the identity 1122 presented by the remote system." 1123 DEFVAL { "" } 1124 ::= { snmpTlstmAddrEntry 2 } 1126 snmpTlstmAddrStorageType OBJECT-TYPE 1127 SYNTAX StorageType 1128 MAX-ACCESS read-create 1129 STATUS current 1130 DESCRIPTION 1131 "The storage type for this conceptual row. Conceptual rows 1132 having the value 'permanent' need not allow write-access to 1133 any columnar objects in the row." 1134 DEFVAL { nonVolatile } 1135 ::= { snmpTlstmAddrEntry 3 } 1137 snmpTlstmAddrRowStatus OBJECT-TYPE 1138 SYNTAX RowStatus 1139 MAX-ACCESS read-create 1140 STATUS current 1141 DESCRIPTION 1142 "The status of this conceptual row. This object may be used 1143 to create or remove rows from this table. 1145 To create a row in this table, an administrator MUST set this 1146 object to either createAndGo(4) or createAndWait(5). 1148 Until instances of all corresponding columns are 1149 appropriately configured, the value of the 1150 corresponding instance of the snmpTlstmAddrRowStatus 1151 column is notReady(3). 1153 In particular, a newly created row cannot be made active until 1154 the corresponding snmpTlstmAddrServerFingerprint column has been 1155 set. 1157 Rows MUST NOT be active if the snmpTlstmAddrServerFingerprint 1158 column is blank and the snmpTlstmAddrServerIdentity is set to 1159 '*' since this would insecurely accept any presented 1160 certificate. 1162 The snmpTlstmAddrServerFingerprint object MUST NOT be modified 1163 while the value of this object is active(1). 1165 An attempt to set these objects while the value of 1166 snmpTlstmAddrRowStatus is active(1) will result in 1167 an inconsistentValue error." 1168 ::= { snmpTlstmAddrEntry 4 } 1170 -- ************************************************ 1171 -- snmpTlstmNotifications - Notifications Information 1172 -- ************************************************ 1174 snmpTlstmServerCertificateUnknown NOTIFICATION-TYPE 1175 OBJECTS { snmpTlstmSessionUnknownServerCertificate } 1176 STATUS current 1177 DESCRIPTION 1178 "Notification that the server certificate presented by an SNMP 1179 over (D)TLS server was invalid because no configured 1180 fingerprint or CA was acceptable to validate it. This may be 1181 because there was no entry in the snmpTlstmAddrTable or 1182 because no path could be found to known Certification 1183 Authority. 1185 To avoid notification loops, this notification MUST NOT be 1186 sent to servers that themselves have triggered the 1187 notification." 1189 ::= { snmpTlstmNotifications 1 } 1191 snmpTlstmServerInvalidCertificate NOTIFICATION-TYPE 1192 OBJECTS { snmpTlstmAddrServerFingerprint, 1193 snmpTlstmSessionInvalidServerCertificates} 1194 STATUS current 1195 DESCRIPTION 1196 "Notification that the server certificate presented by an SNMP 1197 over (D)TLS server could not be validated even if the 1198 fingerprint or expected validation path was known. That is, a 1199 cryptographic validation error occurred during certificate 1200 validation processing. 1202 To avoid notification loops, this notification MUST NOT be 1203 sent to servers that themselves have triggered the 1204 notification." 1205 ::= { snmpTlstmNotifications 2 } 1207 -- ************************************************ 1208 -- snmpTlstmCompliances - Conformance Information 1209 -- ************************************************ 1211 snmpTlstmCompliances OBJECT IDENTIFIER ::= { snmpTlstmConformance 1 } 1213 snmpTlstmGroups OBJECT IDENTIFIER ::= { snmpTlstmConformance 2 } 1215 -- ************************************************ 1216 -- Compliance statements 1217 -- ************************************************ 1219 snmpTlstmCompliance MODULE-COMPLIANCE 1220 STATUS current 1221 DESCRIPTION 1222 "The compliance statement for SNMP engines that support the 1223 SNMP-TLS-TM-MIB" 1224 MODULE 1225 MANDATORY-GROUPS { snmpTlstmStatsGroup, 1226 snmpTlstmIncomingGroup, 1227 snmpTlstmOutgoingGroup, 1228 snmpTlstmNotificationGroup } 1229 ::= { snmpTlstmCompliances 1 } 1231 -- ************************************************ 1232 -- Units of conformance 1233 -- ************************************************ 1234 snmpTlstmStatsGroup OBJECT-GROUP 1235 OBJECTS { 1236 snmpTlstmSessionOpens, 1237 snmpTlstmSessionClientCloses, 1238 snmpTlstmSessionOpenErrors, 1239 snmpTlstmSessionAccepts, 1240 snmpTlstmSessionServerCloses, 1241 snmpTlstmSessionNoSessions, 1242 snmpTlstmSessionInvalidClientCertificates, 1243 snmpTlstmSessionUnknownServerCertificate, 1244 snmpTlstmSessionInvalidServerCertificates, 1245 snmpTlstmSessionInvalidCaches 1246 } 1247 STATUS current 1248 DESCRIPTION 1249 "A collection of objects for maintaining 1250 statistical information of an SNMP engine that 1251 implements the SNMP TLS Transport Model." 1252 ::= { snmpTlstmGroups 1 } 1254 snmpTlstmIncomingGroup OBJECT-GROUP 1255 OBJECTS { 1256 snmpTlstmCertToTSNCount, 1257 snmpTlstmCertToTSNTableLastChanged, 1258 snmpTlstmCertToTSNFingerprint, 1259 snmpTlstmCertToTSNMapType, 1260 snmpTlstmCertToTSNData, 1261 snmpTlstmCertToTSNStorageType, 1262 snmpTlstmCertToTSNRowStatus 1263 } 1264 STATUS current 1265 DESCRIPTION 1266 "A collection of objects for maintaining 1267 incoming connection certificate mappings to 1268 tmSecurityNames of an SNMP engine that implements the 1269 SNMP TLS Transport Model." 1270 ::= { snmpTlstmGroups 2 } 1272 snmpTlstmOutgoingGroup OBJECT-GROUP 1273 OBJECTS { 1274 snmpTlstmParamsCount, 1275 snmpTlstmParamsTableLastChanged, 1276 snmpTlstmParamsClientFingerprint, 1277 snmpTlstmParamsStorageType, 1278 snmpTlstmParamsRowStatus, 1279 snmpTlstmAddrCount, 1280 snmpTlstmAddrTableLastChanged, 1281 snmpTlstmAddrServerFingerprint, 1282 snmpTlstmAddrServerIdentity, 1283 snmpTlstmAddrStorageType, 1284 snmpTlstmAddrRowStatus 1286 } 1287 STATUS current 1288 DESCRIPTION 1289 "A collection of objects for maintaining 1290 outgoing connection certificates to use when opening 1291 connections as a result of SNMP-TARGET-MIB settings." 1292 ::= { snmpTlstmGroups 3 } 1294 snmpTlstmNotificationGroup NOTIFICATION-GROUP 1295 NOTIFICATIONS { 1296 snmpTlstmServerCertificateUnknown, 1297 snmpTlstmServerInvalidCertificate 1298 } 1299 STATUS current 1300 DESCRIPTION 1301 "Notifications" 1302 ::= { snmpTlstmGroups 4 } 1304 END 1306 5. Security Considerations 1308 This document updates a transport model that permits SNMP to utilize 1309 TLS security services. The security threats and how the TLS 1310 transport model mitigates these threats are covered throughout this 1311 document and in [RFC6353]. Security considerations for TLS are 1312 described in Section 10 and Appendix E of TLS 1.3 [RFC8446]. 1314 SNMP versions prior to SNMPv3 did not include adequate security. 1315 Even if the network itself is secure (for example, by using IPsec), 1316 even then, there is no control as to who on the secure network is 1317 allowed to access and GET/SET (read/change/create/delete) the objects 1318 in this MIB module. 1320 It is RECOMMENDED that only SNMPv3 messages using the Transport 1321 Security Model (TSM) or another secure-transport aware security model 1322 be sent over the TLSTM transport. 1324 6. IANA Considerations 1326 This document requires the establishment of a new TLSTM HashAlgorithm 1327 Table, which is referenced in the above MIB as being located at 1328 "http://www.iana.org/assignments/tlstm-parameters/". The initial 1329 values for this table MUST be identical to the contents of the TLS 1330 HashAlgorithm Registry (RFC 5246). 1332 7. Acknowledgements 1334 Acknowledgements This document is based on [RFC6353]. This document 1335 was reviewed by the following people who helped provide useful 1336 comments: Michaela Vanderveen, Joe Clarke, Jürgen 1337 Schönwälder, and Tom Petch 1339 8. References 1341 8.1. Normative References 1343 [I-D.ietf-tls-dtls13] 1344 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 1345 Datagram Transport Layer Security (DTLS) Protocol Version 1346 1.3", Work in Progress, Internet-Draft, draft-ietf-tls- 1347 dtls13-43, 30 April 2021, 1348 . 1351 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1352 Requirement Levels", BCP 14, RFC 2119, 1353 DOI 10.17487/RFC2119, March 1997, 1354 . 1356 [RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen, 1357 "Coexistence between Version 1, Version 2, and Version 3 1358 of the Internet-standard Network Management Framework", 1359 BCP 74, RFC 3584, DOI 10.17487/RFC3584, August 2003, 1360 . 1362 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1363 Housley, R., and W. Polk, "Internet X.509 Public Key 1364 Infrastructure Certificate and Certificate Revocation List 1365 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1366 . 1368 [RFC5591] Harrington, D. and W. Hardaker, "Transport Security Model 1369 for the Simple Network Management Protocol (SNMP)", 1370 STD 78, RFC 5591, DOI 10.17487/RFC5591, June 2009, 1371 . 1373 [RFC6353] Hardaker, W., "Transport Layer Security (TLS) Transport 1374 Model for the Simple Network Management Protocol (SNMP)", 1375 STD 78, RFC 6353, DOI 10.17487/RFC6353, July 2011, 1376 . 1378 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1379 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1380 . 1382 [RFC8996] Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS 1383 1.1", BCP 195, RFC 8996, DOI 10.17487/RFC8996, March 2021, 1384 . 1386 [STD62] Harrington, D., Presuhn, R., and B. Wijnen, "An 1387 Architecture for Describing Simple Network Management 1388 Protocol (SNMP) Management Frameworks", STD 62, RFC 3411, 1389 December 2002. 1391 Case, J., Harrington, D., Presuhn, R., and B. Wijnen, 1392 "Message Processing and Dispatching for the Simple Network 1393 Management Protocol (SNMP)", STD 62, RFC 3412, December 1394 2002. 1396 Levi, D., Meyer, P., and B. Stewart, "Simple Network 1397 Management Protocol (SNMP) Applications", STD 62, 1398 RFC 3413, December 2002. 1400 Blumenthal, U. and B. Wijnen, "User-based Security Model 1401 (USM) for version 3 of the Simple Network Management 1402 Protocol (SNMPv3)", STD 62, RFC 3414, December 2002. 1404 Wijnen, B., Presuhn, R., and K. McCloghrie, "View-based 1405 Access Control Model (VACM) for the Simple Network 1406 Management Protocol (SNMP)", STD 62, RFC 3415, December 1407 2002. 1409 Presuhn, R., Ed., "Version 2 of the Protocol Operations 1410 for the Simple Network Management Protocol (SNMP)", 1411 STD 62, RFC 3416, December 2002. 1413 Presuhn, R., Ed., "Transport Mappings for the Simple 1414 Network Management Protocol (SNMP)", STD 62, RFC 3417, 1415 December 2002. 1417 Presuhn, R., Ed., "Management Information Base (MIB) for 1418 the Simple Network Management Protocol (SNMP)", STD 62, 1419 RFC 3418, December 2002. 1421 8.2. Informative References 1423 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1424 (TLS) Protocol Version 1.2", RFC 5246, 1425 DOI 10.17487/RFC5246, August 2008, 1426 . 1428 [STD58] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1429 Schoenwaelder, Ed., "Structure of Management Information 1430 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 1432 McCloghrie, K., Ed., Perkins, D., Ed., and J. 1433 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 1434 STD 58, RFC 2579, April 1999. 1436 McCloghrie, K., Ed., Perkins, D., Ed., and J. 1437 Schoenwaelder, Ed., "Conformance Statements for SMIv2", 1438 STD 58, RFC 2580, April 1999. 1440 Appendix A. Target and Notification Configuration Example 1442 The following sections describe example configuration for the SNMP- 1443 TLS-TM-MIB, the SNMP-TARGET-MIB, the NOTIFICATION-MIB, and the SNMP- 1444 VIEW-BASED-ACM-MIB. 1446 A.1. Configuring a Notification Originator 1448 The following row adds the "Joe Cool" user to the "administrators" 1449 group: 1451 vacmSecurityModel = 4 (TSM) 1452 vacmSecurityName = "Joe Cool" 1453 vacmGroupName = "administrators" 1454 vacmSecurityToGroupStorageType = 3 (nonVolatile) 1455 vacmSecurityToGroupStatus = 4 (createAndGo) 1457 The following row configures the snmpTlstmAddr13Table to use 1458 certificate path validation and to require the remote notification 1459 receiver to present a certificate for the "server.example.org" 1460 identity. 1462 snmpTargetAddrName = "toNRAddr" 1463 snmpTlstmAddr13ServerFingerprint = "" 1464 snmpTlstmAddr13ServerIdentity = "server.example.org" 1465 snmpTlstmAddr13StorageType = 3 (nonVolatile) 1466 snmpTlstmAddr13RowStatus = 4 (createAndGo) 1468 The following row configures the snmpTargetAddrTable to send 1469 notifications using TLS/TCP to the snmptls-trap port at 192.0.2.1: 1471 snmpTargetAddrName = "toNRAddr" 1472 snmpTargetAddrTDomain = snmpTLSTCPDomain 1473 snmpTargetAddrTAddress = "192.0.2.1:10162" 1474 snmpTargetAddrTimeout = 1500 1475 snmpTargetAddrRetryCount = 3 1476 snmpTargetAddrTagList = "toNRTag" 1477 snmpTargetAddrParams = "toNR" (MUST match below) 1478 snmpTargetAddrStorageType = 3 (nonVolatile) 1479 snmpTargetAddrRowStatus = 4 (createAndGo) 1481 The following row configures the snmpTargetParamsTable to send the 1482 notifications to "Joe Cool", using authPriv SNMPv3 notifications 1483 through the TransportSecurityModel [[RFC5591]]: 1485 snmpTargetParamsName = "toNR" (MUST match above) 1486 snmpTargetParamsMPModel = 3 (SNMPv3) 1487 snmpTargetParamsSecurityModel = 4 (TransportSecurityModel) 1488 snmpTargetParamsSecurityName = "Joe Cool" 1489 snmpTargetParamsSecurityLevel = 3 (authPriv) 1490 snmpTargetParamsStorageType = 3 (nonVolatile) 1491 snmpTargetParamsRowStatus = 4 (createAndGo) 1493 A.2. Configuring TLSTM to Utilize a Simple Derivation of tmSecurityName 1495 The following row configures the snmpTlstmCertToTSN13Table to map a 1496 validated client certificate, referenced by the client's public X.509 1497 hash fingerprint, to a tmSecurityName using the subjectAltName 1498 component of the certificate. 1500 snmpTlstmCertToTSN13ID = 1 1501 (chosen by ordering preference) 1502 snmpTlstmCertToTSN13Fingerprint = HASH (appropriate fingerprint) 1503 snmpTlstmCertToTSN13MapType = snmpTlstmCertSANAny 1504 snmpTlstmCertToTSN13Data = "" (not used) 1505 snmpTlstmCertToTSN13StorageType = 3 (nonVolatile) 1506 snmpTlstmCertToTSN13RowStatus = 4 (createAndGo) 1508 This type of configuration should only be used when the naming 1509 conventions of the (possibly multiple) Certification Authorities are 1510 well understood, so two different principals cannot inadvertently be 1511 identified by the same derived tmSecurityName. 1513 A.3. Configuring TLSTM to Utilize Table-Driven Certificate Mapping 1515 The following row configures the snmpTlstmCertToTSN13Table to map a 1516 validated client certificate, referenced by the client's public X.509 1517 hash fingerprint, to the directly specified tmSecurityName of "Joe 1518 Cool". 1520 snmpTlstmCertToTSN13ID = 2 1521 (chosen by ordering preference) 1522 snmpTlstmCertToTSN13Fingerprint = HASH (appropriate fingerprint) 1523 snmpTlstmCertToTSN13MapType = snmpTlstmCertSpecified 1524 snmpTlstmCertToTSN13SecurityName = "Joe Cool" 1525 snmpTlstmCertToTSN13StorageType = 3 (nonVolatile) 1526 snmpTlstmCertToTSN13RowStatus = 4 (createAndGo) 1528 Author's Address 1530 Kenneth Vaughn (editor) 1531 Trevilon LLC 1532 6606 FM 1488 RD 1533 Suite 148-503 1534 Magnolia, TX 77354 1535 United States of America 1536 Phone: +1 571 331 5670 1537 Email: kvaughn@trevilon.com