idnits 2.17.1 draft-ietf-isms-dtls-tm-03.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 378 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 23, 2009) is 5209 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) -- No information found for draft-seggelmann-tls-dtls-heartbeat - is the name correct? Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 4 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 23, 2009 5 Expires: June 26, 2010 7 Transport Layer Security (TLS) Transport Model for SNMP 8 draft-ietf-isms-dtls-tm-03.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 26, 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 3. How the TLSTM fits into the Transport Subsystem . . . . . . . 9 89 3.1. Security Capabilities of this Model . . . . . . . . . . . 10 90 3.1.1. Threats . . . . . . . . . . . . . . . . . . . . . . . 10 91 3.1.2. Message Protection . . . . . . . . . . . . . . . . . . 12 92 3.1.3. (D)TLS Sessions . . . . . . . . . . . . . . . . . . . 13 93 3.2. Security Parameter Passing . . . . . . . . . . . . . . . . 13 94 3.3. Notifications and Proxy . . . . . . . . . . . . . . . . . 14 95 4. Elements of the Model . . . . . . . . . . . . . . . . . . . . 15 96 4.1. X.509 Certificates . . . . . . . . . . . . . . . . . . . . 15 97 4.1.1. Provisioning for the Certificate . . . . . . . . . . . 15 98 4.2. Messages . . . . . . . . . . . . . . . . . . . . . . . . . 16 99 4.3. SNMP Services . . . . . . . . . . . . . . . . . . . . . . 16 100 4.3.1. SNMP Services for an Outgoing Message . . . . . . . . 17 101 4.3.2. SNMP Services for an Incoming Message . . . . . . . . 18 102 4.4. Cached Information and References . . . . . . . . . . . . 18 103 4.4.1. TLS Transport Model Cached Information . . . . . . . . 19 104 4.4.1.1. tmSecurityName . . . . . . . . . . . . . . . . . . 19 105 4.4.1.2. tmSessionID . . . . . . . . . . . . . . . . . . . 19 106 4.4.1.3. Session State . . . . . . . . . . . . . . . . . . 19 107 5. Elements of Procedure . . . . . . . . . . . . . . . . . . . . 20 108 5.1. Procedures for an Incoming Message . . . . . . . . . . . . 20 109 5.1.1. DTLS Processing for Incoming Messages . . . . . . . . 20 110 5.1.2. Transport Processing for Incoming SNMP Messages . . . 22 111 5.2. Procedures for an Outgoing SNMP Message . . . . . . . . . 23 112 5.3. Establishing a Session . . . . . . . . . . . . . . . . . . 24 113 5.4. Closing a Session . . . . . . . . . . . . . . . . . . . . 27 114 6. MIB Module Overview . . . . . . . . . . . . . . . . . . . . . 27 115 6.1. Structure of the MIB Module . . . . . . . . . . . . . . . 28 116 6.2. Textual Conventions . . . . . . . . . . . . . . . . . . . 28 117 6.3. Statistical Counters . . . . . . . . . . . . . . . . . . . 28 118 6.4. Configuration Tables . . . . . . . . . . . . . . . . . . . 28 119 6.4.1. Notifications . . . . . . . . . . . . . . . . . . . . 28 120 6.5. Relationship to Other MIB Modules . . . . . . . . . . . . 29 121 6.5.1. MIB Modules Required for IMPORTS . . . . . . . . . . . 29 122 7. MIB Module Definition . . . . . . . . . . . . . . . . . . . . 29 123 8. Operational Considerations . . . . . . . . . . . . . . . . . . 50 124 8.1. Sessions . . . . . . . . . . . . . . . . . . . . . . . . . 51 125 8.2. Notification Receiver Credential Selection . . . . . . . . 51 126 8.3. contextEngineID Discovery . . . . . . . . . . . . . . . . 51 127 8.4. Transport Considerations . . . . . . . . . . . . . . . . . 52 128 9. Security Considerations . . . . . . . . . . . . . . . . . . . 52 129 9.1. Certificates, Authentication, and Authorization . . . . . 52 130 9.2. Use with SNMPv1/SNMPv2c Messages . . . . . . . . . . . . . 53 131 9.3. MIB Module Security . . . . . . . . . . . . . . . . . . . 53 132 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 133 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 56 134 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57 135 12.1. Normative References . . . . . . . . . . . . . . . . . . . 57 136 12.2. Informative References . . . . . . . . . . . . . . . . . . 58 137 Appendix A. (D)TLS Overview . . . . . . . . . . . . . . . . . . . 59 138 A.1. The (D)TLS Record Protocol . . . . . . . . . . . . . . . . 59 139 A.2. The (D)TLS Handshake Protocol . . . . . . . . . . . . . . 60 140 Appendix B. PKIX Certificate Infrastructure . . . . . . . . . . . 61 141 Appendix C. Target and Notificaton Configuration Example . . . . 62 142 C.1. Configuring the Notification Generator . . . . . . . . . . 63 143 C.2. Configuring the Command Responder . . . . . . . . . . . . 63 144 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 64 146 1. Introduction 148 It is important to understand the modular SNMPv3 architecture as 149 defined by [RFC3411] and enhanced by the Transport Subsystem 150 [RFC5590]. It is also important to understand the terminology of the 151 SNMPv3 architecture in order to understand where the Transport Model 152 described in this document fits into the architecture and how it 153 interacts with the other architecture subsystems. For a detailed 154 overview of the documents that describe the current Internet-Standard 155 Management Framework, please refer to Section 7 of [RFC3410]. 157 This document describes a Transport Model that makes use of the 158 Transport Layer Security (TLS) [RFC5246] and the Datagram Transport 159 Layer Security (DTLS) Protocol [RFC4347], within a transport 160 subsystem [RFC5590]. DTLS is the datagram variant of the Transport 161 Layer Security (TLS) protocol [RFC5246]. The Transport Model in this 162 document is referred to as the Transport Layer Security Transport 163 Model (TLSTM). TLS and DTLS take advantage of the X.509 public 164 keying infrastructure [RFC5280]. While (D)TLS supports multiple 165 authentication mechanisms, this document only discusses X.509 166 certificate based authentication. Although other forms of 167 authentication are possible they are outside the scope of this 168 specification. This transport model is designed to meet the security 169 and operational needs of network administrators, operating in both 170 environments where a connectionless (e.g. UDP or SCTP) transport is 171 preferred and in environments where large quantities of data need to 172 be sent (e.g. over a TCP based stream). Both TLS and DTLS integrate 173 well into existing public keying infrastructures. This document 174 supports sending of SNMP messages over TLS/TCP, DTLS/UDP and DTLS/ 175 SCTP. 177 This document also defines a portion of the Management Information 178 Base (MIB) for use with network management protocols. In particular 179 it defines objects for managing the TLS Transport Model for SNMP. 181 Managed objects are accessed via a virtual information store, termed 182 the Management Information Base or MIB. MIB objects are generally 183 accessed through the Simple Network Management Protocol (SNMP). 184 Objects in the MIB are defined using the mechanisms defined in the 185 Structure of Management Information (SMI). This memo specifies a MIB 186 module that is compliant to the SMIv2, which is described in STD 58: 187 [RFC2578], [RFC2579] and [RFC2580]. 189 The diagram shown below gives a conceptual overview of two SNMP 190 entities communicating using the TLS Transport Model. One entity 191 contains a command responder and notification originator application, 192 and the other a command generator and notification responder 193 application. It should be understood that this particular mix of 194 application types is an example only and other combinations are 195 equally valid. Note: this diagram shows the Transport Security Model 196 (TSM) being used as the security model which is defined in [RFC5591]. 198 +----------------------------------------------------------------+ 199 | Network | 200 +----------------------------------------------------------------+ 201 ^ | ^ | 202 |Notifications |Commands |Commands |Notifications 203 +---|---------------------|--------+ +--|---------------|-------------+ 204 | | V | | | V | 205 | +------------+ +------------+ | | +-----------+ +----------+ | 206 | | (D)TLS | | (D)TLS | | | | (D)TLS | | (D)TLS | | 207 | | Service | | Service | | | | Service | | Service | | 208 | | (Client) | | (Server) | | | | (Client) | | (Server)| | 209 | +------------+ +------------+ | | +-----------+ +----------+ | 210 | ^ ^ | | ^ ^ | 211 | | | | | | | | 212 | +--+----------+ | | +-+--------------+ | 213 | +-----|---------+----+ | | +---|--------+----+ | 214 | | V |LCD | +-------+ | | | V |LCD | +--------+ | 215 | | +------+ +----+ | | | | | +------+ +----+ | | | 216 | | | TLS | <---------->| Cache | | | | | TLS | <---->| Cache | | 217 | | | TM | | | | | | | | TM | | | | | 218 | | +------+ | +-------+ | | | +------+ | +--------+ | 219 | |Transport Subsystem | ^ | | |Transport Sub. | ^ | 220 | +--------------------+ | | | +-----------------+ | | 221 | ^ +----+ | | ^ | | 222 | | | | | | | | 223 | v | | | V | | 224 | +-------+ +----------+ +-----+ | | | +-----+ +------+ +-----+ | | 225 | | | |Message | |Sec. | | | | | | | MP | |Sec. | | | 226 | | Disp. | |Processing| |Sub- | | | | |Disp.| | Sub- | |Sub- | | | 227 | | | |Subsystem | |sys. | | | | | | |system| |sys. | | | 228 | | | | | | | | | | | | | | | | | | 229 | | | | | |+---+| | | | | | | | |+---+| | | 230 | | | | +-----+ | || || | | | | | |+----+| || || | | 231 | | <--->|v3MP |<-->||TSM|<-+ | | | <-->|v3MP|<->|TSM|<-+ | 232 | | | | +-----+ | || || | | | | |+----+| || || | 233 | +-------+ | | |+---+| | | +-----+ | | |+---+| | 234 | ^ | | | | | | ^ | | | | | 235 | | +----------+ +-----+ | | | +------+ +-----+ | 236 | +-+------------+ | | +-+------------+ | 237 | ^ ^ | | ^ ^ | 238 | | | | | | | | 239 | v v | | V V | 240 | +-------------+ +--------------+ | | +-----------+ +--------------+ | 241 | | COMMAND | | NOTIFICATION | | | | COMMAND | | NOTIFICATION | | 242 | | RESPONDER | | ORIGINATOR | | | | GENERATOR | | RECEIVER | | 243 | | application | | application | | | |application| | application | | 244 | +-------------+ +--------------+ | | +-----------+ +--------------+ | 245 | SNMP entity | | SNMP entity | 246 +----------------------------------+ +--------------------------------+ 248 1.1. Conventions 250 For consistency with SNMP-related specifications, this document 251 favors terminology as defined in STD 62, rather than favoring 252 terminology that is consistent with non-SNMP specifications. This is 253 consistent with the IESG decision to not require the SNMPv3 254 terminology be modified to match the usage of other non-SNMP 255 specifications when SNMPv3 was advanced to Full Standard. 257 "Authentication" in this document typically refers to the English 258 meaning of "serving to prove the authenticity of" the message, not 259 data source authentication or peer identity authentication. 261 The terms "manager" and "agent" are not used in this document 262 because, in the RFC 3411 architecture, all SNMP entities have the 263 capability of acting as manager, agent, or both depending on the SNMP 264 application types supported in the implementation. Where distinction 265 is required, the application names of command generator, command 266 responder, notification originator, notification receiver, and proxy 267 forwarder are used. See "SNMP Applications" [RFC3413] for further 268 information. 270 Authentication in this document typically refers to the English 271 meaning of "serving to prove the authenticity of" the message, not 272 data source authentication or peer identity authentication. 274 The terms "manager" and "agent" are not used in this document, 275 because in the RFC 3411 architecture [RFC3411], all SNMP entities 276 have the capability of acting in either manager or agent or in both 277 roles depending on the SNMP application types supported in the 278 implementation. Where distinction is required, the application names 279 of command generator, command responder, notification originator, 280 Notification Receiver, and proxy forwarder are used. See "SNMP 281 Applications" [RFC3413] for further information. 283 Large portions of this document simultaneously refer to both TLS and 284 DTLS when discussing TLSTM components that function equally with 285 either protocol. "(D)TLS" is used in these places to indicate that 286 the statement applies to either or both protocols as appropriate. 287 When a distinction between the protocols is needed they are referred 288 to independently through the use of "TLS" or "DTLS". The Transport 289 Model, however, is named "TLS Transport Model" and refers not to the 290 TLS or DTLS protocol but to the standard defined in this document, 291 which includes support for both TLS and DTLS. 293 Throughout this document, the terms "client" and "server" are used to 294 refer to the two ends of the (D)TLS transport connection. The client 295 actively opens the (D)TLS connection, and the server passively 296 listens for the incoming (D)TLS connection. Either SNMP entity may 297 act as client or as server. 299 The User-Based Security Model (USM) [RFC3414] is a mandatory-to- 300 implement Security Model in STD 62. While (D)TLS and USM frequently 301 refer to a user, the terminology preferred in RFC3411 and in this 302 memo is "principal". A principal is the "who" on whose behalf 303 services are provided or processing takes place. A principal can be, 304 among other things, an individual acting in a particular role; a set 305 of individuals, with each acting in a particular role; an application 306 or a set of applications, or a combination of these within an 307 administrative domain. 309 Throughout this document, the term "session" is used to refer to a 310 secure association between two TLS Transport Models that permits the 311 transmission of one or more SNMP messages within the lifetime of the 312 session. The (D)TLS protocols also have an internal notion of a 313 session and although these two concepts of a session are related, 314 this document (unless otherwise specified) is referring to TLSTM's 315 specific session and not directly to the (D)TLS protocol's session. 317 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 318 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 319 document are to be interpreted as described in [RFC2119]. 321 2. The Transport Layer Security Protocol 323 (D)TLS provides authentication, data message integrity, and privacy 324 at the transport layer. (See [RFC4347]) 326 The primary goals of the TLS Transport Model are to provide privacy, 327 peer identity authentication and data integrity between two 328 communicating SNMP entities. The TLS and DTLS protocols provide a 329 secure transport upon which the TLSTM is based. An overview of 330 (D)TLS can be found in section Appendix A. Please refer to [RFC5246] 331 and [RFC4347] for complete descriptions of the protocols. 333 3. How the TLSTM fits into the Transport Subsystem 335 A transport model is a component of the Transport Subsystem. The TLS 336 Transport Model thus fits between the underlying (D)TLS transport 337 layer and the Message Dispatcher [RFC3411] component of the SNMP 338 engine and the Transport Subsystem. 340 The TLS Transport Model will establish a session between itself and 341 the TLS Transport Model of another SNMP engine. The sending 342 transport model passes unencrypted and unauthenticated messages from 343 the Dispatcher to (D)TLS to be encrypted and authenticated, and the 344 receiving transport model accepts decrypted and authenticated/ 345 integrity-checked incoming messages from (D)TLS and passes them to 346 the Dispatcher. 348 After a TLS Transport Model session is established, SNMP messages can 349 conceptually be sent through the session from one SNMP message 350 Dispatcher to another SNMP Message Dispatcher. If multiple SNMP 351 messages are needed to be passed between two SNMP applications they 352 MAY be passed through the same session. A TLSTM implementation 353 engine MAY choose to close a (D)TLS session to conserve resources. 355 The TLS Transport Model of an SNMP engine will perform the 356 translation between (D)TLS-specific security parameters and SNMP- 357 specific, model-independent parameters. 359 The diagram below depicts where the TLS Transport Model fits into the 360 architecture described in RFC3411 and the Transport Subsystem: 362 +------------------------------+ 363 | Network | 364 +------------------------------+ 365 ^ ^ ^ 366 | | | 367 v v v 368 +-------------------------------------------------------------------+ 369 | +--------------------------------------------------+ | 370 | | Transport Subsystem | +--------+ | 371 | | +-----+ +-----+ +-------+ +-------+ | | | | 372 | | | UDP | | SSH | |(D)TLS | . . . | other |<--->| Cache | | 373 | | | | | TM | | TM | | | | | | | 374 | | +-----+ +-----+ +-------+ +-------+ | +--------+ | 375 | +--------------------------------------------------+ ^ | 376 | ^ | | 377 | | | | 378 | Dispatcher v | | 379 | +--------------+ +---------------------+ +----------------+ | | 380 | | Transport | | Message Processing | | Security | | | 381 | | Dispatch | | Subsystem | | Subsystem | | | 382 | | | | +------------+ | | +------------+ | | | 383 | | | | +->| v1MP |<--->| | USM | | | | 384 | | | | | +------------+ | | +------------+ | | | 385 | | | | | +------------+ | | +------------+ | | | 386 | | | | +->| v2cMP |<--->| | Transport | | | | 387 | | Message | | | +------------+ | | | Security |<--+ | 388 | | Dispatch <---->| +------------+ | | | Model | | | 389 | | | | +->| v3MP |<--->| +------------+ | | 390 | | | | | +------------+ | | +------------+ | | 391 | | PDU Dispatch | | | +------------+ | | | Other | | | 392 | +--------------+ | +->| otherMP |<--->| | Model(s) | | | 393 | ^ | +------------+ | | +------------+ | | 394 | | +---------------------+ +----------------+ | 395 | v | 396 | +-------+-------------------------+---------------+ | 397 | ^ ^ ^ | 398 | | | | | 399 | v v v | 400 | +-------------+ +---------+ +--------------+ +-------------+ | 401 | | COMMAND | | ACCESS | | NOTIFICATION | | PROXY | | 402 | | RESPONDER |<->| CONTROL |<->| ORIGINATOR | | FORWARDER | | 403 | | application | | | | applications | | application | | 404 | +-------------+ +---------+ +--------------+ +-------------+ | 405 | ^ ^ | 406 | | | | 407 | v v | 408 | +----------------------------------------------+ | 409 | | MIB instrumentation | SNMP entity | 410 +-------------------------------------------------------------------+ 412 3.1. Security Capabilities of this Model 414 3.1.1. Threats 416 The TLS Transport Model provides protection against the threats 417 identified by the RFC 3411 architecture [RFC3411]: 419 1. Modification of Information - The modification threat is the 420 danger that an unauthorized entity may alter in-transit SNMP 421 messages generated on behalf of an authorized principal in such a 422 way as to effect unauthorized management operations, including 423 falsifying the value of an object. 425 (D)TLS provides verification that the content of each received 426 message has not been modified during its transmission through the 427 network, data has not been altered or destroyed in an 428 unauthorized manner, and data sequences have not been altered to 429 an extent greater than can occur non-maliciously. 431 2. Masquerade - The masquerade threat is the danger that management 432 operations unauthorized for a given principal may be attempted by 433 assuming the identity of another principal that has the 434 appropriate authorizations. 436 The TLSTM provides for verification of the identity of the (D)TLS 437 server through the use of the (D)TLS protocol and the X.509 438 certificates. The TLS Transport Model MUST support 439 authentication of both the server and the client. 441 3. Message stream modification - The re-ordering, delay or replay of 442 messages can and does occur through the natural operation of many 443 connectionless transport services. The message stream 444 modification threat is the danger that messages may be 445 maliciously re-ordered, delayed or replayed to an extent which is 446 greater than can occur through the natural operation of 447 connectionless transport services, in order to effect 448 unauthorized management operations. 450 (D)TLS provides replay protection with a MAC that includes a 451 sequence number. Since UDP provides no sequencing ability DTLS 452 uses a sliding window protocol with the sequence number for 453 replay protection (see [RFC4347]). 455 4. Disclosure - The disclosure threat is the danger of eavesdropping 456 on the exchanges between SNMP engines. 458 (D)TLS provides protection against the disclosure of information 459 to unauthorized recipients or eavesdroppers by allowing for 460 encryption of all traffic between SNMP engines. The TLS 461 Transport Model SHOULD support the message encryption to protect 462 sensitive data from eavesdropping attacks. 464 5. Denial of Service - the RFC 3411 architecture [RFC3411] states 465 that denial of service (DoS) attacks need not be addressed by an 466 SNMP security protocol. However, datagram-based security 467 protocols like DTLS are susceptible to a variety of denial of 468 service attacks because it is more vulnerable to spoofed 469 messages. 471 In order to counter these attacks, DTLS borrows the stateless 472 cookie technique used by Photuris [RFC2522] and IKEv2 [RFC4306] 473 and is described fully in section 4.2.1 of [RFC4347]. This 474 mechanism, though, does not provide any defense against denial of 475 service attacks mounted from valid IP addresses. DTLS Transport 476 Model server implementations MUST support DTLS cookies. 478 Implementations are not required to perform the stateless cookie 479 exchange for every DTLS handshake, but in environments where an 480 overload on server side resources is detectable by the 481 implementation it is RECOMMENDED that the cookie exchange is 482 utilized by the implementation. 484 See Section 9 for more detail on the security considerations 485 associated with the TLSTM and these security threats. 487 3.1.2. Message Protection 489 The RFC 3411 architecture recognizes three levels of security: 491 o without authentication and without privacy (noAuthNoPriv) 493 o with authentication but without privacy (authNoPriv) 495 o with authentication and with privacy (authPriv) 497 The TLS Transport Model determines from (D)TLS the identity of the 498 authenticated principal, and the type and address associated with an 499 incoming message. The TLS Transport Model provides the identity and 500 destination type and address to (D)TLS for outgoing messages. 502 When an application requests a session for a message, through the 503 cache, the application requests a security level for that session. 504 The TLS Transport Model MUST ensure that the (D)TLS session provides 505 security at least as high as the requested level of security. How 506 the security level is translated into the algorithms used to provide 507 data integrity and privacy is implementation-dependent. However, the 508 NULL integrity and encryption algorithms MUST NOT be used to fulfill 509 security level requests for authentication or privacy. 510 Implementations MAY choose to force (D)TLS to only allow 511 cipher_suites that provide both authentication and privacy to 512 guarantee this assertion. 514 If a suitable interface between the TLS Transport Model and the 515 (D)TLS Handshake Protocol is implemented to allow the selection of 516 security level dependent algorithms (for example a security level to 517 cipher_suites mapping table) then different security levels may be 518 utilized by the application. 520 The authentication, integrity and privacy algorithms used by the 521 (D)TLS Protocols may vary over time as the science of cryptography 522 continues to evolve and the development of (D)TLS continues over 523 time. Implementers are encouraged to plan for changes in operator 524 trust of particular algorithms. Implementations should offer 525 configuration settings for mapping algorithms to SNMPv3 security 526 levels. 528 3.1.3. (D)TLS Sessions 530 (D)TLS sessions are opened by the TLS Transport Model during the 531 elements of procedure for an outgoing SNMP message. Since the sender 532 of a message initiates the creation of a (D)TLS session if needed, 533 the (D)TLS session will already exist for an incoming message. 535 Implementations MAY choose to instantiate (D)TLS sessions in 536 anticipation of outgoing messages. This approach might be useful to 537 ensure that a (D)TLS session to a given target can be established 538 before it becomes important to send a message over the (D)TLS 539 session. Of course, there is no guarantee that a pre-established 540 session will still be valid when needed. 542 DTLS sessions, when used over UDP, are uniquely identified within the 543 TLS Transport Model by the combination of transportDomain, 544 transportAddress, tmSecurityName, and requestedSecurityLevel 545 associated with each session. Each unique combination of these 546 parameters MUST have a locally-chosen unique tlstmSessionID 547 associated for active sessions. For further information see 548 Section 5. TLS and DTLS over SCTP sessions, on the other hand, do 549 not require a unique pairing of address and port attributes since 550 their lower layer protocols (TCP and SCTP) already provide adequate 551 session framing. But they must still provide a unique tlstmSessionID 552 for referencing the session. 554 The tlstmSessionID MAY be the same as the (D)TLS internal SessionID 555 but caution must be exercised since the (D)TLS internal SessionID may 556 change over the life of the connection as seen by the TLSTM (for 557 example during renegotiation). The tlstmSessionID identifier MUST 558 NOT change during the entire duration of the connection from the 559 TLSTM's perspective. 561 3.2. Security Parameter Passing 563 For the (D)TLS server-side, (D)TLS-specific security parameters 564 (i.e., cipher_suites, X.509 certificate fields, IP address and port) 565 are translated by the TLS Transport Model into security parameters 566 for the TLS Transport Model and security model (e.g.., 567 tmSecurityLevel, tmSecurityName, transportDomain, transportAddress). 568 The transport- related and (D)TLS-security-related information, 569 including the authenticated identity, are stored in a cache 570 referenced by tmStateReference. 572 For the (D)TLS client-side, the TLS Transport Model takes input 573 provided by the Dispatcher in the sendMessage() Abstract Service 574 Interface (ASI) and input from the tmStateReference cache. The 575 (D)TLS Transport Model converts that information into suitable 576 security parameters for (D)TLS and establishes sessions as needed. 578 The elements of procedure in Section 5 discuss these concepts in much 579 greater detail. 581 3.3. Notifications and Proxy 583 (D)TLS sessions may be initiated by (D)TLS clients on behalf of 584 command generators, notification originators, proxy forwarders or 585 other applications. Command generators are frequently operated by a 586 human, but notification originators and proxy forwarders are usually 587 unmanned automated processes. The targets to whom notifications and 588 proxied requests should be sent is typically determined and 589 configured by a network administrator. 591 The SNMP-TARGET-MIB module [RFC3413] contains objects for defining 592 management targets, including transportDomain, transportAddress, 593 securityName, securityModel, and securityLevel parameters, for 594 notification generator, proxy forwarder, and SNMP-controllable 595 command generator applications. Transport domains and transport 596 addresses are configured in the snmpTargetAddrTable, and the 597 securityModel, securityName, and securityLevel parameters are 598 configured in the snmpTargetParamsTable. This document defines a MIB 599 module that extends the SNMP-TARGET-MIB's snmpTargetParamsTable to 600 specify a (D)TLS client-side certificate to use for the connection. 602 When configuring a (D)TLS target, the snmpTargetAddrTDomain and 603 snmpTargetAddrTAddress parameters in snmpTargetAddrTable should be 604 set to the snmpTLSTCPDomain, snmpDTLSUDPDomain, or snmpDTLSSCTPDomain 605 object and an appropriate snmpTLSAddress value. When used with the 606 SNMPv3 message processing model, the snmpTargetParamsMPModel column 607 of the snmpTargetParamsTable should be set to a value of 3. The 608 snmpTargetParamsSecurityName should be set to an appropriate 609 securityName value and the tlstmParamsClientFingerprint parameter of 610 the tlstmParamsTable should be set a value that refers to a locally 611 held certificate to be used. Other parameters, for example 612 cryptographic configuration such as cipher suites to use, must come 613 from configuration mechanisms not defined in this document. The 614 securityName defined in the snmpTargetParamsSecurityName column will 615 be used by the access control model to authorize any notifications 616 that need to be sent. 618 4. Elements of the Model 620 This section contains definitions required to realize the (D)TLS 621 Transport Model defined by this document. 623 4.1. X.509 Certificates 625 (D)TLS can make use of X.509 certificates for authentication of both 626 sides of the transport. This section discusses the use of X.509 627 certificates in the TLSTM. A brief overview of X.509 certificate 628 infrastructure can be found in Appendix B. 630 While (D)TLS supports multiple authentication mechanisms, this 631 document only discusses X.509 certificate based authentication. 632 Although other forms of authentication are possible they are outside 633 the scope of this specification. TLSTM implementations are REQUIRED 634 to support X.509 certificates. 636 4.1.1. Provisioning for the Certificate 638 Authentication using (D)TLS will require that SNMP entities are 639 provisioned with certificates, which are signed by trusted 640 certificate authorities (possibly the certificate itself). 641 Furthermore, SNMP entities will most commonly need to be provisioned 642 with root certificates which represent the list of trusted 643 certificate authorities that an SNMP entity can use for certificate 644 verification. SNMP entities SHOULD also be provisioned with a X.509 645 certificate revocation mechanism which can be used to verify that a 646 certificate has not been revoked. Trusted public keys from either CA 647 certificates and/or self-signed certificates, MUST be installed 648 through a trusted out of band mechanism into the server and its 649 authenticity MUST be verified before access is granted. 651 Having received a certificate from a connecting TLSTM client, the 652 authenticated tmSecurityName of the principal is derived using the 653 tlstmCertToTSNTable. This table allows mapping of incoming 654 connections to tmSecurityNames through defined transformations. The 655 transformations defined in the TLSTM-MIB include: 657 o Mapping a certificate's fingerprint type and value to a directly 658 specified tmSecurityName, or 660 o Mapping a certificate's subjectAltName or CommonName components to 661 a tmSecurityName. 663 Implementations MAY choose to discard any connections for which no 664 potential tlstmCertToTSNTable mapping exists before performing 665 certificate verification to avoid expending computational resources 666 associated with certificate verification. 668 Enterprise configurations are encouraged to map a "subjectAltName" 669 component of the X.509 certificate to the TLSTM specific 670 tmSecurityName. The authenticated identity can be obtained by the 671 TLS Transport Model by extracting the subjectAltName(s) from the 672 peer's certificate. The receiving application will then have an 673 appropriate tmSecurityName for use by other SNMPv3 components like an 674 access control model. 676 An example of this type of mapping setup can be found in Appendix C. 678 This tmSecurityName may be later translated from a TLSTM specific 679 tmSecurityName to a SNMP engine securityName by the security model. 680 A security model, like the TSM security model [RFC5591], may perform 681 an identity mapping or a more complex mapping to derive the 682 securityName from the tmSecurityName offered by the TLS Transport 683 Model. 685 A pictorial view of the complete transformation process (using the 686 TSM security model for the example) is shown below: 688 +-------------+ +-------+ +----------------+ +-----+ 689 | Certificate | | | | | | | 690 | Path | | TLSTM | | tmSecurityName | | TSM | 691 | Validation | --> | | --> | | --> | | 692 +-------------+ +-------+ +----------------+ +-----+ 693 | 694 V 695 +-------------+ +--------------+ 696 | application | <-- | securityName | 697 +-------------+ +--------------+ 699 4.2. Messages 701 As stated in Section 4.1.1 of [RFC4347], each DTLS record must fit 702 within a single DTLS datagram. The TLSTM SHOULD prohibit SNMP 703 messages from being sent that exceeds the maximum DTLS message size. 704 The TLSTM implementation SHOULD return an error when the DTLS message 705 size would be exceeded and the message won't be sent. 707 4.3. SNMP Services 709 This section describes the services provided by the TLS Transport 710 Model with their inputs and outputs. The services are between the 711 Transport Model and the Dispatcher. 713 The services are described as primitives of an abstract service 714 interface (ASI) and the inputs and outputs are described as abstract 715 data elements as they are passed in these abstract service 716 primitives. 718 4.3.1. SNMP Services for an Outgoing Message 720 The Dispatcher passes the information to the TLS Transport Model 721 using the ASI defined in the transport subsystem: 723 statusInformation = 724 sendMessage( 725 IN destTransportDomain -- transport domain to be used 726 IN destTransportAddress -- transport address to be used 727 IN outgoingMessage -- the message to send 728 IN outgoingMessageLength -- its length 729 IN tmStateReference -- reference to transport state 730 ) 732 The abstract data elements returned from or passed as parameters into 733 the abstract service primitives are as follows: 735 statusInformation: An indication of whether the passing of the 736 message was successful. If not, it is an indication of the 737 problem. 739 destTransportDomain: The transport domain for the associated 740 destTransportAddress. The Transport Model uses this parameter to 741 determine the transport type of the associated 742 destTransportAddress. This document specifies the snmpTLSDomain, 743 the snmpDTLSUDPDomain and the snmpDTLSSCTPDomain" transport 744 domains. 746 destTransportAddress: The transport address of the destination TLS 747 Transport Model in a format specified by the SnmpTLSAddress 748 TEXTUAL-CONVENTION. 750 outgoingMessage: The outgoing message to send to (D)TLS for 751 encapsulation. 753 outgoingMessageLength: The length of the outgoingMessage field. 755 tmStateReference: A handle/reference to tmState to be used when 756 securing outgoing messages. 758 4.3.2. SNMP Services for an Incoming Message 760 The TLS Transport Model processes the received message from the 761 network using the (D)TLS service and then passes it to the Dispatcher 762 using the following ASI: 764 statusInformation = 765 receiveMessage( 766 IN transportDomain -- origin transport domain 767 IN transportAddress -- origin transport address 768 IN incomingMessage -- the message received 769 IN incomingMessageLength -- its length 770 IN tmStateReference -- reference to transport state 771 ) 773 The abstract data elements returned from or passed as parameters into 774 the abstract service primitives are as follows: 776 statusInformation: An indication of whether the passing of the 777 message was successful. If not, it is an indication of the 778 problem. 780 transportDomain: The transport domain for the associated 781 transportAddress. This document specifies the snmpTLSDomain, the 782 snmpDTLSUDPDomain and the snmpDTLSSCTPDomain" transport domains. 784 transportAddress: The transport address of the source of the 785 received message in a format specified by the SnmpTLSAddress 786 TEXTUAL-CONVENTION. 788 incomingMessage: The whole SNMP message after being processed by 789 (D)TLS and removed of the (D)TLS transport layer data. 791 incomingMessageLength: The length of the incomingMessage field. 793 tmStateReference: A handle/reference to tmSecurityData to be used by 794 the security model. 796 4.4. Cached Information and References 798 When performing SNMP processing, there are two levels of state 799 information that may need to be retained: the immediate state linking 800 a request-response pair, and potentially longer-term state relating 801 to transport and security. "Transport Subsystem for the Simple 802 Network Management Protocol" [RFC5590] defines general requirements 803 for caches and references. 805 4.4.1. TLS Transport Model Cached Information 807 The TLS Transport Model has specific responsibilities regarding the 808 cached information. See the Elements of Procedure in Section 5 for 809 detailed processing instructions on the use of the tmStateReference 810 fields by the TLS Transport Model 812 4.4.1.1. tmSecurityName 814 The tmSecurityName MUST be a human-readable name (in snmpAdminString 815 format) representing the identity that has been set according to the 816 procedures in Section 5. The tmSecurityName MUST be constant for all 817 traffic passing through an TLSTM session. Messages MUST NOT be sent 818 through an existing (D)TLS session that was established using a 819 different tmSecurityName. 821 On the (D)TLS server side of a connection the tmSecurityName is 822 derived using the procedures described in Section 5.3 and the TLSTM- 823 MIB's tlstmCertToTSNTable DESCRIPTION clause. 825 On the (D)TLS client side of a connection the tmSecurityName is 826 presented to the TLS Transport Model by the application (possibly 827 because of configuration specified in the SNMP-TARGET-MIB). 829 The securityName MAY be derived from the tmSecurityName by a Security 830 Model and MAY be used to configure notifications and access controls 831 in MIB modules. Transport Models SHOULD generate a predictable 832 tmSecurityName so operators will know what to use when configuring 833 MIB modules that use securityNames derived from tmSecurityNames. 835 4.4.1.2. tmSessionID 837 The tmSessionID MUST be recorded per message at the time of receipt. 838 When tmSameSecurity is set, the recorded tmSessionID can be used to 839 determine whether the (D)TLS session available for sending a 840 corresponding outgoing message is the same (D)TLS session as was used 841 when receiving the incoming message (e.g., a response to a request). 843 4.4.1.3. Session State 845 The per-session state that is referenced by tmStateReference may be 846 saved across multiple messages in a Local Configuration Datastore. 847 Additional session/connection state information might also be stored 848 in a Local Configuration Datastore. 850 5. Elements of Procedure 852 Abstract service interfaces have been defined by [RFC3411] and 853 further augmented by [RFC5590] to describe the conceptual data flows 854 between the various subsystems within an SNMP entity. The TLSTM uses 855 some of these conceptual data flows when communicating between 856 subsystems. 858 To simplify the elements of procedure, the release of state 859 information is not always explicitly specified. As a general rule, 860 if state information is available when a message gets discarded, the 861 message-state information should also be released. If state 862 information is available when a session is closed, the session state 863 information should also be released. Sensitive information, like 864 cryptographic keys, should be overwritten appropriately first prior 865 to being released. 867 An error indication in statusInformation will typically include the 868 Object Identifier (OID) and value for an incremented error counter. 869 This may be accompanied by the requested securityLevel and the 870 tmStateReference. Per-message context information is not accessible 871 to Transport Models, so for the returned counter OID and value, 872 contextEngine would be set to the local value of snmpEngineID and 873 contextName to the default context for error counters. 875 5.1. Procedures for an Incoming Message 877 This section describes the procedures followed by the (D)TLS 878 Transport Model when it receives a (D)TLS protected packet. The 879 steps are broken into two different sections. Section 5.1.1 880 describes the needed steps for de-multiplexing multiple DTLS 881 sessions, which is specifically needed for DTLS over UDP sessions. 882 Section 5.1.2 describes the steps specific to transport processing 883 once the (D)TLS processing has been completed. It is assumed that 884 TLS and DTLS/SCP protocol implementations already provide appropriate 885 message demultiplexing and only the processing steps in Section 5.1.2 886 are needed. 888 5.1.1. DTLS Processing for Incoming Messages 890 DTLS over UDP is significantly different in terms of session handling 891 than when TLS or DTLS is run over session based streaming protocols 892 like TCP or SCTP. Specifically, the DTLS protocol, when run over 893 UDP, does not have a session identifier that allows implementations 894 to determine through which session a packet arrived. It is always 895 critical, however, that implementations be able to derive a 896 tlstmSessionID from any session demultiplexing process. When 897 establishing a new session implementations MUST use a different UDP 898 source port number for each connection to a remote destination IP- 899 address/port-number combination to ensure the remote entity can 900 easily disambiguate between multiple sessions from a host to the same 901 port on a server. 903 A process for demultiplexing multiple DTLS sessions arriving over UDP 904 must be incorporated into the procedures for processing an incoming 905 message. The steps in this section describe one possible method to 906 accomplish this, although any implementation-dependent method should 907 be suitable as long as the results are deterministic. The important 908 output results from the steps in this process are the 909 transportDomain, the transportAddress, the wholeMessage, the 910 wholeMessageLength, and a unique implementation-dependent session 911 identifier (tlstmSessionID). 913 This demultiplexing procedure assumes that upon session establishment 914 an entry in a local transport mapping table is created in the 915 Transport Model's Local Configuration Datastore (LCD). The transport 916 mapping table's entry should map a unique combination of the remote 917 address, remote port number, local address and local port number to 918 an implementation-dependent tlstmSessionID. 920 1) The TLS Transport Model examines the raw UDP message, in an 921 implementation-dependent manner. 923 2) The TLS Transport Model queries the LCD using the transport 924 parameters (source and destination addresses and ports) to 925 determine if a session already exists and its tlstmSessionID. 927 If a matching entry in the LCD does not exist then the message is 928 passed to DTLS for processing without a corresponding 929 tlstmSessionID. The incoming packet may result in a new session 930 being established if the receiving entity is acting as a DTLS 931 server. If DTLS returns success then stop processing of this 932 message. If DTLS returns an error then increment the 933 snmpTlstmSessionNoSessions counter and stop processing the 934 message. 936 Note that an entry would already exist if the client and server's 937 session establishment procedures had been successfully completed 938 previously (as described both above and in Section 5.3) even if 939 no message had yet been sent through the newly established 940 session. An entry may not exist, however, if a message not 941 intended the SNMP entity was routed to it by mistake. An entry 942 might also be missing because of a "broken" session (see 943 operational considerations). 945 3) Retrieve the tlstmSessionID from the LCD. 947 4) The UDP packet and the tlstmSessionID are passed to DTLS for 948 integrity checking and decryption. 950 If the message fails integrity checks or other (D)TLS security 951 processing then increment the tlstmDTLSProtectionErrors counter, 952 discard and stop processing the message. 954 5) (D)TLS should return an incomingMessage and an 955 incomingMessageLength. These results and the tlstmSessionID are 956 used below in the Section 5.1.2 to complete the processing of the 957 incoming message. 959 5.1.2. Transport Processing for Incoming SNMP Messages 961 The procedures in this section describe how the TLS Transport Model 962 should process messages that have already been properly extracted 963 from the (D)TLS stream. Note that care must be taken when processing 964 messages originating from either TLS or DTLS to ensure they're 965 complete and single. For example, multiple SNMP messages can be 966 passed through a single DTLS message and partial SNMP messages may be 967 received from a TLS stream. These steps describe the processing of a 968 singular SNMP message after it has been delivered from the (D)TLS 969 stream. 971 Create a tmStateReference cache for the subsequent reference and 972 assign the following values within it: 974 tmTransportDomain = snmpTLSTCPDomain, snmpDTLSUDPDomain or 975 snmpDTLSSCTPDomain as appropriate. 977 tmTransportAddress = The address the message originated from. 979 tmSecurityLevel = The derived tmSecurityLevel for the session, as 980 discussed in Section 3.1.2 and Section 5.3. 982 tmSecurityName = The derived tmSecurityName for the session as 983 discussed in Section 5.3. This value MUST be constant during the 984 lifetime of the (D)TLS session. 986 tmSessionID = The tlstmSessionID, which MUST be a unique session 987 identifier for this (D)TLS connection. The contents and format of 988 this identifier are implementation-dependent as long as it is 989 unique to the session. A session identifier MUST NOT be reused 990 until all references to it are no longer in use. The tmSessionID 991 is equal to the tlstmSessionID discussed in Section 5.1.1. 992 tmSessionID refers to the session identifier when stored in the 993 tmStateReference and tlstmSessionID refers to the session 994 identifier when stored in the LCD. They MUST always be equal when 995 processing a given session's traffic. 997 The wholeMessage and the wholeMessageLength are assigned values from 998 the incomingMessage and incomingMessageLength values from the (D)TLS 999 processing. 1001 The TLS Transport Model passes the transportDomain, transportAddress, 1002 wholeMessage, and wholeMessageLength to the Dispatcher using the 1003 receiveMessage ASI: 1005 statusInformation = 1006 receiveMessage( 1007 IN transportDomain -- snmpTLSTCPDomain, snmpDTLSUDPDomain, 1008 -- or snmpDTLSSCTPDomain 1009 IN transportAddress -- address for the received message 1010 IN wholeMessage -- the whole SNMP message from (D)TLS 1011 IN wholeMessageLength -- the length of the SNMP message 1012 IN tmStateReference -- transport info 1013 ) 1015 5.2. Procedures for an Outgoing SNMP Message 1017 The Dispatcher sends a message to the TLS Transport Model using the 1018 following ASI: 1020 statusInformation = 1021 sendMessage( 1022 IN destTransportDomain -- transport domain to be used 1023 IN destTransportAddress -- transport address to be used 1024 IN outgoingMessage -- the message to send 1025 IN outgoingMessageLength -- its length 1026 IN tmStateReference -- transport info 1027 ) 1029 This section describes the procedure followed by the TLS Transport 1030 Model whenever it is requested through this ASI to send a message. 1032 1) If tmStateReference does not refer to a cache containing values 1033 for tmTransportDomain, tmTransportAddress, tmSecurityName, 1034 tmRequestedSecurityLevel, and tmSameSecurity, then increment the 1035 snmpTlstmSessionInvalidCaches counter, discard the message, and 1036 return the error indication in the statusInformation. Processing 1037 of this message stops. 1039 2) Extract the tmSessionID, tmTransportDomain, tmTransportAddress, 1040 tmSecurityName, tmRequestedSecurityLevel, and tmSameSecurity 1041 values from the tmStateReference. Note: The tmSessionID value 1042 may be undefined if no session exists yet over which the message 1043 can be sent. 1045 3) If tmSameSecurity is true and either tmSessionID is undefined or 1046 refers to a session that is no longer open then increment the 1047 snmpTlstmSessionNoSessions counter, discard the message and 1048 return the error indication in the statusInformation. Processing 1049 of this message stops. 1051 4) If tmSameSecurity is false and tmSessionID refers to a session 1052 that is no longer available then an implementation SHOULD open a 1053 new session using the openSession() ASI (described in greater 1054 detail in step 4b). Instead of opening a new session an 1055 implementation MAY return a snmpTlstmSessionNoSessions error to 1056 the calling module and stop processing of the message. 1058 5) If tmSessionID is undefined, then use tmTransportDomain, 1059 tmTransportAddress, tmSecurityName and tmRequestedSecurityLevel 1060 to see if there is a corresponding entry in the LCD suitable to 1061 send the message over. 1063 4a) If there is a corresponding LCD entry, then this session 1064 will be used to send the message. 1066 4b) If there is not a corresponding LCD entry, then open a 1067 session using the openSession() ASI (discussed further in 1068 Section 5.3). Implementations MAY wish to offer message 1069 buffering to prevent redundant openSession() calls for the 1070 same cache entry. If an error is returned from 1071 openSession(), then discard the message, discard the 1072 tmStateReferenc, increment the snmpTlstmSessionOpenErrors, 1073 return an error indication to the calling module and stop 1074 processing of the message. 1076 6) Using either the session indicated by the tmSessionID if there 1077 was one or the session resulting from a previous step (3 or 4), 1078 pass the outgoingMessage to (D)TLS for encapsulation and 1079 transmission. 1081 5.3. Establishing a Session 1083 The TLS Transport Model provides the following primitive to establish 1084 a new (D)TLS session: 1086 statusInformation = -- errorIndication or success 1087 openSession( 1088 IN tmStateReference -- transport information to be used 1089 OUT tmStateReference -- transport information to be used 1090 IN maxMessageSize -- of the sending SNMP entity 1091 ) 1093 The following describes the procedure to follow when establishing a 1094 SNMP over (D)TLS session between SNMP engines for exchanging SNMP 1095 messages. This process is followed by any SNMP engine establishing a 1096 session for subsequent use. 1098 This MAY be done automatically for an SNMP application that initiates 1099 a transaction, such as a command generator, a notification 1100 originator, or a proxy forwarder. 1102 1) The client selects the appropriate certificate and cipher_suites 1103 for the key agreement based on the tmSecurityName and the 1104 tmRequestedSecurityLevel for the session. For sessions being 1105 established as a result of a SNMP-TARGET-MIB based operation, the 1106 certificate will potentially have been identified via the 1107 tlstmParamsTable mapping and the cipher_suites will have to be 1108 taken from system-wide or implementation-specific configuration. 1109 Otherwise, the certificate and appropriate cipher_suites will 1110 need to be passed to the openSession() ASI as supplemental 1111 information or configured through an implementation-dependent 1112 mechanism. It is also implementation-dependent and possibly 1113 policy-dependent how tmRequestedSecurityLevel will be used to 1114 influence the security capabilities provided by the (D)TLS 1115 session. However this is done, the security capabilities 1116 provided by (D)TLS MUST be at least as high as the level of 1117 security indicated by the tmRequestedSecurityLevel parameter. 1118 The actual security level of the session is reported in the 1119 tmStateReference cache as tmSecurityLevel. For (D)TLS to provide 1120 strong authentication, each principal acting as a command 1121 generator SHOULD have its own certificate. 1123 2) Using the destTransportDomain and destTransportAddress values, 1124 the client will initiate the (D)TLS handshake protocol to 1125 establish session keys for message integrity and encryption. 1127 If the attempt to establish a session is unsuccessful, then 1128 snmpTlstmSessionOpenErrors is incremented, an error indication is 1129 returned, and processing stops. If the session failed to open 1130 because the presented server certificate was unknown or invalid 1131 then the snmpTlstmSessionUnknownServerCertificate or 1132 snmpTlstmSessionInvalidServerCertificates MUST be incremented and 1133 a tlstmServerCertificateUnknown or tlstmServerInvalidCertificate 1134 notification SHOULD be sent as appropriate. Reasons for server 1135 certificate invalidation includes, but is not limited to, 1136 cryptographic validation failures and an unexpected presented 1137 certificate identity. 1139 3) Once a (D)TLS secured session is established and both sides have 1140 verified the authenticity of the peer's certificate (e.g. 1141 [RFC5280]) then each side will determine and/or check the 1142 identity of the remote entity using the procedures described 1143 below. 1145 a) The (D)TLS server side of the connection identifies the 1146 authenticated identity from the (D)TLS client's principal 1147 certificate using configuration information from the 1148 tlstmCertToTSNTable mapping table. The resulting derived 1149 tmSecurityName is recorded in the tmStateReference cache as 1150 tmSecurityName. The details of the lookup process are fully 1151 described in the DESCRIPTION clause of the 1152 tlstmCertToTSNTable MIB object. If any verification fails in 1153 any way (for example because of failures in cryptographic 1154 verification or because of the lack of an appropriate row in 1155 the tlstmCertToTSNTable) then the session establishment MUST 1156 fail, the snmpTlstmSessionInvalidClientCertificates object is 1157 incremented and processing stops. 1159 b) The (D)TLS client side of the connection MUST verify that 1160 authenticated identity of the (D)TLS server's presented 1161 certificate is the expected certificate. 1163 If the connection is being established from configuration 1164 based on SNMP-TARGET-MIB configuration then the procedures in 1165 the tlstmAddrTable DESCRIPTION clause should be followed to 1166 determine the if the presented identity matches the 1167 expectations of the configuration. Path validation 1168 procedures (like those defined in [RFC5280]) MUST be 1169 followed. If a server identity name has been configured in 1170 the tlstmAddrServerIdentity column then this reference 1171 identity must be compared against the presented identity (for 1172 example using procedures described in 1173 [I-D.saintandre-tls-server-id-check]). 1175 If the connection is being established for other reasons then 1176 configuration and procedures outside the scope of this 1177 document should be followed. 1179 (D)TLS provides assurance that the authenticated identity has 1180 been signed by a trusted configured certificate authority. 1181 If verification of the server's certificate fails in any way 1182 (for example because of failures in cryptographic 1183 verification or the presented identity did not match the 1184 expected named entity) then the session establishment MUST 1185 fail, the snmpTlstmSessionInvalidServerCertificates object is 1186 incremented and processing stops. 1188 4) The (D)TLS-specific session identifier is set in the sessionID of 1189 the tmStateReference passed to the TLS Transport Model to 1190 indicate that the session has been established successfully and 1191 to point to a specific (D)TLS session for future use. 1193 Servers that wish to support multiple principals at a particular port 1194 SHOULD make use of the Server Name Indication extension defined in 1195 Section 3.1 of [RFC4366]. Supporting this will allow, for example, 1196 sending notifications to a specific principal at a given TCP, UDP or 1197 SCTP port. 1199 5.4. Closing a Session 1201 The TLS Transport Model provides the following primitive to close a 1202 session: 1204 statusInformation = 1205 closeSession( 1206 IN tmSessionID -- session ID of the session to be closed 1207 ) 1209 The following describes the procedure to follow to close a session 1210 between a client and server. This process is followed by any SNMP 1211 engine closing the corresponding SNMP session. 1213 1) Increment the snmpTlstmSessionCloses counter. 1215 2) Look up the session using the tmSessionID. 1217 3) If there is no open session associated with the tmSessionID, then 1218 closeSession processing is completed. 1220 4) Have (D)TLS close the specified session. This SHOULD include 1221 sending a close_notify TLS Alert to inform the other side that 1222 session cleanup may be performed. 1224 6. MIB Module Overview 1226 This MIB module provides management of the TLS Transport Model. It 1227 defines needed textual conventions, statistical counters, 1228 notifications and configuration infrastructure necessary for session 1229 establishment. Example usage of the configuration tables can be 1230 found in Appendix C. 1232 6.1. Structure of the MIB Module 1234 Objects in this MIB module are arranged into subtrees. Each subtree 1235 is organized as a set of related objects. The overall structure and 1236 assignment of objects to their subtrees, and the intended purpose of 1237 each subtree, is shown below. 1239 6.2. Textual Conventions 1241 Generic and Common Textual Conventions used in this module can be 1242 found summarized at http://www.ops.ietf.org/mib-common-tcs.html 1244 This module defines the following new Textual Conventions: 1246 o New TransportDomain and TransportAddress formats for describing 1247 (D)TLS connection addressing requirements. 1249 o A certificate fingerprint allowing MIB module objects to 1250 generically refer to a stored X.509 certificate using a 1251 cryptographic hash as a reference pointer. 1253 6.3. Statistical Counters 1255 The TLSTM-MIB defines some counters that can provide network managers 1256 with information about (D)TLS session usage and potential errors that 1257 a MIB-instrumented device may be experiencing. 1259 6.4. Configuration Tables 1261 The TLSTM-MIB defines configuration tables that a manager can use for 1262 configuring a MIB-instrumented device for sending and receiving SNMP 1263 messages over (D)TLS. In particular, there are MIB tables that 1264 extend the SNMP-TARGET-MIB for configuring (D)TLS certificate usage 1265 and a MIB table for mapping incoming (D)TLS client certificates to 1266 SNMPv3 securityNames. 1268 6.4.1. Notifications 1270 The TLSTM-MIB defines notifications to alert management stations when 1271 a (D)TLS connection fails because a server's presented certificate 1272 did not meet an expected value (tlstmServerCertificateUnknown) or 1273 because cryptographic validation failed 1274 (tlstmServerInvalidCertificate). 1276 6.5. Relationship to Other MIB Modules 1278 Some management objects defined in other MIB modules are applicable 1279 to an entity implementing the TLS Transport Model. In particular, it 1280 is assumed that an entity implementing the TLSTM-MIB will implement 1281 the SNMPv2-MIB [RFC3418], the SNMP-FRAMEWORK-MIB [RFC3411], the SNMP- 1282 TARGET-MIB [RFC3413], the SNMP-NOTIFICATION-MIB [RFC3413] and the 1283 SNMP-VIEW-BASED-ACM-MIB [RFC3415]. 1285 The TLSTM-MIB module contained in this document is for managing TLS 1286 Transport Model information. 1288 6.5.1. MIB Modules Required for IMPORTS 1290 The TLSTM-MIB module imports items from SNMPv2-SMI [RFC2578], 1291 SNMPv2-TC [RFC2579], SNMP-FRAMEWORK-MIB [RFC3411], SNMP-TARGET-MIB 1292 [RFC3413] and SNMPv2-CONF [RFC2580]. 1294 7. MIB Module Definition 1296 TLSTM-MIB DEFINITIONS ::= BEGIN 1298 IMPORTS 1299 MODULE-IDENTITY, OBJECT-TYPE, 1300 OBJECT-IDENTITY, snmpModules, snmpDomains, 1301 Counter32, Unsigned32, NOTIFICATION-TYPE 1302 FROM SNMPv2-SMI 1303 TEXTUAL-CONVENTION, TimeStamp, RowStatus, StorageType, 1304 AutonomousType 1305 FROM SNMPv2-TC 1306 MODULE-COMPLIANCE, OBJECT-GROUP, NOTIFICATION-GROUP 1307 FROM SNMPv2-CONF 1308 SnmpAdminString 1309 FROM SNMP-FRAMEWORK-MIB 1310 snmpTargetParamsName, snmpTargetAddrName 1311 FROM SNMP-TARGET-MIB 1312 ; 1314 tlstmMIB MODULE-IDENTITY 1315 LAST-UPDATED "200912230000Z" 1316 ORGANIZATION "ISMS Working Group" 1317 CONTACT-INFO "WG-EMail: isms@lists.ietf.org 1318 Subscribe: isms-request@lists.ietf.org 1320 Chairs: 1321 Juergen Schoenwaelder 1322 Jacobs University Bremen 1323 Campus Ring 1 1324 28725 Bremen 1325 Germany 1326 +49 421 200-3587 1327 j.schoenwaelder@jacobs-university.de 1329 Russ Mundy 1330 SPARTA, Inc. 1331 7110 Samuel Morse Drive 1332 Columbia, MD 21046 1333 USA 1335 Co-editors: 1336 Wes Hardaker 1337 Sparta, Inc. 1338 P.O. Box 382 1339 Davis, CA 95617 1340 USA 1341 ietf@hardakers.net 1342 " 1344 DESCRIPTION " 1345 The TLS Transport Model MIB 1347 Copyright (c) 2009 IETF Trust and the persons identified as 1348 the document authors. All rights reserved. 1350 Redistribution and use in source and binary forms, with or 1351 without modification, is permitted pursuant to, and subject 1352 to the license terms contained in, the Simplified BSD License 1353 set forth in Section 4.c of the IETF Trust's Legal Provisions 1354 Relating to IETF Documents 1355 (http://trustee.ietf.org/license-info). 1357 This version of this MIB module is part of RFC XXXX; 1358 see the RFC itself for full legal notices." 1360 -- NOTE to RFC editor: replace XXXX with actual RFC number 1361 -- for this document and remove this note 1363 REVISION "200912230000Z" 1364 DESCRIPTION "The initial version, published in RFC XXXX." 1365 -- NOTE to RFC editor: replace XXXX with actual RFC number 1366 -- for this document and remove this note 1368 ::= { snmpModules xxxx } 1369 -- RFC Ed.: replace xxxx with IANA-assigned number and 1370 -- remove this note 1372 -- ************************************************ 1373 -- subtrees of the TLSTM-MIB 1374 -- ************************************************ 1376 tlstmNotifications OBJECT IDENTIFIER ::= { tlstmMIB 0 } 1377 tlstmIdentities OBJECT IDENTIFIER ::= { tlstmMIB 1 } 1378 tlstmObjects OBJECT IDENTIFIER ::= { tlstmMIB 2 } 1379 tlstmConformance OBJECT IDENTIFIER ::= { tlstmMIB 3 } 1381 -- ************************************************ 1382 -- tlstmObjects - Objects 1383 -- ************************************************ 1385 snmpTLSTCPDomain OBJECT-IDENTITY 1386 STATUS current 1387 DESCRIPTION 1388 "The SNMP over TLS transport domain. The corresponding 1389 transport address is of type SnmpTLSAddress. 1391 The securityName prefix to be associated with the 1392 snmpTLSTCPDomain is 'tls'. This prefix may be used by 1393 security models or other components to identify which secure 1394 transport infrastructure authenticated a securityName." 1396 ::= { snmpDomains xx } 1398 -- RFC Ed.: replace xx with IANA-assigned number and 1399 -- remove this note 1401 -- RFC Ed.: replace 'tls' with the actual IANA assigned prefix string 1402 -- if 'tls' is not assigned to this document. 1404 snmpDTLSUDPDomain OBJECT-IDENTITY 1405 STATUS current 1406 DESCRIPTION 1407 "The SNMP over DTLS/UDP transport domain. The corresponding 1408 transport address is of type SnmpTLSAddress. 1410 The securityName prefix to be associated with the 1411 snmpDTLSUDPDomain is 'dudp'. This prefix may be used by 1412 security models or other components to identify which secure 1413 transport infrastructure authenticated a securityName." 1415 ::= { snmpDomains yy } 1417 -- RFC Ed.: replace yy with IANA-assigned number and 1418 -- remove this note 1420 -- RFC Ed.: replace 'dudp' with the actual IANA assigned prefix string 1421 -- if 'dtls' is not assigned to this document. 1423 snmpDTLSSCTPDomain OBJECT-IDENTITY 1424 STATUS current 1425 DESCRIPTION 1426 "The SNMP over DTLS/SCTP transport domain. The corresponding 1427 transport address is of type SnmpTLSAddress. 1429 The securityName prefix to be associated with the 1430 snmpDTLSSCTPDomain is 'dsct'. This prefix may be used by 1431 security models or other components to identify which secure 1432 transport infrastructure authenticated a securityName." 1434 ::= { snmpDomains zz } 1436 -- RFC Ed.: replace zz with IANA-assigned number and 1437 -- remove this note 1439 -- RFC Ed.: replace 'dsct' with the actual IANA assigned prefix string 1440 -- if 'dtls' is not assigned to this document. 1442 SnmpTLSAddress ::= TEXTUAL-CONVENTION 1443 DISPLAY-HINT "1a" 1444 STATUS current 1445 DESCRIPTION 1446 "Represents a IPv4 address, an IPv6 address or an US-ASCII 1447 encoded hostname and port number. 1449 An IPv4 address must be in dotted decimal format followed by a 1450 colon ':' (US-ASCII character 0x3A) and a decimal port number 1451 in US-ASCII. 1453 An IPv6 address must be a colon separated format, surrounded 1454 by square brackets ('[', US-ASCII character 0x5B, and ']', 1455 US-ASCII character 0x5D), followed by a colon ':' (US-ASCII 1456 character 0x3A) and a decimal port number in US-ASCII. 1458 A hostname is always in US-ASCII (as per RFC1033); 1459 internationalized hostnames are encoded in US-ASCII as 1460 specified in RFC 3490. The hostname is followed by a colon 1461 ':' (US-ASCII character 0x3A) and a decimal port number in 1462 US-ASCII. The name SHOULD be fully qualified whenever 1463 possible. 1465 Values of this textual convention may not be directly usable 1466 as transport-layer addressing information, and may require 1467 run-time resolution. As such, applications that write them 1468 must be prepared for handling errors if such values are not 1469 supported, or cannot be resolved (if resolution occurs at the 1470 time of the management operation). 1472 The DESCRIPTION clause of TransportAddress objects that may 1473 have SnmpTLSAddress values must fully describe how (and 1474 when) such names are to be resolved to IP addresses and vice 1475 versa. 1477 This textual convention SHOULD NOT be used directly in object 1478 definitions since it restricts addresses to a specific 1479 format. However, if it is used, it MAY be used either on its 1480 own or in conjunction with TransportAddressType or 1481 TransportDomain as a pair. 1483 When this textual convention is used as a syntax of an index 1484 object, there may be issues with the limit of 128 1485 sub-identifiers specified in SMIv2 (STD 58). It is RECOMMENDED 1486 that all MIB documents using this textual convention make 1487 explicit any limitations on index component lengths that 1488 management software must observe. This may be done either by 1489 including SIZE constraints on the index components or by 1490 specifying applicable constraints in the conceptual row 1491 DESCRIPTION clause or in the surrounding documentation." 1492 REFERENCE 1493 "RFC 1033: DOMAIN ADMINISTRATORS OPERATIONS GUIDE 1494 RFC 3490: Internationalizing Domain Names in Applications 1495 RFC 3986: Uniform Resource Identifier (URI): Generic Syntax 1496 RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 1497 " 1498 SYNTAX OCTET STRING (SIZE (1..255)) 1500 Fingerprint ::= TEXTUAL-CONVENTION 1501 DISPLAY-HINT "1x:254x" 1502 STATUS current 1503 DESCRIPTION 1504 "A Fingerprint value that can be used to uniquely reference 1505 other data of potentially arbitrary length. 1507 A Fingerprint value is composed of a 1-octet hashing algorithm 1508 identifier followed by the fingerprint value. The octet value 1509 encoded is taken from the IANA TLS HashAlgorithm Registry 1510 (RFC5246). The remaining octets are filled using the results 1511 of the hashing algorithm. 1513 This TEXTUAL-CONVENTION allows for a zero-length (blank) 1514 Fingerprint value for use in tables where the fingerprint value 1515 may be optional. MIB definitions or implementations may refuse 1516 to accept a zero-length value as appropriate." 1517 REFERENCE 1518 "RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 1519 " 1520 SYNTAX OCTET STRING (SIZE (0..255)) 1522 -- Identities 1524 tlstmCertToTSNMIdentities OBJECT IDENTIFIER ::= { tlstmIdentities 1 } 1526 tlstmCertSpecified OBJECT-IDENTITY 1527 STATUS current 1528 DESCRIPTION "Directly specifies the tmSecurityName to be used for 1529 this certificate. The value of the tmSecurityName to 1530 use is specified in the tlstmCertToTSNData column. 1531 The column must contain a SnmpAdminString compliant 1532 value or contains a zero length string then the 1533 mapping will be considered a failure." 1534 ::= { tlstmCertToTSNMIdentities 1 } 1536 tlstmCertSANRFC822Name OBJECT-IDENTITY 1537 STATUS current 1538 DESCRIPTION "Maps a subjectAltName's rfc822Name to a 1539 tmSecurityName. The local part of the rfc822Name is 1540 passed unaltered but the host-part of the name must 1541 be passed in lower case. 1543 Example rfc822Name Field: FooBar@Example.COM 1544 is mapped to tmSecurityName: FooBar@exmaple.com" 1545 ::= { tlstmCertToTSNMIdentities 2 } 1547 tlstmCertSANDNSName OBJECT-IDENTITY 1548 STATUS current 1549 DESCRIPTION "Maps a subjectAltName's dNSName to a 1550 tmSecurityName by directly passing the value without 1551 any transformations." 1552 ::= { tlstmCertToTSNMIdentities 3 } 1554 tlstmCertSANIpAddress OBJECT-IDENTITY 1555 STATUS current 1556 DESCRIPTION "Maps a subjectAltName's ipAddress to a 1557 tmSecurityName by transforming the binary encoded 1558 address as follows: 1560 1) for IPv4 the value is converted into a decimal 1561 dotted quad address (e.g. '192.0.2.1') 1563 2) for IPv6 addresses the value is converted into a 1564 32-character hexadecimal string without any colon 1565 separators. 1567 Note that the resulting length is the maximum 1568 length supported by the View-Based Access Control 1569 Model (VACM). Note that using both the Transport 1570 Security Model's support for transport prefixes 1571 (see the SNMP-TSM-MIB's 1572 snmpTsmConfigurationUsePrefix object for details) 1573 will result in securityName lengths that exceed 1574 what VACM can handle." 1575 ::= { tlstmCertToTSNMIdentities 4 } 1577 tlstmCertSANAny OBJECT-IDENTITY 1578 STATUS current 1579 DESCRIPTION "Maps any of the following fields using the 1580 corresponding mapping algorithms: 1582 |------------+------------------------| 1583 | Type | Algorithm | 1584 |------------+------------------------| 1585 | rfc822Name | tlstmCertSANRFC822Name | 1586 | dNSName | tlstmCertSANDNSName | 1587 | ipAddress | tlstmCertSANIpAddress | 1588 |------------+------------------------| 1590 The first matching subjectAltName value found in the 1591 certificate any of the above types MUST be used when 1592 deriving the tmSecurityName." 1593 ::= { tlstmCertToTSNMIdentities 5 } 1595 tlstmCertCommonName OBJECT-IDENTITY 1596 STATUS current 1597 DESCRIPTION "Maps a certificate's CommonName to a 1598 tmSecurityName by directly passing the value without 1599 any transformations." 1600 ::= { tlstmCertToTSNMIdentities 6 } 1602 -- The snmpTlstmSession Group 1604 snmpTlstmSession OBJECT IDENTIFIER ::= { tlstmObjects 1 } 1606 snmpTlstmSessionOpens OBJECT-TYPE 1607 SYNTAX Counter32 1608 MAX-ACCESS read-only 1609 STATUS current 1610 DESCRIPTION 1611 "The number of times an openSession() request has been 1612 executed as an (D)TLS client, whether it succeeded or failed." 1613 ::= { snmpTlstmSession 1 } 1615 snmpTlstmSessionCloses OBJECT-TYPE 1616 SYNTAX Counter32 1617 MAX-ACCESS read-only 1618 STATUS current 1619 DESCRIPTION 1620 "The number of times a closeSession() request has been 1621 executed as an (D)TLS client, whether it succeeded or failed." 1622 ::= { snmpTlstmSession 2 } 1624 snmpTlstmSessionOpenErrors OBJECT-TYPE 1625 SYNTAX Counter32 1626 MAX-ACCESS read-only 1627 STATUS current 1628 DESCRIPTION 1629 "The number of times an openSession() request failed to open a 1630 session as a (D)TLS client, for any reason." 1631 ::= { snmpTlstmSession 3 } 1633 snmpTlstmSessionNoSessions OBJECT-TYPE 1634 SYNTAX Counter32 1635 MAX-ACCESS read-only 1636 STATUS current 1637 DESCRIPTION 1638 "The number of times an outgoing message was dropped because 1639 the session associated with the passed tmStateReference was no 1640 longer (or was never) available." 1641 ::= { snmpTlstmSession 4 } 1643 snmpTlstmSessionInvalidClientCertificates OBJECT-TYPE 1644 SYNTAX Counter32 1645 MAX-ACCESS read-only 1646 STATUS current 1647 DESCRIPTION 1648 "The number of times an incoming session was not established 1649 on an (D)TLS server because the presented client certificate was 1650 invalid. Reasons for invalidation include, but are not 1651 limited to, cryptographic validation failures or lack of a 1652 suitable mapping row in the tlstmCertToTSNTable." 1653 ::= { snmpTlstmSession 5 } 1655 snmpTlstmSessionUnknownServerCertificate OBJECT-TYPE 1656 SYNTAX Counter32 1657 MAX-ACCESS read-only 1658 STATUS current 1659 DESCRIPTION 1660 "The number of times an outgoing session was not established 1661 on an (D)TLS client because the server certificate presented 1662 by a SNMP over (D)TLS server was invalid because no 1663 configured fingerprint or CA was acceptable to validate it. 1664 This may result because there was no entry in the 1665 tlstmAddrTable or because no path could be found to known 1666 certificate authority." 1667 ::= { snmpTlstmSession 6 } 1669 snmpTlstmSessionInvalidServerCertificates OBJECT-TYPE 1670 SYNTAX Counter32 1671 MAX-ACCESS read-only 1672 STATUS current 1673 DESCRIPTION 1674 "The number of times an outgoing session was not established 1675 on an (D)TLS client because the server certificate presented 1676 by an SNMP over (D)TLS server could not be validated even if 1677 the fingerprint or expected validation path was known. I.E., 1678 a cryptographic validation occurred during certificate 1679 validation processing. 1681 Reasons for invalidation include, but are not 1682 limited to, cryptographic validation failures." 1683 ::= { snmpTlstmSession 7 } 1685 snmpTlstmSessionInvalidCaches OBJECT-TYPE 1686 SYNTAX Counter32 1687 MAX-ACCESS read-only 1688 STATUS current 1689 DESCRIPTION 1690 "The number of outgoing messages dropped because the 1691 tmStateReference referred to an invalid cache." 1692 ::= { snmpTlstmSession 8 } 1694 tlstmTLSProtectionErrors OBJECT-TYPE 1695 SYNTAX Counter32 1696 MAX-ACCESS read-only 1697 STATUS current 1698 DESCRIPTION 1699 "The number of times (D)TLS processing resulted in a message 1700 being discarded because it failed its integrity test, 1701 decryption processing or other (D)TLS processing." 1702 ::= { snmpTlstmSession 9 } 1704 -- Configuration Objects 1706 tlstmConfig OBJECT IDENTIFIER ::= { tlstmObjects 2 } 1708 -- Certificate mapping 1710 tlstmCertificateMapping OBJECT IDENTIFIER ::= { tlstmConfig 1 } 1712 tlstmCertToTSNCount OBJECT-TYPE 1713 SYNTAX Unsigned32 1714 MAX-ACCESS read-only 1715 STATUS current 1716 DESCRIPTION 1717 "A count of the number of entries in the tlstmCertToTSNTable" 1718 ::= { tlstmCertificateMapping 1 } 1720 tlstmCertToTSNTableLastChanged OBJECT-TYPE 1721 SYNTAX TimeStamp 1722 MAX-ACCESS read-only 1723 STATUS current 1724 DESCRIPTION 1725 "The value of sysUpTime.0 when the tlstmCertToTSNTable 1726 was last modified through any means, or 0 if it has not been 1727 modified since the command responder was started." 1728 ::= { tlstmCertificateMapping 2 } 1730 tlstmCertToTSNTable OBJECT-TYPE 1731 SYNTAX SEQUENCE OF TlstmCertToTSNEntry 1732 MAX-ACCESS not-accessible 1733 STATUS current 1734 DESCRIPTION 1735 "A table listing the X.509 certificates known to the entity 1736 and the associated method for determining the SNMPv3 security 1737 name from a certificate. 1739 On an incoming (D)TLS/SNMP connection the client's presented 1740 certificate must be examined and validated based on an 1741 established trusted path from a CA certificate or self-signed 1742 public certificate (e.g. RFC5280). This table provides a 1743 mapping from a validated certificate to a tmSecurityName. 1744 This table does not provide any mechanisms for uploading 1745 trusted certificates; the transfer of any needed trusted 1746 certificates for path validation is expected to occur through 1747 an out-of-band transfer. 1749 Once the authenticity of a certificate has been verified, this 1750 table is consulted to determine the appropriate tmSecurityName 1751 to identify with the remote connection. This is done by 1752 considering each active row from this table in prioritized 1753 order according to its tlstmCertToTSNID value. Each row's 1754 tlstmCertToTSNFingerprint value determines whether the row is a 1755 match for the incoming connection: 1757 1) If the row's tlstmCertToTSNFingerprint value identifies 1758 the presented certificate then consider the row as a 1759 successful match. 1761 2) If the row's tlstmCertToTSNFingerprint value identifies 1762 a locally held copy of a trusted CA certificate and 1763 that CA certificated was used to validate the path to 1764 the presented certificate then consider the row as a 1765 successful match. 1767 Once a matching row has been found, the tlstmCertToTSNMapType 1768 value can be used to determine how the tmSecurityName to 1769 associate with the session should be determined. See the 1770 tlstmCertToTSNMapType column's DESCRIPTION for details on 1771 determining the tmSecurityName value. If it is impossible to 1772 determine a tmSecurityName from the row's data combined with the 1773 data presented in the certificate then additional rows MUST be 1774 searched looking for another potential match. If a resulting 1775 tmSecurityName mapped from a given row is not compatible with 1776 the needed requirements of a tmSecurityName (e.g., VACM imposes 1777 a 32-octet-maximum length and the certificate derived 1778 securityName could be longer) then it must be considered an 1779 invalid match and additional rows MUST be searched looking for 1780 another potential match. 1782 Missing values of tlstmCertToTSNID are acceptable and 1783 implementations should continue to the next highest numbered 1784 row. E.G., the table may legally contain only two rows with 1785 tlstmCertToTSNID values of 10 and 20. 1787 Users are encouraged to make use of certificates with 1788 subjectAltName fields that can be used as tmSecurityNames so 1789 that a single root CA certificate can allow all child 1790 certificate's subjectAltName to map directly to a tmSecurityName 1791 via a 1:1 transformation. However, this table is flexible to 1792 allow for situations where existing deployed certificate 1793 infrastructures do not provide adequate subjectAltName values 1794 for use as tmSecurityNames. Certificates may also be 1795 mapped to tmSecurityNames using the CommonName portion of the 1796 Subject field but usage of the CommonName field is deprecated. 1797 Direct mapping from each individual certificate fingerprint to 1798 a tmSecurityName is also possible but requires one entry in the 1799 table per tmSecurityName and requires more management operations 1800 to completely configure a device." 1801 ::= { tlstmCertificateMapping 3 } 1803 tlstmCertToTSNEntry OBJECT-TYPE 1804 SYNTAX TlstmCertToTSNEntry 1805 MAX-ACCESS not-accessible 1806 STATUS current 1807 DESCRIPTION 1808 "A row in the tlstmCertToTSNTable that specifies a mapping for 1809 an incoming (D)TLS certificate to a tmSecurityName to use for a 1810 connection." 1811 INDEX { tlstmCertToTSNID } 1812 ::= { tlstmCertToTSNTable 1 } 1814 TlstmCertToTSNEntry ::= SEQUENCE { 1815 tlstmCertToTSNID Unsigned32, 1816 tlstmCertToTSNFingerprint Fingerprint, 1817 tlstmCertToTSNMapType AutonomousType, 1818 tlstmCertToTSNData OCTET STRING, 1819 tlstmCertToTSNStorageType StorageType, 1820 tlstmCertToTSNRowStatus RowStatus 1821 } 1823 tlstmCertToTSNID OBJECT-TYPE 1824 SYNTAX Unsigned32 (1..4294967295) 1825 MAX-ACCESS not-accessible 1826 STATUS current 1827 DESCRIPTION 1828 "A unique, prioritized index for the given entry." 1829 ::= { tlstmCertToTSNEntry 1 } 1831 tlstmCertToTSNFingerprint OBJECT-TYPE 1832 SYNTAX Fingerprint (SIZE(1..255)) 1833 MAX-ACCESS read-create 1834 STATUS current 1835 DESCRIPTION 1836 "A cryptographic hash of a X.509 certificate. The results of 1837 a successful matching fingerprint to either the trusted CA in 1838 the certificate validation path or to the certificate itself 1839 is dictated by the tlstmCertToTSNMapType column." 1840 ::= { tlstmCertToTSNEntry 2 } 1842 tlstmCertToTSNMapType OBJECT-TYPE 1843 SYNTAX AutonomousType 1844 MAX-ACCESS read-create 1845 STATUS current 1846 DESCRIPTION 1847 "Specifies the mapping type for deriving a tmSecurityName from a 1848 certificate. Details for mapping of a particular type SHALL 1849 be specified in the DESCRIPTION clause of the OBJECT-IDENTITY 1850 that describes the mapping. If a mapping succeeds it will 1851 return a tmSecurityName for use by the TLSTM model and 1852 processing stops. 1854 If the resulting mapped value is not compatible with the 1855 needed requirements of a tmSecurityName (e.g., VACM imposes a 1856 32-octet-maximum length and the certificate derived 1857 securityName could be longer) then future rows MUST be 1858 searched for additional tlstmCertToTSNFingerprint matches to 1859 look for a mapping that succeeds." 1860 DEFVAL { tlstmCertSpecified } 1861 ::= { tlstmCertToTSNEntry 3 } 1863 tlstmCertToTSNData OBJECT-TYPE 1864 SYNTAX OCTET STRING (SIZE(0..1024)) 1865 MAX-ACCESS read-create 1866 STATUS current 1867 DESCRIPTION 1868 "Axillary data used as optional configuration information for 1869 a given mapping specified by the tlstmCertToTSNMapType column. 1870 Only some mapping systems will make use of this column. The 1871 value in this column MUST be ignored for any mapping type that 1872 does not require data present in this column." 1873 DEFVAL { "" } 1874 ::= { tlstmCertToTSNEntry 4 } 1876 tlstmCertToTSNStorageType OBJECT-TYPE 1877 SYNTAX StorageType 1878 MAX-ACCESS read-create 1879 STATUS current 1880 DESCRIPTION 1881 "The storage type for this conceptual row. Conceptual rows 1882 having the value 'permanent' need not allow write-access to 1883 any columnar objects in the row." 1884 DEFVAL { nonVolatile } 1885 ::= { tlstmCertToTSNEntry 5 } 1887 tlstmCertToTSNRowStatus OBJECT-TYPE 1888 SYNTAX RowStatus 1889 MAX-ACCESS read-create 1890 STATUS current 1891 DESCRIPTION 1892 "The status of this conceptual row. This object may be used 1893 to create or remove rows from this table. 1895 To create a row in this table, a manager must set this object 1896 to either createAndGo(4) or createAndWait(5). 1898 Until instances of all corresponding columns are appropriately 1899 configured, the value of the corresponding instance of the 1900 tlstmParamsRowStatus column is 'notReady'. 1902 In particular, a newly created row cannot be made active until 1903 the corresponding tlstmCertToTSNFingerprint, 1904 tlstmCertToTSNMapType, and tlstmCertToTSNData columns have been 1905 set. 1907 The following objects may not be modified while the 1908 value of this object is active(1): 1909 - tlstmCertToTSNFingerprint 1910 - tlstmCertToTSNMapType 1911 - tlstmCertToTSNData 1912 An attempt to set these objects while the value of 1913 tlstmParamsRowStatus is active(1) will result in 1914 an inconsistentValue error." 1915 ::= { tlstmCertToTSNEntry 6 } 1917 -- Maps tmSecurityNames to certificates for use by the SNMP-TARGET-MIB 1919 tlstmParamsCount OBJECT-TYPE 1920 SYNTAX Unsigned32 1921 MAX-ACCESS read-only 1922 STATUS current 1923 DESCRIPTION 1924 "A count of the number of entries in the tlstmParamsTable" 1925 ::= { tlstmCertificateMapping 4 } 1927 tlstmParamsTableLastChanged OBJECT-TYPE 1928 SYNTAX TimeStamp 1929 MAX-ACCESS read-only 1930 STATUS current 1931 DESCRIPTION 1932 "The value of sysUpTime.0 when the tlstmParamsTable 1933 was last modified through any means, or 0 if it has not been 1934 modified since the command responder was started." 1935 ::= { tlstmCertificateMapping 5 } 1937 tlstmParamsTable OBJECT-TYPE 1938 SYNTAX SEQUENCE OF TlstmParamsEntry 1939 MAX-ACCESS not-accessible 1940 STATUS current 1941 DESCRIPTION 1942 "This table extends the SNMP-TARGET-MIB's 1943 snmpTargetParamsTable with an additional (D)TLS client-side 1944 certificate fingerprint identifier to use when establishing 1945 new (D)TLS connections." 1946 ::= { tlstmCertificateMapping 6 } 1948 tlstmParamsEntry OBJECT-TYPE 1949 SYNTAX TlstmParamsEntry 1950 MAX-ACCESS not-accessible 1951 STATUS current 1952 DESCRIPTION 1953 "A conceptual row containing a fingerprint hash of a locally 1954 held certificate for a given snmpTargetParamsEntry. The 1955 values in this row should be ignored if the connection that 1956 needs to be established, as indicated by the SNMP-TARGET-MIB 1957 infrastructure, is not a certificate and (D)TLS based 1958 connection. The connection SHOULD NOT be established if the 1959 certificate fingerprint stored in this entry does not point to 1960 a valid locally held certificate or if it points to an unusable 1961 certificate (such as might happen when the certificate's 1962 expiration date has been reached)." 1963 INDEX { IMPLIED snmpTargetParamsName } 1964 ::= { tlstmParamsTable 1 } 1966 TlstmParamsEntry ::= SEQUENCE { 1967 tlstmParamsClientFingerprint Fingerprint, 1968 tlstmParamsStorageType StorageType, 1969 tlstmParamsRowStatus RowStatus 1970 } 1972 tlstmParamsClientFingerprint OBJECT-TYPE 1973 SYNTAX Fingerprint 1974 MAX-ACCESS read-create 1975 STATUS current 1976 DESCRIPTION 1977 "A cryptographic hash of a X.509 certificate. This object 1978 should store the hash of a locally held X.509 certificate that 1979 should be used when initiating a (D)TLS connection as a (D)TLS 1980 client." 1981 ::= { tlstmParamsEntry 1 } 1983 tlstmParamsStorageType OBJECT-TYPE 1984 SYNTAX StorageType 1985 MAX-ACCESS read-create 1986 STATUS current 1987 DESCRIPTION 1988 "The storage type for this conceptual row. Conceptual rows 1989 having the value 'permanent' need not allow write-access to 1990 any columnar objects in the row." 1991 DEFVAL { nonVolatile } 1992 ::= { tlstmParamsEntry 2 } 1994 tlstmParamsRowStatus OBJECT-TYPE 1995 SYNTAX RowStatus 1996 MAX-ACCESS read-create 1997 STATUS current 1998 DESCRIPTION 1999 "The status of this conceptual row. This object may be used 2000 to create or remove rows from this table. 2002 To create a row in this table, a manager must set this object 2003 to either createAndGo(4) or createAndWait(5). 2005 Until instances of all corresponding columns are appropriately 2006 configured, the value of the corresponding instance of the 2007 tlstmParamsRowStatus column is 'notReady'. 2009 In particular, a newly created row cannot be made active until 2010 the corresponding tlstmParamsClientFingerprint column has 2011 been set. 2013 The tlstmParamsClientFingerprint object may not be modified 2014 while the value of this object is active(1). 2016 An attempt to set these objects while the value of 2017 tlstmParamsRowStatus is active(1) will result in 2018 an inconsistentValue error. 2020 If this row is deleted it has no effect on the corresponding 2021 row in the targetParamsTable. 2023 If the corresponding row in the targetParamsTable is deleted 2024 then this row must be automatically removed." 2025 ::= { tlstmParamsEntry 3 } 2027 -- Lists expected certificate fingerprints to be presented by a DTLS 2028 -- server 2030 tlstmAddrCount OBJECT-TYPE 2031 SYNTAX Unsigned32 2032 MAX-ACCESS read-only 2033 STATUS current 2034 DESCRIPTION 2035 "A count of the number of entries in the tlstmAddrTable" 2036 ::= { tlstmCertificateMapping 7 } 2038 tlstmAddrTableLastChanged OBJECT-TYPE 2039 SYNTAX TimeStamp 2040 MAX-ACCESS read-only 2041 STATUS current 2042 DESCRIPTION 2043 "The value of sysUpTime.0 when the tlstmAddrTable 2044 was last modified through any means, or 0 if it has not been 2045 modified since the command responder was started." 2046 ::= { tlstmCertificateMapping 8 } 2048 tlstmAddrTable OBJECT-TYPE 2049 SYNTAX SEQUENCE OF TlstmAddrEntry 2050 MAX-ACCESS not-accessible 2051 STATUS current 2052 DESCRIPTION 2053 "This table extends the SNMP-TARGET-MIB's snmpTargetAddrTable 2054 with an expected (D)TLS server-side certificate identifier to 2055 expect when establishing a new (D)TLS connections. If a 2056 matching row in this table exists and the row is active then 2057 the fingerprint identifier from the tlstmAddrServerFingerprint 2058 columnshould be compared against the fingerprint of the 2059 certificate being presented by the server. If the fingerprint 2060 of the certificate presented by the server does not match the 2061 tlstmAddrServerFingerprint column's value then the connection 2062 MUST NOT be established. 2064 If a matching row exists with a zero-length 2065 tlstmAddrServerFingerprint value and the certificate can still 2066 be validated through another certificate validation path 2067 (e.g. RFC5280) then the server's presented identity should be 2068 checked against the value of the tlstmAddrServerIdentity 2069 column. If the server's identity does not match the reference 2070 identity found in the tlstmAddrServerIdentity column then the 2071 connection MUST NOT be established. A tlstmAddrServerIdentity 2072 may contain a '*' to match any server's identity or may 2073 contain a '*.' prefix to match any server identity from a 2074 given domain (e.g. '*.example.com'). 2076 If no matching row exists in this table then the connection 2077 SHOULD still proceed if another certificate validation path 2078 algorithm (e.g. RFC5280) can be followed to a configured trust 2079 anchor." 2080 ::= { tlstmCertificateMapping 9 } 2082 tlstmAddrEntry OBJECT-TYPE 2083 SYNTAX TlstmAddrEntry 2084 MAX-ACCESS not-accessible 2085 STATUS current 2086 DESCRIPTION 2087 "A conceptual row containing a copy of a certificate's 2088 fingerprint for a given snmpTargetAddrEntry. The values in 2089 this row should be ignored if the connection that needs to be 2090 established, as indicated by the SNMP-TARGET-MIB 2091 infrastructure, is not a (D)TLS based connection. If an 2092 tlstmAddrEntry exists for a given snmpTargetAddrEntry then the 2093 presented server certificate MUST match or the connection MUST 2094 NOT be established. If a row in this table does not exist to 2095 match a snmpTargetAddrEntry row then the connection SHOULD 2096 still proceed if some other certificate validation path 2097 algorithm (e.g. RFC5280) can be followed to a configured trust 2098 anchor." 2099 INDEX { IMPLIED snmpTargetAddrName } 2100 ::= { tlstmAddrTable 1 } 2102 TlstmAddrEntry ::= SEQUENCE { 2103 tlstmAddrServerFingerprint Fingerprint, 2104 tlstmAddrServerIdentity SnmpAdminString, 2105 tlstmAddrStorageType StorageType, 2106 tlstmAddrRowStatus RowStatus 2107 } 2109 tlstmAddrServerFingerprint OBJECT-TYPE 2110 SYNTAX Fingerprint 2111 MAX-ACCESS read-create 2112 STATUS current 2113 DESCRIPTION 2114 "A cryptographic hash of a public X.509 certificate. This 2115 object should store the hash of the public X.509 certificate 2116 that the remote server should present during the (D)TLS 2117 connection setup. The fingerprint of the presented 2118 certificate and this hash value MUST match exactly or the 2119 connection MUST NOT be established." 2120 DEFVAL { "" } 2121 ::= { tlstmAddrEntry 1 } 2123 tlstmAddrServerIdentity OBJECT-TYPE 2124 SYNTAX SnmpAdminString 2125 MAX-ACCESS read-create 2126 STATUS current 2127 DESCRIPTION 2128 "The reference identity to check against the identity 2129 presented by the remote system. A single ASCII '*' character 2130 (ASCII code 0x2a) may be used as a wildcard string and will 2131 match any presented server identity. A '*.' prefix may also 2132 be used to match any identity within a given domain 2133 (e.g. '*.example.com' will match both 'foo.example.com' and 2134 'bar.example.com')." 2136 REFERENCE "draft-saintandre-tls-server-id-check" 2137 DEFVAL { "*" } 2138 ::= { tlstmAddrEntry 2 } 2140 tlstmAddrStorageType OBJECT-TYPE 2141 SYNTAX StorageType 2142 MAX-ACCESS read-create 2143 STATUS current 2144 DESCRIPTION 2145 "The storage type for this conceptual row. Conceptual rows 2146 having the value 'permanent' need not allow write-access to 2147 any columnar objects in the row." 2148 DEFVAL { nonVolatile } 2149 ::= { tlstmAddrEntry 3 } 2151 tlstmAddrRowStatus OBJECT-TYPE 2152 SYNTAX RowStatus 2153 MAX-ACCESS read-create 2154 STATUS current 2155 DESCRIPTION 2156 "The status of this conceptual row. This object may be used 2157 to create or remove rows from this table. 2159 To create a row in this table, a manager must 2160 set this object to either createAndGo(4) or 2161 createAndWait(5). 2163 Until instances of all corresponding columns are 2164 appropriately configured, the value of the 2165 corresponding instance of the tlstmAddrRowStatus 2166 column is 'notReady'. 2168 In particular, a newly created row cannot be made active until 2169 the corresponding tlstmAddrServerFingerprint column has been 2170 set. 2172 The tlstmAddrServerFingerprint object may not be modified 2173 while the value of this object is active(1). 2175 An attempt to set these objects while the value of 2176 tlstmAddrRowStatus is active(1) will result in 2177 an inconsistentValue error. 2179 If this row is deleted it has no effect on the corresponding 2180 row in the targetAddrTable. 2182 If the corresponding row in the targetAddrTable is deleted 2183 then this row must be automatically removed." 2184 ::= { tlstmAddrEntry 4 } 2186 -- ************************************************ 2187 -- tlstmNotifications - Notifications Information 2188 -- ************************************************ 2190 tlstmServerCertificateUnknown NOTIFICATION-TYPE 2191 OBJECTS { snmpTlstmSessionUnknownServerCertificate } 2192 STATUS current 2193 DESCRIPTION 2194 "Notification that the server certificate presented by a SNMP 2195 over (D)TLS server was invalid because no configured 2196 fingerprint or CA was acceptable to validate it. This may 2197 result because there was no entry in the tlstmAddrTable or 2198 because no path could be found to known certificate 2199 authority. 2201 To avoid notification loops, this notification MUST NOT be 2202 sent to servers that themselves have triggered the 2203 notification." 2204 ::= { tlstmNotifications 1 } 2206 tlstmServerInvalidCertificate NOTIFICATION-TYPE 2207 OBJECTS { tlstmAddrServerFingerprint, 2208 snmpTlstmSessionInvalidServerCertificates} 2209 STATUS current 2210 DESCRIPTION 2211 "Notification that the server certificate presented by an SNMP 2212 over (D)TLS server could not be validated even if the 2213 fingerprint or expected validation path was known. I.E., a 2214 cryptographic validation occurred during certificate 2215 validation processing. 2217 To avoid notification loops, this notification MUST NOT be 2218 sent to servers that themselves have triggered the 2219 notification." 2220 ::= { tlstmNotifications 2 } 2222 -- ************************************************ 2223 -- tlstmCompliances - Conformance Information 2224 -- ************************************************ 2226 tlstmCompliances OBJECT IDENTIFIER ::= { tlstmConformance 1 } 2228 tlstmGroups OBJECT IDENTIFIER ::= { tlstmConformance 2 } 2229 -- ************************************************ 2230 -- Compliance statements 2231 -- ************************************************ 2233 tlstmCompliance MODULE-COMPLIANCE 2234 STATUS current 2235 DESCRIPTION 2236 "The compliance statement for SNMP engines that support the 2237 TLSTM-MIB" 2238 MODULE 2239 MANDATORY-GROUPS { tlstmStatsGroup, 2240 tlstmIncomingGroup, 2241 tlstmOutgoingGroup, 2242 tlstmNotificationGroup } 2243 ::= { tlstmCompliances 1 } 2245 -- ************************************************ 2246 -- Units of conformance 2247 -- ************************************************ 2248 tlstmStatsGroup OBJECT-GROUP 2249 OBJECTS { 2250 snmpTlstmSessionOpens, 2251 snmpTlstmSessionCloses, 2252 snmpTlstmSessionOpenErrors, 2253 snmpTlstmSessionNoSessions, 2254 snmpTlstmSessionInvalidClientCertificates, 2255 snmpTlstmSessionUnknownServerCertificate, 2256 snmpTlstmSessionInvalidServerCertificates, 2257 snmpTlstmSessionInvalidCaches, 2258 tlstmTLSProtectionErrors 2259 } 2260 STATUS current 2261 DESCRIPTION 2262 "A collection of objects for maintaining 2263 statistical information of an SNMP engine which 2264 implements the SNMP TLS Transport Model." 2265 ::= { tlstmGroups 1 } 2267 tlstmIncomingGroup OBJECT-GROUP 2268 OBJECTS { 2269 tlstmCertToTSNCount, 2270 tlstmCertToTSNTableLastChanged, 2271 tlstmCertToTSNFingerprint, 2272 tlstmCertToTSNMapType, 2273 tlstmCertToTSNData, 2274 tlstmCertToTSNStorageType, 2275 tlstmCertToTSNRowStatus 2276 } 2277 STATUS current 2278 DESCRIPTION 2279 "A collection of objects for maintaining 2280 incoming connection certificate mappings to 2281 tmSecurityNames of an SNMP engine which implements the 2282 SNMP TLS Transport Model." 2283 ::= { tlstmGroups 2 } 2285 tlstmOutgoingGroup OBJECT-GROUP 2286 OBJECTS { 2287 tlstmParamsCount, 2288 tlstmParamsTableLastChanged, 2289 tlstmParamsClientFingerprint, 2290 tlstmParamsStorageType, 2291 tlstmParamsRowStatus, 2292 tlstmAddrCount, 2293 tlstmAddrTableLastChanged, 2294 tlstmAddrServerFingerprint, 2295 tlstmAddrServerIdentity, 2296 tlstmAddrStorageType, 2297 tlstmAddrRowStatus 2298 } 2299 STATUS current 2300 DESCRIPTION 2301 "A collection of objects for maintaining 2302 outgoing connection certificates to use when opening 2303 connections as a result of SNMP-TARGET-MIB settings." 2304 ::= { tlstmGroups 3 } 2306 tlstmNotificationGroup NOTIFICATION-GROUP 2307 NOTIFICATIONS { 2308 tlstmServerCertificateUnknown, 2309 tlstmServerInvalidCertificate 2310 } 2311 STATUS current 2312 DESCRIPTION 2313 "Notifications" 2314 ::= { tlstmGroups 4 } 2316 END 2318 8. Operational Considerations 2320 This section discusses various operational aspects of deploying 2321 TLSTM. 2323 8.1. Sessions 2325 A session is discussed throughout this document as meaning a security 2326 association between the (D)TLS client and the (D)TLS server. State 2327 information for the sessions are maintained in each TLSTM 2328 implementation and this information is created and destroyed as 2329 sessions are opened and closed. A "broken" session (one side up and 2330 one side down) can result if one side of a session is brought down 2331 abruptly (i.e., reboot, power outage, etc.). Whenever possible, 2332 implementations SHOULD provide graceful session termination through 2333 the use of disconnect messages. Implementations SHOULD also have a 2334 system in place for detecting "broken" sessions through the use of 2335 heartbeats [I-D.seggelmann-tls-dtls-heartbeat] or other detection 2336 mechanisms. 2338 Implementations SHOULD limit the lifetime of established sessions 2339 depending on the algorithms used for generation of the master session 2340 secret, the privacy and integrity algorithms used to protect 2341 messages, the environment of the session, the amount of data 2342 transferred, and the sensitivity of the data. 2344 8.2. Notification Receiver Credential Selection 2346 When an SNMP engine needs to establish an outgoing session for 2347 notifications, the snmpTargetParamsTable includes an entry for the 2348 snmpTargetParamsSecurityName of the target. However, the receiving 2349 SNMP engine (Server) does not know which (D)TLS certificate to offer 2350 to the Client so that the tmSecurityName identity-authentication will 2351 be successful. 2353 One solution is to maintain a one-to-one mapping between certificates 2354 and incoming ports for notification receivers. This can be handled 2355 at the notification originator by configuring the snmpTargetAddrTable 2356 (snmpTargetAddrTDomain and snmpTargetAddrTAddress) and requiring the 2357 receiving SNMP engine to monitor multiple incoming static ports based 2358 on which principals are capable of receiving notifications. 2360 Implementations MAY also choose to designate a single Notification 2361 Receiver Principal to receive all incoming notifications or select an 2362 implementation specific method of selecting a server certificate to 2363 present to clients. 2365 8.3. contextEngineID Discovery 2367 Most command responders have contextEngineIDs that are identical to 2368 the USM securityEngineID. USM provides a discovery service that 2369 allows command generators to determine a securityEngineID and thus a 2370 default contextEngineID to use. Because the TLS Transport Model does 2371 not make use of a securityEngineID, it may be difficult for command 2372 generators to discover a suitable default contextEngineID. 2373 Implementations should consider offering another engineID discovery 2374 mechanism to continue providing Command Generators with a suitable 2375 contextEngineID mechanism. A recommended discovery solution is 2376 documented in [RFC5343]. 2378 8.4. Transport Considerations 2380 This document defines how SNMP messages can be transmitted over the 2381 TLS and DTLS based protocols. Each of these protocols are 2382 additionally based on other transports (TCP, UDP and SCTP). These 2383 three protocols also have operational considerations that must be 2384 taken into consideration when selecting a (D)TLS based protocol to 2385 use such as its performance in degraded or limited networks. It is 2386 beyond the scope of this document to summarize the characteristics of 2387 these transport mechanisms. Please refer to the base protocol 2388 documents for details on messaging considerations with respect to MTU 2389 size, fragmentation, performance in lossy-networks, etc. 2391 9. Security Considerations 2393 This document describes a transport model that permits SNMP to 2394 utilize (D)TLS security services. The security threats and how the 2395 (D)TLS transport model mitigates these threats are covered in detail 2396 throughout this document. Security considerations for DTLS are 2397 covered in [RFC4347] and security considerations for TLS are 2398 described in Section 11 and Appendices D, E, and F of TLS 1.2 2399 [RFC5246]. DTLS adds to the security considerations of TLS only 2400 because it is more vulnerable to denial of service attacks. A random 2401 cookie exchange was added to the handshake to prevent anonymous 2402 denial of service attacks. RFC 4347 recommends that the cookie 2403 exchange is utilized for all handshakes and therefore this 2404 specification also RECOMMENDEDs that implementers also support this 2405 cookie exchange. 2407 9.1. Certificates, Authentication, and Authorization 2409 Implementations are responsible for providing a security certificate 2410 installation and configuration mechanism. Implementations SHOULD 2411 support certificate revocation lists. 2413 (D)TLS provides for authentication of the identity of both the (D)TLS 2414 server and the (D)TLS client. Access to MIB objects for the 2415 authenticated principal MUST be enforced by an access control 2416 subsystem (e.g. the VACM). 2418 Authentication of the command generator principal's identity is 2419 important for use with the SNMP access control subsystem to ensure 2420 that only authorized principals have access to potentially sensitive 2421 data. The authenticated identity of the command generator 2422 principal's certificate is mapped to an SNMP model-independent 2423 securityName for use with SNMP access control. 2425 The (D)TLS handshake only provides assurance that the certificate of 2426 the authenticated identity has been signed by an configured accepted 2427 Certificate Authority. (D)TLS has no way to further authorize or 2428 reject access based on the authenticated identity. An Access Control 2429 Model (such as the VACM) provides access control and authorization of 2430 a command generator's requests to a command responder and a 2431 notification responder's authorization to receive Notifications from 2432 a notification originator. However to avoid man-in-the-middle 2433 attacks both ends of the (D)TLS based connection MUST check the 2434 certificate presented by the other side against what was expected. 2435 For example, command generators must check that the command responder 2436 presented and authenticated itself with a X.509 certificate that was 2437 expected. Not doing so would allow an impostor, at a minimum, to 2438 present false data, receive sensitive information and/or provide a 2439 false belief that configuration was actually received and acted upon. 2440 Authenticating and verifying the identity of the (D)TLS server and 2441 the (D)TLS client for all operations ensures the authenticity of the 2442 SNMP engine that provides MIB data. 2444 The instructions found in the DESCRIPTION clause of the 2445 tlstmCertToTSNTable object must be followed exactly. It is also 2446 important that the rows of the table be searched in prioritized order 2447 starting with the row containing the lowest numbered tlstmCertToTSNID 2448 value. 2450 9.2. Use with SNMPv1/SNMPv2c Messages 2452 The SNMPv1 and SNMPv2c message processing described in [RFC3584] (BCP 2453 74) always selects the SNMPv1 or SNMPv2c Security Models, 2454 respectively. Both of these and the User-based Security Model 2455 typically used with SNMPv3 derive the securityName and securityLevel 2456 from the SNMP message received, even when the message was received 2457 over a secure transport. Access control decisions are therefore made 2458 based on the contents of the SNMP message, rather than using the 2459 authenticated identity and securityLevel provided by the TLS 2460 Transport Model. 2462 9.3. MIB Module Security 2464 There are a number of management objects defined in this MIB module 2465 with a MAX-ACCESS clause of read-write and/or read-create. Such 2466 objects may be considered sensitive or vulnerable in some network 2467 environments. The support for SET operations in a non-secure 2468 environment without proper protection can have a negative effect on 2469 network operations. These are the tables and objects and their 2470 sensitivity/vulnerability: 2472 o The tlstmParamsTable can be used to change the outgoing X.509 2473 certificate used to establish a (D)TLS connection. Modification 2474 to objects in this table need to be adequately authenticated since 2475 modification to values in this table will have profound impacts to 2476 the security of outbound connections from the device. Since 2477 knowledge of authorization rules and certificate usage mechanisms 2478 may be considered sensitive, protection from disclosure of the 2479 SNMP traffic via encryption is also highly recommended. 2481 o The tlstmAddrTable can be used to change the expectations of the 2482 certificates presented by a remote (D)TLS server. Modification to 2483 objects in this table need to be adequately authenticated since 2484 modification to values in this table will have profound impacts to 2485 the security of outbound connections from the device. Since 2486 knowledge of authorization rules and certificate usage mechanisms 2487 may be considered sensitive, protection from disclosure of the 2488 SNMP traffic via encryption is also highly recommended. 2490 o The tlstmCertToTSNTable is used to specify the mapping of incoming 2491 X.509 certificates to tmSecurityNames which eventually get mapped 2492 to a SNMPv3 securityName. Modification to objects in this table 2493 need to be adequately authenticated since modification to values 2494 in this table will have profound impacts to the security of 2495 incoming connections to the device. Since knowledge of 2496 authorization rules and certificate usage mechanisms may be 2497 considered sensitive, protection from disclosure of the SNMP 2498 traffic via encryption is also highly recommended. 2500 Some of the readable objects in this MIB module (i.e., objects with a 2501 MAX-ACCESS other than not-accessible) may be considered sensitive or 2502 vulnerable in some network environments. It is thus important to 2503 control even GET and/or NOTIFY access to these objects and possibly 2504 to even encrypt the values of these objects when sending them over 2505 the network via SNMP. These are the tables and objects and their 2506 sensitivity/vulnerability: 2508 o This MIB contains a collection of counters that monitor the (D)TLS 2509 connections being established with a device. Since knowledge of 2510 connection and certificate usage mechanisms may be considered 2511 sensitive, protection from disclosure of the SNMP traffic via 2512 encryption is also highly recommended. 2514 SNMP versions prior to SNMPv3 did not include adequate security. 2515 Even if the network itself is secure (for example by using IPsec), 2516 even then, there is no control as to who on the secure network is 2517 allowed to access and GET/SET (read/change/create/delete) the objects 2518 in this MIB module. 2520 It is RECOMMENDED that implementers consider the security features as 2521 provided by the SNMPv3 framework (see [RFC3410], section 8), 2522 including full support for the SNMPv3 cryptographic mechanisms (for 2523 authentication and privacy). 2525 Further, deployment of SNMP versions prior to SNMPv3 is NOT 2526 RECOMMENDED. Instead, it is RECOMMENDED to deploy SNMPv3 and to 2527 enable cryptographic security. It is then a customer/operator 2528 responsibility to ensure that the SNMP entity giving access to an 2529 instance of this MIB module is properly configured to give access to 2530 the objects only to those principals (users) that have legitimate 2531 rights to indeed GET or SET (change/create/delete) them. 2533 10. IANA Considerations 2535 IANA is requested to assign: 2537 1. a TCP port number above 1023 in the 2538 http://www.iana.org/assignments/port-numbers registry which will 2539 be the default port for receipt of SNMP command messages over a 2540 TLS Transport Model as defined in this document, 2542 2. a TCP port number above 1023 in the 2543 http://www.iana.org/assignments/port-numbers registry which will 2544 be the default port for receipt of SNMP notification messages 2545 over a TLS Transport Model as defined in this document, 2547 3. a UDP port number above 1023 in the 2548 http://www.iana.org/assignments/port-numbers registry which will 2549 be the default port for receipt of SNMP command messages over a 2550 DTLS/UDP connection as defined in this document, 2552 4. a UDP port number above 1023 in the 2553 http://www.iana.org/assignments/port-numbers registry which will 2554 be the default port for receipt of SNMP notification messages 2555 over a DTLS/UDP connection as defined in this document, 2557 5. a SCTP port number above 1023 in the 2558 http://www.iana.org/assignments/port-numbers registry which will 2559 be the default port for receipt of SNMP command messages over a 2560 DTLS/SCTP connection as defined in this document, 2562 6. a SCTP port number above 1023 in the 2563 http://www.iana.org/assignments/port-numbers registry which will 2564 be the default port for receipt of SNMP notification messages 2565 over a DTLS/SCTP connection as defined in this document, 2567 7. an SMI number under snmpDomains for the snmpTLSTCPDomain object 2568 identifier, 2570 8. an SMI number under snmpDomains for the snmpDTLSUDPDomain object 2571 identifier, 2573 9. an SMI number under snmpDomains for the snmpDTLSSCTPDomain 2574 object identifier, 2576 10. a SMI number under snmpModules, for the MIB module in this 2577 document, 2579 11. "tls" as the corresponding prefix for the snmpTLSTCPDomain in 2580 the SNMP Transport Model registry, 2582 12. "dudp" as the corresponding prefix for the snmpDTLSUDPDomain in 2583 the SNMP Transport Model registry, 2585 13. "dsct" as the corresponding prefix for the snmpDTLSSCTPDomain in 2586 the SNMP Transport Model registry; 2588 If possible, IANA is requested to use matching port numbers for all 2589 assignments for SNMP Commands being sent over TLS, DTLS/UDP, DTLS/ 2590 SCTP. 2592 If possible, IANA is requested to use matching port numbers for all 2593 assignments for SNMP Notifications being sent over TLS, DTLS/UDP, 2594 DTLS/SCTP. 2596 Editor's note: this section should be replaced with appropriate 2597 descriptive assignment text after IANA assignments are made and prior 2598 to publication. 2600 11. Acknowledgements 2602 This document closely follows and copies the Secure Shell Transport 2603 Model for SNMP defined by David Harrington and Joseph Salowey in 2604 [RFC5292]. 2606 This document was reviewed by the following people who helped provide 2607 useful comments (in alphabetical order): Andy Donati, Pasi Eronen, 2608 David Harrington, Jeffrey Hutzelman, Alan Luchuk, Randy Presuhn, Ray 2609 Purvis, Joseph Salowey, Jurgen Schonwalder, Dave Shield. 2611 This work was supported in part by the United States Department of 2612 Defense. Large portions of this document are based on work by 2613 General Dynamics C4 Systems and the following individuals: Brian 2614 Baril, Kim Bryant, Dana Deluca, Dan Hanson, Tim Huemiller, John 2615 Holzhauer, Colin Hoogeboom, Dave Kornbau, Chris Knaian, Dan Knaul, 2616 Charles Limoges, Steve Moccaldi, Gerardo Orlando, and Brandon Yip. 2618 12. References 2620 12.1. Normative References 2622 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2623 Requirement Levels", BCP 14, RFC 2119, March 1997. 2625 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2626 Schoenwaelder, Ed., "Structure of Management Information 2627 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 2629 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2630 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 2631 STD 58, RFC 2579, April 1999. 2633 [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 2634 "Conformance Statements for SMIv2", STD 58, RFC 2580, 2635 April 1999. 2637 [RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An 2638 Architecture for Describing Simple Network Management 2639 Protocol (SNMP) Management Frameworks", STD 62, RFC 3411, 2640 December 2002. 2642 [RFC3413] Levi, D., Meyer, P., and B. Stewart, "Simple Network 2643 Management Protocol (SNMP) Applications", STD 62, 2644 RFC 3413, December 2002. 2646 [RFC3414] Blumenthal, U. and B. Wijnen, "User-based Security Model 2647 (USM) for version 3 of the Simple Network Management 2648 Protocol (SNMPv3)", STD 62, RFC 3414, December 2002. 2650 [RFC3415] Wijnen, B., Presuhn, R., and K. McCloghrie, "View-based 2651 Access Control Model (VACM) for the Simple Network 2652 Management Protocol (SNMP)", STD 62, RFC 3415, 2653 December 2002. 2655 [RFC3418] Presuhn, R., "Management Information Base (MIB) for the 2656 Simple Network Management Protocol (SNMP)", STD 62, 2657 RFC 3418, December 2002. 2659 [RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen, 2660 "Coexistence between Version 1, Version 2, and Version 3 2661 of the Internet-standard Network Management Framework", 2662 BCP 74, RFC 3584, August 2003. 2664 [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2665 Security", RFC 4347, April 2006. 2667 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2668 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2670 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2671 Housley, R., and W. Polk, "Internet X.509 Public Key 2672 Infrastructure Certificate and Certificate Revocation List 2673 (CRL) Profile", RFC 5280, May 2008. 2675 [RFC5590] Harrington, D. and J. Schoenwaelder, "Transport Subsystem 2676 for the Simple Network Management Protocol (SNMP)", 2677 RFC 5590, June 2009. 2679 [RFC5591] Harrington, D. and W. Hardaker, "Transport Security Model 2680 for the Simple Network Management Protocol (SNMP)", 2681 RFC 5591, June 2009. 2683 12.2. Informative References 2685 [RFC2522] Karn, P. and W. Simpson, "Photuris: Session-Key Management 2686 Protocol", RFC 2522, March 1999. 2688 [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, 2689 "Introduction and Applicability Statements for Internet- 2690 Standard Management Framework", RFC 3410, December 2002. 2692 [RFC4306] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", 2693 RFC 4306, December 2005. 2695 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 2696 and T. Wright, "Transport Layer Security (TLS) 2697 Extensions", RFC 4366, April 2006. 2699 [RFC5292] Chen, E. and S. Sangli, "Address-Prefix-Based Outbound 2700 Route Filter for BGP-4", RFC 5292, August 2008. 2702 [RFC5343] Schoenwaelder, J., "Simple Network Management Protocol 2703 (SNMP) Context EngineID Discovery", RFC 5343, 2704 September 2008. 2706 [I-D.saintandre-tls-server-id-check] 2707 Saint-Andre, P., Zeilenga, K., Hodges, J., and B. Morgan, 2708 "Best Practices for Checking of Server Identities in the 2709 Context of Transport Layer Security (TLS)". 2711 [I-D.seggelmann-tls-dtls-heartbeat] 2712 Seggelmann, R., Tuexen, M., and M. Williams, "Transport 2713 Layer Security and Datagram Transport Layer Security 2714 Heartbeat Extension". 2716 [AES] National Institute of Standards, "Specification for the 2717 Advanced Encryption Standard (AES)". 2719 [DES] National Institute of Standards, "American National 2720 Standard for Information Systems-Data Link Encryption". 2722 [DSS] National Institute of Standards, "Digital Signature 2723 Standard". 2725 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 2726 Obtaining Digital Signatures and Public-Key 2727 Cryptosystems". 2729 [X509] , ITU., "INFORMATION TECHNOLOGY OPEN SYSTEMS 2730 INTERCONNECTION THE DIRECTORY: PUBLIC-KEY AND ATTRIBUTE 2731 CERTIFICATE FRAMEWORKS". 2733 Appendix A. (D)TLS Overview 2735 The (D)TLS protocol is composed of two layers: the (D)TLS Record 2736 Protocol and the (D)TLS Handshake Protocol. The following 2737 subsections provide an overview of these two layers. Please refer to 2738 [RFC4347] for a complete description of the protocol. 2740 A.1. The (D)TLS Record Protocol 2742 At the lowest layer, layered on top of the transport control protocol 2743 or a datagram transport protocol (e.g. UDP or SCTP) is the (D)TLS 2744 Record Protocol. 2746 The (D)TLS Record Protocol provides security that has three basic 2747 properties: 2749 o The session can be confidential. Symmetric cryptography is used 2750 for data encryption (e.g., [AES], [DES] etc.). The keys for this 2751 symmetric encryption are generated uniquely for each session and 2752 are based on a secret negotiated by another protocol (such as the 2753 (D)TLS Handshake Protocol). The Record Protocol can also be used 2754 without encryption. 2756 o Messages can have data integrity. Message transport includes a 2757 message integrity check using a keyed MAC. Secure hash functions 2758 (e.g., SHA, MD5, etc.) are used for MAC computations. The Record 2759 Protocol can operate without a MAC, but is generally only used in 2760 this mode while another protocol is using the Record Protocol as a 2761 transport for negotiating security parameters. 2763 o Messages are protected against replay. (D)TLS uses explicit 2764 sequence numbers and integrity checks. DTLS uses a sliding window 2765 to protect against replay of messages within a session. 2767 (D)TLS also provides protection against replay of entire sessions. 2768 In a properly-implemented keying material exchange, both sides will 2769 generate new random numbers for each exchange. This results in 2770 different encryption and integrity keys for every session. 2772 A.2. The (D)TLS Handshake Protocol 2774 The (D)TLS Record Protocol is used for encapsulation of various 2775 higher-level protocols. One such encapsulated protocol, the (D)TLS 2776 Handshake Protocol, allows the server and client to authenticate each 2777 other and to negotiate an integrity algorithm, an encryption 2778 algorithm and cryptographic keys before the application protocol 2779 transmits or receives its first octet of data. Only the (D)TLS 2780 client can initiate the handshake protocol. The (D)TLS Handshake 2781 Protocol provides security that has four basic properties: 2783 o The peer's identity can be authenticated using asymmetric (public 2784 key) cryptography (e.g., RSA [RSA], DSS [DSS], etc.). This 2785 authentication can be made optional, but is generally required by 2786 at least one of the peers. 2788 (D)TLS supports three authentication modes: authentication of both 2789 the server and the client, server authentication with an 2790 unauthenticated client, and total anonymity. For authentication 2791 of both entities, each entity provides a valid certificate chain 2792 leading to an acceptable certificate authority. Each entity is 2793 responsible for verifying that the other's certificate is valid 2794 and has not expired or been revoked. See 2795 [I-D.saintandre-tls-server-id-check] for further details on 2796 standardized processing when checking server certificate 2797 identities. 2799 o The negotiation of a shared secret is secure: the negotiated 2800 secret is unavailable to eavesdroppers, and for any authenticated 2801 handshake the secret cannot be obtained, even by an attacker who 2802 can place himself in the middle of the session. 2804 o The negotiation is not vulnerable to malicious modification: it is 2805 infeasible for an attacker to modify negotiation communication 2806 without being detected by the parties to the communication. 2808 o DTLS uses a stateless cookie exchange to protect against anonymous 2809 denial of service attacks and has retransmission timers, sequence 2810 numbers, and counters to handle message loss, reordering, and 2811 fragmentation. 2813 Appendix B. PKIX Certificate Infrastructure 2815 Users of a public key from a PKIX / X.509 certificate can be be 2816 confident that the associated private key is owned by the correct 2817 remote subject (person or system) with which an encryption or digital 2818 signature mechanism will be used. This confidence is obtained 2819 through the use of public key certificates, which are data structures 2820 that bind public key values to subjects. The binding is asserted by 2821 having a trusted CA digitally sign each certificate. The CA may base 2822 this assertion upon technical means (i.e., proof of possession 2823 through a challenge-response protocol), presentation of the private 2824 key, or on an assertion by the subject. A certificate has a limited 2825 valid lifetime which is indicated in its signed contents. Because a 2826 certificate's signature and timeliness can be independently checked 2827 by a certificate-using client, certificates can be distributed via 2828 untrusted communications and server systems, and can be cached in 2829 unsecured storage in certificate-using systems. 2831 ITU-T X.509 (formerly CCITT X.509) or ISO/IEC/ITU 9594-8 [X509], 2832 which was first published in 1988 as part of the X.500 Directory 2833 recommendations, defines a standard certificate format which is a 2834 certificate which binds a subject (principal) to a public key value. 2835 This was later further expanded and documented in [RFC5280]. 2837 A X.509 certificate is a sequence of three required fields: 2839 tbsCertificate: The tbsCertificate field contains the names of the 2840 subject and issuer, a public key associated with the subject, a 2841 validity period, and other associated information. This field may 2842 also contain extension components. 2844 signatureAlgorithm: The signatureAlgorithm field contains the 2845 identifier for the cryptographic algorithm used by the certificate 2846 authority (CA) to sign this certificate. 2848 signatureValue: The signatureValue field contains a digital 2849 signature computed by the CA upon the ASN.1 DER encoded 2850 tbsCertificate field. The ASN.1 DER encoded tbsCertificate is 2851 used as the input to the signature function. This signature value 2852 is then ASN.1 DER encoded as a BIT STRING and included in the 2853 Certificate's signature field. By generating this signature, the 2854 CA certifies the validity of the information in the tbsCertificate 2855 field. In particular, the CA certifies the binding between the 2856 public key material and the subject of the certificate. 2858 The basic X.509 authentication procedure is as follows: A system is 2859 initialized with a number of root certificates that contain the 2860 public keys of a number of trusted CAs. When a system receives a 2861 X.509 certificate, signed by one of those CAs, the certificate has to 2862 be verified. It first checks the signatureValue field by using the 2863 public key of the corresponding trusted CA. Then it compares the 2864 digest of the received certificate with a digest of the 2865 tbsCertificate field. If they match, then the subject in the 2866 tbsCertificate field is authenticated. 2868 Appendix C. Target and Notificaton Configuration Example 2870 Configuring the SNMP-TARGET-MIB and NOTIFICATION-MIB along with 2871 access control settings for the SNMP-VIEW-BASED-ACM-MIB can be a 2872 daunting task without an example to follow. The following section 2873 describes an example of what pieces must be in place to accomplish 2874 this configuration. 2876 The isAccessAllowed() ASI requires configuration to exist in the 2877 following SNMP-VIEW-BASED-ACM-MIB tables: 2879 vacmSecurityToGroupTable 2880 vacmAccessTable 2881 vacmViewTreeFamilyTable 2883 The only table that needs to be discussed as particularly different 2884 here is the vacmSecurityToGroupTable. This table is indexed by both 2885 the SNMPv3 security model and the security name. The security model, 2886 when TLSTM is in use, should be set to the value of 4, corresponding 2887 to the TSM [RFC5591]. An example vacmSecurityToGroupTable row might 2888 be filled out as follows (using a single SNMP SET request): 2890 vacmSecurityModel = 4 (TSM) 2891 vacmSecurityName = "blueberry" 2892 vacmGroupName = "administrators" 2893 vacmSecurityToGroupStorageType = 3 (nonVolatile) 2894 vacmSecurityToGroupStatus = 4 (createAndGo) 2896 This example will assume that the "administrators" group has been 2897 given proper permissions via rows in the vacmAccessTable and 2898 vacmViewTreeFamilyTable. 2900 Depending on whether this VACM configuration is for a Command 2901 Responder or a command generator the security name "blueberry" will 2902 come from a few different locations. 2904 C.1. Configuring the Notification Generator 2906 For notification generators performing authorization checks, the 2907 server's certificate must be verified against the expected 2908 certificate before proceeding to send the notification. The expected 2909 certificate from the server may be listed in the tlstmAddrTable or 2910 may be determined through other X.509 path validation mechanisms. 2911 The securityName to use for VACM authorization checks is set by the 2912 SNMP-TARGET-MIB's snmpTargetParamsSecurityName column. 2914 The certificate that the notification generator should present to the 2915 server is taken from the tlstmParamsClientFingerprint column from the 2916 appropriate entry in the tlstmParamsTable table. 2918 C.2. Configuring the Command Responder 2920 For command responder applications, the vacmSecurityName "blueberry" 2921 value is a value that derived from an incoming (D)TLS session. The 2922 mapping from a recevied (D)TLS client certificate to a tmSecurityName 2923 is done with the tlstmCertToTSNTable. The certificates must be 2924 loaded into the device so that a tlstmCertToTSNEntry may refer to it. 2925 As an example, consider the following entry which will provide a 2926 mapping from a client's public X.509's hash fingerprint directly to 2927 the "blueberry" tmSecurityName: 2929 tlstmCertToTSNID = 1 (chosen by ordering preference) 2930 tlstmCertToTSNFingerprint = HASH (appropriate fingerprint) 2931 tlstmCertToTSNMapType = 1 (specified) 2932 tlstmCertToTSNSecurityName = "blueberry" 2933 tlstmCertToTSNStorageType = 3 (nonVolatile) 2934 tlstmCertToTSNRowStatus = 4 (createAndGo) 2936 The above is an example of how to map a particular certificate to a 2937 particular tmSecurityName. It is recommended, however, that users 2938 make use of direct subjectAltName or CommonName mappings where 2939 possible as it provides a more scalable approach to certificate 2940 management. This entry provides an example of using a subjectAltName 2941 mapping: 2943 tlstmCertToTSNID = 1 (chosen by ordering preference) 2944 tlstmCertToTSNFingerprint = HASH (appropriate fingerprint) 2945 tlstmCertToTSNMapType = 2 (bySubjectAltName) 2946 tlstmCertToTSNSANType = 1 (any) 2947 tlstmCertToTSNStorageType = 3 (nonVolatile) 2948 tlstmCertToTSNRowStatus = 4 (createAndGo) 2950 The above entry indicates the subjectAltName field for certificates 2951 created by an issuing certificate with a corresponding fingerprint 2952 will be trusted to always produce common names that are directly one- 2953 to-one mappable into tmSecurityNames. This type of configuration 2954 should only be used when the certificate authorities naming 2955 conventions are carefully controlled. 2957 In the example, if the incoming (D)TLS client provided certificate 2958 contained a subjectAltName where the first listed subjectAltName in 2959 the extension is the rfc822Name of "blueberry@example.com", the 2960 certificate was signed by a certificate matching the 2961 tlstmCertToTSNFingerprint value and the CA's certificate was properly 2962 installed on the device then the string "blueberry@example.com" would 2963 be used as the tmSecurityName for the session. 2965 Author's Address 2967 Wes Hardaker 2968 Sparta, Inc. 2969 P.O. Box 382 2970 Davis, CA 95617 2971 USA 2973 Phone: +1 530 792 1913 2974 Email: ietf@hardakers.net