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