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