idnits 2.17.1 draft-ietf-isms-dtls-tm-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) 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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 376 has weird spacing: '...patcher v ...' == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 8, 2009) is 5245 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) ** Obsolete normative reference: RFC 4347 (Obsoleted by RFC 6347) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 4306 (Obsoleted by RFC 5996) -- Obsolete informational reference (is this intentional?): RFC 4366 (Obsoleted by RFC 5246, RFC 6066) Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ISMS W. Hardaker 3 Internet-Draft Sparta, Inc. 4 Intended status: Standards Track December 8, 2009 5 Expires: June 11, 2010 7 Transport Layer Security (TLS) Transport Model for SNMP 8 draft-ietf-isms-dtls-tm-02.txt 10 Abstract 12 This document describes a Transport Model for the Simple Network 13 Management Protocol (SNMP), that uses either the Transport Layer 14 Security protocol or the Datagram Transport Layer Security (DTLS) 15 protocol. The TLS and DTLS protocols provide authentication and 16 privacy services for SNMP applications. This document describes how 17 the TLS Transport Model (TLSTM) implements the needed features of a 18 SNMP Transport Subsystem to make this protection possible in an 19 interoperable way. 21 This transport model is designed to meet the security and operational 22 needs of network administrators. It supports sending of SNMP 23 messages over TLS/TCP, DTLS/UDP and DTLS/SCTP. The TLS mode can make 24 use of TCP's improved support for larger packet sizes and the DTLS 25 mode provides potentially superior operation in environments where a 26 connectionless (e.g. UDP or SCTP) transport is preferred. Both TLS 27 and DTLS integrate well into existing public keying infrastructures. 29 This document also defines a portion of the Management Information 30 Base (MIB) for use with network management protocols. In particular 31 it defines objects for managing the TLS Transport Model for SNMP. 33 Status of this Memo 35 This Internet-Draft is submitted to IETF in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF), its areas, and its working groups. Note that 40 other groups may also distribute working documents as Internet- 41 Drafts. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 The list of current Internet-Drafts can be accessed at 49 http://www.ietf.org/ietf/1id-abstracts.txt. 51 The list of Internet-Draft Shadow Directories can be accessed at 52 http://www.ietf.org/shadow.html. 54 This Internet-Draft will expire on June 11, 2010. 56 Copyright Notice 58 Copyright (c) 2009 IETF Trust and the persons identified as the 59 document authors. All rights reserved. 61 This document is subject to BCP 78 and the IETF Trust's Legal 62 Provisions Relating to IETF Documents 63 (http://trustee.ietf.org/license-info) in effect on the date of 64 publication of this document. Please review these documents 65 carefully, as they describe your rights and restrictions with respect 66 to this document. Code Components extracted from this document must 67 include Simplified BSD License text as described in Section 4.e of 68 the Trust Legal Provisions and are provided without warranty as 69 described in the BSD License. 71 This document may contain material from IETF Documents or IETF 72 Contributions published or made publicly available before November 73 10, 2008. The person(s) controlling the copyright in some of this 74 material may not have granted the IETF Trust the right to allow 75 modifications of such material outside the IETF Standards Process. 76 Without obtaining an adequate license from the person(s) controlling 77 the copyright in such materials, this document may not be modified 78 outside the IETF Standards Process, and derivative works of it may 79 not be created outside the IETF Standards Process, except to format 80 it for publication as an RFC or to translate it into languages other 81 than English. 83 Table of Contents 85 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 86 1.1. Conventions . . . . . . . . . . . . . . . . . . . . . . . 7 87 2. The Transport Layer Security Protocol . . . . . . . . . . . . 8 88 2.1. SNMP requirements of (D)TLS . . . . . . . . . . . . . . . 8 89 3. How the TLSTM fits into the Transport Subsystem . . . . . . . 9 90 3.1. Security Capabilities of this Model . . . . . . . . . . . 10 91 3.1.1. Threats . . . . . . . . . . . . . . . . . . . . . . . 10 92 3.1.2. Message Protection . . . . . . . . . . . . . . . . . . 12 93 3.1.3. (D)TLS Sessions . . . . . . . . . . . . . . . . . . . 13 94 3.2. Security Parameter Passing . . . . . . . . . . . . . . . . 13 95 3.3. Notifications and Proxy . . . . . . . . . . . . . . . . . 14 96 4. Elements of the Model . . . . . . . . . . . . . . . . . . . . 14 97 4.1. X.509 Certificates . . . . . . . . . . . . . . . . . . . . 15 98 4.1.1. Provisioning for the Certificate . . . . . . . . . . . 15 99 4.2. Messages . . . . . . . . . . . . . . . . . . . . . . . . . 16 100 4.3. SNMP Services . . . . . . . . . . . . . . . . . . . . . . 16 101 4.3.1. SNMP Services for an Outgoing Message . . . . . . . . 17 102 4.3.2. SNMP Services for an Incoming Message . . . . . . . . 17 103 4.4. Cached Information and References . . . . . . . . . . . . 18 104 4.4.1. TLS Transport Model Cached Information . . . . . . . . 18 105 5. Elements of Procedure . . . . . . . . . . . . . . . . . . . . 19 106 5.1. Procedures for an Incoming Message . . . . . . . . . . . . 19 107 5.1.1. DTLS Processing for Incoming Messages . . . . . . . . 19 108 5.1.2. Transport Processing for Incoming SNMP Messages . . . 21 109 5.2. Procedures for an Outgoing SNMP Message . . . . . . . . . 22 110 5.3. Establishing a Session . . . . . . . . . . . . . . . . . . 23 111 5.4. Closing a Session . . . . . . . . . . . . . . . . . . . . 26 112 6. MIB Module Overview . . . . . . . . . . . . . . . . . . . . . 26 113 6.1. Structure of the MIB Module . . . . . . . . . . . . . . . 26 114 6.2. Textual Conventions . . . . . . . . . . . . . . . . . . . 27 115 6.3. Statistical Counters . . . . . . . . . . . . . . . . . . . 27 116 6.4. Configuration Tables . . . . . . . . . . . . . . . . . . . 27 117 6.4.1. Notifications . . . . . . . . . . . . . . . . . . . . 27 118 6.5. Relationship to Other MIB Modules . . . . . . . . . . . . 27 119 6.5.1. MIB Modules Required for IMPORTS . . . . . . . . . . . 28 120 7. MIB Module Definition . . . . . . . . . . . . . . . . . . . . 28 121 8. Operational Considerations . . . . . . . . . . . . . . . . . . 50 122 8.1. Sessions . . . . . . . . . . . . . . . . . . . . . . . . . 50 123 8.2. Notification Receiver Credential Selection . . . . . . . . 50 124 8.3. contextEngineID Discovery . . . . . . . . . . . . . . . . 51 125 8.4. Transport Considerations . . . . . . . . . . . . . . . . . 51 126 9. Security Considerations . . . . . . . . . . . . . . . . . . . 51 127 9.1. Certificates, Authentication, and Authorization . . . . . 52 128 9.2. Use with SNMPv1/SNMPv2c Messages . . . . . . . . . . . . . 52 129 9.3. MIB Module Security . . . . . . . . . . . . . . . . . . . 53 130 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54 131 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 56 132 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 56 133 12.1. Normative References . . . . . . . . . . . . . . . . . . . 56 134 12.2. Informative References . . . . . . . . . . . . . . . . . . 57 135 Appendix A. (D)TLS Overview . . . . . . . . . . . . . . . . . . . 58 136 A.1. The (D)TLS Record Protocol . . . . . . . . . . . . . . . . 59 137 A.2. The (D)TLS Handshake Protocol . . . . . . . . . . . . . . 59 138 Appendix B. PKIX Certificate Infrastructure . . . . . . . . . . . 60 139 Appendix C. Target and Notificaton Configuration Example . . . . 61 140 C.1. Configuring the Notification Generator . . . . . . . . . . 62 141 C.2. Configuring the Command Responder . . . . . . . . . . . . 62 142 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 63 144 1. Introduction 146 It is important to understand the modular SNMPv3 architecture as 147 defined by [RFC3411] and enhanced by the Transport Subsystem 148 [RFC5590]. It is also important to understand the terminology of the 149 SNMPv3 architecture in order to understand where the Transport Model 150 described in this document fits into the architecture and how it 151 interacts with the other architecture subsystems. For a detailed 152 overview of the documents that describe the current Internet-Standard 153 Management Framework, please refer to Section 7 of [RFC3410]. 155 This document describes a Transport Model that makes use of the 156 Transport Layer Security (TLS) [RFC5246] and the Datagram Transport 157 Layer Security (DTLS) Protocol [RFC4347], within a transport 158 subsystem [RFC5590]. DTLS is the datagram variant of the Transport 159 Layer Security (TLS) protocol [RFC5246]. The Transport Model in this 160 document is referred to as the Transport Layer Security Transport 161 Model (TLSTM). TLS and DTLS take advantage of the X.509 public 162 keying infrastructure [RFC5280]. While (D)TLS supports multiple 163 authentication mechanisms, this document only discusses X.509 164 certificate based authentication. Although other forms of 165 authentication are possible they are outside the scope of this 166 specification. This transport model is designed to meet the security 167 and operational needs of network administrators, operating in both 168 environments where a connectionless (e.g. UDP or SCTP) transport is 169 preferred and in environments where large quantities of data need to 170 be sent (e.g. over a TCP based stream). Both TLS and DTLS integrate 171 well into existing public keying infrastructures. This document 172 defines supports sending of SNMP messages over TLS/TCP, DTLS/UDP and 173 DTLS/SCTP. 175 This document also defines a portion of the Management Information 176 Base (MIB) for use with network management protocols. In particular 177 it defines objects for managing the TLS Transport Model for SNMP. 179 For a detailed overview of the documents that describe the current 180 Internet-Standard Management Framework, please refer to section 7 of 181 RFC [RFC3410]. 183 Managed objects are accessed via a virtual information store, termed 184 the Management Information Base or MIB. MIB objects are generally 185 accessed through the Simple Network Management Protocol (SNMP). 186 Objects in the MIB are defined using the mechanisms defined in the 187 Structure of Management Information (SMI). This memo specifies a MIB 188 module that is compliant to the SMIv2, which is described in STD 58: 189 [RFC2578], [RFC2579] and [RFC2580]. 191 The diagram shown below gives a conceptual overview of two SNMP 192 entities communicating using the TLS Transport Model. One entity 193 contains a Command Responder and Notification Originator application, 194 and the other a Command Generator and Notification Responder 195 application. It should be understood that this particular mix of 196 application types is an example only and other combinations are 197 equally valid. 199 +----------------------------------------------------------------+ 200 | Network | 201 +----------------------------------------------------------------+ 202 ^ | ^ | 203 |Notifications |Commands |Commands |Notifications 204 +---|---------------------|--------+ +--|---------------|-------------+ 205 | | V | | | V | 206 | +------------+ +------------+ | | +-----------+ +----------+ | 207 | | (D)TLS | | (D)TLS | | | | (D)TLS | | (D)TLS | | 208 | | Service | | Service | | | | Service | | Service | | 209 | | (Client) | | (Server) | | | | (Client) | | (Server)| | 210 | +------------+ +------------+ | | +-----------+ +----------+ | 211 | ^ ^ | | ^ ^ | 212 | | | | | | | | 213 | +--+----------+ | | +-+--------------+ | 214 | +-----|---------+----+ | | +---|--------+----+ | 215 | | V |LCD | +-------+ | | | V |LCD | +--------+ | 216 | | +------+ +----+ | | | | | +------+ +----+ | | | 217 | | | DTLS | <---------->| Cache | | | | | DTLS | <---->| Cache | | 218 | | | TM | | | | | | | | TM | | | | | 219 | | +------+ | +-------+ | | | +------+ | +--------+ | 220 | |Transport Subsystem | ^ | | |Transport Sub. | ^ | 221 | +--------------------+ | | | +-----------------+ | | 222 | ^ +----+ | | ^ | | 223 | | | | | | | | 224 | v | | | V | | 225 | +-------+ +----------+ +-----+ | | | +-----+ +------+ +-----+ | | 226 | | | |Message | |Sec. | | | | | | | MP | |Sec. | | | 227 | | Disp. | |Processing| |Sub- | | | | |Disp.| | Sub- | |Sub- | | | 228 | | | |Subsystem | |sys. | | | | | | |system| |sys. | | | 229 | | | | | | | | | | | | | | | | | | 230 | | | | | |+---+| | | | | | | | |+---+| | | 231 | | | | +-----+ | || || | | | | | |+----+| || || | | 232 | | <--->|v3MP |<-->||TSM|<-+ | | | <-->|v3MP|<->|TSM|<-+ | 233 | | | | +-----+ | || || | | | | |+----+| || || | 234 | +-------+ | | |+---+| | | +-----+ | | |+---+| | 235 | ^ | | | | | | ^ | | | | | 236 | | +----------+ +-----+ | | | +------+ +-----+ | 237 | +-+------------+ | | +-+------------+ | 238 | ^ ^ | | ^ ^ | 239 | | | | | | | | 240 | v v | | V V | 241 | +-------------+ +--------------+ | | +-----------+ +--------------+ | 242 | | COMMAND | | NOTIFICATION | | | | COMMAND | | NOTIFICATION | | 243 | | RESPONDER | | ORIGINATOR | | | | GENERATOR | | RESPONDER | | 244 | | application | | applications | | | |application| | application | | 245 | +-------------+ +--------------+ | | +-----------+ +--------------+ | 246 | SNMP entity | | SNMP entity | 247 +----------------------------------+ +--------------------------------+ 249 1.1. Conventions 251 For consistency with SNMP-related specifications, this document 252 favors terminology as defined in STD62 rather than favoring 253 terminology that is consistent with non-SNMP specifications. This is 254 consistent with the IESG decision to not require the SNMPv3 255 terminology be modified to match the usage of other non-SNMP 256 specifications when SNMPv3 was advanced to Full Standard. 258 Authentication in this document typically refers to the English 259 meaning of "serving to prove the authenticity of" the message, not 260 data source authentication or peer identity authentication. 262 Large portions of this document simultaneously refer to both TLS and 263 DTLS when discussing TLSTM components that function equally with 264 either protocol. "(D)TLS" is used in these places to indicate that 265 the statement applies to either or both protocols as appropriate. 266 When a distinction between the protocols is needed they are referred 267 to independently through the use of "TLS" or "DTLS". The Transport 268 Model, however, is named "TLS Transport Model" and refers not to the 269 TLS or DTLS protocol but to the standard defined in this document, 270 which includes support for both TLS and DTLS. 272 The terms "manager" and "agent" are not used in this document, 273 because in the RFC 3411 architecture [RFC3411], all SNMP entities 274 have the capability of acting in either manager or agent or in both 275 roles depending on the SNMP application types supported in the 276 implementation. Where distinction is required, the application names 277 of Command Generator, Command Responder, Notification Originator, 278 Notification Receiver, and Proxy Forwarder are used. See "SNMP 279 Applications" [RFC3413] for further information. 281 Throughout this document, the terms "client" and "server" are used to 282 refer to the two ends of the (D)TLS transport connection. The client 283 actively opens the (D)TLS connection, and the server passively 284 listens for the incoming (D)TLS connection. Either SNMP entity may 285 act as client or as server. 287 The User-Based Security Model (USM) [RFC3414] is a mandatory-to- 288 implement Security Model in STD 62. While (D)TLS and USM frequently 289 refer to a user, the terminology preferred in RFC3411 and in this 290 memo is "principal". A principal is the "who" on whose behalf 291 services are provided or processing takes place. A principal can be, 292 among other things, an individual acting in a particular role; a set 293 of individuals, with each acting in a particular role; an application 294 or a set of applications, or a combination of these within an 295 administrative domain. 297 Throughout this document, the term "session" is used to refer to a 298 secure association between two TLS Transport Models that permits the 299 transmission of one or more SNMP messages within the lifetime of the 300 session. The (D)TLS protocols also have an internal notion of a 301 session and although these two concepts of a session are related, 302 this document (unless otherwise specified) is referring to TLSTM's 303 specific session and not directly to the (D)TLS protocol's session. 305 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 306 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 307 document are to be interpreted as described in [RFC2119]. 309 2. The Transport Layer Security Protocol 311 (D)TLS provides authentication, data message integrity, and privacy 312 at the transport layer. (See [RFC4347]) 314 The primary goals of the TLS Transport Model are to provide privacy, 315 source authentication and data integrity between two communicating 316 SNMP entities. The TLS and DTLS protocols provide a secure transport 317 upon which the TLSTM is based. An overview of (D)TLS can be found in 318 section Appendix A. Please refer to [RFC5246] and [RFC4347] for 319 complete descriptions of the protocols. 321 2.1. SNMP requirements of (D)TLS 323 To properly support the SNMP over TLS Transport Model, the (D)TLS 324 implementation requires the following: 326 o The TLS Transport Model MUST support authentication of both the 327 server and the client. 329 o The TLS Transport Model SHOULD support the message encryption to 330 protect sensitive data from eavesdropping attacks. 332 3. How the TLSTM fits into the Transport Subsystem 334 A transport model is a component of the Transport Subsystem. The TLS 335 Transport Model thus fits between the underlying (D)TLS transport 336 layer and the message dispatcher [RFC3411] component of the SNMP 337 engine and the Transport Subsystem. 339 The TLS Transport Model will establish a session between itself and 340 the TLS Transport Model of another SNMP engine. The sending 341 transport model passes unprotected messages from the dispatcher to 342 (D)TLS to be protected, and the receiving transport model accepts 343 decrypted and authenticated/integrity-checked incoming messages from 344 (D)TLS and passes them to the dispatcher. 346 After a TLS Transport Model session is established, SNMP messages can 347 conceptually be sent through the session from one SNMP message 348 dispatcher to another SNMP message dispatcher. If multiple SNMP 349 messages are needed to be passed between two SNMP applications they 350 SHOULD be passed through the same session. A TLSTM implementation 351 engine MAY choose to close a (D)TLS session to conserve resources. 353 The TLS Transport Model of an SNMP engine will perform the 354 translation between (D)TLS-specific security parameters and SNMP- 355 specific, model-independent parameters. 357 The diagram below depicts where the TLS Transport Model fits into the 358 architecture described in RFC3411 and the Transport Subsystem: 360 +------------------------------+ 361 | Network | 362 +------------------------------+ 363 ^ ^ ^ 364 | | | 365 v v v 366 +-------------------------------------------------------------------+ 367 | +--------------------------------------------------+ | 368 | | Transport Subsystem | +--------+ | 369 | | +-----+ +-----+ +-------+ +-------+ | | | | 370 | | | UDP | | SSH | |(D)TLS | . . . | other |<--->| Cache | | 371 | | | | | TM | | TM | | | | | | | 372 | | +-----+ +-----+ +-------+ +-------+ | +--------+ | 373 | +--------------------------------------------------+ ^ | 374 | ^ | | 375 | | | | 376 | Dispatcher v | | 377 | +--------------+ +---------------------+ +----------------+ | | 378 | | Transport | | Message Processing | | Security | | | 379 | | Dispatch | | Subsystem | | Subsystem | | | 380 | | | | +------------+ | | +------------+ | | | 381 | | | | +->| v1MP |<--->| | USM | | | | 382 | | | | | +------------+ | | +------------+ | | | 383 | | | | | +------------+ | | +------------+ | | | 384 | | | | +->| v2cMP |<--->| | Transport | | | | 385 | | Message | | | +------------+ | | | Security |<--+ | 386 | | Dispatch <---->| +------------+ | | | Model | | | 387 | | | | +->| v3MP |<--->| +------------+ | | 388 | | | | | +------------+ | | +------------+ | | 389 | | PDU Dispatch | | | +------------+ | | | Other | | | 390 | +--------------+ | +->| otherMP |<--->| | Model(s) | | | 391 | ^ | +------------+ | | +------------+ | | 392 | | +---------------------+ +----------------+ | 393 | v | 394 | +-------+-------------------------+---------------+ | 395 | ^ ^ ^ | 396 | | | | | 397 | v v v | 398 | +-------------+ +---------+ +--------------+ +-------------+ | 399 | | COMMAND | | ACCESS | | NOTIFICATION | | PROXY | | 400 | | RESPONDER |<->| CONTROL |<->| ORIGINATOR | | FORWARDER | | 401 | | application | | | | applications | | application | | 402 | +-------------+ +---------+ +--------------+ +-------------+ | 403 | ^ ^ | 404 | | | | 405 | v v | 406 | +----------------------------------------------+ | 407 | | MIB instrumentation | SNMP entity | 408 +-------------------------------------------------------------------+ 410 3.1. Security Capabilities of this Model 412 3.1.1. Threats 414 The TLS Transport Model provides protection against the threats 415 identified by the RFC 3411 architecture [RFC3411]: 417 1. Modification of Information - The modification threat is the 418 danger that an unauthorized entity may alter in-transit SNMP 419 messages generated on behalf of an authorized principal in such a 420 way as to effect unauthorized management operations, including 421 falsifying the value of an object. 423 (D)TLS provides verification that the content of each received 424 message has not been modified during its transmission through the 425 network, data has not been altered or destroyed in an 426 unauthorized manner, and data sequences have not been altered to 427 an extent greater than can occur non-maliciously. 429 2. Masquerade - The masquerade threat is the danger that management 430 operations unauthorized for a given principal may be attempted by 431 assuming the identity of another principal that has the 432 appropriate authorizations. 434 The TLSTM provides for authentication of the Command Generator, 435 Command Responder, Notification Generator, Notification Responder 436 and Proxy Forwarder through the use of X.509 certificates. 438 The masquerade threat can be mitigated against by using an 439 appropriate Access Control Model (ACM) such as the View-based 440 Access Control Module (VACM) [RFC3415]. 442 3. Message stream modification - The re-ordering, delay or replay of 443 messages can and does occur through the natural operation of many 444 connectionless transport services. The message stream 445 modification threat is the danger that messages may be 446 maliciously re-ordered, delayed or replayed to an extent which is 447 greater than can occur through the natural operation of 448 connectionless transport services, in order to effect 449 unauthorized management operations. 451 (D)TLS provides replay protection with a MAC that includes a 452 sequence number. Since UDP provides no sequencing ability DTLS 453 uses a sliding window protocol with the sequence number for 454 replay protection (see [RFC4347]). 456 4. Disclosure - The disclosure threat is the danger of eavesdropping 457 on the exchanges between SNMP engines. 459 The TLS and DTLS protocols provide support for data privacy 460 through TLS cipher suites that provide encryption. 462 5. Denial of Service - the RFC 3411 architecture [RFC3411] states 463 that denial of service (DoS) attacks need not be addressed by an 464 SNMP security protocol. However, datagram-based security 465 protocols like DTLS are susceptible to a variety of denial of 466 service attacks because it is more vulnerable to spoofed 467 messages. 469 In order to counter these attacks, DTLS borrows the stateless 470 cookie technique used by Photuris [RFC2522] and IKEv2 [RFC4306] 471 and is described fully in section 4.2.1 of [RFC4347]. This 472 mechanism, though, does not provide any defense against denial of 473 service attacks mounted from valid IP addresses. DTLS Transport 474 Model server implementations MUST support DTLS cookies. 476 Implementations are not required to perform the stateless cookie 477 exchange for every DTLS handshake, but in environments where an 478 overload on server side resources is detectable it is RECOMMENDED 479 that the cookie exchange is utilized. 481 See Section 9 for more detail on the security considerations 482 associated with the DTLSTM and these security threats. 484 3.1.2. Message Protection 486 The RFC 3411 architecture recognizes three levels of security: 488 o without authentication and without privacy (noAuthNoPriv) 490 o with authentication but without privacy (authNoPriv) 492 o with authentication and with privacy (authPriv) 494 The TLS Transport Model determines from (D)TLS the identity of the 495 authenticated principal, and the type and address associated with an 496 incoming message. The TLS Transport Model provides this information 497 to (D)TLS for an outgoing message. 499 When an application requests a session for a message, through the 500 cache, the application requests a security level for that session. 501 The TLS Transport Model MUST ensure that the (D)TLS session provides 502 security at least as high as the requested level of security. How 503 the security level is translated into the algorithms used to provide 504 data integrity and privacy is implementation-dependent. However, the 505 NULL integrity and encryption algorithms MUST NOT be used to fulfill 506 security level requests for authentication or privacy. 507 Implementations MAY choose to force (D)TLS to only allow 508 cipher_suites that provide both authentication and privacy to 509 guarantee this assertion. 511 If a suitable interface between the TLS Transport Model and the 512 (D)TLS Handshake Protocol is implemented to allow the selection of 513 security level dependent algorithms (for example a security level to 514 cipher_suites mapping table) then different security levels may be 515 utilized by the application. 517 The authentication, integrity and privacy algorithms used by the 518 (D)TLS Protocols may vary over time as the science of cryptography 519 continues to evolve and the development of (D)TLS continues over 520 time. Implementers are encouraged to plan for changes in operator 521 trust of particular algorithms and implementations should offer 522 configuration settings for mapping algorithms to SNMPv3 security 523 levels. 525 3.1.3. (D)TLS Sessions 527 (D)TLS sessions are opened by the TLS Transport Model during the 528 elements of procedure for an outgoing SNMP message. Since the sender 529 of a message initiates the creation of a (D)TLS session if needed, 530 the (D)TLS session will already exist for an incoming message. 532 Implementations MAY choose to instantiate (D)TLS sessions in 533 anticipation of outgoing messages. This approach might be useful to 534 ensure that a (D)TLS session to a given target can be established 535 before it becomes important to send a message over the (D)TLS 536 session. Of course, there is no guarantee that a pre-established 537 session will still be valid when needed. 539 DTLS sessions, when used over UDP, are uniquely identified within the 540 TLS Transport Model by the combination of transportDomain, 541 transportAddress, tmSecurityName, and requestedSecurityLevel 542 associated with each session. Each unique combination of these 543 parameters MUST have a locally-chosen unique tlsSnmpSessionID 544 associated for active sessions. For further information see 545 Section 5. TLS and DTLS over SCTP sessions, on the other hand, do 546 not require a unique pairing of address and port attributes since 547 their lower layer protocols (TCP and SCTP) already provide adequate 548 session framing. But they must still provide a unique 549 tlsSnmpSessionID for referencing the session. 551 The tlsSnmpSessionID MAY be the same as the (D)TLS internal SessionID 552 but caution must be exercised since the (D)TLS internal SessionID may 553 change over the life of the connection as seen by the TLSTM (for 554 example during renegotiation). The tlsSnmpSessionID identifier MUST 555 NOT change during the entire duration of the connection from the 556 TLSTM's perspective. 558 3.2. Security Parameter Passing 560 For the (D)TLS server-side, (D)TLS-specific security parameters 561 (i.e., cipher_suites, X.509 certificate fields, IP address and port) 562 are translated by the TLS Transport Model into security parameters 563 for the TLS Transport Model and security model (i.e., securityLevel, 564 tmSecurityName, transportDomain, transportAddress). The transport- 565 related and (D)TLS-security-related information, including the 566 authenticated identity, are stored in a cache referenced by 567 tmStateReference. 569 For the (D)TLS client-side, the TLS Transport Model takes input 570 provided by the dispatcher in the sendMessage() Abstract Service 571 Interface (ASI) and input from the tmStateReference cache. The 572 (D)TLS Transport Model converts that information into suitable 573 security parameters for (D)TLS and establishes sessions as needed. 575 The elements of procedure in Section 5 discuss these concepts in much 576 greater detail. 578 3.3. Notifications and Proxy 580 (D)TLS sessions may be initiated by (D)TLS clients on behalf of 581 command generators, notification originators or proxy forwarders. 582 Command generators are frequently operated by a human, but 583 notification originators and proxy forwarders are usually unmanned 584 automated processes. The targets to whom notifications should be 585 sent is typically determined and configured by a network 586 administrator. 588 The SNMP-TARGET-MIB module [RFC3413] contains objects for defining 589 management targets, including transportDomain, transportAddress, 590 securityName, securityModel, and securityLevel parameters, for 591 Notification Generator, Proxy Forwarder, and SNMP-controllable 592 Command Generator applications. Transport domains and transport 593 addresses are configured in the snmpTargetAddrTable, and the 594 securityModel, securityName, and securityLevel parameters are 595 configured in the snmpTargetParamsTable. This document defines a MIB 596 module that extends the SNMP-TARGET-MIB's snmpTargetParamsTable to 597 specify a (D)TLS client-side certificate to use for the connection. 599 When configuring a (D)TLS target, the snmpTargetAddrTDomain and 600 snmpTargetAddrTAddress parameters in snmpTargetAddrTable should be 601 set to the snmpTLSTCPDomain, snmpDTLSUDPDomain, or snmpDTLSSCTPDomain 602 object and an appropriate snmpTLSAddress value. The 603 snmpTargetParamsMPModel column of the snmpTargetParamsTable should be 604 set to a value of 3 to indicate the SNMPv3 message processing model. 605 The snmpTargetParamsSecurityName should be set to an appropriate 606 securityName value and the tlstmParamsClientFingerprint parameter of 607 the tlstmParamsTable should be set a value that refers to a locally 608 held certificate to be used. Other parameters, for example 609 cryptographic configuration such as cipher suites to use, must come 610 from configuration mechanisms not defined in this document. The 611 securityName defined in the snmpTargetParamsSecurityName column will 612 be used by the access control model to authorize any notifications 613 that need to be sent. 615 4. Elements of the Model 617 This section contains definitions required to realize the (D)TLS 618 Transport Model defined by this document. 620 4.1. X.509 Certificates 622 (D)TLS makes use of X.509 certificates for authentication of both 623 sides of the transport. This section discusses the use of 624 certificates in the TLSTM. A brief overview of X.509 certificate 625 infrastructure can be found in Appendix B. 627 While (D)TLS supports multiple authentication mechanisms, this 628 document only discusses X.509 certificate based authentication. 629 Although other forms of authentication are possible they are outside 630 the scope of this specification. 632 4.1.1. Provisioning for the Certificate 634 Authentication using (D)TLS will require that SNMP entities are 635 provisioned with certificates, which are signed by trusted 636 certificate authorities. Furthermore, SNMP entities will most 637 commonly need to be provisioned with root certificates which 638 represent the list of trusted certificate authorities that an SNMP 639 entity can use for certificate verification. SNMP entities SHOULD 640 also be provisioned with a X.509 certificate revocation mechanism 641 which can be used to verify that a certificate has not been revoked. 642 Trusted public keys from either CA certificates and/or self-signed 643 certificates, must be installed through a trusted out of band 644 mechanism into the server and its authenticity MUST be verified 645 before access is granted. 647 Having received a certificate from a connecting TLSTM client, the 648 authenticated tmSecurityName of the principal is derived up using the 649 tlstmCertToTSNTable. This table allows mapping of incoming 650 connections to tmSecurityNames through defined transformations. The 651 transformations defined in the TLSTM-MIB include: 653 o Mapping a certificate's fingerprint type and value to a directly 654 specified tmSecurityName, or 656 o Mapping a certificate's subjectAltName or CommonName components to 657 a tmSecurityName. 659 Implementations MAY choose to discard any connections for which no 660 potential tlstmCertToTSNTable mapping exists before performing 661 certificate verification to avoid expending computational resources 662 associated with certificate verification. 664 The typical enterprise configuration will map a "subjectAltName" 665 component of the tbsCertificate to the TLSTM specific tmSecurityName. 666 The authenticated identity can be obtained by the TLS Transport Model 667 by extracting the subjectAltName(s) from the peer's certificate. The 668 receiving application will then have an appropriate tmSecurityName 669 for use by other SNMPv3 components like an access control model. 671 An example of this type of mapping setup can be found in Appendix C. 673 This tmSecurityName may be later translated from a TLSTM specific 674 tmSecurityName to a SNMP engine securityName by the security model. 675 A security model, like the TSM security model [RFC5591], may perform 676 an identity mapping or a more complex mapping to derive the 677 securityName from the tmSecurityName offered by the TLS Transport 678 Model. 680 A pictorial view of the complete transformation process (using the 681 TSM security model for the example) is shown below: 683 +-------------+ +-------+ +----------------+ +-----+ 684 | Certificate | | | | | | | 685 | Path | | TLSTM | | tmSecurityName | | TSM | 686 | Validation | --> | | --> | | --> | | 687 +-------------+ +-------+ +----------------+ +-----+ 688 | 689 V 690 +-------------+ +--------------+ 691 | application | <-- | securityName | 692 +-------------+ +--------------+ 694 4.2. Messages 696 As stated in Section 4.1.1 of [RFC4347], each DTLS record must fit 697 within a single DTLS datagram. The TLSTM SHOULD prohibit SNMP 698 messages from being sent that exceeds the maximum DTLS message size. 699 The TLSTM implementation SHOULD return an error when the DTLS message 700 size would be exceeded and the message won't be sent. 702 4.3. SNMP Services 704 This section describes the services provided by the TLS Transport 705 Model with their inputs and outputs. The services are between the 706 Transport Model and the dispatcher. 708 The services are described as primitives of an abstract service 709 interface (ASI) and the inputs and outputs are described as abstract 710 data elements as they are passed in these abstract service 711 primitives. 713 4.3.1. SNMP Services for an Outgoing Message 715 The dispatcher passes the information to the TLS Transport Model 716 using the ASI defined in the transport subsystem: 718 statusInformation = 719 sendMessage( 720 IN destTransportDomain -- transport domain to be used 721 IN destTransportAddress -- transport address to be used 722 IN outgoingMessage -- the message to send 723 IN outgoingMessageLength -- its length 724 IN tmStateReference -- reference to transport state 725 ) 727 The abstract data elements returned from or passed as parameters into 728 the abstract service primitives are as follows: 730 statusInformation: An indication of whether the passing of the 731 message was successful. If not, it is an indication of the 732 problem. 734 destTransportDomain: The transport domain for the associated 735 destTransportAddress. The Transport Model uses this parameter to 736 determine the transport type of the associated 737 destTransportAddress. This parameter may also be used by the 738 transport subsystem to route the message to the appropriate 739 Transport Model. This document specifies the snmpTLSDomain, the 740 snmpDTLSUDPDomain and the snmpDTLSSCTPDomain" transport domains. 742 destTransportAddress: The transport address of the destination TLS 743 Transport Model in a format specified by the SnmpTLSAddress 744 TEXTUAL-CONVENTION. 746 outgoingMessage: The outgoing message to send to (D)TLS for 747 encapsulation. 749 outgoingMessageLength: The length of the outgoingMessage field. 751 tmStateReference: A handle/reference to tmSecurityData to be used 752 when securing outgoing messages. 754 4.3.2. SNMP Services for an Incoming Message 756 The TLS Transport Model processes the received message from the 757 network using the (D)TLS service and then passes it to the dispatcher 758 using the following ASI: 760 statusInformation = 761 receiveMessage( 762 IN transportDomain -- origin transport domain 763 IN transportAddress -- origin transport address 764 IN incomingMessage -- the message received 765 IN incomingMessageLength -- its length 766 IN tmStateReference -- reference to transport state 767 ) 769 The abstract data elements returned from or passed as parameters into 770 the abstract service primitives are as follows: 772 statusInformation: An indication of whether the passing of the 773 message was successful. If not, it is an indication of the 774 problem. 776 transportDomain: The transport domain for the associated 777 transportAddress. This document specifies the snmpTLSDomain, the 778 snmpDTLSUDPDomain and the snmpDTLSSCTPDomain" transport domains. 780 transportAddress: The transport address of the source of the 781 received message in a format specified by the SnmpTLSAddress 782 TEXTUAL-CONVENTION. 784 incomingMessage: The whole SNMP message after being processed by 785 (D)TLS and removed of the (D)TLS transport layer data. 787 incomingMessageLength: The length of the incomingMessage field. 789 tmStateReference: A handle/reference to tmSecurityData to be used by 790 the security model. 792 4.4. Cached Information and References 794 When performing SNMP processing, there are two levels of state 795 information that may need to be retained: the immediate state linking 796 a request-response pair, and potentially longer-term state relating 797 to transport and security. "Transport Subsystem for the Simple 798 Network Management Protocol" [RFC5590] defines general requirements 799 for caches and references. 801 4.4.1. TLS Transport Model Cached Information 803 The TLSTM has no specific responsibilities regarding the cached 804 information beyond those discussed in "Transport Subsystem for the 805 Simple Network Management Protocol" [RFC5590]. 807 5. Elements of Procedure 809 Abstract service interfaces have been defined by [RFC3411] and 810 further augmented by [RFC5590] to describe the conceptual data flows 811 between the various subsystems within an SNMP entity. The TLSTM uses 812 some of these conceptual data flows when communicating between 813 subsystems. 815 To simplify the elements of procedure, the release of state 816 information is not always explicitly specified. As a general rule, 817 if state information is available when a message gets discarded, the 818 message-state information should also be released. If state 819 information is available when a session is closed, the session state 820 information should also be released. Sensitive information, like 821 cryptographic keys, should be overwritten appropriately first prior 822 to being released. 824 An error indication in statusInformation will typically include the 825 Object Identifier (OID) and value for an incremented error counter. 826 This may be accompanied by the requested securityLevel and the 827 tmStateReference. Per-message context information is not accessible 828 to Transport Models, so for the returned counter OID and value, 829 contextEngine would be set to the local value of snmpEngineID and 830 contextName to the default context for error counters. 832 5.1. Procedures for an Incoming Message 834 This section describes the procedures followed by the (D)TLS 835 Transport Model when it receives a (D)TLS protected packet. The 836 steps are broken into two different sections. Section 5.1.1 837 describes the needed steps for de-multiplexing multiple DTLS 838 sessions, which is specifically needed for DTLS over UDP sessions. 839 Section 5.1.2 describes the steps specific to transport processing 840 once the (D)TLS processing has been completed. It is assumed that 841 TLS and DTLS/SCP protocol implementations already provide appropriate 842 message demultiplexing and only the processing steps in Section 5.1.2 843 are needed. 845 5.1.1. DTLS Processing for Incoming Messages 847 DTLS is significantly different in terms of session handling than 848 when TLS or DTLS is run over session based streaming protocols like 849 TCP or SCTP. Specifically, the DTLS protocol, when run over UDP, 850 does not have a session identifier that allows implementations to 851 determine through what session a packet arrived. DTLS over SCTP and 852 TLS over TCP streams have built in session demultiplexing and thus 853 the steps in this section are not necessary for those protocol 854 combinations. It is always critical, however, that implementations 855 be able to derive a tlsSnmpSessionID from any session demultiplexing 856 process. 858 A process for demultiplexing multiple DTLS sessions arriving over UDP 859 must be incorporated into the procedures for processing an incoming 860 message. The steps in this section describe one possible method to 861 accomplish this, although any implementation-dependent method should 862 be suitable as long as the results are deterministic. The important 863 output results from the steps in this process are the 864 transportDomain, the transportAddress, the wholeMessage, the 865 wholeMessageLength, and a unique implementation-dependent session 866 identifier (tlsSnmpSessionID). 868 This demultiplexing procedure assumes that upon session establishment 869 an entry in a local transport mapping table is created in the 870 Transport Model's Local Configuration Datastore (LCD). The transport 871 mapping table's entry should map a unique combination of the remote 872 address, remote port number, local address and local port number to 873 an implementation-dependent tlsSnmpSessionID. 875 1) The TLS Transport Model examines the raw UDP message, in an 876 implementation-dependent manner. 878 2) The TLS Transport Model queries the LCD using the transport 879 parameters (source and destination addresses and ports) to 880 determine if a session already exists and its tlsSnmpSessionID. 882 If a matching entry in the LCD does not exist then the message is 883 passed to DTLS for processing without a corresponding 884 tlsSnmpSessionID. The incoming packet may result in a new 885 session being established if the receiving entity is acting as a 886 DTLS server. If DTLS returns success then stop processing of 887 this message. If DTLS returns an error then and the the 888 tlstmSessionNoAvailableSessions counter and stop processing the 889 message. 891 Note that an entry would already exist if the client and server's 892 session establishment procedures had been successfully completed 893 previously (as described both above and in Section 5.3) even if 894 no message had yet been sent through the newly established 895 session. An entry may not exist, however, if a "rogue" message 896 was routed to the SNMP entity by mistake. An entry might also be 897 missing because of a "broken" session (see operational 898 considerations). 900 3) Retrieve the tlsSnmpSessionID from the LCD. 902 4) The UDP packet and the tlsSnmpSessionID are passed to DTLS for 903 integrity checking and decryption. 905 If the message fails integrity checks or other (D)TLS security 906 processing then increment the tlstmDTLSProtectionErrors counter, 907 discard and stop processing the message. 909 5) (D)TLS should return an incomingMessage and an 910 incomingMessageLength. These results and the tlsSnmpSessionID 911 are used below in the Section 5.1.2 to complete the processing of 912 the incoming message. 914 5.1.2. Transport Processing for Incoming SNMP Messages 916 The procedures in this section describe how the TLS Transport Model 917 should process messages that have already been properly extracted 918 from the (D)TLS stream. Note that care must be taken when processing 919 messages originating from either TLS or DTLS to ensure they're 920 complete and singular. For example, multiple SNMP messages can be 921 passed through a single DTLS message and partial SNMP messages may be 922 received from a TLS stream. These steps describe the processing of a 923 singular SNMP message after it has been delivered from the (D)TLS 924 stream. 926 Create a tmStateReference cache for the subsequent reference and 927 assign the following values within it: 929 tmTransportDomain = snmpTLSTCPDomain, snmpDTLSUDPDomain or 930 snmpDTLSSCTPDomain as appropriate. 932 tmTransportAddress = The address the message originated from. 934 tmSecurityLevel = The derived tmSecurityLevel for the session, as 935 discussed in Section 3.1.2 and Section 5.3. 937 tmSecurityName = The derived tmSecurityName for the session as 938 discussed in Section 5.3. This value MUST be constant during the 939 lifetime of the (D)TLS session. 941 tmSessionID = The tlsSnmpSessionID, which MUST be a unique session 942 identifier for this (D)TLS connection. The contents and format of 943 this identifier are implementation-dependent as long as it is 944 unique to the session. A session identifier MUST NOT be reused 945 until all references to it are no longer in use. The tmSessionID 946 is equal to the tlsSnmpSessionID discussed in Section 5.1.1. 947 tmSessionID refers to the session identifier when stored in the 948 tmStateReference and tlsSnmpSessionID refers to the session 949 identifier when stored in the LCD. They MUST always be equal when 950 processing a given session's traffic. 952 The wholeMessage and the wholeMessageLength are assigned values from 953 the incomingMessage and incomingMessageLength values from the (D)TLS 954 processing. 956 The TLS Transport Model passes the transportDomain, transportAddress, 957 wholeMessage, and wholeMessageLength to the dispatcher using the 958 receiveMessage ASI: 960 statusInformation = 961 receiveMessage( 962 IN transportDomain -- snmpTLSTCPDomain, snmpDTLSUDPDomain, 963 -- or snmpDTLSSCTPDomain 964 IN transportAddress -- address for the received message 965 IN wholeMessage -- the whole SNMP message from (D)TLS 966 IN wholeMessageLength -- the length of the SNMP message 967 IN tmStateReference -- transport info 968 ) 970 5.2. Procedures for an Outgoing SNMP Message 972 The dispatcher sends a message to the TLS Transport Model using the 973 following ASI: 975 statusInformation = 976 sendMessage( 977 IN destTransportDomain -- transport domain to be used 978 IN destTransportAddress -- transport address to be used 979 IN outgoingMessage -- the message to send 980 IN outgoingMessageLength -- its length 981 IN tmStateReference -- transport info 982 ) 984 This section describes the procedure followed by the TLS Transport 985 Model whenever it is requested through this ASI to send a message. 987 1) Extract the tmSessionID, tmTransportAddress, tmSecurityName, 988 tmRequestedSecurityLevel, and tmSameSecurity values from the 989 tmStateReference. Note: The tmSessionID value may be undefined 990 if no session exists yet over which the message can be sent. 992 2) If tmSameSecurity is true and either tmSessionID is undefined or 993 refers to a session that is no longer open then increment the 994 tlstmSessionNoAvailableSessions counter, discard the message and 995 return the error indication in the statusInformation. Processing 996 of this message stops. 998 3) If tmSameSecurity is false and tmSessionID refers to a session 999 that is no longer available then an implementation SHOULD open a 1000 new session using the openSession() ASI (described in greater 1001 detail in step 4b). An implementation MAY choose to return an 1002 error to the calling module and stop processing of the message. 1004 4) If tmSessionID is undefined, then use tmTransportAddress, 1005 tmSecurityName and tmRequestedSecurityLevel to see if there is a 1006 corresponding entry in the LCD suitable to send the message over. 1008 4a) If there is a corresponding LCD entry, then this session 1009 will be used to send the message. 1011 4b) If there is not a corresponding LCD entry, then open a 1012 session using the openSession() ASI (discussed further in 1013 Section 5.3). Implementations MAY wish to offer message 1014 buffering to prevent redundant openSession() calls for the 1015 same cache entry. If an error is returned from 1016 openSession(), then discard the message, increment the 1017 tlstmSessionOpenErrors, return an error indication to the 1018 calling module and stop processing of the message. 1020 5) Using either the session indicated by the tmSessionID if there 1021 was one or the session resulting from a previous step (3 or 4), 1022 pass the outgoingMessage to (D)TLS for encapsulation and 1023 transmission. 1025 5.3. Establishing a Session 1027 The TLS Transport Model provides the following primitive to establish 1028 a new (D)TLS session (previously discussed in Section 5.3): 1030 statusInformation = -- errorIndication or success 1031 openSession( 1032 IN tmStateReference -- transport information to be used 1033 OUT tmStateReference -- transport information to be used 1034 IN maxMessageSize -- of the sending SNMP entity 1035 ) 1037 The following describes the procedure to follow when establishing a 1038 SNMP over (D)TLS session between SNMP engines for exchanging SNMP 1039 messages. This process is followed by any SNMP engine establishing a 1040 session for subsequent use. 1042 This MAY be done automatically for SNMP messages which are not 1043 Response or Report messages. 1045 1) The client selects the appropriate certificate and cipher_suites 1046 for the key agreement based on the tmSecurityName and the 1047 tmRequestedSecurityLevel for the session. For sessions being 1048 established as a result of a SNMP-TARGET-MIB based operation, the 1049 certificate will potentially have been identified via the 1050 tlstmParamsTable mapping and the cipher_suites will have to be 1051 taken from system-wide or implementation-specific configuration. 1052 Otherwise, the certificate and appropriate cipher_suites will 1053 need to be passed to the openSession() ASI as supplemental 1054 information or configured through an implementation-dependent 1055 mechanism. It is also implementation-dependent and possibly 1056 policy-dependent how tmRequestedSecurityLevel will be used to 1057 influence the security capabilities provided by the (D)TLS 1058 session. However this is done, the security capabilities 1059 provided by (D)TLS MUST be at least as high as the level of 1060 security indicated by the tmRequestedSecurityLevel parameter. 1061 The actual security level of the session is reported in the 1062 tmStateReference cache as tmSecurityLevel. For (D)TLS to provide 1063 strong authentication, each principal acting as a Command 1064 Generator SHOULD have its own certificate. 1066 2) Using the destTransportDomain and destTransportAddress values, 1067 the client will initiate the (D)TLS handshake protocol to 1068 establish session keys for message integrity and encryption. 1070 If the attempt to establish a session is unsuccessful, then 1071 tlstmSessionOpenErrors is incremented, an error indication is 1072 returned, and processing stops. If the session failed to open 1073 because the presented server certificate was unknown or invalid 1074 then the tlstmSessionUnknownServerCertificate or 1075 tlstmSessionInvalidServerCertificates MUST be incremented and a 1076 tlstmServerCertificateUnknown or tlstmServerInvalidCertificate 1077 notification SHOULD be sent as appropriate. Reasons for server 1078 certificate invalidation includes, but is not limited to, 1079 cryptographic validation failures and an unexpected presented 1080 certificate identity. 1082 3) Once a (D)TLS secured session is established and both sides have 1083 verified the authenticity of the peer's certificate (e.g. 1084 [RFC5280]) then each side will determine and/or check the 1085 identity of the remote entity using the procedures described 1086 below. 1088 a) The (D)TLS server side of the connection identifies the 1089 authenticated identity from the (D)TLS client's principal 1090 certificate using configuration information from the 1091 tlstmCertToTSNTable mapping table. The resulting derived 1092 tmSecurityName is recorded in the tmStateReference cache as 1093 tmSecurityName. The details of the lookup process are fully 1094 described in the DESCRIPTION clause of the 1095 tlstmCertToTSNTable MIB object. If any verification fails in 1096 any way (for example because of failures in cryptographic 1097 verification or because of the lack of an appropriate row in 1098 the tlstmCertToTSNTable) then the session establishment MUST 1099 fail, the tlstmSessionInvalidClientCertificates object is 1100 incremented and processing stops. 1102 b) The (D)TLS client side of the connection MUST verify that 1103 authenticated identity of the (D)TLS server's certificate is 1104 the certificate. 1106 If the connection is being established from configuration 1107 based on SNMP-TARGET-MIB configuration then the procedures in 1108 the tlstmAddrTable DESCRIPTION clause should be followed to 1109 determine the if the presented identity matches the 1110 expectations of the configuration. Path validation 1111 procedures (like those defined in [RFC5280]) MUST be 1112 followed. If a server identity name has been configured in 1113 the tlstmAddrServerIdentity column then this reference 1114 identity must be compared against the presented identity (for 1115 example using procedures described in 1116 [I-D.saintandre-tls-server-id-check]). 1118 If the connection is being established for other reasons then 1119 configuration and procedures outside the scope of this 1120 document should be followed. 1122 (D)TLS provides assurance that the authenticated identity has 1123 been signed by a trusted configured certificate authority. 1124 If verification of the server's certificate fails in any way 1125 (for example because of failures in cryptographic 1126 verification or the presented identity did not match the 1127 expected named entity) then the session establishment MUST 1128 fail, the tlstmSessionInvalidServerCertificates object is 1129 incremented and processing stops. 1131 4) The (D)TLS-specific session identifier is passed to the TLS 1132 Transport Model and associated with the tmStateReference cache 1133 entry to indicate that the session has been established 1134 successfully and to point to a specific (D)TLS session for future 1135 use. 1137 Servers that wish to support multiple principals at a particular port 1138 SHOULD make use of the Server Name Indication extension defined in 1139 Section 3.1 of [RFC4366]. Supporting this will allow, for example, 1140 sending notifications to a specific principal at a given TCP, UDP or 1141 SCTP port. 1143 5.4. Closing a Session 1145 The TLS Transport Model provides the following primitive to close a 1146 session: 1148 statusInformation = 1149 closeSession( 1150 IN tmStateReference -- transport info 1151 ) 1153 The following describes the procedure to follow to close a session 1154 between a client and server. This process is followed by any SNMP 1155 engine closing the corresponding SNMP session. 1157 1) Look up the session in the cache and the LCD using the 1158 tmStateReference and its contents. 1160 2) If there is no open session associated with the tmStateReference, 1161 then closeSession processing is completed. 1163 3) Delete the entry from the cache and any other implementation- 1164 dependent information in the LCD. 1166 4) Have (D)TLS close the specified session. This SHOULD include 1167 sending a close_notify TLS Alert to inform the other side that 1168 session cleanup may be performed. 1170 6. MIB Module Overview 1172 This MIB module provides management of the TLS Transport Model. It 1173 defines needed textual conventions, statistical counters, 1174 notifications and configuration infrastructure necessary for session 1175 establishment. Example usage of the configuration tables can be 1176 found in Appendix C. 1178 6.1. Structure of the MIB Module 1180 Objects in this MIB module are arranged into subtrees. Each subtree 1181 is organized as a set of related objects. The overall structure and 1182 assignment of objects to their subtrees, and the intended purpose of 1183 each subtree, is shown below. 1185 6.2. Textual Conventions 1187 Generic and Common Textual Conventions used in this module can be 1188 found summarized at http://www.ops.ietf.org/mib-common-tcs.html 1190 This module defines the following new Textual Conventions: 1192 o New TransportDomain and TransportAddress formats for describing 1193 (D)TLS connection addressing requirements. 1195 o A certificate fingerprint allowing MIB module objects to 1196 generically refer to a stored X.509 certificate using a 1197 cryptographic hash as a reference pointer. 1199 6.3. Statistical Counters 1201 The TLSTM-MIB defines some counters that can provide network managers 1202 with information about (D)TLS session usage and potential errors that 1203 a MIB-instrumented device may be experiencing. 1205 6.4. Configuration Tables 1207 The TLSTM-MIB defines configuration tables that a manager can use for 1208 configuring a MIB-instrumented device for sending and receiving SNMP 1209 messages over (D)TLS. In particular, there are MIB tables that 1210 extend the SNMP-TARGET-MIB for configuring (D)TLS certificate usage 1211 and a MIB table for mapping incoming (D)TLS client certificates to 1212 SNMPv3 securityNames. 1214 6.4.1. Notifications 1216 The TLSTM-MIB defines notifications to alert management stations when 1217 a (D)TLS connection fails because a server's presented certificate 1218 did not meet an expected value (tlstmServerCertificateUnknown) or 1219 because cryptographic validation failed 1220 (tlstmServerInvalidCertificate). 1222 6.5. Relationship to Other MIB Modules 1224 Some management objects defined in other MIB modules are applicable 1225 to an entity implementing the TLS Transport Model. In particular, it 1226 is assumed that an entity implementing the TLSTM-MIB will implement 1227 the SNMPv2-MIB [RFC3418], the SNMP-FRAMEWORK-MIB [RFC3411], the SNMP- 1228 TARGET-MIB [RFC3413], the SNMP-NOTIFICATION-MIB [RFC3413] and the 1229 SNMP-VIEW-BASED-ACM-MIB [RFC3415]. 1231 The TLSTM-MIB module contained in this document is for managing TLS 1232 Transport Model information. 1234 6.5.1. MIB Modules Required for IMPORTS 1236 The TLSTM-MIB module imports items from SNMPv2-SMI [RFC2578], 1237 SNMPv2-TC [RFC2579], SNMP-FRAMEWORK-MIB [RFC3411], SNMP-TARGET-MIB 1238 [RFC3413] and SNMPv2-CONF [RFC2580]. 1240 7. MIB Module Definition 1242 TLSTM-MIB DEFINITIONS ::= BEGIN 1244 IMPORTS 1245 MODULE-IDENTITY, OBJECT-TYPE, 1246 OBJECT-IDENTITY, snmpModules, snmpDomains, 1247 Counter32, Unsigned32, NOTIFICATION-TYPE 1248 FROM SNMPv2-SMI 1249 TEXTUAL-CONVENTION, TimeStamp, RowStatus, StorageType, 1250 AutonomousType 1251 FROM SNMPv2-TC 1252 MODULE-COMPLIANCE, OBJECT-GROUP, NOTIFICATION-GROUP 1253 FROM SNMPv2-CONF 1254 SnmpAdminString 1255 FROM SNMP-FRAMEWORK-MIB 1256 snmpTargetParamsName, snmpTargetAddrName 1257 FROM SNMP-TARGET-MIB 1258 ; 1260 tlstmMIB MODULE-IDENTITY 1261 LAST-UPDATED "200912080000Z" 1262 ORGANIZATION "ISMS Working Group" 1263 CONTACT-INFO "WG-EMail: isms@lists.ietf.org 1264 Subscribe: isms-request@lists.ietf.org 1266 Chairs: 1267 Juergen Schoenwaelder 1268 Jacobs University Bremen 1269 Campus Ring 1 1270 28725 Bremen 1271 Germany 1272 +49 421 200-3587 1273 j.schoenwaelder@jacobs-university.de 1275 Russ Mundy 1276 SPARTA, Inc. 1278 7110 Samuel Morse Drive 1279 Columbia, MD 21046 1280 USA 1282 Co-editors: 1283 Wes Hardaker 1284 Sparta, Inc. 1285 P.O. Box 382 1286 Davis, CA 95617 1287 USA 1288 ietf@hardakers.net 1289 " 1291 DESCRIPTION " 1292 The TLS Transport Model MIB 1294 Copyright (c) 2009 IETF Trust and the persons 1295 identified as authors of the code. All rights reserved. 1297 Redistribution and use in source and binary forms, with or 1298 without modification, are permitted provided that the 1299 following conditions are met: 1301 - Redistributions of source code must retain the above copyright 1302 notice, this list of conditions and the following disclaimer. 1304 - Redistributions in binary form must reproduce the above 1305 copyright notice, this list of conditions and the following 1306 disclaimer in the documentation and/or other materials 1307 provided with the distribution. 1309 - Neither the name of Internet Society, IETF or IETF Trust, 1310 nor the names of specific contributors, may be used to endorse 1311 or promote products derived from this software without 1312 specific prior written permission. 1314 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 1315 CONTRIBUTORS 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, 1316 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 1317 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 1318 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 1319 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 1321 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 1322 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 1323 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 1324 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 1325 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 1326 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 1327 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 1329 This version of this MIB module is part of RFC XXXX; 1330 see the RFC itself for full legal notices." 1332 -- NOTE to RFC editor: replace XXXX with actual RFC number 1333 -- for this document and remove this note 1335 REVISION "200912080000Z" 1336 DESCRIPTION "The initial version, published in RFC XXXX." 1337 -- NOTE to RFC editor: replace XXXX with actual RFC number 1338 -- for this document and remove this note 1340 ::= { snmpModules xxxx } 1341 -- RFC Ed.: replace xxxx with IANA-assigned number and 1342 -- remove this note 1344 -- ************************************************ 1345 -- subtrees of the TLSTM-MIB 1346 -- ************************************************ 1348 tlstmNotifications OBJECT IDENTIFIER ::= { tlstmMIB 0 } 1349 tlstmIdentities OBJECT IDENTIFIER ::= { tlstmMIB 1 } 1350 tlstmObjects OBJECT IDENTIFIER ::= { tlstmMIB 2 } 1351 tlstmConformance OBJECT IDENTIFIER ::= { tlstmMIB 3 } 1353 -- ************************************************ 1354 -- tlstmObjects - Objects 1355 -- ************************************************ 1357 snmpTLSTCPDomain OBJECT-IDENTITY 1358 STATUS current 1359 DESCRIPTION 1360 "The SNMP over TLS transport domain. The corresponding 1361 transport address is of type SnmpTLSAddress. 1363 The securityName prefix to be associated with the 1364 snmpTLSTCPDomain is 'tls'. This prefix may be used by 1365 security models or other components to identify which secure 1366 transport infrastructure authenticated a securityName." 1368 ::= { snmpDomains xx } 1370 -- RFC Ed.: replace xx with IANA-assigned number and 1371 -- remove this note 1372 -- RFC Ed.: replace 'tls' with the actual IANA assigned prefix string 1373 -- if 'tls' is not assigned to this document. 1375 snmpDTLSUDPDomain OBJECT-IDENTITY 1376 STATUS current 1377 DESCRIPTION 1378 "The SNMP over DTLS/UDP transport domain. The corresponding 1379 transport address is of type SnmpTLSAddress. 1381 The securityName prefix to be associated with the 1382 snmpDTLSUDPDomain is 'dudp'. This prefix may be used by 1383 security models or other components to identify which secure 1384 transport infrastructure authenticated a securityName." 1386 ::= { snmpDomains yy } 1388 -- RFC Ed.: replace yy with IANA-assigned number and 1389 -- remove this note 1391 -- RFC Ed.: replace 'dudp' with the actual IANA assigned prefix string 1392 -- if 'dtls' is not assigned to this document. 1394 snmpDTLSSCTPDomain OBJECT-IDENTITY 1395 STATUS current 1396 DESCRIPTION 1397 "The SNMP over DTLS/SCTP transport domain. The corresponding 1398 transport address is of type SnmpTLSAddress. 1400 The securityName prefix to be associated with the 1401 snmpDTLSSCTPDomain is 'dsct'. This prefix may be used by 1402 security models or other components to identify which secure 1403 transport infrastructure authenticated a securityName." 1405 ::= { snmpDomains zz } 1407 -- RFC Ed.: replace zz with IANA-assigned number and 1408 -- remove this note 1410 -- RFC Ed.: replace 'dsct' with the actual IANA assigned prefix string 1411 -- if 'dtls' is not assigned to this document. 1413 SnmpTLSAddress ::= TEXTUAL-CONVENTION 1414 DISPLAY-HINT "1a" 1415 STATUS current 1416 DESCRIPTION 1417 "Represents a IPv4 address, an IPv6 address or an US-ASCII 1418 encoded hostname and port number. 1420 An IPv4 address must be in dotted decimal format followed by a 1421 colon ':' (US-ASCII character 0x3A) and a decimal port number 1422 in US-ASCII. 1424 An IPv6 address must be a colon separated format, surrounded 1425 by square brackets ('[', US-ASCII character 0x5B, and ']', 1426 US-ASCII character 0x5D), followed by a colon ':' (US-ASCII 1427 character 0x3A) and a decimal port number in US-ASCII. 1429 A hostname is always in US-ASCII (as per RFC1033); 1430 internationalized hostnames are encoded in US-ASCII as 1431 specified in RFC 3490. The hostname is followed by a colon 1432 ':' (US-ASCII character 0x3A) and a decimal port number in 1433 US-ASCII. The name SHOULD be fully qualified whenever 1434 possible. 1436 Values of this textual convention may not be directly usable 1437 as transport-layer addressing information, and may require 1438 run-time resolution. As such, applications that write them 1439 must be prepared for handling errors if such values are not 1440 supported, or cannot be resolved (if resolution occurs at the 1441 time of the management operation). 1443 The DESCRIPTION clause of TransportAddress objects that may 1444 have SnmpTLSAddress values must fully describe how (and 1445 when) such names are to be resolved to IP addresses and vice 1446 versa. 1448 This textual convention SHOULD NOT be used directly in object 1449 definitions since it restricts addresses to a specific 1450 format. However, if it is used, it MAY be used either on its 1451 own or in conjunction with TransportAddressType or 1452 TransportDomain as a pair. 1454 When this textual convention is used as a syntax of an index 1455 object, there may be issues with the limit of 128 1456 sub-identifiers specified in SMIv2 (STD 58). It is RECOMMENDED 1457 that all MIB documents using this textual convention make 1458 explicit any limitations on index component lengths that 1459 management software must observe. This may be done either by 1460 including SIZE constraints on the index components or by 1461 specifying applicable constraints in the conceptual row 1462 DESCRIPTION clause or in the surrounding documentation." 1463 REFERENCE 1464 "RFC 1033: DOMAIN ADMINISTRATORS OPERATIONS GUIDE 1465 RFC 3490: Internationalizing Domain Names in Applications 1466 RFC 3986: Uniform Resource Identifier (URI): Generic Syntax 1467 RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 1468 " 1469 SYNTAX OCTET STRING (SIZE (1..255)) 1471 Fingerprint ::= TEXTUAL-CONVENTION 1472 DISPLAY-HINT "1x:254x" 1473 STATUS current 1474 DESCRIPTION 1475 "A Fingerprint value that can be used to uniquely reference 1476 other data of potentially arbitrary length. 1478 A Fingerprint value is composed of a 1-octet hashing algorithm 1479 identifier followed by the fingerprint value. The octet value 1480 encoded is taken from the IANA TLS HashAlgorithm Registry 1481 (RFC5246). The remaining octets are filled using the results 1482 of the hashing algorithm. 1484 This TEXTUAL-CONVENTION allows for a zero-length (blank) 1485 Fingerprint value for use in tables where the fingerprint value 1486 may be optional. MIB definitions or implementations may refuse 1487 to accept a zero-length value as appropriate." 1488 REFERENCE 1489 "RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 1490 " 1491 SYNTAX OCTET STRING (SIZE (0..255)) 1493 -- Identities 1495 tlstmCertToTSNMIdentities OBJECT IDENTIFIER ::= { tlstmIdentities 1 } 1497 tlstmCertSpecified OBJECT-IDENTITY 1498 STATUS current 1499 DESCRIPTION "Directly specifies the tmSecurityName to be used for 1500 this certificate. The value of the tmSecurityName to 1501 use is specified in the tlstmCertToTSNData column. 1502 The column must contain a SnmpAdminString compliant 1503 value or contains a zero length string then the 1504 mapping will be considered a failure." 1505 ::= { tlstmCertToTSNMIdentities 1 } 1507 tlstmCertSANRFC822Name OBJECT-IDENTITY 1508 STATUS current 1509 DESCRIPTION "Maps a subjectAltName's rfc822Name to a 1510 tmSecurityName. The local part of the rfc822Name is 1511 passed unaltered but the host-part of the name must 1512 be passed in lower case. 1514 Example rfc822Name Field: FooBar@Example.COM 1515 is mapped to tmSecurityName: FooBar@exmaple.com" 1516 ::= { tlstmCertToTSNMIdentities 2 } 1518 tlstmCertSANDNSName OBJECT-IDENTITY 1519 STATUS current 1520 DESCRIPTION "Maps a subjectAltName's dNSName to a 1521 tmSecurityName by directly passing the value without 1522 any transformations." 1523 ::= { tlstmCertToTSNMIdentities 3 } 1525 tlstmCertSANIpAddress OBJECT-IDENTITY 1526 STATUS current 1527 DESCRIPTION "Maps a subjectAltName's ipAddress to a 1528 tmSecurityName by transforming the binary encoded 1529 address as follows: 1531 1) for IPv4 the value is converted into a decimal 1532 dotted quad address (e.g. '192.0.2.1') 1534 2) for IPv6 addresses the value is converted into a 1535 32-character hexadecimal string without any colon 1536 separators. 1538 Note that the resulting length is the maximum 1539 length supported by the View-Based Access Control 1540 Model (VACM). Note that using both the Transport 1541 Security Model's support for transport prefixes 1542 (see the SNMP-TSM-MIB's 1543 snmpTsmConfigurationUsePrefix object for details) 1544 will result in securityName lengths that exceed 1545 what VACM can handle." 1546 ::= { tlstmCertToTSNMIdentities 4 } 1548 tlstmCertSANAny OBJECT-IDENTITY 1549 STATUS current 1550 DESCRIPTION "Maps any of the following fields using the 1551 corresponding mapping algorithms: 1553 |------------+------------------------| 1554 | Type | Algorithm | 1555 |------------+------------------------| 1556 | rfc822Name | tlstmCertSANRFC822Name | 1557 | dNSName | tlstmCertSANDNSName | 1558 | ipAddress | tlstmCertSANIpAddress | 1559 |------------+------------------------| 1560 The first matching subjectAltName value found in the 1561 certificate any of the above types MUST be used when 1562 deriving the tmSecurityName." 1563 ::= { tlstmCertToTSNMIdentities 5 } 1565 tlstmCertCommonName OBJECT-IDENTITY 1566 STATUS current 1567 DESCRIPTION "Maps a certificate's CommonName to a 1568 tmSecurityName by directly passing the value without 1569 any transformations." 1570 ::= { tlstmCertToTSNMIdentities 6 } 1572 -- The tlstmSession Group 1574 tlstmSession OBJECT IDENTIFIER ::= { tlstmObjects 1 } 1576 tlstmSessionOpens OBJECT-TYPE 1577 SYNTAX Counter32 1578 MAX-ACCESS read-only 1579 STATUS current 1580 DESCRIPTION 1581 "The number of times an openSession() request has been 1582 executed as an (D)TLS client, whether it succeeded or failed." 1583 ::= { tlstmSession 1 } 1585 tlstmSessionCloses OBJECT-TYPE 1586 SYNTAX Counter32 1587 MAX-ACCESS read-only 1588 STATUS current 1589 DESCRIPTION 1590 "The number of times a closeSession() request has been 1591 executed as an (D)TLS client, whether it succeeded or failed." 1592 ::= { tlstmSession 2 } 1594 tlstmSessionOpenErrors OBJECT-TYPE 1595 SYNTAX Counter32 1596 MAX-ACCESS read-only 1597 STATUS current 1598 DESCRIPTION 1599 "The number of times an openSession() request failed to open a 1600 session as a (D)TLS client, for any reason." 1601 ::= { tlstmSession 3 } 1603 tlstmSessionNoAvailableSessions OBJECT-TYPE 1604 SYNTAX Counter32 1605 MAX-ACCESS read-only 1606 STATUS current 1607 DESCRIPTION 1608 "The number of times an outgoing message was dropped because 1609 the session associated with the passed tmStateReference was no 1610 longer (or was never) available." 1611 ::= { tlstmSession 4 } 1613 tlstmSessionInvalidClientCertificates OBJECT-TYPE 1614 SYNTAX Counter32 1615 MAX-ACCESS read-only 1616 STATUS current 1617 DESCRIPTION 1618 "The number of times an incoming session was not established 1619 on an (D)TLS server because the presented client certificate was 1620 invalid. Reasons for invalidation include, but are not 1621 limited to, cryptographic validation failures or lack of a 1622 suitable mapping row in the tlstmCertToTSNTable." 1623 ::= { tlstmSession 5 } 1625 tlstmSessionUnknownServerCertificate OBJECT-TYPE 1626 SYNTAX Counter32 1627 MAX-ACCESS read-only 1628 STATUS current 1629 DESCRIPTION 1630 "The number of times an outgoing session was not established 1631 on an (D)TLS client because the server certificate presented 1632 by a SNMP over (D)TLS server was invalid because no 1633 configured fingerprint or CA was acceptable to validate it. 1634 This may result because there was no entry in the 1635 tlstmAddrTable or because no path could be found to known 1636 certificate authority." 1637 ::= { tlstmSession 6 } 1639 tlstmSessionInvalidServerCertificates OBJECT-TYPE 1640 SYNTAX Counter32 1641 MAX-ACCESS read-only 1642 STATUS current 1643 DESCRIPTION 1644 "The number of times an outgoing session was not established 1645 on an (D)TLS client because the server certificate presented 1646 by an SNMP over (D)TLS server could not be validated even if 1647 the fingerprint or expected validation path was known. I.E., 1648 a cryptographic validation occurred during certificate 1649 validation processing. 1651 Reasons for invalidation include, but are not 1652 limited to, cryptographic validation failures." 1653 ::= { tlstmSession 7 } 1655 tlstmTLSProtectionErrors OBJECT-TYPE 1656 SYNTAX Counter32 1657 MAX-ACCESS read-only 1658 STATUS current 1659 DESCRIPTION 1660 "The number of times (D)TLS processing resulted in a message 1661 being discarded because it failed its integrity test, 1662 decryption processing or other (D)TLS processing." 1663 ::= { tlstmSession 8 } 1665 -- Configuration Objects 1667 tlstmConfig OBJECT IDENTIFIER ::= { tlstmObjects 2 } 1669 -- Certificate mapping 1671 tlstmCertificateMapping OBJECT IDENTIFIER ::= { tlstmConfig 1 } 1673 tlstmCertToTSNCount OBJECT-TYPE 1674 SYNTAX Unsigned32 1675 MAX-ACCESS read-only 1676 STATUS current 1677 DESCRIPTION 1678 "A count of the number of entries in the tlstmCertToTSNTable" 1679 ::= { tlstmCertificateMapping 1 } 1681 tlstmCertToTSNTableLastChanged OBJECT-TYPE 1682 SYNTAX TimeStamp 1683 MAX-ACCESS read-only 1684 STATUS current 1685 DESCRIPTION 1686 "The value of sysUpTime.0 when the tlstmCertToTSNTable 1687 was last modified through any means, or 0 if it has not been 1688 modified since the command responder was started." 1689 ::= { tlstmCertificateMapping 2 } 1691 tlstmCertToTSNTable OBJECT-TYPE 1692 SYNTAX SEQUENCE OF TlstmCertToTSNEntry 1693 MAX-ACCESS not-accessible 1694 STATUS current 1695 DESCRIPTION 1696 "A table listing the X.509 certificates known to the entity 1697 and the associated method for determining the SNMPv3 security 1698 name from a certificate. 1700 On an incoming (D)TLS/SNMP connection the client's presented 1701 certificate must be examined and validated based on an 1702 established trusted path from a CA certificate or self-signed 1703 public certificate (e.g. RFC5280). This table provides a 1704 mapping from a validated certificate to a tmSecurityName. 1705 This table does not provide any mechanisms for uploading 1706 trusted certificates; the transfer of any needed trusted 1707 certificates for path validation is expected to occur through 1708 an out-of-band transfer. 1710 Once the authenticity of a certificate has been verified, this 1711 table is consulted to determine the appropriate tmSecurityName 1712 to identify with the remote connection. This is done by 1713 considering each active row from this table in prioritized 1714 order according to its tlstmCertToTSNID value. Each row's 1715 tlstmCertToTSNFingerprint value determines whether the row is a 1716 match for the incoming connection: 1718 1) If the row's tlstmCertToTSNFingerprint value identifies 1719 the presented certificate then consider the row as a 1720 successful match. 1722 2) If the row's tlstmCertToTSNFingerprint value identifies 1723 a locally held copy of a trusted CA certificate and 1724 that CA certificated was used to validate the path to 1725 the presented certificate then consider the row as a 1726 successful match. 1728 Once a matching row has been found, the tlstmCertToTSNMapType 1729 value can be used to determine how the tmSecurityName to 1730 associate with the session should be determined. See the 1731 tlstmCertToTSNMapType column's DESCRIPTION for details on 1732 determining the tmSecurityName value. If it is impossible to 1733 determine a tmSecurityName from the row's data combined with the 1734 data presented in the certificate then additional rows MUST be 1735 searched looking for another potential match. If a resulting 1736 tmSecurityName mapped from a given row is not compatible with 1737 the needed requirements of a tmSecurityName (e.g., VACM imposes 1738 a 32-octet-maximum length and the certificate derived 1739 securityName could be longer) then it must be considered an 1740 invalid match and additional rows MUST be searched looking for 1741 another potential match. 1743 Missing values of tlstmCertToTSNID are acceptable and 1744 implementations should continue to the next highest numbered 1745 row. E.G., the table may legally contain only two rows with 1746 tlstmCertToTSNID values of 10 and 20. 1748 Users are encouraged to make use of certificates with 1749 subjectAltName fields that can be used as tmSecurityNames so 1750 that a single root CA certificate can allow all child 1751 certificate's subjectAltName to map directly to a tmSecurityName 1752 via a 1:1 transformation. However, this table is flexible to 1753 allow for situations where existing deployed certificate 1754 infrastructures do not provide adequate subjectAltName values 1755 for use as tmSecurityNames. Certificates may also be 1756 mapped to tmSecurityNames using the CommonName portion of the 1757 Subject field but usage of the CommonName field is deprecated. 1758 Direct mapping from each individual certificate fingerprint to 1759 a tmSecurityName is also possible but requires one entry in the 1760 table per tmSecurityName and requires more management operations 1761 to completely configure a device." 1762 ::= { tlstmCertificateMapping 3 } 1764 tlstmCertToTSNEntry OBJECT-TYPE 1765 SYNTAX TlstmCertToTSNEntry 1766 MAX-ACCESS not-accessible 1767 STATUS current 1768 DESCRIPTION 1769 "A row in the tlstmCertToTSNTable that specifies a mapping for 1770 an incoming (D)TLS certificate to a tmSecurityName to use for a 1771 connection." 1772 INDEX { tlstmCertToTSNID } 1773 ::= { tlstmCertToTSNTable 1 } 1775 TlstmCertToTSNEntry ::= SEQUENCE { 1776 tlstmCertToTSNID Unsigned32, 1777 tlstmCertToTSNFingerprint Fingerprint, 1778 tlstmCertToTSNMapType AutonomousType, 1779 tlstmCertToTSNData OCTET STRING, 1780 tlstmCertToTSNStorageType StorageType, 1781 tlstmCertToTSNRowStatus RowStatus 1782 } 1784 tlstmCertToTSNID OBJECT-TYPE 1785 SYNTAX Unsigned32 (1..4294967295) 1786 MAX-ACCESS not-accessible 1787 STATUS current 1788 DESCRIPTION 1789 "A unique, prioritized index for the given entry." 1790 ::= { tlstmCertToTSNEntry 1 } 1792 tlstmCertToTSNFingerprint OBJECT-TYPE 1793 SYNTAX Fingerprint (SIZE(1..255)) 1794 MAX-ACCESS read-create 1795 STATUS current 1796 DESCRIPTION 1797 "A cryptographic hash of a X.509 certificate. The results of 1798 a successful matching fingerprint to either the trusted CA in 1799 the certificate validation path or to the certificate itself 1800 is dictated by the tlstmCertToTSNMapType column." 1801 ::= { tlstmCertToTSNEntry 2 } 1803 tlstmCertToTSNMapType OBJECT-TYPE 1804 SYNTAX AutonomousType 1805 MAX-ACCESS read-create 1806 STATUS current 1807 DESCRIPTION 1808 "Specifies the mapping type for deriving a tmSecurityName from a 1809 certificate. Details for mapping of a particular type SHALL 1810 be specified in the DESCRIPTION clause of the OBJECT-IDENTITY 1811 that describes the mapping. If a mapping succeeds it will 1812 return a tmSecurityName for use by the TLSTM model and 1813 processing stops. 1815 If the resulting mapped value is not compatible with the 1816 needed requirements of a tmSecurityName (e.g., VACM imposes a 1817 32-octet-maximum length and the certificate derived 1818 securityName could be longer) then future rows MUST be 1819 searched for additional tlstmCertToTSNFingerprint matches to 1820 look for a mapping that succeeds." 1821 DEFVAL { tlstmCertSpecified } 1822 ::= { tlstmCertToTSNEntry 3 } 1824 tlstmCertToTSNData OBJECT-TYPE 1825 SYNTAX OCTET STRING (SIZE(0..1024)) 1826 MAX-ACCESS read-create 1827 STATUS current 1828 DESCRIPTION 1829 "Axillary data used as optional configuration information for 1830 a given mapping specified by the tlstmCertToTSNMapType column. 1831 Only some mapping systems will make use of this column. The 1832 value in this column MUST be ignored for any mapping type that 1833 does not require data present in this column." 1834 DEFVAL { "" } 1835 ::= { tlstmCertToTSNEntry 4 } 1837 tlstmCertToTSNStorageType OBJECT-TYPE 1838 SYNTAX StorageType 1839 MAX-ACCESS read-create 1840 STATUS current 1841 DESCRIPTION 1842 "The storage type for this conceptual row. Conceptual rows 1843 having the value 'permanent' need not allow write-access to 1844 any columnar objects in the row." 1845 DEFVAL { nonVolatile } 1846 ::= { tlstmCertToTSNEntry 5 } 1848 tlstmCertToTSNRowStatus OBJECT-TYPE 1849 SYNTAX RowStatus 1850 MAX-ACCESS read-create 1851 STATUS current 1852 DESCRIPTION 1853 "The status of this conceptual row. This object may be used 1854 to create or remove rows from this table. 1856 To create a row in this table, a manager must set this object 1857 to either createAndGo(4) or createAndWait(5). 1859 Until instances of all corresponding columns are appropriately 1860 configured, the value of the corresponding instance of the 1861 tlstmParamsRowStatus column is 'notReady'. 1863 In particular, a newly created row cannot be made active until 1864 the corresponding tlstmCertToTSNFingerprint, 1865 tlstmCertToTSNMapType, and tlstmCertToTSNData columns have been 1866 set. 1868 The following objects may not be modified while the 1869 value of this object is active(1): 1870 - tlstmCertToTSNFingerprint 1871 - tlstmCertToTSNMapType 1872 - tlstmCertToTSNData 1873 An attempt to set these objects while the value of 1874 tlstmParamsRowStatus is active(1) will result in 1875 an inconsistentValue error." 1876 ::= { tlstmCertToTSNEntry 6 } 1878 -- Maps tmSecurityNames to certificates for use by the SNMP-TARGET-MIB 1880 tlstmParamsCount OBJECT-TYPE 1881 SYNTAX Unsigned32 1882 MAX-ACCESS read-only 1883 STATUS current 1884 DESCRIPTION 1885 "A count of the number of entries in the tlstmParamsTable" 1886 ::= { tlstmCertificateMapping 4 } 1888 tlstmParamsTableLastChanged OBJECT-TYPE 1889 SYNTAX TimeStamp 1890 MAX-ACCESS read-only 1891 STATUS current 1892 DESCRIPTION 1893 "The value of sysUpTime.0 when the tlstmParamsTable 1894 was last modified through any means, or 0 if it has not been 1895 modified since the command responder was started." 1897 ::= { tlstmCertificateMapping 5 } 1899 tlstmParamsTable OBJECT-TYPE 1900 SYNTAX SEQUENCE OF TlstmParamsEntry 1901 MAX-ACCESS not-accessible 1902 STATUS current 1903 DESCRIPTION 1904 "This table extends the SNMP-TARGET-MIB's 1905 snmpTargetParamsTable with an additional (D)TLS client-side 1906 certificate fingerprint identifier to use when establishing 1907 new (D)TLS connections." 1908 ::= { tlstmCertificateMapping 6 } 1910 tlstmParamsEntry OBJECT-TYPE 1911 SYNTAX TlstmParamsEntry 1912 MAX-ACCESS not-accessible 1913 STATUS current 1914 DESCRIPTION 1915 "A conceptual row containing a fingerprint hash of a locally 1916 held certificate for a given snmpTargetParamsEntry. The 1917 values in this row should be ignored if the connection that 1918 needs to be established, as indicated by the SNMP-TARGET-MIB 1919 infrastructure, is not a certificate and (D)TLS based 1920 connection. The connection SHOULD NOT be established if the 1921 certificate fingerprint stored in this entry does not point to 1922 a valid locally held certificate or if it points to an unusable 1923 certificate (such as might happen when the certificate's 1924 expiration date has been reached)." 1925 INDEX { IMPLIED snmpTargetParamsName } 1926 ::= { tlstmParamsTable 1 } 1928 TlstmParamsEntry ::= SEQUENCE { 1929 tlstmParamsClientFingerprint Fingerprint, 1930 tlstmParamsStorageType StorageType, 1931 tlstmParamsRowStatus RowStatus 1932 } 1934 tlstmParamsClientFingerprint OBJECT-TYPE 1935 SYNTAX Fingerprint 1936 MAX-ACCESS read-create 1937 STATUS current 1938 DESCRIPTION 1939 "A cryptographic hash of a X.509 certificate. This object 1940 should store the hash of a locally held X.509 certificate that 1941 should be used when initiating a (D)TLS connection as a (D)TLS 1942 client." 1943 ::= { tlstmParamsEntry 1 } 1945 tlstmParamsStorageType OBJECT-TYPE 1946 SYNTAX StorageType 1947 MAX-ACCESS read-create 1948 STATUS current 1949 DESCRIPTION 1950 "The storage type for this conceptual row. Conceptual rows 1951 having the value 'permanent' need not allow write-access to 1952 any columnar objects in the row." 1953 DEFVAL { nonVolatile } 1954 ::= { tlstmParamsEntry 2 } 1956 tlstmParamsRowStatus OBJECT-TYPE 1957 SYNTAX RowStatus 1958 MAX-ACCESS read-create 1959 STATUS current 1960 DESCRIPTION 1961 "The status of this conceptual row. This object may be used 1962 to create or remove rows from this table. 1964 To create a row in this table, a manager must set this object 1965 to either createAndGo(4) or createAndWait(5). 1967 Until instances of all corresponding columns are appropriately 1968 configured, the value of the corresponding instance of the 1969 tlstmParamsRowStatus column is 'notReady'. 1971 In particular, a newly created row cannot be made active until 1972 the corresponding tlstmParamsClientFingerprint column has 1973 been set. 1975 The tlstmParamsClientFingerprint object may not be modified 1976 while the value of this object is active(1). 1978 An attempt to set these objects while the value of 1979 tlstmParamsRowStatus is active(1) will result in 1980 an inconsistentValue error. 1982 If this row is deleted it has no effect on the corresponding 1983 row in the targetParamsTable. 1985 If the corresponding row in the targetParamsTable is deleted 1986 then this row must be automatically removed." 1987 ::= { tlstmParamsEntry 3 } 1989 -- Lists expected certificate fingerprints to be presented by a DTLS 1990 -- server 1991 tlstmAddrCount OBJECT-TYPE 1992 SYNTAX Unsigned32 1993 MAX-ACCESS read-only 1994 STATUS current 1995 DESCRIPTION 1996 "A count of the number of entries in the tlstmAddrTable" 1997 ::= { tlstmCertificateMapping 7 } 1999 tlstmAddrTableLastChanged OBJECT-TYPE 2000 SYNTAX TimeStamp 2001 MAX-ACCESS read-only 2002 STATUS current 2003 DESCRIPTION 2004 "The value of sysUpTime.0 when the tlstmAddrTable 2005 was last modified through any means, or 0 if it has not been 2006 modified since the command responder was started." 2007 ::= { tlstmCertificateMapping 8 } 2009 tlstmAddrTable OBJECT-TYPE 2010 SYNTAX SEQUENCE OF TlstmAddrEntry 2011 MAX-ACCESS not-accessible 2012 STATUS current 2013 DESCRIPTION 2014 "This table extends the SNMP-TARGET-MIB's snmpTargetAddrTable 2015 with an expected (D)TLS server-side certificate identifier to 2016 expect when establishing a new (D)TLS connections. If a 2017 matching row in this table exists and the row is active then 2018 the fingerprint identifier from the tlstmAddrServerFingerprint 2019 columnshould be compared against the fingerprint of the 2020 certificate being presented by the server. If the fingerprint 2021 of the certificate presented by the server does not match the 2022 tlstmAddrServerFingerprint column's value then the connection 2023 MUST NOT be established. 2025 If a matching row exists with a zero-length 2026 tlstmAddrServerFingerprint value and the certificate can still 2027 be validated through another certificate validation path 2028 (e.g. RFC5280) then the server's presented identity should be 2029 checked against the value of the tlstmAddrServerIdentity 2030 column. If the server's identity does not match the reference 2031 identity found in the tlstmAddrServerIdentity column then the 2032 connection MUST NOT be established. A tlstmAddrServerIdentity 2033 may contain a '*' to match any server's identity or may 2034 contain a '*.' prefix to match any server identity from a 2035 given domain (e.g. '*.example.com'). 2037 If no matching row exists in this table then the connection 2038 SHOULD still proceed if another certificate validation path 2039 algorithm (e.g. RFC5280) can be followed to a configured trust 2040 anchor." 2041 ::= { tlstmCertificateMapping 9 } 2043 tlstmAddrEntry OBJECT-TYPE 2044 SYNTAX TlstmAddrEntry 2045 MAX-ACCESS not-accessible 2046 STATUS current 2047 DESCRIPTION 2048 "A conceptual row containing a copy of a certificate's 2049 fingerprint for a given snmpTargetAddrEntry. The values in 2050 this row should be ignored if the connection that needs to be 2051 established, as indicated by the SNMP-TARGET-MIB 2052 infrastructure, is not a (D)TLS based connection. If an 2053 tlstmAddrEntry exists for a given snmpTargetAddrEntry then the 2054 presented server certificate MUST match or the connection MUST 2055 NOT be established. If a row in this table does not exist to 2056 match a snmpTargetAddrEntry row then the connection SHOULD 2057 still proceed if some other certificate validation path 2058 algorithm (e.g. RFC5280) can be followed to a configured trust 2059 anchor." 2060 INDEX { IMPLIED snmpTargetAddrName } 2061 ::= { tlstmAddrTable 1 } 2063 TlstmAddrEntry ::= SEQUENCE { 2064 tlstmAddrServerFingerprint Fingerprint, 2065 tlstmAddrServerIdentity SnmpAdminString, 2066 tlstmAddrStorageType StorageType, 2067 tlstmAddrRowStatus RowStatus 2068 } 2070 tlstmAddrServerFingerprint OBJECT-TYPE 2071 SYNTAX Fingerprint 2072 MAX-ACCESS read-create 2073 STATUS current 2074 DESCRIPTION 2075 "A cryptographic hash of a public X.509 certificate. This 2076 object should store the hash of the public X.509 certificate 2077 that the remote server should present during the (D)TLS 2078 connection setup. The fingerprint of the presented 2079 certificate and this hash value MUST match exactly or the 2080 connection MUST NOT be established." 2081 DEFVAL { "" } 2082 ::= { tlstmAddrEntry 1 } 2084 tlstmAddrServerIdentity OBJECT-TYPE 2085 SYNTAX SnmpAdminString 2086 MAX-ACCESS read-create 2087 STATUS current 2088 DESCRIPTION 2089 "The reference identity to check against the identity 2090 presented by the remote system. A single ASCII '*' character 2091 (ASCII code 0x2a) may be used as a wildcard string and will 2092 match any presented server identity. A '*.' prefix may also 2093 be used to match any identity within a given domain 2094 (e.g. '*.example.com' will match both 'foo.example.com' and 2095 'bar.example.com')." 2096 REFERENCE "draft-saintandre-tls-server-id-check" 2097 DEFVAL { "*" } 2098 ::= { tlstmAddrEntry 2 } 2100 tlstmAddrStorageType OBJECT-TYPE 2101 SYNTAX StorageType 2102 MAX-ACCESS read-create 2103 STATUS current 2104 DESCRIPTION 2105 "The storage type for this conceptual row. Conceptual rows 2106 having the value 'permanent' need not allow write-access to 2107 any columnar objects in the row." 2108 DEFVAL { nonVolatile } 2109 ::= { tlstmAddrEntry 3 } 2111 tlstmAddrRowStatus OBJECT-TYPE 2112 SYNTAX RowStatus 2113 MAX-ACCESS read-create 2114 STATUS current 2115 DESCRIPTION 2116 "The status of this conceptual row. This object may be used 2117 to create or remove rows from this table. 2119 To create a row in this table, a manager must 2120 set this object to either createAndGo(4) or 2121 createAndWait(5). 2123 Until instances of all corresponding columns are 2124 appropriately configured, the value of the 2125 corresponding instance of the tlstmAddrRowStatus 2126 column is 'notReady'. 2128 In particular, a newly created row cannot be made active until 2129 the corresponding tlstmAddrServerFingerprint column has been 2130 set. 2132 The tlstmAddrServerFingerprint object may not be modified 2133 while the value of this object is active(1). 2135 An attempt to set these objects while the value of 2136 tlstmAddrRowStatus is active(1) will result in 2137 an inconsistentValue error. 2139 If this row is deleted it has no effect on the corresponding 2140 row in the targetAddrTable. 2142 If the corresponding row in the targetAddrTable is deleted 2143 then this row must be automatically removed." 2144 ::= { tlstmAddrEntry 4 } 2146 -- ************************************************ 2147 -- tlstmNotifications - Notifications Information 2148 -- ************************************************ 2150 tlstmServerCertificateUnknown NOTIFICATION-TYPE 2151 OBJECTS { tlstmSessionUnknownServerCertificate } 2152 STATUS current 2153 DESCRIPTION 2154 "Notification that the server certificate presented by a SNMP 2155 over (D)TLS server was invalid because no configured 2156 fingerprint or CA was acceptable to validate it. This may 2157 result because there was no entry in the tlstmAddrTable or 2158 because no path could be found to known certificate 2159 authority. 2161 To avoid notification loops, this notification MUST NOT be 2162 sent to servers that themselves have triggered the 2163 notification." 2164 ::= { tlstmNotifications 1 } 2166 tlstmServerInvalidCertificate NOTIFICATION-TYPE 2167 OBJECTS { tlstmAddrServerFingerprint, 2168 tlstmSessionInvalidServerCertificates} 2169 STATUS current 2170 DESCRIPTION 2171 "Notification that the server certificate presented by an SNMP 2172 over (D)TLS server could not be validated even if the 2173 fingerprint or expected validation path was known. I.E., a 2174 cryptographic validation occurred during certificate 2175 validation processing. 2177 To avoid notification loops, this notification MUST NOT be 2178 sent to servers that themselves have triggered the 2179 notification." 2180 ::= { tlstmNotifications 2 } 2182 -- ************************************************ 2183 -- tlstmCompliances - Conformance Information 2184 -- ************************************************ 2186 tlstmCompliances OBJECT IDENTIFIER ::= { tlstmConformance 1 } 2188 tlstmGroups OBJECT IDENTIFIER ::= { tlstmConformance 2 } 2190 -- ************************************************ 2191 -- Compliance statements 2192 -- ************************************************ 2194 tlstmCompliance MODULE-COMPLIANCE 2195 STATUS current 2196 DESCRIPTION 2197 "The compliance statement for SNMP engines that support the 2198 TLSTM-MIB" 2199 MODULE 2200 MANDATORY-GROUPS { tlstmStatsGroup, 2201 tlstmIncomingGroup, 2202 tlstmOutgoingGroup, 2203 tlstmNotificationGroup } 2204 ::= { tlstmCompliances 1 } 2206 -- ************************************************ 2207 -- Units of conformance 2208 -- ************************************************ 2209 tlstmStatsGroup OBJECT-GROUP 2210 OBJECTS { 2211 tlstmSessionOpens, 2212 tlstmSessionCloses, 2213 tlstmSessionOpenErrors, 2214 tlstmSessionNoAvailableSessions, 2215 tlstmSessionInvalidClientCertificates, 2216 tlstmSessionUnknownServerCertificate, 2217 tlstmSessionInvalidServerCertificates, 2218 tlstmTLSProtectionErrors 2219 } 2220 STATUS current 2221 DESCRIPTION 2222 "A collection of objects for maintaining 2223 statistical information of an SNMP engine which 2224 implements the SNMP TLS Transport Model." 2225 ::= { tlstmGroups 1 } 2227 tlstmIncomingGroup OBJECT-GROUP 2228 OBJECTS { 2229 tlstmCertToTSNCount, 2230 tlstmCertToTSNTableLastChanged, 2231 tlstmCertToTSNFingerprint, 2232 tlstmCertToTSNMapType, 2233 tlstmCertToTSNData, 2234 tlstmCertToTSNStorageType, 2235 tlstmCertToTSNRowStatus 2236 } 2237 STATUS current 2238 DESCRIPTION 2239 "A collection of objects for maintaining 2240 incoming connection certificate mappings to 2241 tmSecurityNames of an SNMP engine which implements the 2242 SNMP TLS Transport Model." 2243 ::= { tlstmGroups 2 } 2245 tlstmOutgoingGroup OBJECT-GROUP 2246 OBJECTS { 2247 tlstmParamsCount, 2248 tlstmParamsTableLastChanged, 2249 tlstmParamsClientFingerprint, 2250 tlstmParamsStorageType, 2251 tlstmParamsRowStatus, 2252 tlstmAddrCount, 2253 tlstmAddrTableLastChanged, 2254 tlstmAddrServerFingerprint, 2255 tlstmAddrServerIdentity, 2256 tlstmAddrStorageType, 2257 tlstmAddrRowStatus 2258 } 2259 STATUS current 2260 DESCRIPTION 2261 "A collection of objects for maintaining 2262 outgoing connection certificates to use when opening 2263 connections as a result of SNMP-TARGET-MIB settings." 2264 ::= { tlstmGroups 3 } 2266 tlstmNotificationGroup NOTIFICATION-GROUP 2267 NOTIFICATIONS { 2268 tlstmServerCertificateUnknown, 2269 tlstmServerInvalidCertificate 2270 } 2271 STATUS current 2272 DESCRIPTION 2273 "Notifications" 2274 ::= { tlstmGroups 4 } 2276 END 2278 8. Operational Considerations 2280 This section discusses various operational aspects of deploying 2281 TLSTM. 2283 8.1. Sessions 2285 A session is discussed throughout this document as meaning a security 2286 association between the (D)TLS client and the (D)TLS server. State 2287 information for the sessions are maintained in each TLSTM 2288 implementation and this information is created and destroyed as 2289 sessions are opened and closed. A "broken" session (one side up and 2290 one side down) can result if one side of a session is brought down 2291 abruptly (i.e., reboot, power outage, etc.). Whenever possible, 2292 implementations SHOULD provide graceful session termination through 2293 the use of disconnect messages. Implementations SHOULD also have a 2294 system in place for detecting "broken" sessions through the use of 2295 heartbeats [I-D.seggelmann-tls-dtls-heartbeat] or other detection 2296 mechanisms. 2298 Implementations SHOULD limit the lifetime of established sessions 2299 depending on the algorithms used for generation of the master session 2300 secret, the privacy and integrity algorithms used to protect 2301 messages, the environment of the session, the amount of data 2302 transferred, and the sensitivity of the data. 2304 8.2. Notification Receiver Credential Selection 2306 When an SNMP engine needs to establish an outgoing session for 2307 notifications, the snmpTargetParamsTable includes an entry for the 2308 snmpTargetParamsSecurityName of the target. However, the receiving 2309 SNMP engine (Server) does not know which (D)TLS certificate to offer 2310 to the Client so that the tmSecurityName identity-authentication will 2311 be successful. 2313 One solution is to maintain a one-to-one mapping between certificates 2314 and incoming ports for notification receivers. This can be handled 2315 at the Notification Originator by configuring the snmpTargetAddrTable 2316 (snmpTargetAddrTDomain and snmpTargetAddrTAddress) and requiring the 2317 receiving SNMP engine to monitor multiple incoming static ports based 2318 on which principals are capable of receiving notifications. 2320 Implementations MAY also choose to designate a single Notification 2321 Receiver Principal to receive all incoming notifications or select an 2322 implementation specific method of selecting a server certificate to 2323 present to clients. 2325 8.3. contextEngineID Discovery 2327 Most Command Responders have contextEngineIDs that are identical to 2328 the USM securityEngineID. USM provides a discovery service that 2329 allows Command Generators to determine a securityEngineID and thus a 2330 default contextEngineID to use. Because the TLS Transport Model does 2331 not make use of a securityEngineID, it may be difficult for Command 2332 Generators to discover a suitable default contextEngineID. 2333 Implementations should consider offering another engineID discovery 2334 mechanism to continue providing Command Generators with a suitable 2335 contextEngineID mechanism. A recommended discovery solution is 2336 documented in [RFC5343]. 2338 8.4. Transport Considerations 2340 This document defines how SNMP messages can be transmitted over the 2341 TLS and DTLS based protocols. Each of these protocols are 2342 additionally based on other transports (TCP, UDP and SCTP). These 2343 three protocols also have operational considerations that must be 2344 taken into consideration when selecting a (D)TLS based protocol to 2345 use such as its performance in degraded or limited networks. It is 2346 beyond the scope of this document to summarize the characteristics of 2347 these transport mechanisms. Please refer to the base protocol 2348 documents for details on messaging considerations with respect to MTU 2349 size, fragmentation, performance in lossy-networks, etc. 2351 9. Security Considerations 2353 This document describes a transport model that permits SNMP to 2354 utilize (D)TLS security services. The security threats and how the 2355 (D)TLS transport model mitigates these threats are covered in detail 2356 throughout this document. Security considerations for DTLS are 2357 covered in [RFC4347] and security considerations for TLS are 2358 described in Section 11 and Appendices D, E, and F of TLS 1.2 2359 [RFC5246]. DTLS adds to the security considerations of TLS only 2360 because it is more vulnerable to denial of service attacks. A random 2361 cookie exchange was added to the handshake to prevent anonymous 2362 denial of service attacks. RFC 4347 recommends that the cookie 2363 exchange is utilized for all handshakes and therefore this 2364 specification also RECOMMENDEDs that implementers also support this 2365 cookie exchange. 2367 9.1. Certificates, Authentication, and Authorization 2369 Implementations are responsible for providing a security certificate 2370 installation and configuration mechanism. Implementations SHOULD 2371 support certificate revocation lists. 2373 (D)TLS provides for authentication of the identity of both the (D)TLS 2374 server and the (D)TLS client. Access to MIB objects for the 2375 authenticated principal MUST be enforced by an access control 2376 subsystem (e.g. the VACM). 2378 Authentication of the Command Generator principal's identity is 2379 important for use with the SNMP access control subsystem to ensure 2380 that only authorized principals have access to potentially sensitive 2381 data. The authenticated identity of the Command Generator 2382 principal's certificate is mapped to an SNMP model-independent 2383 securityName for use with SNMP access control. 2385 The (D)TLS handshake only provides assurance that the certificate of 2386 the authenticated identity has been signed by an configured accepted 2387 Certificate Authority. (D)TLS has no way to further authorize or 2388 reject access based on the authenticated identity. An Access Control 2389 Model (such as the VACM) provides access control and authorization of 2390 a Command Generator's requests to a Command Responder and a 2391 Notification Responder's authorization to receive Notifications from 2392 a Notification Originator. However to avoid man-in-the-middle 2393 attacks both ends of the (D)TLS based connection MUST check the 2394 certificate presented by the other side against what was expected. 2395 For example, Command Generators must check that the Command Responder 2396 presented and authenticated itself with a X.509 certificate that was 2397 expected. Not doing so would allow an impostor, at a minimum, to 2398 present false data, receive sensitive information and/or provide a 2399 false belief that configuration was actually received and acted upon. 2400 Authenticating and verifying the identity of the (D)TLS server and 2401 the (D)TLS client for all operations ensures the authenticity of the 2402 SNMP engine that provides MIB data. 2404 The instructions found in the DESCRIPTION clause of the 2405 tlstmCertToTSNTable object must be followed exactly. It is also 2406 important that the rows of the table be searched in prioritized order 2407 starting with the row containing the lowest numbered tlstmCertToTSNID 2408 value. 2410 9.2. Use with SNMPv1/SNMPv2c Messages 2412 The SNMPv1 and SNMPv2c message processing described in [RFC3584] (BCP 2413 74) always selects the SNMPv1 or SNMPv2c Security Models, 2414 respectively. Both of these and the User-based Security Model 2415 typically used with SNMPv3 derive the securityName and securityLevel 2416 from the SNMP message received, even when the message was received 2417 over a secure transport. Access control decisions are therefore made 2418 based on the contents of the SNMP message, rather than using the 2419 authenticated identity and securityLevel provided by the SSH 2420 Transport Model. 2422 9.3. MIB Module Security 2424 There are a number of management objects defined in this MIB module 2425 with a MAX-ACCESS clause of read-write and/or read-create. Such 2426 objects may be considered sensitive or vulnerable in some network 2427 environments. The support for SET operations in a non-secure 2428 environment without proper protection can have a negative effect on 2429 network operations. These are the tables and objects and their 2430 sensitivity/vulnerability: 2432 o The tlstmParamsTable can be used to change the outgoing X.509 2433 certificate used to establish a (D)TLS connection. Modification 2434 to objects in this table need to be adequately authenticated since 2435 modification to values in this table will have profound impacts to 2436 the security of outbound connections from the device. Since 2437 knowledge of authorization rules and certificate usage mechanisms 2438 may be considered sensitive, protection from disclosure of the 2439 SNMP traffic via encryption is also highly recommended. 2441 o The tlstmAddrTable can be used to change the expectations of the 2442 certificates presented by a remote (D)TLS server. Modification to 2443 objects in this table need to be adequately authenticated since 2444 modification to values in this table will have profound impacts to 2445 the security of outbound connections from the device. Since 2446 knowledge of authorization rules and certificate usage mechanisms 2447 may be considered sensitive, protection from disclosure of the 2448 SNMP traffic via encryption is also highly recommended. 2450 o The tlstmCertToTSNTable is used to specify the mapping of incoming 2451 X.509 certificates to tmSecurityNames which eventually get mapped 2452 to a SNMPv3 securityName. Modification to objects in this table 2453 need to be adequately authenticated since modification to values 2454 in this table will have profound impacts to the security of 2455 incoming connections to the device. Since knowledge of 2456 authorization rules and certificate usage mechanisms may be 2457 considered sensitive, protection from disclosure of the SNMP 2458 traffic via encryption is also highly recommended. 2460 Some of the readable objects in this MIB module (i.e., objects with a 2461 MAX-ACCESS other than not-accessible) may be considered sensitive or 2462 vulnerable in some network environments. It is thus important to 2463 control even GET and/or NOTIFY access to these objects and possibly 2464 to even encrypt the values of these objects when sending them over 2465 the network via SNMP. These are the tables and objects and their 2466 sensitivity/vulnerability: 2468 o This MIB contains a collection of counters that monitor the (D)TLS 2469 connections being established with a device. Since knowledge of 2470 connection and certificate usage mechanisms may be considered 2471 sensitive, protection from disclosure of the SNMP traffic via 2472 encryption is also highly recommended. 2474 SNMP versions prior to SNMPv3 did not include adequate security. 2475 Even if the network itself is secure (for example by using IPsec), 2476 even then, there is no control as to who on the secure network is 2477 allowed to access and GET/SET (read/change/create/delete) the objects 2478 in this MIB module. 2480 It is RECOMMENDED that implementers consider the security features as 2481 provided by the SNMPv3 framework (see [RFC3410], section 8), 2482 including full support for the SNMPv3 cryptographic mechanisms (for 2483 authentication and privacy). 2485 Further, deployment of SNMP versions prior to SNMPv3 is NOT 2486 RECOMMENDED. Instead, it is RECOMMENDED to deploy SNMPv3 and to 2487 enable cryptographic security. It is then a customer/operator 2488 responsibility to ensure that the SNMP entity giving access to an 2489 instance of this MIB module is properly configured to give access to 2490 the objects only to those principals (users) that have legitimate 2491 rights to indeed GET or SET (change/create/delete) them. 2493 10. IANA Considerations 2495 IANA is requested to assign: 2497 1. a TCP port number above 1023 in the 2498 http://www.iana.org/assignments/port-numbers registry which will 2499 be the default port for receipt of SNMP command messages over a 2500 TLS Transport Model as defined in this document, 2502 2. a TCP port number above 1023 in the 2503 http://www.iana.org/assignments/port-numbers registry which will 2504 be the default port for receipt of SNMP notification messages 2505 over a TLS Transport Model as defined in this document, 2507 3. a UDP port number above 1023 in the 2508 http://www.iana.org/assignments/port-numbers registry which will 2509 be the default port for receipt of SNMP command messages over a 2510 DTLS/UDP connection as defined in this document, 2512 4. a UDP port number above 1023 in the 2513 http://www.iana.org/assignments/port-numbers registry which will 2514 be the default port for receipt of SNMP notification messages 2515 over a DTLS/UDP connection as defined in this document, 2517 5. a SCTP port number above 1023 in the 2518 http://www.iana.org/assignments/port-numbers registry which will 2519 be the default port for receipt of SNMP command messages over a 2520 DTLS/SCTP connection as defined in this document, 2522 6. a SCTP port number above 1023 in the 2523 http://www.iana.org/assignments/port-numbers registry which will 2524 be the default port for receipt of SNMP notification messages 2525 over a DTLS/SCTP connection as defined in this document, 2527 7. an SMI number under snmpDomains for the snmpTLSTCPDomain object 2528 identifier, 2530 8. an SMI number under snmpDomains for the snmpDTLSUDPDomain object 2531 identifier, 2533 9. an SMI number under snmpDomains for the snmpDTLSSCTPDomain 2534 object identifier, 2536 10. a SMI number under snmpModules, for the MIB module in this 2537 document, 2539 11. "tls" as the corresponding prefix for the snmpTLSTCPDomain in 2540 the SNMP Transport Model registry, 2542 12. "dudp" as the corresponding prefix for the snmpDTLSUDPDomain in 2543 the SNMP Transport Model registry, 2545 13. "dsct" as the corresponding prefix for the snmpDTLSSCTPDomain in 2546 the SNMP Transport Model registry; 2548 If possible, IANA is requested to use matching port numbers for all 2549 assignments for SNMP Commands being sent over TLS, DTLS/UDP, DTLS/ 2550 SCTP. 2552 If possible, IANA is requested to use matching port numbers for all 2553 assignments for SNMP Notifications being sent over TLS, DTLS/UDP, 2554 DTLS/SCTP. 2556 Editor's note: this section should be replaced with appropriate 2557 descriptive assignment text after IANA assignments are made and prior 2558 to publication. 2560 11. Acknowledgements 2562 This document closely follows and copies the Secure Shell Transport 2563 Model for SNMP defined by David Harrington and Joseph Salowey in 2564 [RFC5292]. 2566 This document was reviewed by the following people who helped provide 2567 useful comments (in alphabetical order): Andy Donati, Pasi Eronen, 2568 David Harrington, Jeffrey Hutzelman, Alan Luchuk, Randy Presuhn, Ray 2569 Purvis, Joseph Salowey, Jurgen Schonwalder, Dave Shield. 2571 This work was supported in part by the United States Department of 2572 Defense. Large portions of this document are based on work by 2573 General Dynamics C4 Systems and the following individuals: Brian 2574 Baril, Kim Bryant, Dana Deluca, Dan Hanson, Tim Huemiller, John 2575 Holzhauer, Colin Hoogeboom, Dave Kornbau, Chris Knaian, Dan Knaul, 2576 Charles Limoges, Steve Moccaldi, Gerardo Orlando, and Brandon Yip. 2578 12. References 2580 12.1. Normative References 2582 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2583 Requirement Levels", BCP 14, RFC 2119, March 1997. 2585 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2586 Schoenwaelder, Ed., "Structure of Management Information 2587 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 2589 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2590 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 2591 STD 58, RFC 2579, April 1999. 2593 [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 2594 "Conformance Statements for SMIv2", STD 58, RFC 2580, 2595 April 1999. 2597 [RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An 2598 Architecture for Describing Simple Network Management 2599 Protocol (SNMP) Management Frameworks", STD 62, RFC 3411, 2600 December 2002. 2602 [RFC3413] Levi, D., Meyer, P., and B. Stewart, "Simple Network 2603 Management Protocol (SNMP) Applications", STD 62, 2604 RFC 3413, December 2002. 2606 [RFC3414] Blumenthal, U. and B. Wijnen, "User-based Security Model 2607 (USM) for version 3 of the Simple Network Management 2608 Protocol (SNMPv3)", STD 62, RFC 3414, December 2002. 2610 [RFC3415] Wijnen, B., Presuhn, R., and K. McCloghrie, "View-based 2611 Access Control Model (VACM) for the Simple Network 2612 Management Protocol (SNMP)", STD 62, RFC 3415, 2613 December 2002. 2615 [RFC3418] Presuhn, R., "Management Information Base (MIB) for the 2616 Simple Network Management Protocol (SNMP)", STD 62, 2617 RFC 3418, December 2002. 2619 [RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen, 2620 "Coexistence between Version 1, Version 2, and Version 3 2621 of the Internet-standard Network Management Framework", 2622 BCP 74, RFC 3584, August 2003. 2624 [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2625 Security", RFC 4347, April 2006. 2627 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2628 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2630 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2631 Housley, R., and W. Polk, "Internet X.509 Public Key 2632 Infrastructure Certificate and Certificate Revocation List 2633 (CRL) Profile", RFC 5280, May 2008. 2635 [RFC5590] Harrington, D. and J. Schoenwaelder, "Transport Subsystem 2636 for the Simple Network Management Protocol (SNMP)", 2637 RFC 5590, June 2009. 2639 [RFC5591] Harrington, D. and W. Hardaker, "Transport Security Model 2640 for the Simple Network Management Protocol (SNMP)", 2641 RFC 5591, June 2009. 2643 12.2. Informative References 2645 [RFC2522] Karn, P. and W. Simpson, "Photuris: Session-Key Management 2646 Protocol", RFC 2522, March 1999. 2648 [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, 2649 "Introduction and Applicability Statements for Internet- 2650 Standard Management Framework", RFC 3410, December 2002. 2652 [RFC4306] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", 2653 RFC 4306, December 2005. 2655 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 2656 and T. Wright, "Transport Layer Security (TLS) 2657 Extensions", RFC 4366, April 2006. 2659 [RFC5292] Chen, E. and S. Sangli, "Address-Prefix-Based Outbound 2660 Route Filter for BGP-4", RFC 5292, August 2008. 2662 [RFC5343] Schoenwaelder, J., "Simple Network Management Protocol 2663 (SNMP) Context EngineID Discovery", RFC 5343, 2664 September 2008. 2666 [I-D.saintandre-tls-server-id-check] 2667 Saint-Andre, P., Zeilenga, K., Hodges, J., and B. Morgan, 2668 "Best Practices for Checking of Server Identities in the 2669 Context of Transport Layer Security (TLS)". 2671 [I-D.seggelmann-tls-dtls-heartbeat] 2672 Seggelmann, R., Tuexen, M., and M. Williams, "Transport 2673 Layer Security and Datagram Transport Layer Security 2674 Heartbeat Extension". 2676 [AES] National Institute of Standards, "Specification for the 2677 Advanced Encryption Standard (AES)". 2679 [DES] National Institute of Standards, "American National 2680 Standard for Information Systems-Data Link Encryption". 2682 [DSS] National Institute of Standards, "Digital Signature 2683 Standard". 2685 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 2686 Obtaining Digital Signatures and Public-Key 2687 Cryptosystems". 2689 [X509] , ITU., "INFORMATION TECHNOLOGY OPEN SYSTEMS 2690 INTERCONNECTION THE DIRECTORY: PUBLIC-KEY AND ATTRIBUTE 2691 CERTIFICATE FRAMEWORKS". 2693 Appendix A. (D)TLS Overview 2695 The (D)TLS protocol is composed of two layers: the (D)TLS Record 2696 Protocol and the (D)TLS Handshake Protocol. The following 2697 subsections provide an overview of these two layers. Please refer to 2698 [RFC4347] for a complete description of the protocol. 2700 A.1. The (D)TLS Record Protocol 2702 At the lowest layer, layered on top of the transport control protocol 2703 or a datagram transport protocol (e.g. UDP or SCTP) is the (D)TLS 2704 Record Protocol. 2706 The (D)TLS Record Protocol provides security that has three basic 2707 properties: 2709 o The session can be confidential. Symmetric cryptography is used 2710 for data encryption (e.g., [AES], [DES] etc.). The keys for this 2711 symmetric encryption are generated uniquely for each session and 2712 are based on a secret negotiated by another protocol (such as the 2713 (D)TLS Handshake Protocol). The Record Protocol can also be used 2714 without encryption. 2716 o Messages can have data integrity. Message transport includes a 2717 message integrity check using a keyed MAC. Secure hash functions 2718 (e.g., SHA, MD5, etc.) are used for MAC computations. The Record 2719 Protocol can operate without a MAC, but is generally only used in 2720 this mode while another protocol is using the Record Protocol as a 2721 transport for negotiating security parameters. 2723 o Messages are protected against replay. (D)TLS uses explicit 2724 sequence numbers and integrity checks. DTLS uses a sliding window 2725 to protect against replay of messages within a session. 2727 (D)TLS also provides protection against replay of entire sessions. 2728 In a properly-implemented keying material exchange, both sides will 2729 generate new random numbers for each exchange. This results in 2730 different encryption and integrity keys for every session. 2732 A.2. The (D)TLS Handshake Protocol 2734 The (D)TLS Record Protocol is used for encapsulation of various 2735 higher-level protocols. One such encapsulated protocol, the (D)TLS 2736 Handshake Protocol, allows the server and client to authenticate each 2737 other and to negotiate an integrity algorithm, an encryption 2738 algorithm and cryptographic keys before the application protocol 2739 transmits or receives its first octet of data. Only the (D)TLS 2740 client can initiate the handshake protocol. The (D)TLS Handshake 2741 Protocol provides security that has four basic properties: 2743 o The peer's identity can be authenticated using asymmetric (public 2744 key) cryptography (e.g., RSA [RSA], DSS [DSS], etc.). This 2745 authentication can be made optional, but is generally required by 2746 at least one of the peers. 2748 (D)TLS supports three authentication modes: authentication of both 2749 the server and the client, server authentication with an 2750 unauthenticated client, and total anonymity. For authentication 2751 of both entities, each entity provides a valid certificate chain 2752 leading to an acceptable certificate authority. Each entity is 2753 responsible for verifying that the other's certificate is valid 2754 and has not expired or been revoked. See 2755 [I-D.saintandre-tls-server-id-check] for further details on 2756 standardized processing when checking server certificate 2757 identities. 2759 o The negotiation of a shared secret is secure: the negotiated 2760 secret is unavailable to eavesdroppers, and for any authenticated 2761 handshake the secret cannot be obtained, even by an attacker who 2762 can place himself in the middle of the session. 2764 o The negotiation is not vulnerable to malicious modification: it is 2765 infeasible for an attacker to modify negotiation communication 2766 without being detected by the parties to the communication. 2768 o DTLS uses a stateless cookie exchange to protect against anonymous 2769 denial of service attacks and has retransmission timers, sequence 2770 numbers, and counters to handle message loss, reordering, and 2771 fragmentation. 2773 Appendix B. PKIX Certificate Infrastructure 2775 Users of a public key from a PKIX / X.509 certificate can be be 2776 confident that the associated private key is owned by the correct 2777 remote subject (person or system) with which an encryption or digital 2778 signature mechanism will be used. This confidence is obtained 2779 through the use of public key certificates, which are data structures 2780 that bind public key values to subjects. The binding is asserted by 2781 having a trusted CA digitally sign each certificate. The CA may base 2782 this assertion upon technical means (i.e., proof of possession 2783 through a challenge-response protocol), presentation of the private 2784 key, or on an assertion by the subject. A certificate has a limited 2785 valid lifetime which is indicated in its signed contents. Because a 2786 certificate's signature and timeliness can be independently checked 2787 by a certificate-using client, certificates can be distributed via 2788 untrusted communications and server systems, and can be cached in 2789 unsecured storage in certificate-using systems. 2791 ITU-T X.509 (formerly CCITT X.509) or ISO/IEC/ITU 9594-8 [X509], 2792 which was first published in 1988 as part of the X.500 Directory 2793 recommendations, defines a standard certificate format which is a 2794 certificate which binds a subject (principal) to a public key value. 2796 This was later further expanded and documented in [RFC5280]. 2798 A X.509 certificate is a sequence of three required fields: 2800 tbsCertificate: The tbsCertificate field contains the names of the 2801 subject and issuer, a public key associated with the subject, a 2802 validity period, and other associated information. This field may 2803 also contain extension components. 2805 signatureAlgorithm: The signatureAlgorithm field contains the 2806 identifier for the cryptographic algorithm used by the certificate 2807 authority (CA) to sign this certificate. 2809 signatureValue: The signatureValue field contains a digital 2810 signature computed by the CA upon the ASN.1 DER encoded 2811 tbsCertificate field. The ASN.1 DER encoded tbsCertificate is 2812 used as the input to the signature function. This signature value 2813 is then ASN.1 DER encoded as a BIT STRING and included in the 2814 Certificate's signature field. By generating this signature, the 2815 CA certifies the validity of the information in the tbsCertificate 2816 field. In particular, the CA certifies the binding between the 2817 public key material and the subject of the certificate. 2819 The basic X.509 authentication procedure is as follows: A system is 2820 initialized with a number of root certificates that contain the 2821 public keys of a number of trusted CAs. When a system receives a 2822 X.509 certificate, signed by one of those CAs, the certificate has to 2823 be verified. It first checks the signatureValue field by using the 2824 public key of the corresponding trusted CA. Then it compares the 2825 digest of the received certificate with a digest of the 2826 tbsCertificate field. If they match, then the subject in the 2827 tbsCertificate field is authenticated. 2829 Appendix C. Target and Notificaton Configuration Example 2831 Configuring the SNMP-TARGET-MIB and NOTIFICATION-MIB along with 2832 access control settings for the SNMP-VIEW-BASED-ACM-MIB can be a 2833 daunting task without an example to follow. The following section 2834 describes an example of what pieces must be in place to accomplish 2835 this configuration. 2837 The isAccessAllowed() ASI requires configuration to exist in the 2838 following SNMP-VIEW-BASED-ACM-MIB tables: 2840 vacmSecurityToGroupTable 2841 vacmAccessTable 2842 vacmViewTreeFamilyTable 2844 The only table that needs to be discussed as particularly different 2845 here is the vacmSecurityToGroupTable. This table is indexed by both 2846 the SNMPv3 security model and the security name. The security model, 2847 when TLSTM is in use, should be set to the value of 4, corresponding 2848 to the TSM [RFC5591]. An example vacmSecurityToGroupTable row might 2849 be filled out as follows (using a single SNMP SET request): 2851 vacmSecurityModel = 4 (TSM) 2852 vacmSecurityName = "blueberry" 2853 vacmGroupName = "administrators" 2854 vacmSecurityToGroupStorageType = 3 (nonVolatile) 2855 vacmSecurityToGroupStatus = 4 (createAndGo) 2857 This example will assume that the "administrators" group has been 2858 given proper permissions via rows in the vacmAccessTable and 2859 vacmViewTreeFamilyTable. 2861 Depending on whether this VACM configuration is for a Command 2862 Responder or a Command Generator the security name "blueberry" will 2863 come from a few different locations. 2865 C.1. Configuring the Notification Generator 2867 For Notification Generators performing authorization checks, the 2868 server's certificate must be verified against the expected 2869 certificate before proceeding to send the notification. The expected 2870 certificate from the server may be listed in the tlstmAddrTable or 2871 may be determined through other X.509 path validation mechanisms. 2872 The securityName to use for VACM authorization checks is set by the 2873 SNMP-TARGET-MIB's snmpTargetParamsSecurityName column. 2875 The certificate that the notification generator should present to the 2876 server is taken from the tlstmParamsClientFingerprint column from the 2877 appropriate entry in the tlstmParamsTable table. 2879 C.2. Configuring the Command Responder 2881 For Command Responder applications, the vacmSecurityName "blueberry" 2882 value is a value that derived from an incoming (D)TLS session. The 2883 mapping from a recevied (D)TLS client certificate to a tmSecurityName 2884 is done with the tlstmCertToTSNTable. The certificates must be 2885 loaded into the device so that a tlstmCertToTSNEntry may refer to it. 2886 As an example, consider the following entry which will provide a 2887 mapping from a client's public X.509's hash fingerprint directly to 2888 the "blueberry" tmSecurityName: 2890 tlstmCertToTSNID = 1 (chosen by ordering preference) 2891 tlstmCertToTSNFingerprint = HASH (appropriate fingerprint) 2892 tlstmCertToTSNMapType = 1 (specified) 2893 tlstmCertToTSNSecurityName = "blueberry" 2894 tlstmCertToTSNStorageType = 3 (nonVolatile) 2895 tlstmCertToTSNRowStatus = 4 (createAndGo) 2897 The above is an example of how to map a particular certificate to a 2898 particular tmSecurityName. It is recommended, however, that users 2899 make use of direct subjectAltName or CommonName mappings where 2900 possible as it provides a more scalable approach to certificate 2901 management. This entry provides an example of using a subjectAltName 2902 mapping: 2904 tlstmCertToTSNID = 1 (chosen by ordering preference) 2905 tlstmCertToTSNFingerprint = HASH (appropriate fingerprint) 2906 tlstmCertToTSNMapType = 2 (bySubjectAltName) 2907 tlstmCertToTSNSANType = 1 (any) 2908 tlstmCertToTSNStorageType = 3 (nonVolatile) 2909 tlstmCertToTSNRowStatus = 4 (createAndGo) 2911 The above entry indicates the subjectAltName field for certificates 2912 created by an issuing certificate with a corresponding fingerprint 2913 will be trusted to always produce common names that are directly one- 2914 to-one mappable into tmSecurityNames. This type of configuration 2915 should only be used when the certificate authorities naming 2916 conventions are carefully controlled. 2918 In the example, if the incoming (D)TLS client provided certificate 2919 contained a subjectAltName where the first listed subjectAltName in 2920 the extension is the rfc822Name of "blueberry@example.com", the 2921 certificate was signed by a certificate matching the 2922 tlstmCertToTSNFingerprint value and the CA's certificate was properly 2923 installed on the device then the string "blueberry@example.com" would 2924 be used as the tmSecurityName for the session. 2926 Author's Address 2928 Wes Hardaker 2929 Sparta, Inc. 2930 P.O. Box 382 2931 Davis, CA 95617 2932 USA 2934 Phone: +1 530 792 1913 2935 Email: ietf@hardakers.net