idnits 2.17.1 draft-ietf-isms-dtls-tm-05.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 379 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 (January 8, 2010) is 5194 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 January 8, 2010 5 Expires: July 12, 2010 7 Transport Layer Security (TLS) Transport Model for SNMP 8 draft-ietf-isms-dtls-tm-05.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 July 12, 2010. 56 Copyright Notice 58 Copyright (c) 2010 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 . . . . . . . . . . . . . . . . . . . . . 28 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 . . . . . . . . . . . . . . . . . . . . 29 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 . . . . . . . . . . . . . . . . 52 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 . . . . . . . . . . . . . . . . . . . 54 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. An SNMP entity may act 297 as a (D)TLS client or server or both, depending on the SNMP 298 applications supported. 300 The User-Based Security Model (USM) [RFC3414] is a mandatory-to- 301 implement Security Model in STD 62. While (D)TLS and USM frequently 302 refer to a user, the terminology preferred in RFC3411 and in this 303 memo is "principal". A principal is the "who" on whose behalf 304 services are provided or processing takes place. A principal can be, 305 among other things, an individual acting in a particular role; a set 306 of individuals, with each acting in a particular role; an application 307 or a set of applications, or a combination of these within an 308 administrative domain. 310 Throughout this document, the term "session" is used to refer to a 311 secure association between two TLS Transport Models that permits the 312 transmission of one or more SNMP messages within the lifetime of the 313 session. The (D)TLS protocols also have an internal notion of a 314 session and although these two concepts of a session are related, 315 this document (unless otherwise specified) is referring to TLSTM's 316 specific session and not directly to the (D)TLS protocol's session. 318 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 319 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 320 document are to be interpreted as described in [RFC2119]. 322 2. The Transport Layer Security Protocol 324 (D)TLS provides authentication, data message integrity, and privacy 325 at the transport layer. (See [RFC4347]) 327 The primary goals of the TLS Transport Model are to provide privacy, 328 peer identity authentication and data integrity between two 329 communicating SNMP entities. The TLS and DTLS protocols provide a 330 secure transport upon which the TLSTM is based. An overview of 331 (D)TLS can be found in section Appendix A. Please refer to [RFC5246] 332 and [RFC4347] for complete descriptions of the protocols. 334 3. How the TLSTM fits into the Transport Subsystem 336 A transport model is a component of the Transport Subsystem. The TLS 337 Transport Model thus fits between the underlying (D)TLS transport 338 layer and the Message Dispatcher [RFC3411] component of the SNMP 339 engine and the Transport Subsystem. 341 The TLS Transport Model will establish a session between itself and 342 the TLS Transport Model of another SNMP engine. The sending 343 transport model passes unencrypted and unauthenticated messages from 344 the Dispatcher to (D)TLS to be encrypted and authenticated, and the 345 receiving transport model accepts decrypted and authenticated/ 346 integrity-checked incoming messages from (D)TLS and passes them to 347 the Dispatcher. 349 After a TLS Transport Model session is established, SNMP messages can 350 conceptually be sent through the session from one SNMP message 351 Dispatcher to another SNMP Message Dispatcher. If multiple SNMP 352 messages are needed to be passed between two SNMP applications they 353 MAY be passed through the same session. A TLSTM implementation 354 engine MAY choose to close a (D)TLS session to conserve resources. 356 The TLS Transport Model of an SNMP engine will perform the 357 translation between (D)TLS-specific security parameters and SNMP- 358 specific, model-independent parameters. 360 The diagram below depicts where the TLS Transport Model fits into the 361 architecture described in RFC3411 and the Transport Subsystem: 363 +------------------------------+ 364 | Network | 365 +------------------------------+ 366 ^ ^ ^ 367 | | | 368 v v v 369 +-------------------------------------------------------------------+ 370 | +--------------------------------------------------+ | 371 | | Transport Subsystem | +--------+ | 372 | | +-----+ +-----+ +-------+ +-------+ | | | | 373 | | | UDP | | SSH | |(D)TLS | . . . | other |<--->| Cache | | 374 | | | | | TM | | TM | | | | | | | 375 | | +-----+ +-----+ +-------+ +-------+ | +--------+ | 376 | +--------------------------------------------------+ ^ | 377 | ^ | | 378 | | | | 379 | Dispatcher v | | 380 | +--------------+ +---------------------+ +----------------+ | | 381 | | Transport | | Message Processing | | Security | | | 382 | | Dispatch | | Subsystem | | Subsystem | | | 383 | | | | +------------+ | | +------------+ | | | 384 | | | | +->| v1MP |<--->| | USM | | | | 385 | | | | | +------------+ | | +------------+ | | | 386 | | | | | +------------+ | | +------------+ | | | 387 | | | | +->| v2cMP |<--->| | Transport | | | | 388 | | Message | | | +------------+ | | | Security |<--+ | 389 | | Dispatch <---->| +------------+ | | | Model | | | 390 | | | | +->| v3MP |<--->| +------------+ | | 391 | | | | | +------------+ | | +------------+ | | 392 | | PDU Dispatch | | | +------------+ | | | Other | | | 393 | +--------------+ | +->| otherMP |<--->| | Model(s) | | | 394 | ^ | +------------+ | | +------------+ | | 395 | | +---------------------+ +----------------+ | 396 | v | 397 | +-------+-------------------------+---------------+ | 398 | ^ ^ ^ | 399 | | | | | 400 | v v v | 401 | +-------------+ +---------+ +--------------+ +-------------+ | 402 | | COMMAND | | ACCESS | | NOTIFICATION | | PROXY | | 403 | | RESPONDER |<->| CONTROL |<->| ORIGINATOR | | FORWARDER | | 404 | | application | | | | applications | | application | | 405 | +-------------+ +---------+ +--------------+ +-------------+ | 406 | ^ ^ | 407 | | | | 408 | v v | 409 | +----------------------------------------------+ | 410 | | MIB instrumentation | SNMP entity | 411 +-------------------------------------------------------------------+ 413 3.1. Security Capabilities of this Model 415 3.1.1. Threats 417 The TLS Transport Model provides protection against the threats 418 identified by the RFC 3411 architecture [RFC3411]: 420 1. Modification of Information - The modification threat is the 421 danger that an unauthorized entity may alter in-transit SNMP 422 messages generated on behalf of an authorized principal in such a 423 way as to effect unauthorized management operations, including 424 falsifying the value of an object. 426 (D)TLS provides verification that the content of each received 427 message has not been modified during its transmission through the 428 network, data has not been altered or destroyed in an 429 unauthorized manner, and data sequences have not been altered to 430 an extent greater than can occur non-maliciously. 432 2. Masquerade - The masquerade threat is the danger that management 433 operations unauthorized for a given principal may be attempted by 434 assuming the identity of another principal that has the 435 appropriate authorizations. 437 The TLSTM verifies of the identity of the (D)TLS server through 438 the use of the (D)TLS protocol and X.509 certificates. The TLS 439 Transport Model MUST support authentication of both the server 440 and the client. 442 3. Message stream modification - The re-ordering, delay or replay of 443 messages can and does occur through the natural operation of many 444 connectionless transport services. The message stream 445 modification threat is the danger that messages may be 446 maliciously re-ordered, delayed or replayed to an extent which is 447 greater than can occur through the natural operation of 448 connectionless transport services, in order to effect 449 unauthorized management operations. 451 (D)TLS provides replay protection with a MAC that includes a 452 sequence number. Since UDP provides no sequencing ability DTLS 453 uses a sliding window protocol with the sequence number for 454 replay protection (see [RFC4347]). 456 4. Disclosure - The disclosure threat is the danger of eavesdropping 457 on the exchanges between SNMP engines. 459 (D)TLS provides protection against the disclosure of information 460 to unauthorized recipients or eavesdroppers by allowing for 461 encryption of all traffic between SNMP engines. The TLS 462 Transport Model SHOULD support the message encryption to protect 463 sensitive data from eavesdropping attacks. 465 5. Denial of Service - the RFC 3411 architecture [RFC3411] states 466 that denial of service (DoS) attacks need not be addressed by an 467 SNMP security protocol. However, datagram-based security 468 protocols like DTLS are susceptible to a variety of denial of 469 service attacks because they are more vulnerable to spoofed 470 messages. 472 In order to counter these attacks, DTLS borrows the stateless 473 cookie technique used by Photuris [RFC2522] and IKEv2 [RFC4306] 474 and is described fully in section 4.2.1 of [RFC4347]. This 475 mechanism, though, does not provide any defense against denial of 476 service attacks mounted from valid IP addresses. DTLS Transport 477 Model server implementations MUST support DTLS cookies. 479 Implementations are not required to perform the stateless cookie 480 exchange for every DTLS handshake, but in environments where an 481 overload on server side resources is detectable by the 482 implementation it is RECOMMENDED that the cookie exchange is 483 utilized by the implementation. 485 See Section 9 for more detail on the security considerations 486 associated with the TLSTM and these security threats. 488 3.1.2. Message Protection 490 The RFC 3411 architecture recognizes three levels of security: 492 o without authentication and without privacy (noAuthNoPriv) 494 o with authentication but without privacy (authNoPriv) 496 o with authentication and with privacy (authPriv) 498 The TLS Transport Model determines from (D)TLS the identity of the 499 authenticated principal, the transport type and the transport address 500 associated with an incoming message. The TLS Transport Model 501 provides the identity and destination type and address to (D)TLS for 502 outgoing messages. 504 When an application requests a session for a message, through the 505 cache, the application requests a security level for that session. 506 The TLS Transport Model MUST ensure that the (D)TLS session provides 507 security at least as high as the requested level of security. How 508 the security level is translated into the algorithms used to provide 509 data integrity and privacy is implementation-dependent. However, the 510 NULL integrity and encryption algorithms MUST NOT be used to fulfill 511 security level requests for authentication or privacy. 512 Implementations MAY choose to force (D)TLS to only allow 513 cipher_suites that provide both authentication and privacy to 514 guarantee this assertion. 516 If a suitable interface between the TLS Transport Model and the 517 (D)TLS Handshake Protocol is implemented to allow the selection of 518 security level dependent algorithms (for example a security level to 519 cipher_suites mapping table) then different security levels may be 520 utilized by the application. 522 The authentication, integrity and privacy algorithms used by the 523 (D)TLS Protocols may vary over time as the science of cryptography 524 continues to evolve and the development of (D)TLS continues over 525 time. Implementers are encouraged to plan for changes in operator 526 trust of particular algorithms. Implementations should offer 527 configuration settings for mapping algorithms to SNMPv3 security 528 levels. 530 3.1.3. (D)TLS Sessions 532 (D)TLS sessions are opened by the TLS Transport Model during the 533 elements of procedure for an outgoing SNMP message. Since the sender 534 of a message initiates the creation of a (D)TLS session if needed, 535 the (D)TLS session will already exist for an incoming message. 537 Implementations MAY choose to instantiate (D)TLS sessions in 538 anticipation of outgoing messages. This approach might be useful to 539 ensure that a (D)TLS session to a given target can be established 540 before it becomes important to send a message over the (D)TLS 541 session. Of course, there is no guarantee that a pre-established 542 session will still be valid when needed. 544 DTLS sessions, when used over UDP, are uniquely identified within the 545 TLS Transport Model by the combination of transportDomain, 546 transportAddress, tmSecurityName, and requestedSecurityLevel 547 associated with each session. Each unique combination of these 548 parameters MUST have a locally-chosen unique tlstmSessionID for each 549 active session. For further information see Section 5. TLS over TCP 550 and DTLS over SCTP sessions, on the other hand, do not require a 551 unique pairing of address and port attributes since their lower layer 552 protocols (TCP and SCTP) already provide adequate session framing. 553 But they must still provide a unique tlstmSessionID for referencing 554 the session. 556 As an implementation hint: although the tlstmSessionID may be the 557 same as the (D)TLS internal SessionID caution must be exercised since 558 the (D)TLS internal SessionID may change over the life of the 559 connection as seen by the TLSTM (for example during renegotiation). 560 The tlstmSessionID identifier MUST NOT change during the entire 561 duration of the session from the TLSTM's perspective even if the TLS 562 internal session identifier does change. 564 3.2. Security Parameter Passing 566 For the (D)TLS server-side, (D)TLS-specific security parameters 567 (i.e., cipher_suites, X.509 certificate fields, IP address and port) 568 are translated by the TLS Transport Model into security parameters 569 for the TLS Transport Model and security model (e.g., 570 tmSecurityLevel, tmSecurityName, transportDomain, transportAddress). 571 The transport- related and (D)TLS-security-related information, 572 including the authenticated identity, are stored in a cache 573 referenced by tmStateReference. 575 For the (D)TLS client-side, the TLS Transport Model takes input 576 provided by the Dispatcher in the sendMessage() Abstract Service 577 Interface (ASI) and input from the tmStateReference cache. The 578 (D)TLS Transport Model converts that information into suitable 579 security parameters for (D)TLS and establishes sessions as needed. 581 The elements of procedure in Section 5 discuss these concepts in much 582 greater detail. 584 3.3. Notifications and Proxy 586 (D)TLS sessions may be initiated by (D)TLS clients on behalf of SNMP 587 appplications that initiate communications, such as command 588 generators, notification originators, proxy forwarders. Command 589 generators are frequently operated by a human, but notification 590 originators and proxy forwarders are usually unmanned automated 591 processes. The targets to whom notifications and proxied requests 592 should be sent is typically determined and configured by a network 593 administrator. 595 The SNMP-TARGET-MIB module [RFC3413] contains objects for defining 596 management targets, including transportDomain, transportAddress, 597 securityName, securityModel, and securityLevel parameters, for 598 notification generator, proxy forwarder, and SNMP-controllable 599 command generator applications. Transport domains and transport 600 addresses are configured in the snmpTargetAddrTable, and the 601 securityModel, securityName, and securityLevel parameters are 602 configured in the snmpTargetParamsTable. This document defines a MIB 603 module that extends the SNMP-TARGET-MIB's snmpTargetParamsTable to 604 specify a (D)TLS client-side certificate to use for the connection. 606 When configuring a (D)TLS target, the snmpTargetAddrTDomain and 607 snmpTargetAddrTAddress parameters in snmpTargetAddrTable should be 608 set to the snmpTLSTCPDomain, snmpDTLSUDPDomain, or snmpDTLSSCTPDomain 609 object and an appropriate snmpTLSAddress value. When used with the 610 SNMPv3 message processing model, the snmpTargetParamsMPModel column 611 of the snmpTargetParamsTable should be set to a value of 3. The 612 snmpTargetParamsSecurityName should be set to an appropriate 613 securityName value and the tlstmParamsClientFingerprint parameter of 614 the tlstmParamsTable should be set a value that refers to a locally 615 held certificate to be used. Other parameters, for example 616 cryptographic configuration such as cipher suites to use, must come 617 from configuration mechanisms not defined in this document. The 618 securityName defined in the snmpTargetParamsSecurityName column will 619 be used by the access control model to authorize any notifications 620 that need to be sent. 622 4. Elements of the Model 624 This section contains definitions required to realize the (D)TLS 625 Transport Model defined by this document. 627 4.1. X.509 Certificates 629 (D)TLS can make use of X.509 certificates for authentication of both 630 sides of the transport. This section discusses the use of X.509 631 certificates in the TLSTM. A brief overview of X.509 certificate 632 infrastructure can be found in Appendix B. 634 While (D)TLS supports multiple authentication mechanisms, this 635 document only discusses X.509 certificate based authentication. 636 Although other forms of authentication are possible they are outside 637 the scope of this specification. TLSTM implementations are REQUIRED 638 to support X.509 certificates. 640 4.1.1. Provisioning for the Certificate 642 Authentication using (D)TLS will require that SNMP entities are 643 provisioned with certificates, which are signed by trusted 644 certificate authorities (possibly the certificate itself). 645 Furthermore, SNMP entities will most commonly need to be provisioned 646 with root certificates which represent the list of trusted 647 certificate authorities that an SNMP entity can use for certificate 648 verification. SNMP entities SHOULD also be provisioned with a X.509 649 certificate revocation mechanism which can be used to verify that a 650 certificate has not been revoked. Trusted public keys from either CA 651 certificates and/or self-signed certificates, MUST be installed 652 through a trusted out of band mechanism into the server and its 653 authenticity MUST be verified before access is granted. 655 Having received a certificate from a connecting TLSTM client, the 656 authenticated tmSecurityName of the principal is derived using the 657 tlstmCertToTSNTable. This table allows mapping of incoming 658 connections to tmSecurityNames through defined transformations. The 659 transformations defined in the TLSTM-MIB include: 661 o Mapping a certificate's fingerprint type and value to a directly 662 specified tmSecurityName, or 664 o Mapping a certificate's subjectAltName or CommonName components to 665 a tmSecurityName. 667 As an implementation hint: implementations may choose to discard any 668 connections for which no potential tlstmCertToTSNTable mapping exists 669 before performing certificate verification to avoid expending 670 computational resources associated with certificate verification. 672 Enterprise configurations are encouraged to map a "subjectAltName" 673 component of the X.509 certificate to the TLSTM specific 674 tmSecurityName. The authenticated identity can be obtained by the 675 TLS Transport Model by extracting the subjectAltName(s) from the 676 peer's certificate. The receiving application will then have an 677 appropriate tmSecurityName for use by other SNMPv3 components like an 678 access control model. 680 An example of this type of mapping setup can be found in Appendix C. 682 This tmSecurityName may be later translated from a TLSTM specific 683 tmSecurityName to a SNMP engine securityName by the security model. 684 A security model, like the TSM security model [RFC5591], may perform 685 an identity mapping or a more complex mapping to derive the 686 securityName from the tmSecurityName offered by the TLS Transport 687 Model. 689 A pictorial view of the complete transformation process (using the 690 TSM security model for the example) is shown below: 692 +-------------+ +-------+ +----------------+ +-----+ 693 | Certificate | | | | | | | 694 | Path | | TLSTM | | tmSecurityName | | TSM | 695 | Validation | --> | | --> | | --> | | 696 +-------------+ +-------+ +----------------+ +-----+ 697 | 698 V 699 +-------------+ +--------------+ 700 | application | <-- | securityName | 701 +-------------+ +--------------+ 703 4.2. Messages 705 As stated in Section 4.1.1 of [RFC4347], each DTLS record must fit 706 within a single DTLS datagram. The TLSTM SHOULD prohibit SNMP 707 messages from being sent that exceeds the maximum DTLS message size. 708 The TLSTM implementation SHOULD return an error when the DTLS message 709 size would be exceeded and the message won't be sent. 711 4.3. SNMP Services 713 This section describes the services provided by the TLS Transport 714 Model with their inputs and outputs. The services are between the 715 Transport Model and the Dispatcher. 717 The services are described as primitives of an abstract service 718 interface (ASI) and the inputs and outputs are described as abstract 719 data elements as they are passed in these abstract service 720 primitives. 722 4.3.1. SNMP Services for an Outgoing Message 724 The Dispatcher passes the information to the TLS Transport Model 725 using the ASI defined in the transport subsystem: 727 statusInformation = 728 sendMessage( 729 IN destTransportDomain -- transport domain to be used 730 IN destTransportAddress -- transport address to be used 731 IN outgoingMessage -- the message to send 732 IN outgoingMessageLength -- its length 733 IN tmStateReference -- reference to transport state 734 ) 736 The abstract data elements returned from or passed as parameters into 737 the abstract service primitives are as follows: 739 statusInformation: An indication of whether the passing of the 740 message was successful. If not, it is an indication of the 741 problem. 743 destTransportDomain: The transport domain for the associated 744 destTransportAddress. The Transport Model uses this parameter to 745 determine the transport type of the associated 746 destTransportAddress. This document specifies the snmpTLSDomain, 747 the snmpDTLSUDPDomain and the snmpDTLSSCTPDomain" transport 748 domains. 750 destTransportAddress: The transport address of the destination TLS 751 Transport Model in a format specified by the SnmpTLSAddress 752 TEXTUAL-CONVENTION. 754 outgoingMessage: The outgoing message to send to (D)TLS for 755 encapsulation. 757 outgoingMessageLength: The length of the outgoingMessage field. 759 tmStateReference: A handle/reference to tmState to be used when 760 securing outgoing messages. 762 4.3.2. SNMP Services for an Incoming Message 764 The TLS Transport Model processes the received message from the 765 network using the (D)TLS service and then passes it to the Dispatcher 766 using the following ASI: 768 statusInformation = 769 receiveMessage( 770 IN transportDomain -- origin transport domain 771 IN transportAddress -- origin transport address 772 IN incomingMessage -- the message received 773 IN incomingMessageLength -- its length 774 IN tmStateReference -- reference to transport state 775 ) 777 The abstract data elements returned from or passed as parameters into 778 the abstract service primitives are as follows: 780 statusInformation: An indication of whether the passing of the 781 message was successful. If not, it is an indication of the 782 problem. 784 transportDomain: The transport domain for the associated 785 transportAddress. This document specifies the snmpTLSDomain, the 786 snmpDTLSUDPDomain and the snmpDTLSSCTPDomain" transport domains. 788 transportAddress: The transport address of the source of the 789 received message in a format specified by the SnmpTLSAddress 790 TEXTUAL-CONVENTION. 792 incomingMessage: The whole SNMP message after being processed by 793 (D)TLS and removed of the (D)TLS transport layer data. 795 incomingMessageLength: The length of the incomingMessage field. 797 tmStateReference: A handle/reference to tmSecurityData to be used by 798 the security model. 800 4.4. Cached Information and References 802 When performing SNMP processing, there are two levels of state 803 information that may need to be retained: the immediate state linking 804 a request-response pair, and potentially longer-term state relating 805 to transport and security. "Transport Subsystem for the Simple 806 Network Management Protocol" [RFC5590] defines general requirements 807 for caches and references. 809 4.4.1. TLS Transport Model Cached Information 811 The TLS Transport Model has specific responsibilities regarding the 812 cached information. See the Elements of Procedure in Section 5 for 813 detailed processing instructions on the use of the tmStateReference 814 fields by the TLS Transport Model. 816 4.4.1.1. tmSecurityName 818 The tmSecurityName MUST be a human-readable name (in snmpAdminString 819 format) representing the identity that has been set according to the 820 procedures in Section 5. The tmSecurityName MUST be constant for all 821 traffic passing through an TLSTM session. Messages MUST NOT be sent 822 through an existing (D)TLS session that was established using a 823 different tmSecurityName. 825 On the (D)TLS server side of a connection the tmSecurityName is 826 derived using the procedures described in Section 5.3 and the TLSTM- 827 MIB's tlstmCertToTSNTable DESCRIPTION clause. 829 On the (D)TLS client side of a connection the tmSecurityName is 830 presented to the TLS Transport Model by the application (possibly 831 because of configuration specified in the SNMP-TARGET-MIB). 833 The securityName MAY be derived from the tmSecurityName by a Security 834 Model and MAY be used to configure notifications and access controls 835 in MIB modules. Transport Models SHOULD generate a predictable 836 tmSecurityName so operators will know what to use when configuring 837 MIB modules that use securityNames derived from tmSecurityNames. 839 4.4.1.2. tmSessionID 841 The tmSessionID MUST be recorded per message at the time of receipt. 842 When tmSameSecurity is set, the recorded tmSessionID can be used to 843 determine whether the (D)TLS session available for sending a 844 corresponding outgoing message is the same (D)TLS session as was used 845 when receiving the incoming message (e.g., a response to a request). 847 4.4.1.3. Session State 849 The per-session state that is referenced by tmStateReference may be 850 saved across multiple messages in a Local Configuration Datastore. 851 Additional session/connection state information might also be stored 852 in a Local Configuration Datastore. 854 5. Elements of Procedure 856 Abstract service interfaces have been defined by [RFC3411] and 857 further augmented by [RFC5590] to describe the conceptual data flows 858 between the various subsystems within an SNMP entity. The TLSTM uses 859 some of these conceptual data flows when communicating between 860 subsystems. 862 To simplify the elements of procedure, the release of state 863 information is not always explicitly specified. As a general rule, 864 if state information is available when a message gets discarded, the 865 message-state information should also be released. If state 866 information is available when a session is closed, the session state 867 information should also be released. Sensitive information, like 868 cryptographic keys, should be overwritten appropriately first prior 869 to being released. 871 An error indication in statusInformation will typically include the 872 Object Identifier (OID) and value for an incremented error counter. 873 This may be accompanied by the requested securityLevel and the 874 tmStateReference. Per-message context information is not accessible 875 to Transport Models, so for the returned counter OID and value, 876 contextEngine would be set to the local value of snmpEngineID and 877 contextName to the default context for error counters. 879 5.1. Procedures for an Incoming Message 881 This section describes the procedures followed by the (D)TLS 882 Transport Model when it receives a (D)TLS protected packet. The 883 steps are broken into two different sections. Section 5.1.1 884 describes the needed steps for de-multiplexing multiple DTLS 885 sessions, which is specifically needed for DTLS over UDP sessions. 886 Section 5.1.2 describes the steps specific to transport processing 887 once the (D)TLS processing has been completed. It is assumed that 888 TLS and DTLS/SCP protocol implementations already provide appropriate 889 message demultiplexing and only the processing steps in Section 5.1.2 890 are needed. 892 5.1.1. DTLS Processing for Incoming Messages 894 DTLS over UDP is significantly different in terms of session handling 895 than when TLS or DTLS is run over session based streaming protocols 896 like TCP or SCTP. Specifically, the DTLS protocol, when run over 897 UDP, does not have a session identifier that allows implementations 898 to determine through which session a packet arrived. It is always 899 critical, however, that implementations be able to derive a 900 tlstmSessionID from any session demultiplexing process. When 901 establishing a new session implementations MUST use a different UDP 902 source port number for each connection to a remote destination IP- 903 address/port-number combination to ensure the remote entity can 904 easily disambiguate between multiple sessions from a host to the same 905 port on a server. 907 A process for demultiplexing multiple DTLS sessions arriving over UDP 908 must be incorporated into the procedures for processing an incoming 909 message. The steps in this section describe one possible method to 910 accomplish this, although any implementation-dependent method should 911 be suitable as long as the results are deterministic. The important 912 output results from the steps in this process are the 913 transportDomain, the transportAddress, the wholeMessage, the 914 wholeMessageLength, and a unique implementation-dependent session 915 identifier (tlstmSessionID). 917 This demultiplexing procedure assumes that upon session establishment 918 an entry in a local transport mapping table is created in the 919 Transport Model's Local Configuration Datastore (LCD). The transport 920 mapping table's entry should map a unique combination of the remote 921 address, remote port number, local address and local port number to 922 an implementation-dependent tlstmSessionID. 924 1) The TLS Transport Model examines the raw UDP message, in an 925 implementation-dependent manner. 927 2) The TLS Transport Model queries the LCD using the transport 928 parameters (source and destination addresses and ports) to 929 determine if a session already exists and its tlstmSessionID. 931 If a matching entry in the LCD does not exist then the message is 932 passed to DTLS for processing without a corresponding 933 tlstmSessionID. The incoming packet may result in a new session 934 being established if the receiving entity is acting as a DTLS 935 server. If DTLS returns success then stop processing of this 936 message. If DTLS returns an error then increment the 937 snmpTlstmSessionNoSessions counter and stop processing the 938 message. 940 Note that an entry would already exist if the client and server's 941 session establishment procedures had been successfully completed 942 previously (as described both above and in Section 5.3) even if 943 no message had yet been sent through the newly established 944 session. An entry may not exist, however, if a message not 945 intended the SNMP entity was routed to it by mistake. An entry 946 might also be missing because of a "broken" session (see 947 operational considerations). 949 3) Retrieve the tlstmSessionID from the LCD. 951 4) The UDP packet and the tlstmSessionID are passed to DTLS for 952 integrity checking and decryption. 954 If the message fails integrity checks or other (D)TLS security 955 processing then increment the tlstmDTLSProtectionErrors counter, 956 discard and stop processing the message. 958 5) DTLS should return an incomingMessage and an 959 incomingMessageLength. These results and the tlstmSessionID are 960 used below in the Section 5.1.2 to complete the processing of the 961 incoming message. 963 5.1.2. Transport Processing for Incoming SNMP Messages 965 The procedures in this section describe how the TLS Transport Model 966 should process messages that have already been properly extracted 967 from the (D)TLS stream. Note that care must be taken when processing 968 messages originating from either TLS or DTLS to ensure they're 969 complete and single. For example, multiple SNMP messages can be 970 passed through a single DTLS message and partial SNMP messages may be 971 received from a TLS stream. These steps describe the processing of a 972 singular SNMP message after it has been delivered from the (D)TLS 973 stream. 975 Create a tmStateReference cache for the subsequent reference and 976 assign the following values within it: 978 tmTransportDomain = snmpTLSTCPDomain, snmpDTLSUDPDomain or 979 snmpDTLSSCTPDomain as appropriate. 981 tmTransportAddress = The address the message originated from. 983 tmSecurityLevel = The derived tmSecurityLevel for the session, as 984 discussed in Section 3.1.2 and Section 5.3. 986 tmSecurityName = The derived tmSecurityName for the session as 987 discussed in Section 5.3. This value MUST be constant during the 988 lifetime of the (D)TLS session. 990 tmSessionID = The tlstmSessionID, which MUST be a unique session 991 identifier for this (D)TLS connection. The contents and format of 992 this identifier are implementation-dependent as long as it is 993 unique to the session. A session identifier MUST NOT be reused 994 until all references to it are no longer in use. The tmSessionID 995 is equal to the tlstmSessionID discussed in Section 5.1.1. 996 tmSessionID refers to the session identifier when stored in the 997 tmStateReference and tlstmSessionID refers to the session 998 identifier when stored in the LCD. They MUST always be equal when 999 processing a given session's traffic. 1001 The wholeMessage and the wholeMessageLength are assigned values from 1002 the incomingMessage and incomingMessageLength values from the (D)TLS 1003 processing. 1005 The TLS Transport Model passes the transportDomain, transportAddress, 1006 wholeMessage, and wholeMessageLength to the Dispatcher using the 1007 receiveMessage ASI: 1009 statusInformation = 1010 receiveMessage( 1011 IN transportDomain -- snmpTLSTCPDomain, snmpDTLSUDPDomain, 1012 -- or snmpDTLSSCTPDomain 1013 IN transportAddress -- address for the received message 1014 IN wholeMessage -- the whole SNMP message from (D)TLS 1015 IN wholeMessageLength -- the length of the SNMP message 1016 IN tmStateReference -- transport info 1017 ) 1019 5.2. Procedures for an Outgoing SNMP Message 1021 The Dispatcher sends a message to the TLS Transport Model using the 1022 following ASI: 1024 statusInformation = 1025 sendMessage( 1026 IN destTransportDomain -- transport domain to be used 1027 IN destTransportAddress -- transport address to be used 1028 IN outgoingMessage -- the message to send 1029 IN outgoingMessageLength -- its length 1030 IN tmStateReference -- transport info 1031 ) 1033 This section describes the procedure followed by the TLS Transport 1034 Model whenever it is requested through this ASI to send a message. 1036 1) If tmStateReference does not refer to a cache containing values 1037 for tmTransportDomain, tmTransportAddress, tmSecurityName, 1038 tmRequestedSecurityLevel, and tmSameSecurity, then increment the 1039 snmpTlstmSessionInvalidCaches counter, discard the message, and 1040 return the error indication in the statusInformation. Processing 1041 of this message stops. 1043 2) Extract the tmSessionID, tmTransportDomain, tmTransportAddress, 1044 tmSecurityName, tmRequestedSecurityLevel, and tmSameSecurity 1045 values from the tmStateReference. Note: The tmSessionID value 1046 may be undefined if no session exists yet over which the message 1047 can be sent. 1049 3) If tmSameSecurity is true and either tmSessionID is undefined or 1050 refers to a session that is no longer open then increment the 1051 snmpTlstmSessionNoSessions counter, discard the message and 1052 return the error indication in the statusInformation. Processing 1053 of this message stops. 1055 4) If tmSameSecurity is false and tmSessionID refers to a session 1056 that is no longer available then an implementation SHOULD open a 1057 new session using the openSession() ASI (described in greater 1058 detail in step 4b). Instead of opening a new session an 1059 implementation MAY return a snmpTlstmSessionNoSessions error to 1060 the calling module and stop processing of the message. 1062 5) If tmSessionID is undefined, then use tmTransportDomain, 1063 tmTransportAddress, tmSecurityName and tmRequestedSecurityLevel 1064 to see if there is a corresponding entry in the LCD suitable to 1065 send the message over. 1067 5a) If there is a corresponding LCD entry, then this session 1068 will be used to send the message. 1070 5b) If there is not a corresponding LCD entry, then open a 1071 session using the openSession() ASI (discussed further in 1072 Section 5.3). Implementations MAY wish to offer message 1073 buffering to prevent redundant openSession() calls for the 1074 same cache entry. If an error is returned from 1075 openSession(), then discard the message, discard the 1076 tmStateReference, increment the snmpTlstmSessionOpenErrors, 1077 return an error indication to the calling module and stop 1078 processing of the message. 1080 6) Using either the session indicated by the tmSessionID if there 1081 was one or the session resulting from a previous step (3 or 4), 1082 pass the outgoingMessage to (D)TLS for encapsulation and 1083 transmission. 1085 5.3. Establishing a Session 1087 The TLS Transport Model provides the following primitive to establish 1088 a new (D)TLS session: 1090 statusInformation = -- errorIndication or success 1091 openSession( 1092 IN tmStateReference -- transport information to be used 1093 OUT tmStateReference -- transport information to be used 1094 IN maxMessageSize -- of the sending SNMP entity 1095 ) 1097 The following describes the procedure to follow when establishing a 1098 SNMP over (D)TLS session between SNMP engines for exchanging SNMP 1099 messages. This process is followed by any SNMP engine establishing a 1100 session for subsequent use. 1102 This MAY be done automatically for an SNMP application that initiates 1103 a transaction, such as a command generator, a notification 1104 originator, or a proxy forwarder. 1106 1) The client selects the appropriate certificate and cipher_suites 1107 for the key agreement based on the tmSecurityName and the 1108 tmRequestedSecurityLevel for the session. For sessions being 1109 established as a result of a SNMP-TARGET-MIB based operation, the 1110 certificate will potentially have been identified via the 1111 tlstmParamsTable mapping and the cipher_suites will have to be 1112 taken from system-wide or implementation-specific configuration. 1113 Otherwise, the certificate and appropriate cipher_suites will 1114 need to be passed to the openSession() ASI as supplemental 1115 information or configured through an implementation-dependent 1116 mechanism. It is also implementation-dependent and possibly 1117 policy-dependent how tmRequestedSecurityLevel will be used to 1118 influence the security capabilities provided by the (D)TLS 1119 session. However this is done, the security capabilities 1120 provided by (D)TLS MUST be at least as high as the level of 1121 security indicated by the tmRequestedSecurityLevel parameter. 1122 The actual security level of the session is reported in the 1123 tmStateReference cache as tmSecurityLevel. For (D)TLS to provide 1124 strong authentication, each principal acting as a command 1125 generator SHOULD have its own certificate. 1127 2) Using the destTransportDomain and destTransportAddress values, 1128 the client will initiate the (D)TLS handshake protocol to 1129 establish session keys for message integrity and encryption. 1131 If the attempt to establish a session is unsuccessful, then 1132 snmpTlstmSessionOpenErrors is incremented, an error indication is 1133 returned, and processing stops. If the session failed to open 1134 because the presented server certificate was unknown or invalid 1135 then the snmpTlstmSessionUnknownServerCertificate or 1136 snmpTlstmSessionInvalidServerCertificates MUST be incremented and 1137 a tlstmServerCertificateUnknown or tlstmServerInvalidCertificate 1138 notification SHOULD be sent as appropriate. Reasons for server 1139 certificate invalidation includes, but is not limited to, 1140 cryptographic validation failures and an unexpected presented 1141 certificate identity. 1143 3) Once a (D)TLS secured session is established and both sides have 1144 verified the authenticity of the peer's certificate (e.g. 1145 [RFC5280]) then each side will determine and/or check the 1146 identity of the remote entity using the procedures described 1147 below. 1149 a) The (D)TLS server side of the connection identifies the 1150 authenticated identity from the (D)TLS client's principal 1151 certificate using configuration information from the 1152 tlstmCertToTSNTable mapping table. The (D)TLS server MUST 1153 request and expect a certificate from the client and MUST NOT 1154 accept SNMP messages over the (D)TLS session until the client 1155 has sent a certificate and it has been authenticated. The 1156 resulting derived tmSecurityName is recorded in the 1157 tmStateReference cache as tmSecurityName. The details of the 1158 lookup process are fully described in the DESCRIPTION clause 1159 of the tlstmCertToTSNTable MIB object. If any verification 1160 fails in any way (for example because of failures in 1161 cryptographic verification or because of the lack of an 1162 appropriate row in the tlstmCertToTSNTable) then the session 1163 establishment MUST fail, the 1164 snmpTlstmSessionInvalidClientCertificates object is 1165 incremented and processing stops. 1167 b) The (D)TLS client side of the connection MUST verify that the 1168 (D)TLS server's presented certificate is the expected 1169 certificate. The (D)TLS client MUST NOT transmit SNMP 1170 messages until the server certificate has been authenticated 1171 and the client certificate has been transmitted. 1173 If the connection is being established from configuration 1174 based on SNMP-TARGET-MIB configuration then the procedures in 1175 the tlstmAddrTable DESCRIPTION clause should be followed to 1176 determine if the presented identity matches the expectations 1177 of the configuration. Path validation procedures (like those 1178 defined in [RFC5280]) MUST be followed. If a server identity 1179 name has been configured in the tlstmAddrServerIdentity 1180 column then this reference identity must be compared against 1181 the presented identity (for example using procedures 1182 described in [I-D.saintandre-tls-server-id-check]). 1184 If the connection is being established for other reasons then 1185 configuration and procedures outside the scope of this 1186 document should be followed. 1188 (D)TLS provides assurance that the authenticated identity has 1189 been signed by a trusted configured certificate authority. 1190 If verification of the server's certificate fails in any way 1191 (for example because of failures in cryptographic 1192 verification or the presented identity did not match the 1193 expected named entity) then the session establishment MUST 1194 fail, the snmpTlstmSessionInvalidServerCertificates object is 1195 incremented and processing stops. 1197 4) The TLSTM-specific session identifier (tlstmSessionID) is set in 1198 the tmSessionID of the tmStateReference passed to the TLS 1199 Transport Model to indicate that the session has been established 1200 successfully and to point to a specific (D)TLS session for future 1201 use. 1203 Servers that wish to support multiple principals at a particular port 1204 SHOULD make use of a (D)TLS extension that allows server-side 1205 principal selection like the Server Name Indication extension defined 1206 in Section 3.1 of [RFC4366]. Supporting this will allow, for 1207 example, sending notifications to a specific principal at a given 1208 TCP, UDP or SCTP port. 1210 5.4. Closing a Session 1212 The TLS Transport Model provides the following primitive to close a 1213 session: 1215 statusInformation = 1216 closeSession( 1217 IN tmSessionID -- session ID of the session to be closed 1218 ) 1220 The following describes the procedure to follow to close a session 1221 between a client and server. This process is followed by any SNMP 1222 engine closing the corresponding SNMP session. 1224 1) Increment the snmpTlstmSessionCloses counter. 1226 2) Look up the session using the tmSessionID. 1228 3) If there is no open session associated with the tmSessionID, then 1229 closeSession processing is completed. 1231 4) Have (D)TLS close the specified session. This SHOULD include 1232 sending a close_notify TLS Alert to inform the other side that 1233 session cleanup may be performed. 1235 6. MIB Module Overview 1237 This MIB module provides management of the TLS Transport Model. It 1238 defines needed textual conventions, statistical counters, 1239 notifications and configuration infrastructure necessary for session 1240 establishment. Example usage of the configuration tables can be 1241 found in Appendix C. 1243 6.1. Structure of the MIB Module 1245 Objects in this MIB module are arranged into subtrees. Each subtree 1246 is organized as a set of related objects. The overall structure and 1247 assignment of objects to their subtrees, and the intended purpose of 1248 each subtree, is shown below. 1250 6.2. Textual Conventions 1252 Generic and Common Textual Conventions used in this module can be 1253 found summarized at http://www.ops.ietf.org/mib-common-tcs.html 1255 This module defines the following new Textual Conventions: 1257 o New TransportDomain and TransportAddress formats for describing 1258 (D)TLS connection addressing requirements. 1260 o A certificate fingerprint allowing MIB module objects to 1261 generically refer to a stored X.509 certificate using a 1262 cryptographic hash as a reference pointer. 1264 6.3. Statistical Counters 1266 The TLSTM-MIB defines some counters that can provide network managers 1267 with information about (D)TLS session usage and potential errors that 1268 a MIB-instrumented device may be experiencing. 1270 6.4. Configuration Tables 1272 The TLSTM-MIB defines configuration tables that a manager can use for 1273 configuring a MIB-instrumented device for sending and receiving SNMP 1274 messages over (D)TLS. In particular, there are MIB tables that 1275 extend the SNMP-TARGET-MIB for configuring (D)TLS certificate usage 1276 and a MIB table for mapping incoming (D)TLS client certificates to 1277 SNMPv3 securityNames. 1279 6.4.1. Notifications 1281 The TLSTM-MIB defines notifications to alert management stations when 1282 a (D)TLS connection fails because a server's presented certificate 1283 did not meet an expected value (tlstmServerCertificateUnknown) or 1284 because cryptographic validation failed 1285 (tlstmServerInvalidCertificate). 1287 6.5. Relationship to Other MIB Modules 1289 Some management objects defined in other MIB modules are applicable 1290 to an entity implementing the TLS Transport Model. In particular, it 1291 is assumed that an entity implementing the TLSTM-MIB will implement 1292 the SNMPv2-MIB [RFC3418], the SNMP-FRAMEWORK-MIB [RFC3411], the SNMP- 1293 TARGET-MIB [RFC3413], the SNMP-NOTIFICATION-MIB [RFC3413] and the 1294 SNMP-VIEW-BASED-ACM-MIB [RFC3415]. 1296 The TLSTM-MIB module contained in this document is for managing TLS 1297 Transport Model information. 1299 6.5.1. MIB Modules Required for IMPORTS 1301 The TLSTM-MIB module imports items from SNMPv2-SMI [RFC2578], 1302 SNMPv2-TC [RFC2579], SNMP-FRAMEWORK-MIB [RFC3411], SNMP-TARGET-MIB 1303 [RFC3413] and SNMPv2-CONF [RFC2580]. 1305 7. MIB Module Definition 1307 TLSTM-MIB DEFINITIONS ::= BEGIN 1309 IMPORTS 1310 MODULE-IDENTITY, OBJECT-TYPE, 1311 OBJECT-IDENTITY, snmpModules, snmpDomains, 1312 Counter32, Unsigned32, NOTIFICATION-TYPE 1313 FROM SNMPv2-SMI 1314 TEXTUAL-CONVENTION, TimeStamp, RowStatus, StorageType, 1315 AutonomousType 1316 FROM SNMPv2-TC 1317 MODULE-COMPLIANCE, OBJECT-GROUP, NOTIFICATION-GROUP 1318 FROM SNMPv2-CONF 1319 SnmpAdminString 1320 FROM SNMP-FRAMEWORK-MIB 1321 snmpTargetParamsName, snmpTargetAddrName 1322 FROM SNMP-TARGET-MIB 1323 ; 1325 tlstmMIB MODULE-IDENTITY 1326 LAST-UPDATED "201001080000Z" 1327 ORGANIZATION "ISMS Working Group" 1328 CONTACT-INFO "WG-EMail: isms@lists.ietf.org 1329 Subscribe: isms-request@lists.ietf.org 1331 Chairs: 1332 Juergen Schoenwaelder 1333 Jacobs University Bremen 1334 Campus Ring 1 1335 28725 Bremen 1336 Germany 1337 +49 421 200-3587 1338 j.schoenwaelder@jacobs-university.de 1340 Russ Mundy 1341 SPARTA, Inc. 1342 7110 Samuel Morse Drive 1343 Columbia, MD 21046 1344 USA 1346 Co-editors: 1347 Wes Hardaker 1348 Sparta, Inc. 1349 P.O. Box 382 1350 Davis, CA 95617 1351 USA 1352 ietf@hardakers.net 1353 " 1355 DESCRIPTION " 1356 The TLS Transport Model MIB 1358 Copyright (c) 2010 IETF Trust and the persons identified as 1359 the document authors. All rights reserved. 1361 Redistribution and use in source and binary forms, with or 1362 without modification, is permitted pursuant to, and subject 1363 to the license terms contained in, the Simplified BSD License 1364 set forth in Section 4.c of the IETF Trust's Legal Provisions 1365 Relating to IETF Documents 1366 (http://trustee.ietf.org/license-info). 1368 This version of this MIB module is part of RFC XXXX; 1369 see the RFC itself for full legal notices." 1371 -- NOTE to RFC editor: replace XXXX with actual RFC number 1372 -- for this document and remove this note 1373 REVISION "201001080000Z" 1374 DESCRIPTION "The initial version, published in RFC XXXX." 1375 -- NOTE to RFC editor: replace XXXX with actual RFC number 1376 -- for this document and remove this note 1378 ::= { snmpModules xxxx } 1379 -- RFC Ed.: replace xxxx with IANA-assigned number and 1380 -- remove this note 1382 -- ************************************************ 1383 -- subtrees of the TLSTM-MIB 1384 -- ************************************************ 1386 tlstmNotifications OBJECT IDENTIFIER ::= { tlstmMIB 0 } 1387 tlstmIdentities OBJECT IDENTIFIER ::= { tlstmMIB 1 } 1388 tlstmObjects OBJECT IDENTIFIER ::= { tlstmMIB 2 } 1389 tlstmConformance OBJECT IDENTIFIER ::= { tlstmMIB 3 } 1391 -- ************************************************ 1392 -- tlstmObjects - Objects 1393 -- ************************************************ 1395 snmpTLSTCPDomain OBJECT-IDENTITY 1396 STATUS current 1397 DESCRIPTION 1398 "The SNMP over TLS transport domain. The corresponding 1399 transport address is of type SnmpTLSAddress. 1401 The securityName prefix to be associated with the 1402 snmpTLSTCPDomain is 'tls'. This prefix may be used by 1403 security models or other components to identify which secure 1404 transport infrastructure authenticated a securityName." 1406 ::= { snmpDomains xx } 1408 -- RFC Ed.: replace xx with IANA-assigned number and 1409 -- remove this note 1411 -- RFC Ed.: replace 'tls' with the actual IANA assigned prefix string 1412 -- if 'tls' is not assigned to this document. 1414 snmpDTLSUDPDomain OBJECT-IDENTITY 1415 STATUS current 1416 DESCRIPTION 1417 "The SNMP over DTLS/UDP transport domain. The corresponding 1418 transport address is of type SnmpTLSAddress. 1420 The securityName prefix to be associated with the 1421 snmpDTLSUDPDomain is 'dudp'. This prefix may be used by 1422 security models or other components to identify which secure 1423 transport infrastructure authenticated a securityName." 1425 ::= { snmpDomains yy } 1427 -- RFC Ed.: replace yy with IANA-assigned number and 1428 -- remove this note 1430 -- RFC Ed.: replace 'dudp' with the actual IANA assigned prefix string 1431 -- if 'dtls' is not assigned to this document. 1433 snmpDTLSSCTPDomain OBJECT-IDENTITY 1434 STATUS current 1435 DESCRIPTION 1436 "The SNMP over DTLS/SCTP transport domain. The corresponding 1437 transport address is of type SnmpTLSAddress. 1439 The securityName prefix to be associated with the 1440 snmpDTLSSCTPDomain is 'dsct'. This prefix may be used by 1441 security models or other components to identify which secure 1442 transport infrastructure authenticated a securityName." 1444 ::= { snmpDomains zz } 1446 -- RFC Ed.: replace zz with IANA-assigned number and 1447 -- remove this note 1449 -- RFC Ed.: replace 'dsct' with the actual IANA assigned prefix string 1450 -- if 'dtls' is not assigned to this document. 1452 SnmpTLSAddress ::= TEXTUAL-CONVENTION 1453 DISPLAY-HINT "1a" 1454 STATUS current 1455 DESCRIPTION 1456 "Represents a IPv4 address, an IPv6 address or an US-ASCII 1457 encoded hostname and port number. 1459 An IPv4 address must be in dotted decimal format followed by a 1460 colon ':' (US-ASCII character 0x3A) and a decimal port number 1461 in US-ASCII. 1463 An IPv6 address must be a colon separated format, surrounded 1464 by square brackets ('[', US-ASCII character 0x5B, and ']', 1465 US-ASCII character 0x5D), followed by a colon ':' (US-ASCII 1466 character 0x3A) and a decimal port number in US-ASCII. 1468 A hostname is always in US-ASCII (as per RFC1033); 1469 internationalized hostnames are encoded in US-ASCII as 1470 specified in RFC 3490. The hostname is followed by a colon 1471 ':' (US-ASCII character 0x3A) and a decimal port number in 1472 US-ASCII. The name SHOULD be fully qualified whenever 1473 possible. 1475 Values of this textual convention may not be directly usable 1476 as transport-layer addressing information, and may require 1477 run-time resolution. As such, applications that write them 1478 must be prepared for handling errors if such values are not 1479 supported, or cannot be resolved (if resolution occurs at the 1480 time of the management operation). 1482 The DESCRIPTION clause of TransportAddress objects that may 1483 have SnmpTLSAddress values must fully describe how (and 1484 when) such names are to be resolved to IP addresses and vice 1485 versa. 1487 This textual convention SHOULD NOT be used directly in object 1488 definitions since it restricts addresses to a specific 1489 format. However, if it is used, it MAY be used either on its 1490 own or in conjunction with TransportAddressType or 1491 TransportDomain as a pair. 1493 When this textual convention is used as a syntax of an index 1494 object, there may be issues with the limit of 128 1495 sub-identifiers specified in SMIv2 (STD 58). It is RECOMMENDED 1496 that all MIB documents using this textual convention make 1497 explicit any limitations on index component lengths that 1498 management software must observe. This may be done either by 1499 including SIZE constraints on the index components or by 1500 specifying applicable constraints in the conceptual row 1501 DESCRIPTION clause or in the surrounding documentation." 1502 REFERENCE 1503 "RFC 1033: DOMAIN ADMINISTRATORS OPERATIONS GUIDE 1504 RFC 3490: Internationalizing Domain Names in Applications 1505 RFC 3986: Uniform Resource Identifier (URI): Generic Syntax 1506 RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 1507 " 1508 SYNTAX OCTET STRING (SIZE (1..255)) 1510 Fingerprint ::= TEXTUAL-CONVENTION 1511 DISPLAY-HINT "1x:254x" 1512 STATUS current 1513 DESCRIPTION 1514 "A Fingerprint value that can be used to uniquely reference 1515 other data of potentially arbitrary length. 1517 A Fingerprint value is composed of a 1-octet hashing algorithm 1518 identifier followed by the fingerprint value. The octet value 1519 encoded is taken from the IANA TLS HashAlgorithm Registry 1520 (RFC5246). The remaining octets are filled using the results 1521 of the hashing algorithm. 1523 This TEXTUAL-CONVENTION allows for a zero-length (blank) 1524 Fingerprint value for use in tables where the fingerprint value 1525 may be optional. MIB definitions or implementations may refuse 1526 to accept a zero-length value as appropriate." 1527 REFERENCE 1528 "RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 1529 " 1530 SYNTAX OCTET STRING (SIZE (0..255)) 1532 -- Identities 1534 tlstmCertToTSNMIdentities OBJECT IDENTIFIER ::= { tlstmIdentities 1 } 1536 tlstmCertSpecified OBJECT-IDENTITY 1537 STATUS current 1538 DESCRIPTION "Directly specifies the tmSecurityName to be used for 1539 this certificate. The value of the tmSecurityName to 1540 use is specified in the tlstmCertToTSNData column. 1541 The column must contain a SnmpAdminString compliant 1542 value or contains a zero length string then the 1543 mapping will be considered a failure." 1544 ::= { tlstmCertToTSNMIdentities 1 } 1546 tlstmCertSANRFC822Name OBJECT-IDENTITY 1547 STATUS current 1548 DESCRIPTION "Maps a subjectAltName's rfc822Name to a 1549 tmSecurityName. The local part of the rfc822Name is 1550 passed unaltered but the host-part of the name must 1551 be passed in lower case. 1553 Example rfc822Name Field: FooBar@Example.COM 1554 is mapped to tmSecurityName: FooBar@exmaple.com" 1555 ::= { tlstmCertToTSNMIdentities 2 } 1557 tlstmCertSANDNSName OBJECT-IDENTITY 1558 STATUS current 1559 DESCRIPTION "Maps a subjectAltName's dNSName to a 1560 tmSecurityName by directly passing the value without 1561 any transformations." 1563 ::= { tlstmCertToTSNMIdentities 3 } 1565 tlstmCertSANIpAddress OBJECT-IDENTITY 1566 STATUS current 1567 DESCRIPTION "Maps a subjectAltName's ipAddress to a 1568 tmSecurityName by transforming the binary encoded 1569 address as follows: 1571 1) for IPv4 the value is converted into a decimal 1572 dotted quad address (e.g. '192.0.2.1') 1574 2) for IPv6 addresses the value is converted into a 1575 32-character hexadecimal string without any colon 1576 separators. 1578 Note that the resulting length is the maximum 1579 length supported by the View-Based Access Control 1580 Model (VACM). Note that using both the Transport 1581 Security Model's support for transport prefixes 1582 (see the SNMP-TSM-MIB's 1583 snmpTsmConfigurationUsePrefix object for details) 1584 will result in securityName lengths that exceed 1585 what VACM can handle." 1586 ::= { tlstmCertToTSNMIdentities 4 } 1588 tlstmCertSANAny OBJECT-IDENTITY 1589 STATUS current 1590 DESCRIPTION "Maps any of the following fields using the 1591 corresponding mapping algorithms: 1593 |------------+------------------------| 1594 | Type | Algorithm | 1595 |------------+------------------------| 1596 | rfc822Name | tlstmCertSANRFC822Name | 1597 | dNSName | tlstmCertSANDNSName | 1598 | ipAddress | tlstmCertSANIpAddress | 1599 |------------+------------------------| 1601 The first matching subjectAltName value found in the 1602 certificate any of the above types MUST be used when 1603 deriving the tmSecurityName." 1604 ::= { tlstmCertToTSNMIdentities 5 } 1606 tlstmCertCommonName OBJECT-IDENTITY 1607 STATUS current 1608 DESCRIPTION "Maps a certificate's CommonName to a 1609 tmSecurityName by directly passing the value without 1610 any transformations." 1611 ::= { tlstmCertToTSNMIdentities 6 } 1613 -- The snmpTlstmSession Group 1615 snmpTlstmSession OBJECT IDENTIFIER ::= { tlstmObjects 1 } 1617 snmpTlstmSessionOpens OBJECT-TYPE 1618 SYNTAX Counter32 1619 MAX-ACCESS read-only 1620 STATUS current 1621 DESCRIPTION 1622 "The number of times an openSession() request has been 1623 executed as an (D)TLS client, whether it succeeded or failed." 1624 ::= { snmpTlstmSession 1 } 1626 snmpTlstmSessionCloses OBJECT-TYPE 1627 SYNTAX Counter32 1628 MAX-ACCESS read-only 1629 STATUS current 1630 DESCRIPTION 1631 "The number of times a closeSession() request has been 1632 executed as an (D)TLS client, whether it succeeded or failed." 1633 ::= { snmpTlstmSession 2 } 1635 snmpTlstmSessionOpenErrors OBJECT-TYPE 1636 SYNTAX Counter32 1637 MAX-ACCESS read-only 1638 STATUS current 1639 DESCRIPTION 1640 "The number of times an openSession() request failed to open a 1641 session as a (D)TLS client, for any reason." 1642 ::= { snmpTlstmSession 3 } 1644 snmpTlstmSessionNoSessions OBJECT-TYPE 1645 SYNTAX Counter32 1646 MAX-ACCESS read-only 1647 STATUS current 1648 DESCRIPTION 1649 "The number of times an outgoing message was dropped because 1650 the session associated with the passed tmStateReference was no 1651 longer (or was never) available." 1652 ::= { snmpTlstmSession 4 } 1654 snmpTlstmSessionInvalidClientCertificates OBJECT-TYPE 1655 SYNTAX Counter32 1656 MAX-ACCESS read-only 1657 STATUS current 1658 DESCRIPTION 1659 "The number of times an incoming session was not established 1660 on an (D)TLS server because the presented client certificate was 1661 invalid. Reasons for invalidation include, but are not 1662 limited to, cryptographic validation failures or lack of a 1663 suitable mapping row in the tlstmCertToTSNTable." 1664 ::= { snmpTlstmSession 5 } 1666 snmpTlstmSessionUnknownServerCertificate OBJECT-TYPE 1667 SYNTAX Counter32 1668 MAX-ACCESS read-only 1669 STATUS current 1670 DESCRIPTION 1671 "The number of times an outgoing session was not established 1672 on an (D)TLS client because the server certificate presented 1673 by a SNMP over (D)TLS server was invalid because no 1674 configured fingerprint or CA was acceptable to validate it. 1675 This may result because there was no entry in the 1676 tlstmAddrTable or because no path could be found to known 1677 certificate authority." 1678 ::= { snmpTlstmSession 6 } 1680 snmpTlstmSessionInvalidServerCertificates OBJECT-TYPE 1681 SYNTAX Counter32 1682 MAX-ACCESS read-only 1683 STATUS current 1684 DESCRIPTION 1685 "The number of times an outgoing session was not established 1686 on an (D)TLS client because the server certificate presented 1687 by an SNMP over (D)TLS server could not be validated even if 1688 the fingerprint or expected validation path was known. I.E., 1689 a cryptographic validation occurred during certificate 1690 validation processing. 1692 Reasons for invalidation include, but are not 1693 limited to, cryptographic validation failures." 1694 ::= { snmpTlstmSession 7 } 1696 snmpTlstmSessionInvalidCaches OBJECT-TYPE 1697 SYNTAX Counter32 1698 MAX-ACCESS read-only 1699 STATUS current 1700 DESCRIPTION 1701 "The number of outgoing messages dropped because the 1702 tmStateReference referred to an invalid cache." 1703 ::= { snmpTlstmSession 8 } 1705 tlstmTLSProtectionErrors OBJECT-TYPE 1706 SYNTAX Counter32 1707 MAX-ACCESS read-only 1708 STATUS current 1709 DESCRIPTION 1710 "The number of times (D)TLS processing resulted in a message 1711 being discarded because it failed its integrity test, 1712 decryption processing or other (D)TLS processing." 1713 ::= { snmpTlstmSession 9 } 1715 -- Configuration Objects 1717 tlstmConfig OBJECT IDENTIFIER ::= { tlstmObjects 2 } 1719 -- Certificate mapping 1721 tlstmCertificateMapping OBJECT IDENTIFIER ::= { tlstmConfig 1 } 1723 tlstmCertToTSNCount OBJECT-TYPE 1724 SYNTAX Unsigned32 1725 MAX-ACCESS read-only 1726 STATUS current 1727 DESCRIPTION 1728 "A count of the number of entries in the tlstmCertToTSNTable" 1729 ::= { tlstmCertificateMapping 1 } 1731 tlstmCertToTSNTableLastChanged OBJECT-TYPE 1732 SYNTAX TimeStamp 1733 MAX-ACCESS read-only 1734 STATUS current 1735 DESCRIPTION 1736 "The value of sysUpTime.0 when the tlstmCertToTSNTable 1737 was last modified through any means, or 0 if it has not been 1738 modified since the command responder was started." 1739 ::= { tlstmCertificateMapping 2 } 1741 tlstmCertToTSNTable OBJECT-TYPE 1742 SYNTAX SEQUENCE OF TlstmCertToTSNEntry 1743 MAX-ACCESS not-accessible 1744 STATUS current 1745 DESCRIPTION 1746 "A table listing the X.509 certificates known to the entity 1747 and the associated method for determining the SNMPv3 security 1748 name from a certificate. 1750 On an incoming (D)TLS/SNMP connection the client's presented 1751 certificate must be examined and validated based on an 1752 established trusted path from a CA certificate or self-signed 1753 public certificate (e.g. RFC5280). This table provides a 1754 mapping from a validated certificate to a tmSecurityName. 1755 This table does not provide any mechanisms for uploading 1756 trusted certificates; the transfer of any needed trusted 1757 certificates for path validation is expected to occur through 1758 an out-of-band transfer. 1760 Once the authenticity of a certificate has been verified, this 1761 table is consulted to determine the appropriate tmSecurityName 1762 to identify with the remote connection. This is done by 1763 considering each active row from this table in prioritized 1764 order according to its tlstmCertToTSNID value. Each row's 1765 tlstmCertToTSNFingerprint value determines whether the row is a 1766 match for the incoming connection: 1768 1) If the row's tlstmCertToTSNFingerprint value identifies 1769 the presented certificate then consider the row as a 1770 successful match. 1772 2) If the row's tlstmCertToTSNFingerprint value identifies 1773 a locally held copy of a trusted CA certificate and 1774 that CA certificated was used to validate the path to 1775 the presented certificate then consider the row as a 1776 successful match. 1778 Once a matching row has been found, the tlstmCertToTSNMapType 1779 value can be used to determine how the tmSecurityName to 1780 associate with the session should be determined. See the 1781 tlstmCertToTSNMapType column's DESCRIPTION for details on 1782 determining the tmSecurityName value. If it is impossible to 1783 determine a tmSecurityName from the row's data combined with the 1784 data presented in the certificate then additional rows MUST be 1785 searched looking for another potential match. If a resulting 1786 tmSecurityName mapped from a given row is not compatible with 1787 the needed requirements of a tmSecurityName (e.g., VACM imposes 1788 a 32-octet-maximum length and the certificate derived 1789 securityName could be longer) then it must be considered an 1790 invalid match and additional rows MUST be searched looking for 1791 another potential match. 1793 Missing values of tlstmCertToTSNID are acceptable and 1794 implementations should continue to the next highest numbered 1795 row. E.G., the table may legally contain only two rows with 1796 tlstmCertToTSNID values of 10 and 20. 1798 Users are encouraged to make use of certificates with 1799 subjectAltName fields that can be used as tmSecurityNames so 1800 that a single root CA certificate can allow all child 1801 certificate's subjectAltName to map directly to a tmSecurityName 1802 via a 1:1 transformation. However, this table is flexible to 1803 allow for situations where existing deployed certificate 1804 infrastructures do not provide adequate subjectAltName values 1805 for use as tmSecurityNames. Certificates may also be 1806 mapped to tmSecurityNames using the CommonName portion of the 1807 Subject field but usage of the CommonName field is deprecated. 1808 Direct mapping from each individual certificate fingerprint to 1809 a tmSecurityName is also possible but requires one entry in the 1810 table per tmSecurityName and requires more management operations 1811 to completely configure a device." 1812 ::= { tlstmCertificateMapping 3 } 1814 tlstmCertToTSNEntry OBJECT-TYPE 1815 SYNTAX TlstmCertToTSNEntry 1816 MAX-ACCESS not-accessible 1817 STATUS current 1818 DESCRIPTION 1819 "A row in the tlstmCertToTSNTable that specifies a mapping for 1820 an incoming (D)TLS certificate to a tmSecurityName to use for a 1821 connection." 1822 INDEX { tlstmCertToTSNID } 1823 ::= { tlstmCertToTSNTable 1 } 1825 TlstmCertToTSNEntry ::= SEQUENCE { 1826 tlstmCertToTSNID Unsigned32, 1827 tlstmCertToTSNFingerprint Fingerprint, 1828 tlstmCertToTSNMapType AutonomousType, 1829 tlstmCertToTSNData OCTET STRING, 1830 tlstmCertToTSNStorageType StorageType, 1831 tlstmCertToTSNRowStatus RowStatus 1832 } 1834 tlstmCertToTSNID OBJECT-TYPE 1835 SYNTAX Unsigned32 (1..4294967295) 1836 MAX-ACCESS not-accessible 1837 STATUS current 1838 DESCRIPTION 1839 "A unique, prioritized index for the given entry." 1840 ::= { tlstmCertToTSNEntry 1 } 1842 tlstmCertToTSNFingerprint OBJECT-TYPE 1843 SYNTAX Fingerprint (SIZE(1..255)) 1844 MAX-ACCESS read-create 1845 STATUS current 1846 DESCRIPTION 1847 "A cryptographic hash of a X.509 certificate. The results of 1848 a successful matching fingerprint to either the trusted CA in 1849 the certificate validation path or to the certificate itself 1850 is dictated by the tlstmCertToTSNMapType column." 1851 ::= { tlstmCertToTSNEntry 2 } 1853 tlstmCertToTSNMapType OBJECT-TYPE 1854 SYNTAX AutonomousType 1855 MAX-ACCESS read-create 1856 STATUS current 1857 DESCRIPTION 1858 "Specifies the mapping type for deriving a tmSecurityName from a 1859 certificate. Details for mapping of a particular type SHALL 1860 be specified in the DESCRIPTION clause of the OBJECT-IDENTITY 1861 that describes the mapping. If a mapping succeeds it will 1862 return a tmSecurityName for use by the TLSTM model and 1863 processing stops. 1865 If the resulting mapped value is not compatible with the 1866 needed requirements of a tmSecurityName (e.g., VACM imposes a 1867 32-octet-maximum length and the certificate derived 1868 securityName could be longer) then future rows MUST be 1869 searched for additional tlstmCertToTSNFingerprint matches to 1870 look for a mapping that succeeds." 1871 DEFVAL { tlstmCertSpecified } 1872 ::= { tlstmCertToTSNEntry 3 } 1874 tlstmCertToTSNData OBJECT-TYPE 1875 SYNTAX OCTET STRING (SIZE(0..1024)) 1876 MAX-ACCESS read-create 1877 STATUS current 1878 DESCRIPTION 1879 "Axillary data used as optional configuration information for 1880 a given mapping specified by the tlstmCertToTSNMapType column. 1881 Only some mapping systems will make use of this column. The 1882 value in this column MUST be ignored for any mapping type that 1883 does not require data present in this column." 1884 DEFVAL { "" } 1885 ::= { tlstmCertToTSNEntry 4 } 1887 tlstmCertToTSNStorageType OBJECT-TYPE 1888 SYNTAX StorageType 1889 MAX-ACCESS read-create 1890 STATUS current 1891 DESCRIPTION 1892 "The storage type for this conceptual row. Conceptual rows 1893 having the value 'permanent' need not allow write-access to 1894 any columnar objects in the row." 1895 DEFVAL { nonVolatile } 1896 ::= { tlstmCertToTSNEntry 5 } 1898 tlstmCertToTSNRowStatus OBJECT-TYPE 1899 SYNTAX RowStatus 1900 MAX-ACCESS read-create 1901 STATUS current 1902 DESCRIPTION 1903 "The status of this conceptual row. This object may be used 1904 to create or remove rows from this table. 1906 To create a row in this table, a manager must set this object 1907 to either createAndGo(4) or createAndWait(5). 1909 Until instances of all corresponding columns are appropriately 1910 configured, the value of the corresponding instance of the 1911 tlstmParamsRowStatus column is 'notReady'. 1913 In particular, a newly created row cannot be made active until 1914 the corresponding tlstmCertToTSNFingerprint, 1915 tlstmCertToTSNMapType, and tlstmCertToTSNData columns have been 1916 set. 1918 The following objects may not be modified while the 1919 value of this object is active(1): 1920 - tlstmCertToTSNFingerprint 1921 - tlstmCertToTSNMapType 1922 - tlstmCertToTSNData 1923 An attempt to set these objects while the value of 1924 tlstmParamsRowStatus is active(1) will result in 1925 an inconsistentValue error." 1926 ::= { tlstmCertToTSNEntry 6 } 1928 -- Maps tmSecurityNames to certificates for use by the SNMP-TARGET-MIB 1930 tlstmParamsCount OBJECT-TYPE 1931 SYNTAX Unsigned32 1932 MAX-ACCESS read-only 1933 STATUS current 1934 DESCRIPTION 1935 "A count of the number of entries in the tlstmParamsTable" 1936 ::= { tlstmCertificateMapping 4 } 1938 tlstmParamsTableLastChanged OBJECT-TYPE 1939 SYNTAX TimeStamp 1940 MAX-ACCESS read-only 1941 STATUS current 1942 DESCRIPTION 1943 "The value of sysUpTime.0 when the tlstmParamsTable 1944 was last modified through any means, or 0 if it has not been 1945 modified since the command responder was started." 1947 ::= { tlstmCertificateMapping 5 } 1949 tlstmParamsTable OBJECT-TYPE 1950 SYNTAX SEQUENCE OF TlstmParamsEntry 1951 MAX-ACCESS not-accessible 1952 STATUS current 1953 DESCRIPTION 1954 "This table extends the SNMP-TARGET-MIB's 1955 snmpTargetParamsTable with an additional (D)TLS client-side 1956 certificate fingerprint identifier to use when establishing 1957 new (D)TLS connections." 1958 ::= { tlstmCertificateMapping 6 } 1960 tlstmParamsEntry OBJECT-TYPE 1961 SYNTAX TlstmParamsEntry 1962 MAX-ACCESS not-accessible 1963 STATUS current 1964 DESCRIPTION 1965 "A conceptual row containing a fingerprint hash of a locally 1966 held certificate for a given snmpTargetParamsEntry. The 1967 values in this row should be ignored if the connection that 1968 needs to be established, as indicated by the SNMP-TARGET-MIB 1969 infrastructure, is not a certificate and (D)TLS based 1970 connection. The connection SHOULD NOT be established if the 1971 certificate fingerprint stored in this entry does not point to 1972 a valid locally held certificate or if it points to an unusable 1973 certificate (such as might happen when the certificate's 1974 expiration date has been reached)." 1975 INDEX { IMPLIED snmpTargetParamsName } 1976 ::= { tlstmParamsTable 1 } 1978 TlstmParamsEntry ::= SEQUENCE { 1979 tlstmParamsClientFingerprint Fingerprint, 1980 tlstmParamsStorageType StorageType, 1981 tlstmParamsRowStatus RowStatus 1982 } 1984 tlstmParamsClientFingerprint OBJECT-TYPE 1985 SYNTAX Fingerprint 1986 MAX-ACCESS read-create 1987 STATUS current 1988 DESCRIPTION 1989 "A cryptographic hash of a X.509 certificate. This object 1990 should store the hash of a locally held X.509 certificate that 1991 should be used when initiating a (D)TLS connection as a (D)TLS 1992 client." 1993 ::= { tlstmParamsEntry 1 } 1995 tlstmParamsStorageType OBJECT-TYPE 1996 SYNTAX StorageType 1997 MAX-ACCESS read-create 1998 STATUS current 1999 DESCRIPTION 2000 "The storage type for this conceptual row. Conceptual rows 2001 having the value 'permanent' need not allow write-access to 2002 any columnar objects in the row." 2003 DEFVAL { nonVolatile } 2004 ::= { tlstmParamsEntry 2 } 2006 tlstmParamsRowStatus OBJECT-TYPE 2007 SYNTAX RowStatus 2008 MAX-ACCESS read-create 2009 STATUS current 2010 DESCRIPTION 2011 "The status of this conceptual row. This object may be used 2012 to create or remove rows from this table. 2014 To create a row in this table, a manager must set this object 2015 to either createAndGo(4) or createAndWait(5). 2017 Until instances of all corresponding columns are appropriately 2018 configured, the value of the corresponding instance of the 2019 tlstmParamsRowStatus column is 'notReady'. 2021 In particular, a newly created row cannot be made active until 2022 the corresponding tlstmParamsClientFingerprint column has 2023 been set. 2025 The tlstmParamsClientFingerprint object may not be modified 2026 while the value of this object is active(1). 2028 An attempt to set these objects while the value of 2029 tlstmParamsRowStatus is active(1) will result in 2030 an inconsistentValue error." 2031 ::= { tlstmParamsEntry 3 } 2033 -- Lists expected certificate fingerprints to be presented by a DTLS 2034 -- server 2036 tlstmAddrCount OBJECT-TYPE 2037 SYNTAX Unsigned32 2038 MAX-ACCESS read-only 2039 STATUS current 2040 DESCRIPTION 2041 "A count of the number of entries in the tlstmAddrTable" 2043 ::= { tlstmCertificateMapping 7 } 2045 tlstmAddrTableLastChanged OBJECT-TYPE 2046 SYNTAX TimeStamp 2047 MAX-ACCESS read-only 2048 STATUS current 2049 DESCRIPTION 2050 "The value of sysUpTime.0 when the tlstmAddrTable 2051 was last modified through any means, or 0 if it has not been 2052 modified since the command responder was started." 2053 ::= { tlstmCertificateMapping 8 } 2055 tlstmAddrTable OBJECT-TYPE 2056 SYNTAX SEQUENCE OF TlstmAddrEntry 2057 MAX-ACCESS not-accessible 2058 STATUS current 2059 DESCRIPTION 2060 "This table extends the SNMP-TARGET-MIB's snmpTargetAddrTable 2061 with an expected (D)TLS server-side certificate identifier to 2062 expect when establishing a new (D)TLS connections. If a 2063 matching row in this table exists and the row is active then 2064 the fingerprint identifier from the tlstmAddrServerFingerprint 2065 columnshould be compared against the fingerprint of the 2066 certificate being presented by the server. If the fingerprint 2067 of the certificate presented by the server does not match the 2068 tlstmAddrServerFingerprint column's value then the connection 2069 MUST NOT be established. 2071 If a matching row exists with a zero-length 2072 tlstmAddrServerFingerprint value and the certificate can still 2073 be validated through another certificate validation path 2074 (e.g. RFC5280) then the server's presented identity should be 2075 checked against the value of the tlstmAddrServerIdentity 2076 column. If the server's identity does not match the reference 2077 identity found in the tlstmAddrServerIdentity column then the 2078 connection MUST NOT be established. A tlstmAddrServerIdentity 2079 may contain a '*' to match any server's identity or may 2080 contain a '*.' prefix to match any server identity from a 2081 given domain (e.g. '*.example.com'). 2083 If no matching row exists in this table then the connection 2084 SHOULD still proceed if another certificate validation path 2085 algorithm (e.g. RFC5280) can be followed to a configured trust 2086 anchor." 2087 ::= { tlstmCertificateMapping 9 } 2089 tlstmAddrEntry OBJECT-TYPE 2090 SYNTAX TlstmAddrEntry 2091 MAX-ACCESS not-accessible 2092 STATUS current 2093 DESCRIPTION 2094 "A conceptual row containing a copy of a certificate's 2095 fingerprint for a given snmpTargetAddrEntry. The values in 2096 this row should be ignored if the connection that needs to be 2097 established, as indicated by the SNMP-TARGET-MIB 2098 infrastructure, is not a (D)TLS based connection. If an 2099 tlstmAddrEntry exists for a given snmpTargetAddrEntry then the 2100 presented server certificate MUST match or the connection MUST 2101 NOT be established. If a row in this table does not exist to 2102 match a snmpTargetAddrEntry row then the connection SHOULD 2103 still proceed if some other certificate validation path 2104 algorithm (e.g. RFC5280) can be followed to a configured trust 2105 anchor." 2106 INDEX { IMPLIED snmpTargetAddrName } 2107 ::= { tlstmAddrTable 1 } 2109 TlstmAddrEntry ::= SEQUENCE { 2110 tlstmAddrServerFingerprint Fingerprint, 2111 tlstmAddrServerIdentity SnmpAdminString, 2112 tlstmAddrStorageType StorageType, 2113 tlstmAddrRowStatus RowStatus 2114 } 2116 tlstmAddrServerFingerprint OBJECT-TYPE 2117 SYNTAX Fingerprint 2118 MAX-ACCESS read-create 2119 STATUS current 2120 DESCRIPTION 2121 "A cryptographic hash of a public X.509 certificate. This 2122 object should store the hash of the public X.509 certificate 2123 that the remote server should present during the (D)TLS 2124 connection setup. The fingerprint of the presented 2125 certificate and this hash value MUST match exactly or the 2126 connection MUST NOT be established." 2127 DEFVAL { "" } 2128 ::= { tlstmAddrEntry 1 } 2130 tlstmAddrServerIdentity OBJECT-TYPE 2131 SYNTAX SnmpAdminString 2132 MAX-ACCESS read-create 2133 STATUS current 2134 DESCRIPTION 2135 "The reference identity to check against the identity 2136 presented by the remote system. A single ASCII '*' character 2137 (ASCII code 0x2a) may be used as a wildcard string and will 2138 match any presented server identity. A '*.' prefix may also 2139 be used to match any identity within a given domain 2140 (e.g. '*.example.com' will match both 'foo.example.com' and 2141 'bar.example.com')." 2142 REFERENCE "draft-saintandre-tls-server-id-check" 2143 DEFVAL { "*" } 2144 ::= { tlstmAddrEntry 2 } 2146 tlstmAddrStorageType OBJECT-TYPE 2147 SYNTAX StorageType 2148 MAX-ACCESS read-create 2149 STATUS current 2150 DESCRIPTION 2151 "The storage type for this conceptual row. Conceptual rows 2152 having the value 'permanent' need not allow write-access to 2153 any columnar objects in the row." 2154 DEFVAL { nonVolatile } 2155 ::= { tlstmAddrEntry 3 } 2157 tlstmAddrRowStatus OBJECT-TYPE 2158 SYNTAX RowStatus 2159 MAX-ACCESS read-create 2160 STATUS current 2161 DESCRIPTION 2162 "The status of this conceptual row. This object may be used 2163 to create or remove rows from this table. 2165 To create a row in this table, a manager must 2166 set this object to either createAndGo(4) or 2167 createAndWait(5). 2169 Until instances of all corresponding columns are 2170 appropriately configured, the value of the 2171 corresponding instance of the tlstmAddrRowStatus 2172 column is 'notReady'. 2174 In particular, a newly created row cannot be made active until 2175 the corresponding tlstmAddrServerFingerprint column has been 2176 set. 2178 The tlstmAddrServerFingerprint object may not be modified 2179 while the value of this object is active(1). 2181 An attempt to set these objects while the value of 2182 tlstmAddrRowStatus is active(1) will result in 2183 an inconsistentValue error." 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 } 2230 -- ************************************************ 2231 -- Compliance statements 2232 -- ************************************************ 2234 tlstmCompliance MODULE-COMPLIANCE 2235 STATUS current 2236 DESCRIPTION 2237 "The compliance statement for SNMP engines that support the 2238 TLSTM-MIB" 2239 MODULE 2240 MANDATORY-GROUPS { tlstmStatsGroup, 2241 tlstmIncomingGroup, 2242 tlstmOutgoingGroup, 2243 tlstmNotificationGroup } 2244 ::= { tlstmCompliances 1 } 2246 -- ************************************************ 2247 -- Units of conformance 2248 -- ************************************************ 2249 tlstmStatsGroup OBJECT-GROUP 2250 OBJECTS { 2251 snmpTlstmSessionOpens, 2252 snmpTlstmSessionCloses, 2253 snmpTlstmSessionOpenErrors, 2254 snmpTlstmSessionNoSessions, 2255 snmpTlstmSessionInvalidClientCertificates, 2256 snmpTlstmSessionUnknownServerCertificate, 2257 snmpTlstmSessionInvalidServerCertificates, 2258 snmpTlstmSessionInvalidCaches, 2259 tlstmTLSProtectionErrors 2260 } 2261 STATUS current 2262 DESCRIPTION 2263 "A collection of objects for maintaining 2264 statistical information of an SNMP engine which 2265 implements the SNMP TLS Transport Model." 2266 ::= { tlstmGroups 1 } 2268 tlstmIncomingGroup OBJECT-GROUP 2269 OBJECTS { 2270 tlstmCertToTSNCount, 2271 tlstmCertToTSNTableLastChanged, 2272 tlstmCertToTSNFingerprint, 2273 tlstmCertToTSNMapType, 2274 tlstmCertToTSNData, 2275 tlstmCertToTSNStorageType, 2276 tlstmCertToTSNRowStatus 2277 } 2278 STATUS current 2279 DESCRIPTION 2280 "A collection of objects for maintaining 2281 incoming connection certificate mappings to 2282 tmSecurityNames of an SNMP engine which implements the 2283 SNMP TLS Transport Model." 2284 ::= { tlstmGroups 2 } 2286 tlstmOutgoingGroup OBJECT-GROUP 2287 OBJECTS { 2288 tlstmParamsCount, 2289 tlstmParamsTableLastChanged, 2290 tlstmParamsClientFingerprint, 2291 tlstmParamsStorageType, 2292 tlstmParamsRowStatus, 2293 tlstmAddrCount, 2294 tlstmAddrTableLastChanged, 2295 tlstmAddrServerFingerprint, 2296 tlstmAddrServerIdentity, 2297 tlstmAddrStorageType, 2298 tlstmAddrRowStatus 2299 } 2300 STATUS current 2301 DESCRIPTION 2302 "A collection of objects for maintaining 2303 outgoing connection certificates to use when opening 2304 connections as a result of SNMP-TARGET-MIB settings." 2305 ::= { tlstmGroups 3 } 2307 tlstmNotificationGroup NOTIFICATION-GROUP 2308 NOTIFICATIONS { 2309 tlstmServerCertificateUnknown, 2310 tlstmServerInvalidCertificate 2311 } 2312 STATUS current 2313 DESCRIPTION 2314 "Notifications" 2315 ::= { tlstmGroups 4 } 2317 END 2319 8. Operational Considerations 2321 This section discusses various operational aspects of deploying 2322 TLSTM. 2324 8.1. Sessions 2326 A session is discussed throughout this document as meaning a security 2327 association between the (D)TLS client and the (D)TLS server. State 2328 information for the sessions are maintained in each TLSTM 2329 implementation and this information is created and destroyed as 2330 sessions are opened and closed. A "broken" session (one side up and 2331 one side down) can result if one side of a session is brought down 2332 abruptly (i.e., reboot, power outage, etc.). Whenever possible, 2333 implementations SHOULD provide graceful session termination through 2334 the use of disconnect messages. Implementations SHOULD also have a 2335 system in place for detecting "broken" sessions through the use of 2336 heartbeats [I-D.seggelmann-tls-dtls-heartbeat] or other detection 2337 mechanisms. 2339 Implementations SHOULD limit the lifetime of established sessions 2340 depending on the algorithms used for generation of the master session 2341 secret, the privacy and integrity algorithms used to protect 2342 messages, the environment of the session, the amount of data 2343 transferred, and the sensitivity of the data. 2345 8.2. Notification Receiver Credential Selection 2347 When an SNMP engine needs to establish an outgoing session for 2348 notifications, the snmpTargetParamsTable includes an entry for the 2349 snmpTargetParamsSecurityName of the target. Servers that wish to 2350 support multiple principals at a particular port SHOULD make use of 2351 the Server Name Indication extension defined in Section 3.1 of 2352 [RFC4366]. Without the Server Name Indication the receiving SNMP 2353 engine (Server) will not know which (D)TLS certificate to offer to 2354 the Client so that the tmSecurityName identity-authentication will be 2355 successful. 2357 Another solution is to maintain a one-to-one mapping between 2358 certificates and incoming ports for notification receivers. This can 2359 be handled at the notification originator by configuring the 2360 snmpTargetAddrTable (snmpTargetAddrTDomain and 2361 snmpTargetAddrTAddress) and requiring the receiving SNMP engine to 2362 monitor multiple incoming static ports based on which principals are 2363 capable of receiving notifications. 2365 Implementations MAY also choose to designate a single Notification 2366 Receiver Principal to receive all incoming notifications or select an 2367 implementation specific method of selecting a server certificate to 2368 present to clients. 2370 8.3. contextEngineID Discovery 2372 Most command responders have contextEngineIDs that are identical to 2373 the USM securityEngineID. USM provides a discovery service that 2374 allows command generators to determine a securityEngineID and thus a 2375 default contextEngineID to use. Because the TLS Transport Model does 2376 not make use of a securityEngineID, it may be difficult for command 2377 generators to discover a suitable default contextEngineID. 2378 Implementations should consider offering another engineID discovery 2379 mechanism to continue providing Command Generators with a suitable 2380 contextEngineID mechanism. A recommended discovery solution is 2381 documented in [RFC5343]. 2383 8.4. Transport Considerations 2385 This document defines how SNMP messages can be transmitted over the 2386 TLS and DTLS based protocols. Each of these protocols are 2387 additionally based on other transports (TCP, UDP and SCTP). These 2388 three protocols also have operational considerations that must be 2389 taken into consideration when selecting a (D)TLS based protocol to 2390 use such as its performance in degraded or limited networks. It is 2391 beyond the scope of this document to summarize the characteristics of 2392 these transport mechanisms. Please refer to the base protocol 2393 documents for details on messaging considerations with respect to MTU 2394 size, fragmentation, performance in lossy-networks, etc. 2396 9. Security Considerations 2398 This document describes a transport model that permits SNMP to 2399 utilize (D)TLS security services. The security threats and how the 2400 (D)TLS transport model mitigates these threats are covered in detail 2401 throughout this document. Security considerations for DTLS are 2402 covered in [RFC4347] and security considerations for TLS are 2403 described in Section 11 and Appendices D, E, and F of TLS 1.2 2404 [RFC5246]. DTLS adds to the security considerations of TLS only 2405 because it is more vulnerable to denial of service attacks. A random 2406 cookie exchange was added to the handshake to prevent anonymous 2407 denial of service attacks. RFC 4347 recommends that the cookie 2408 exchange is utilized for all handshakes and therefore this 2409 specification also RECOMMENDEDs that implementers also support this 2410 cookie exchange. 2412 9.1. Certificates, Authentication, and Authorization 2414 Implementations are responsible for providing a security certificate 2415 installation and configuration mechanism. Implementations SHOULD 2416 support certificate revocation lists. 2418 (D)TLS provides for authentication of the identity of both the (D)TLS 2419 server and the (D)TLS client. Access to MIB objects for the 2420 authenticated principal MUST be enforced by an access control 2421 subsystem (e.g. the VACM). 2423 Authentication of the command generator principal's identity is 2424 important for use with the SNMP access control subsystem to ensure 2425 that only authorized principals have access to potentially sensitive 2426 data. The authenticated identity of the command generator 2427 principal's certificate is mapped to an SNMP model-independent 2428 securityName for use with SNMP access control. 2430 The (D)TLS handshake only provides assurance that the certificate of 2431 the authenticated identity has been signed by an configured accepted 2432 Certificate Authority. (D)TLS has no way to further authorize or 2433 reject access based on the authenticated identity. An Access Control 2434 Model (such as the VACM) provides access control and authorization of 2435 a command generator's requests to a command responder and a 2436 notification responder's authorization to receive Notifications from 2437 a notification originator. However to avoid man-in-the-middle 2438 attacks both ends of the (D)TLS based connection MUST check the 2439 certificate presented by the other side against what was expected. 2440 For example, command generators must check that the command responder 2441 presented and authenticated itself with a X.509 certificate that was 2442 expected. Not doing so would allow an impostor, at a minimum, to 2443 present false data, receive sensitive information and/or provide a 2444 false belief that configuration was actually received and acted upon. 2445 Authenticating and verifying the identity of the (D)TLS server and 2446 the (D)TLS client for all operations ensures the authenticity of the 2447 SNMP engine that provides MIB data. 2449 The instructions found in the DESCRIPTION clause of the 2450 tlstmCertToTSNTable object must be followed exactly. It is also 2451 important that the rows of the table be searched in prioritized order 2452 starting with the row containing the lowest numbered tlstmCertToTSNID 2453 value. 2455 9.2. Use with SNMPv1/SNMPv2c Messages 2457 The SNMPv1 and SNMPv2c message processing described in [RFC3584] (BCP 2458 74) always selects the SNMPv1 or SNMPv2c Security Models, 2459 respectively. Both of these and the User-based Security Model 2460 typically used with SNMPv3 derive the securityName and securityLevel 2461 from the SNMP message received, even when the message was received 2462 over a secure transport. Access control decisions are therefore made 2463 based on the contents of the SNMP message, rather than using the 2464 authenticated identity and securityLevel provided by the TLS 2465 Transport Model. 2467 9.3. MIB Module Security 2469 There are a number of management objects defined in this MIB module 2470 with a MAX-ACCESS clause of read-write and/or read-create. Such 2471 objects may be considered sensitive or vulnerable in some network 2472 environments. The support for SET operations in a non-secure 2473 environment without proper protection can have a negative effect on 2474 network operations. These are the tables and objects and their 2475 sensitivity/vulnerability: 2477 o The tlstmParamsTable can be used to change the outgoing X.509 2478 certificate used to establish a (D)TLS connection. Modification 2479 to objects in this table need to be adequately authenticated since 2480 modification to values in this table will have profound impacts to 2481 the security of outbound connections from the device. Since 2482 knowledge of authorization rules and certificate usage mechanisms 2483 may be considered sensitive, protection from disclosure of the 2484 SNMP traffic via encryption is also highly recommended. 2486 o The tlstmAddrTable can be used to change the expectations of the 2487 certificates presented by a remote (D)TLS server. Modification to 2488 objects in this table need to be adequately authenticated since 2489 modification to values in this table will have profound impacts to 2490 the security of outbound connections from the device. Since 2491 knowledge of authorization rules and certificate usage mechanisms 2492 may be considered sensitive, protection from disclosure of the 2493 SNMP traffic via encryption is also highly recommended. 2495 o The tlstmCertToTSNTable is used to specify the mapping of incoming 2496 X.509 certificates to tmSecurityNames which eventually get mapped 2497 to a SNMPv3 securityName. Modification to objects in this table 2498 need to be adequately authenticated since modification to values 2499 in this table will have profound impacts to the security of 2500 incoming connections to the device. Since knowledge of 2501 authorization rules and certificate usage mechanisms may be 2502 considered sensitive, protection from disclosure of the SNMP 2503 traffic via encryption is also highly recommended. 2505 Some of the readable objects in this MIB module (i.e., objects with a 2506 MAX-ACCESS other than not-accessible) may be considered sensitive or 2507 vulnerable in some network environments. It is thus important to 2508 control even GET and/or NOTIFY access to these objects and possibly 2509 to even encrypt the values of these objects when sending them over 2510 the network via SNMP. These are the tables and objects and their 2511 sensitivity/vulnerability: 2513 o This MIB contains a collection of counters that monitor the (D)TLS 2514 connections being established with a device. Since knowledge of 2515 connection and certificate usage mechanisms may be considered 2516 sensitive, protection from disclosure of the SNMP traffic via 2517 encryption is also highly recommended. 2519 SNMP versions prior to SNMPv3 did not include adequate security. 2520 Even if the network itself is secure (for example by using IPsec), 2521 even then, there is no control as to who on the secure network is 2522 allowed to access and GET/SET (read/change/create/delete) the objects 2523 in this MIB module. 2525 It is RECOMMENDED that implementers consider the security features as 2526 provided by the SNMPv3 framework (see [RFC3410], section 8), 2527 including full support for the SNMPv3 cryptographic mechanisms (for 2528 authentication and privacy). 2530 Further, deployment of SNMP versions prior to SNMPv3 is NOT 2531 RECOMMENDED. Instead, it is RECOMMENDED to deploy SNMPv3 and to 2532 enable cryptographic security. It is then a customer/operator 2533 responsibility to ensure that the SNMP entity giving access to an 2534 instance of this MIB module is properly configured to give access to 2535 the objects only to those principals (users) that have legitimate 2536 rights to indeed GET or SET (change/create/delete) them. 2538 10. IANA Considerations 2540 IANA is requested to assign: 2542 1. 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 command messages over a 2545 TLS Transport Model as defined in this document, 2547 2. a TCP 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 notification messages 2550 over a TLS Transport Model as defined in this document, 2552 3. 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 command messages over a 2555 DTLS/UDP connection as defined in this document, 2557 4. a UDP 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 notification messages 2560 over a DTLS/UDP connection as defined in this document, 2562 5. 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 command messages over a 2565 DTLS/SCTP connection as defined in this document, 2567 6. a SCTP port number above 1023 in the 2568 http://www.iana.org/assignments/port-numbers registry which will 2569 be the default port for receipt of SNMP notification messages 2570 over a DTLS/SCTP connection as defined in this document, 2572 7. an SMI number under snmpDomains for the snmpTLSTCPDomain object 2573 identifier, 2575 8. an SMI number under snmpDomains for the snmpDTLSUDPDomain object 2576 identifier, 2578 9. an SMI number under snmpDomains for the snmpDTLSSCTPDomain 2579 object identifier, 2581 10. a SMI number under snmpModules, for the MIB module in this 2582 document, 2584 11. "tls" as the corresponding prefix for the snmpTLSTCPDomain in 2585 the SNMP Transport Model registry, 2587 12. "dudp" as the corresponding prefix for the snmpDTLSUDPDomain in 2588 the SNMP Transport Model registry, 2590 13. "dsct" as the corresponding prefix for the snmpDTLSSCTPDomain in 2591 the SNMP Transport Model registry; 2593 If possible, IANA is requested to use matching port numbers for all 2594 assignments for SNMP Commands being sent over TLS, DTLS/UDP, DTLS/ 2595 SCTP. 2597 If possible, IANA is requested to use matching port numbers for all 2598 assignments for SNMP Notifications being sent over TLS, DTLS/UDP, 2599 DTLS/SCTP. 2601 Editor's note: this section should be replaced with appropriate 2602 descriptive assignment text after IANA assignments are made and prior 2603 to publication. 2605 11. Acknowledgements 2607 This document closely follows and copies the Secure Shell Transport 2608 Model for SNMP defined by David Harrington and Joseph Salowey in 2610 [RFC5292]. 2612 This document was reviewed by the following people who helped provide 2613 useful comments (in alphabetical order): Andy Donati, Pasi Eronen, 2614 David Harrington, Jeffrey Hutzelman, Alan Luchuk, Tom Petch, Randy 2615 Presuhn, Ray Purvis, Joseph Salowey, Jurgen Schonwalder, Dave Shield. 2617 This work was supported in part by the United States Department of 2618 Defense. Large portions of this document are based on work by 2619 General Dynamics C4 Systems and the following individuals: Brian 2620 Baril, Kim Bryant, Dana Deluca, Dan Hanson, Tim Huemiller, John 2621 Holzhauer, Colin Hoogeboom, Dave Kornbau, Chris Knaian, Dan Knaul, 2622 Charles Limoges, Steve Moccaldi, Gerardo Orlando, and Brandon Yip. 2624 12. References 2626 12.1. Normative References 2628 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2629 Requirement Levels", BCP 14, RFC 2119, March 1997. 2631 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2632 Schoenwaelder, Ed., "Structure of Management Information 2633 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 2635 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2636 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 2637 STD 58, RFC 2579, April 1999. 2639 [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 2640 "Conformance Statements for SMIv2", STD 58, RFC 2580, 2641 April 1999. 2643 [RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An 2644 Architecture for Describing Simple Network Management 2645 Protocol (SNMP) Management Frameworks", STD 62, RFC 3411, 2646 December 2002. 2648 [RFC3413] Levi, D., Meyer, P., and B. Stewart, "Simple Network 2649 Management Protocol (SNMP) Applications", STD 62, 2650 RFC 3413, December 2002. 2652 [RFC3414] Blumenthal, U. and B. Wijnen, "User-based Security Model 2653 (USM) for version 3 of the Simple Network Management 2654 Protocol (SNMPv3)", STD 62, RFC 3414, December 2002. 2656 [RFC3415] Wijnen, B., Presuhn, R., and K. McCloghrie, "View-based 2657 Access Control Model (VACM) for the Simple Network 2658 Management Protocol (SNMP)", STD 62, RFC 3415, 2659 December 2002. 2661 [RFC3418] Presuhn, R., "Management Information Base (MIB) for the 2662 Simple Network Management Protocol (SNMP)", STD 62, 2663 RFC 3418, December 2002. 2665 [RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen, 2666 "Coexistence between Version 1, Version 2, and Version 3 2667 of the Internet-standard Network Management Framework", 2668 BCP 74, RFC 3584, August 2003. 2670 [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2671 Security", RFC 4347, April 2006. 2673 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2674 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2676 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2677 Housley, R., and W. Polk, "Internet X.509 Public Key 2678 Infrastructure Certificate and Certificate Revocation List 2679 (CRL) Profile", RFC 5280, May 2008. 2681 [RFC5590] Harrington, D. and J. Schoenwaelder, "Transport Subsystem 2682 for the Simple Network Management Protocol (SNMP)", 2683 RFC 5590, June 2009. 2685 [RFC5591] Harrington, D. and W. Hardaker, "Transport Security Model 2686 for the Simple Network Management Protocol (SNMP)", 2687 RFC 5591, June 2009. 2689 12.2. Informative References 2691 [RFC2522] Karn, P. and W. Simpson, "Photuris: Session-Key Management 2692 Protocol", RFC 2522, March 1999. 2694 [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, 2695 "Introduction and Applicability Statements for Internet- 2696 Standard Management Framework", RFC 3410, December 2002. 2698 [RFC4306] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", 2699 RFC 4306, December 2005. 2701 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 2702 and T. Wright, "Transport Layer Security (TLS) 2703 Extensions", RFC 4366, April 2006. 2705 [RFC5292] Chen, E. and S. Sangli, "Address-Prefix-Based Outbound 2706 Route Filter for BGP-4", RFC 5292, August 2008. 2708 [RFC5343] Schoenwaelder, J., "Simple Network Management Protocol 2709 (SNMP) Context EngineID Discovery", RFC 5343, 2710 September 2008. 2712 [I-D.saintandre-tls-server-id-check] 2713 Saint-Andre, P., Zeilenga, K., Hodges, J., and B. Morgan, 2714 "Best Practices for Checking of Server Identities in the 2715 Context of Transport Layer Security (TLS)". 2717 [I-D.seggelmann-tls-dtls-heartbeat] 2718 Seggelmann, R., Tuexen, M., and M. Williams, "Transport 2719 Layer Security and Datagram Transport Layer Security 2720 Heartbeat Extension". 2722 [AES] National Institute of Standards, "Specification for the 2723 Advanced Encryption Standard (AES)". 2725 [DES] National Institute of Standards, "American National 2726 Standard for Information Systems-Data Link Encryption". 2728 [DSS] National Institute of Standards, "Digital Signature 2729 Standard". 2731 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 2732 Obtaining Digital Signatures and Public-Key 2733 Cryptosystems". 2735 [X509] , ITU., "INFORMATION TECHNOLOGY OPEN SYSTEMS 2736 INTERCONNECTION THE DIRECTORY: PUBLIC-KEY AND ATTRIBUTE 2737 CERTIFICATE FRAMEWORKS". 2739 Appendix A. (D)TLS Overview 2741 The (D)TLS protocol is composed of two layers: the (D)TLS Record 2742 Protocol and the (D)TLS Handshake Protocol. The following 2743 subsections provide an overview of these two layers. Please refer to 2744 [RFC4347] for a complete description of the protocol. 2746 A.1. The (D)TLS Record Protocol 2748 At the lowest layer, layered on top of the transport control protocol 2749 or a datagram transport protocol (e.g. UDP or SCTP) is the (D)TLS 2750 Record Protocol. 2752 The (D)TLS Record Protocol provides security that has three basic 2753 properties: 2755 o The session can be confidential. Symmetric cryptography is used 2756 for data encryption (e.g., [AES], [DES] etc.). The keys for this 2757 symmetric encryption are generated uniquely for each session and 2758 are based on a secret negotiated by another protocol (such as the 2759 (D)TLS Handshake Protocol). The Record Protocol can also be used 2760 without encryption. 2762 o Messages can have data integrity. Message transport includes a 2763 message integrity check using a keyed MAC. Secure hash functions 2764 (e.g., SHA, MD5, etc.) are used for MAC computations. The Record 2765 Protocol can operate without a MAC, but is generally only used in 2766 this mode while another protocol is using the Record Protocol as a 2767 transport for negotiating security parameters. 2769 o Messages are protected against replay. (D)TLS uses explicit 2770 sequence numbers and integrity checks. DTLS uses a sliding window 2771 to protect against replay of messages within a session. 2773 (D)TLS also provides protection against replay of entire sessions. 2774 In a properly-implemented keying material exchange, both sides will 2775 generate new random numbers for each exchange. This results in 2776 different encryption and integrity keys for every session. 2778 A.2. The (D)TLS Handshake Protocol 2780 The (D)TLS Record Protocol is used for encapsulation of various 2781 higher-level protocols. One such encapsulated protocol, the (D)TLS 2782 Handshake Protocol, allows the server and client to authenticate each 2783 other and to negotiate an integrity algorithm, an encryption 2784 algorithm and cryptographic keys before the application protocol 2785 transmits or receives its first octet of data. Only the (D)TLS 2786 client can initiate the handshake protocol. The (D)TLS Handshake 2787 Protocol provides security that has four basic properties: 2789 o The peer's identity can be authenticated using asymmetric (public 2790 key) cryptography (e.g., RSA [RSA], DSS [DSS], etc.). This 2791 authentication can be made optional, but is generally required by 2792 at least one of the peers. 2794 (D)TLS supports three authentication modes: authentication of both 2795 the server and the client, server authentication with an 2796 unauthenticated client, and total anonymity. For authentication 2797 of both entities, each entity provides a valid certificate chain 2798 leading to an acceptable certificate authority. Each entity is 2799 responsible for verifying that the other's certificate is valid 2800 and has not expired or been revoked. See 2801 [I-D.saintandre-tls-server-id-check] for further details on 2802 standardized processing when checking server certificate 2803 identities. 2805 o The negotiation of a shared secret is secure: the negotiated 2806 secret is unavailable to eavesdroppers, and for any authenticated 2807 handshake the secret cannot be obtained, even by an attacker who 2808 can place himself in the middle of the session. 2810 o The negotiation is not vulnerable to malicious modification: it is 2811 infeasible for an attacker to modify negotiation communication 2812 without being detected by the parties to the communication. 2814 o DTLS uses a stateless cookie exchange to protect against anonymous 2815 denial of service attacks and has retransmission timers, sequence 2816 numbers, and counters to handle message loss, reordering, and 2817 fragmentation. 2819 Appendix B. PKIX Certificate Infrastructure 2821 Users of a public key from a PKIX / X.509 certificate can be be 2822 confident that the associated private key is owned by the correct 2823 remote subject (person or system) with which an encryption or digital 2824 signature mechanism will be used. This confidence is obtained 2825 through the use of public key certificates, which are data structures 2826 that bind public key values to subjects. The binding is asserted by 2827 having a trusted CA digitally sign each certificate. The CA may base 2828 this assertion upon technical means (i.e., proof of possession 2829 through a challenge-response protocol), presentation of the private 2830 key, or on an assertion by the subject. A certificate has a limited 2831 valid lifetime which is indicated in its signed contents. Because a 2832 certificate's signature and timeliness can be independently checked 2833 by a certificate-using client, certificates can be distributed via 2834 untrusted communications and server systems, and can be cached in 2835 unsecured storage in certificate-using systems. 2837 ITU-T X.509 (formerly CCITT X.509) or ISO/IEC/ITU 9594-8 [X509], 2838 which was first published in 1988 as part of the X.500 Directory 2839 recommendations, defines a standard certificate format which is a 2840 certificate which binds a subject (principal) to a public key value. 2841 This was later further expanded and documented in [RFC5280]. 2843 A X.509 certificate is a sequence of three required fields: 2845 tbsCertificate: The tbsCertificate field contains the names of the 2846 subject and issuer, a public key associated with the subject, a 2847 validity period, and other associated information. This field may 2848 also contain extension components. 2850 signatureAlgorithm: The signatureAlgorithm field contains the 2851 identifier for the cryptographic algorithm used by the certificate 2852 authority (CA) to sign this certificate. 2854 signatureValue: The signatureValue field contains a digital 2855 signature computed by the CA upon the ASN.1 DER encoded 2856 tbsCertificate field. The ASN.1 DER encoded tbsCertificate is 2857 used as the input to the signature function. This signature value 2858 is then ASN.1 DER encoded as a BIT STRING and included in the 2859 Certificate's signature field. By generating this signature, the 2860 CA certifies the validity of the information in the tbsCertificate 2861 field. In particular, the CA certifies the binding between the 2862 public key material and the subject of the certificate. 2864 The basic X.509 authentication procedure is as follows: A system is 2865 initialized with a number of root certificates that contain the 2866 public keys of a number of trusted CAs. When a system receives a 2867 X.509 certificate, signed by one of those CAs, the certificate has to 2868 be verified. It first checks the signatureValue field by using the 2869 public key of the corresponding trusted CA. Then it compares the 2870 digest of the received certificate with a digest of the 2871 tbsCertificate field. If they match, then the subject in the 2872 tbsCertificate field is authenticated. 2874 Appendix C. Target and Notificaton Configuration Example 2876 Configuring the SNMP-TARGET-MIB and NOTIFICATION-MIB along with 2877 access control settings for the SNMP-VIEW-BASED-ACM-MIB can be a 2878 daunting task without an example to follow. The following section 2879 describes an example of what pieces must be in place to accomplish 2880 this configuration. 2882 The isAccessAllowed() ASI requires configuration to exist in the 2883 following SNMP-VIEW-BASED-ACM-MIB tables: 2885 vacmSecurityToGroupTable 2886 vacmAccessTable 2887 vacmViewTreeFamilyTable 2889 The only table that needs to be discussed as particularly different 2890 here is the vacmSecurityToGroupTable. This table is indexed by both 2891 the SNMPv3 security model and the security name. The security model, 2892 when TLSTM is in use, should be set to the value of 4, corresponding 2893 to the TSM [RFC5591]. An example vacmSecurityToGroupTable row might 2894 be filled out as follows (using a single SNMP SET request): 2896 vacmSecurityModel = 4 (TSM) 2897 vacmSecurityName = "blueberry" 2898 vacmGroupName = "administrators" 2899 vacmSecurityToGroupStorageType = 3 (nonVolatile) 2900 vacmSecurityToGroupStatus = 4 (createAndGo) 2902 This example will assume that the "administrators" group has been 2903 given proper permissions via rows in the vacmAccessTable and 2904 vacmViewTreeFamilyTable. 2906 Depending on whether this VACM configuration is for a Command 2907 Responder or a command generator the security name "blueberry" will 2908 come from a few different locations. 2910 C.1. Configuring the Notification Generator 2912 For notification generators performing authorization checks, the 2913 server's certificate must be verified against the expected 2914 certificate before proceeding to send the notification. The expected 2915 certificate from the server may be listed in the tlstmAddrTable or 2916 may be determined through other X.509 path validation mechanisms. 2917 The securityName to use for VACM authorization checks is set by the 2918 SNMP-TARGET-MIB's snmpTargetParamsSecurityName column. 2920 The certificate that the notification generator should present to the 2921 server is taken from the tlstmParamsClientFingerprint column from the 2922 appropriate entry in the tlstmParamsTable table. 2924 C.2. Configuring the Command Responder 2926 For command responder applications, the vacmSecurityName "blueberry" 2927 value is a value that derived from an incoming (D)TLS session. The 2928 mapping from a recevied (D)TLS client certificate to a tmSecurityName 2929 is done with the tlstmCertToTSNTable. The certificates must be 2930 loaded into the device so that a tlstmCertToTSNEntry may refer to it. 2931 As an example, consider the following entry which will provide a 2932 mapping from a client's public X.509's hash fingerprint directly to 2933 the "blueberry" tmSecurityName: 2935 tlstmCertToTSNID = 1 (chosen by ordering preference) 2936 tlstmCertToTSNFingerprint = HASH (appropriate fingerprint) 2937 tlstmCertToTSNMapType = 1 (specified) 2938 tlstmCertToTSNSecurityName = "blueberry" 2939 tlstmCertToTSNStorageType = 3 (nonVolatile) 2940 tlstmCertToTSNRowStatus = 4 (createAndGo) 2942 The above is an example of how to map a particular certificate to a 2943 particular tmSecurityName. It is recommended, however, that users 2944 make use of direct subjectAltName or CommonName mappings where 2945 possible as it provides a more scalable approach to certificate 2946 management. This entry provides an example of using a subjectAltName 2947 mapping: 2949 tlstmCertToTSNID = 1 (chosen by ordering preference) 2950 tlstmCertToTSNFingerprint = HASH (appropriate fingerprint) 2951 tlstmCertToTSNMapType = 2 (bySubjectAltName) 2952 tlstmCertToTSNSANType = 1 (any) 2953 tlstmCertToTSNStorageType = 3 (nonVolatile) 2954 tlstmCertToTSNRowStatus = 4 (createAndGo) 2956 The above entry indicates the subjectAltName field for certificates 2957 created by an issuing certificate with a corresponding fingerprint 2958 will be trusted to always produce common names that are directly one- 2959 to-one mappable into tmSecurityNames. This type of configuration 2960 should only be used when the certificate authorities naming 2961 conventions are carefully controlled. 2963 In the example, if the incoming (D)TLS client provided certificate 2964 contained a subjectAltName where the first listed subjectAltName in 2965 the extension is the rfc822Name of "blueberry@example.com", the 2966 certificate was signed by a certificate matching the 2967 tlstmCertToTSNFingerprint value and the CA's certificate was properly 2968 installed on the device then the string "blueberry@example.com" would 2969 be used as the tmSecurityName for the session. 2971 Author's Address 2973 Wes Hardaker 2974 Sparta, Inc. 2975 P.O. Box 382 2976 Davis, CA 95617 2977 USA 2979 Phone: +1 530 792 1913 2980 Email: ietf@hardakers.net